xemacs-beta: man/widget.texi annotate

annotate man/widget.texi @ 5903:5afddd952c46

Return ratios in canonical form too, #'string-to-number src/ChangeLog addition: 2015-05-08 Aidan Kehoe <kehoea@parhasard.net> * data.c (Fstring_to_number): Canonicalise ratios in this function, as we do bignums.

author	Aidan Kehoe <kehoea@parhasard.net>
date	Fri, 08 May 2015 13:58:22 +0100
parents	d11efddf3617
children

rev	line source
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1 \input texinfo.tex
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	2 @c %**start of header
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	3 @setfilename ../info/widget.info
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	4 @settitle The Emacs Widget Library
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	5 @syncodeindex fn cp
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	6 @syncodeindex vr cp
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	7 @syncodeindex ky cp
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	8 @c %**end of header
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	9 @c Synced up with: FSF 24.3
d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	10 @c Synced by: Jerry James, 19-Jun-2013.
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	11
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	12 @copying
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	13 Copyright @copyright{} 2000--2013 Free Software Foundation, Inc.
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	14
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	15 @quotation
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	16 Permission is granted to copy, distribute and/or modify this document
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	17 under the terms of the GNU Free Documentation License, Version 1.3 or
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	18 any later version published by the Free Software Foundation; with no
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	19 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	20 and with the Back-Cover Texts as in (a) below. A copy of the license
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	21 is included in the section entitled ``GNU Free Documentation License''.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	22
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	23 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	24 modify this GNU manual. Buying copies from the FSF supports it in
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	25 developing GNU and promoting software freedom.''
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	26 @end quotation
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	27 @end copying
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	28
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	29 @ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	30 @dircategory XEmacs Editor
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	31 @direntry
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	32 * Widget: (widget). The "widget" package used by the Emacs Customization
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	33 facility.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	34 @end direntry
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	35 @end ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	36
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	37 @contents
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	38
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	39 @node Top, Introduction, (dir), (dir)
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	40 @comment node-name, next, previous, up
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	41 @top The Emacs Widget Library
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	42
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	43 @insertcopying
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	44
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	45 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	46 * Introduction::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	47 * User Interface::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	48 * Programming Example::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	49 * Setting Up the Buffer::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	50 * Basic Types::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	51 * Sexp Types::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	52 * Widget Properties::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	53 * Defining New Widgets::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	54 * Widget Browser::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	55 * Widget Minor Mode::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	56 * Utilities::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	57 * Widget Wishlist::
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	58 * Widget Internals::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	59 * GNU Free Documentation License::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	60 * Index::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	61 @detailmenu
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	62 --- The Detailed Node Listing ---
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	63
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	64 The Emacs Widget Library
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	65
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	66 * Introduction::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	67 * User Interface::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	68 * Programming Example::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	69 * Setting Up the Buffer::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	70 * Basic Types::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	71 * Sexp Types::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	72 * Widget Properties::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	73 * Defining New Widgets::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	74 * Widget Browser::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	75 * Widget Minor Mode::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	76 * Utilities::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	77 * Widget Wishlist::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	78 * Widget Internals::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	79 * GNU Free Documentation License::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	80 * Index::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	81
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	82 Basic Types
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	83
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	84 * link::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	85 * url-link::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	86 * info-link::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	87 * push-button::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	88 * editable-field::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	89 * text::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	90 * menu-choice::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	91 * radio-button-choice::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	92 * item::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	93 * choice-item::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	94 * toggle::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	95 * checkbox::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	96 * checklist::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	97 * editable-list::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	98 * group::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	99
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	100 Sexp Types
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	101
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	102 * constants::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	103 * generic::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	104 * atoms::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	105 * composite::
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	106
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	107 @end detailmenu
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	108 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	109
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	110 @node Introduction, User Interface, Top, Top
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	111 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	112 @chapter Introduction
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	113
2028 2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	114 @c XEmacs changes to reflect history, native widgets, and GTK
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	115 Most graphical user interface toolkits provide
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	116 a number of standard user interface controls (sometimes known as
2028 2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	117 `widgets' or `gadgets'). Historically, Emacs didn't support anything like
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	118 this, except for its incredibly powerful text ``widget''. However,
2028 2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	119 since XEmacs 21.4, XEmacs has supported ``native'' widgets (GUI controls
2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	120 implemented as Lisp APIs in C for the MS Windows, Motif, Athena, and GTK
2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	121 toolkits) and libglade (GUI controls with an XML API for the GTK
2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	122 toolkit). On the other hand, Emacs does provide the necessary
2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	123 primitives to implement many other widgets within a text buffer, and of
2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	124 course this is the only way to implement self-contained controls in a
2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	125 text terminal. The @code{widget} package simplifies this task.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	126
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	127 @cindex basic widgets
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	128 @cindex widgets, basic types
2028 2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	129 Examples of some basic widgets include:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	130
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	131 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	132 @item link
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	133 Areas of text with an associated action. Intended for hypertext links
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	134 embedded in text.
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	135 @item push-button
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	136 Like link, but intended for stand-alone buttons.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	137 @item editable-field
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	138 An editable text field. It can be either variable or fixed length.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	139 @item menu-choice
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	140 Allows the user to choose one of multiple options from a menu, each
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	141 option is itself a widget. Only the selected option will be visible in
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	142 the buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	143 @item radio-button-choice
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	144 Allows the user to choose one of multiple options by activating radio
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	145 buttons. The options are implemented as widgets. All options will be
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	146 visible in the buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	147 @item item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	148 A simple constant widget intended to be used in the @code{menu-choice} and
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	149 @code{radio-button-choice} widgets.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	150 @item choice-item
901 37e56e920ac5 [xemacs-hg @ 2002-07-05 20:35:47 by adrian] adrian parents: 785 diff changeset	151 A button item only intended for use in choices. When invoked, the user
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	152 will be asked to select another option from the choice widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	153 @item toggle
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	154 A simple @samp{on}/@samp{off} switch.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	155 @item checkbox
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	156 A checkbox (@samp{[ ]}/@samp{[X]}).
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	157 @item editable-list
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	158 Create an editable list. The user can insert or delete items in the
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	159 list. Each list item is itself a widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	160 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	161
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	162 Now, of what possible use can support for widgets be in a text editor?
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	163 I'm glad you asked. The answer is that widgets are useful for
2028 2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	164 implementing forms. A @dfn{form} in Emacs is a buffer where the user is
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	165 supposed to fill out a number of fields, each of which has a specific
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	166 meaning. The user is not supposed to change or delete any of the text
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	167 between the fields. Examples of forms in Emacs are the @file{forms}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	168 package (of course), the customize buffers, the mail and news compose
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	169 modes, and the @acronym{HTML} form support in the @file{w3} browser.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	170
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	171 @cindex widget library, why use it
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	172 The advantages for a programmer of using the @code{widget} package to
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	173 implement forms are:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	174
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	175 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	176 @item
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	177 More complex fields than just editable text are supported.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	178 @item
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	179 You can give the users immediate feedback if they enter invalid data in a
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	180 text field, and sometimes prevent entering invalid data.
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	181 @item
2028 2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	182 You can have fixed sized fields, thus allowing multiple fields to be
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	183 lined up in columns.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	184 @item
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	185 It is simple to query or set the value of a field.
d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	186 @item
2028 2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	187 Editing happens in a normal buffer, not in the mini-buffer.
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	188 @item
2028 2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	189 Packages using the library get a uniform look-and-feel, making them easier for
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	190 the user to learn.
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	191 @item
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	192 As support for embedded graphics improve, the widget library will be
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	193 extended to use the GUI features. This means that your code using the
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	194 widget library will also use the new graphic features automatically.
2028 2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	195 @item
2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	196 A widget specification is implemented as a class, and new subclasses can
2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	197 be derived from any class, by restricting or extending the behavior.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	198 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	199
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	200 In order to minimize the code that is loaded by users who does not
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	201 create any widgets, the code has been split in two files:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	202
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	203 @table @file
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	204 @item widget.el
2028 2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	205 This declares the user variables, defines the function
2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	206 @code{define-widget}, and autoloads the function @code{widget-create}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	207 @item wid-edit.el
2028 2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	208 Everything else is here. Do not load it explicitly, as
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	209 it will be autoloaded when needed.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	210 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	211
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	212 In order to minimize the code that is loaded by users who does not
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	213 create any widgets, the code has been split in two files:
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	214
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	215 @table @file
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	216 @item widget.el
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	217 This will declare the user variables, define the function
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	218 @code{widget-define}, and autoload the function @code{widget-create}.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	219 @item wid-edit.el
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	220 Everything else is here, there is no reason to load it explicitly, as
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	221 it will be autoloaded when needed.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	222 @end table
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	223
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	224 @node User Interface, Programming Example, Introduction, Top
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	225 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	226 @chapter User Interface
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	227
904 47c30044fc4e [xemacs-hg @ 2002-07-06 18:56:24 by adrian] adrian parents: 901 diff changeset	228 A form consists of read only text for documentation and some fields,
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	229 where each field contains two parts, a tag and a value. The tags are
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	230 used to identify the fields, so the documentation can refer to the
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	231 @samp{foo field}, meaning the field tagged with @samp{Foo}. Here is an
904 47c30044fc4e [xemacs-hg @ 2002-07-06 18:56:24 by adrian] adrian parents: 901 diff changeset	232 example form:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	233
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	234 @example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	235 Here is some documentation.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	236
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	237 Name: @i{My Name} @strong{Choose}: This option
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	238 Address: @i{Some Place
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	239 In some City
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	240 Some country.}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	241
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	242 See also @b{_other work_} for more information.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	243
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	244 Numbers: count to three below
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	245 @b{[INS]} @b{[DEL]} @i{One}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	246 @b{[INS]} @b{[DEL]} @i{Eh, two?}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	247 @b{[INS]} @b{[DEL]} @i{Five!}
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	248 @b{[INS]}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	249
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	250 Select multiple:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	251
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	252 @b{[X]} This
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	253 @b{[ ]} That
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	254 @b{[X]} Thus
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	255
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	256 Select one:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	257
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	258 @b{(*)} One
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	259 @b{( )} Another One.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	260 @b{( )} A Final One.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	261
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	262 @b{[Apply Form]} @b{[Reset Form]}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	263 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	264
2028 2ba4f06a264d [xemacs-hg @ 2004-04-19 08:02:27 by stephent] stephent parents: 1347 diff changeset	265 The top level widgets in this example are tagged @samp{Name},
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	266 @samp{Choose}, @samp{Address}, @samp{_other work_}, @samp{Numbers},
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	267 @samp{Select multiple}, @samp{Select one}, @samp{[Apply Form]}, and
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	268 @samp{[Reset Form]}. There are basically two things the user can do
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	269 within a form, namely editing the editable text fields and activating
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	270 the buttons.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	271
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	272 @section Editable Text Fields
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	273
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	274 In the example, the value for the @samp{Name} is most likely displayed
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	275 in an editable text field, and so are values for each of the members of
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	276 the @samp{Numbers} list. All the normal Emacs editing operations are
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	277 available for editing these fields. The only restriction is that each
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	278 change you make must be contained within a single editable text field.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	279 For example, capitalizing all text from the middle of one field to the
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	280 middle of another field is prohibited.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	281
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	282 Editable text fields are created by the @code{editable-field} widget.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	283
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	284 @strong{Warning:} In an @code{editable-field} widget, the editable
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	285 field must not be adjacent to another widget---that won't work.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	286 You must put some text in between. Either make this text part of
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	287 the @code{editable-field} widget itself, or insert it with
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	288 @code{widget-insert}.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	289
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	290 The @code{:format} keyword is useful for generating the necessary
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	291 text; for instance, if you give it a value of @code{"Name: %v "},
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	292 the @samp{Name: } part will provide the necessary separating text
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	293 before the field and the trailing space will provide the
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	294 separating text after the field. If you don't include the
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	295 @code{:size} keyword, the field will extend to the end of the
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	296 line, and the terminating newline will provide separation after.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	297
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	298 @strong{Warning:} In an @code{editable-field} widget, the @samp{%v} escape
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	299 must be preceded by some other text in the @code{:format} string
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	300 (if specified).
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	301
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	302 The editing text fields are highlighted with the
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	303 @code{widget-field-face} face, making them easy to find.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	304
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	305 @deffn Face widget-field-face
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	306 Face used for other editing fields.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	307 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	308
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	309 @section Buttons
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	310
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	311 @cindex widget buttons
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	312 @cindex button widgets
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	313 Some portions of the buffer have an associated @dfn{action}, which can
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	314 be @dfn{invoked} by a standard key or mouse command. These portions
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	315 are called @dfn{buttons}. The default commands for activating a button
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	316 are:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	317
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	318 @table @kbd
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	319 @item @key{RET}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	320 @deffn Command widget-button-press @var{pos} &optional @var{event}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	321 Invoke the button at @var{pos}, defaulting to point.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	322 If point is not located on a button, invoke the binding in
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	323 @code{widget-global-map} (by default the global map).
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	324 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	325
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	326 @kindex Mouse-2 @r{(on button widgets})
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	327 @item Mouse-2
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	328 @deffn Command widget-button-click @var{event}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	329 Invoke the button at the location of the mouse pointer. If the mouse
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	330 pointer is located in an editable text field, invoke the binding in
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	331 @code{widget-global-map} (by default the global map).
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	332 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	333 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	334
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	335 There are several different kind of buttons, all of which are present in
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	336 the example:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	337
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	338 @table @emph
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	339 @cindex option field tag
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	340 @item The Option Field Tags
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	341 When you invoke one of these buttons, you will be asked to choose
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	342 between a number of different options. This is how you edit an option
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	343 field. Option fields are created by the @code{menu-choice} widget. In
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	344 the example, @samp{@b{Choose}} is an option field tag.
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	345 @item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons
904 47c30044fc4e [xemacs-hg @ 2002-07-06 18:56:24 by adrian] adrian parents: 901 diff changeset	346 Activating these will insert or delete elements from an editable list.
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	347 The list is created by the @code{editable-list} widget.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	348 @cindex embedded buttons
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	349 @item Embedded Buttons
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	350 The @samp{@b{_other work_}} is an example of an embedded
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	351 button. Embedded buttons are not associated with any fields, but can serve
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	352 any purpose, such as implementing hypertext references. They are
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	353 usually created by the @code{link} widget.
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	354 @item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	355 Activating one of these will convert it to the other. This is useful
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	356 for implementing multiple-choice fields. You can create them with the
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	357 @code{checkbox} widget.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	358 @item The @samp{@b{( )}} and @samp{@b{(*)}} buttons
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	359 Only one radio button in a @code{radio-button-choice} widget can be
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	360 selected at any time. When you invoke one of the unselected radio
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	361 buttons, it will be selected and the previous selected radio button will
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	362 become unselected.
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	363 @item The @samp{@b{[Apply Form]}} and @samp{@b{[Reset Form]}} buttons
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	364 These are explicit buttons made with the @code{push-button} widget. The
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	365 main difference from the @code{link} widget is that the buttons will be
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	366 displayed as GUI buttons when possible.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	367 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	368
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	369 To make them easier to locate, buttons are emphasized in the buffer.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	370
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	371 @deffn Face widget-button-face
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	372 Face used for buttons.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	373 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	374
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	375 @defopt widget-mouse-face
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	376 Face used for highlighting a button when the mouse pointer moves across
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	377 it.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	378 @end defopt
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	379
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	380 @section Navigation
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	381
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	382 You can use all the normal Emacs commands to move around in a form
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	383 buffer, plus you will have these additional commands:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	384
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	385 @table @kbd
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	386 @item @key{TAB}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	387 @deffn Command widget-forward &optional count
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	388 Move point @var{count} buttons or editing fields forward.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	389 @end deffn
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	390 @item @kbd{M-@key{TAB}}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	391 @itemx @kbd{S-@key{TAB}}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	392 @deffn Command widget-backward &optional count
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	393 Move point @var{count} buttons or editing fields backward.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	394 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	395 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	396
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	397 @node Programming Example, Setting Up the Buffer, User Interface, Top
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	398 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	399 @chapter Programming Example
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	400
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	401 @cindex widgets, programming example
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	402 @cindex example of using widgets
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	403 Here is the code to implement the user interface example (@pxref{User
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	404 Interface}).
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	405
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	406 @lisp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	407 (require 'widget)
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	408
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	409 (eval-when-compile
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	410 (require 'wid-edit))
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	411
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	412 (defvar widget-example-repeat)
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	413
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	414 (defun widget-example ()
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	415 "Create the widgets from the Widget manual."
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	416 (interactive)
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	417 (kill-buffer (get-buffer-create "Widget Example"))
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	418 (switch-to-buffer (get-buffer-create "Widget Example"))
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	419 (kill-all-local-variables)
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	420 (make-local-variable 'widget-example-repeat)
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	421 (widget-insert "Here is some documentation.\n\n")
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	422 (widget-create 'editable-field
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	423 :size 13
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	424 :format "Name: %v " ; Text after the field!
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	425 "My Name")
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	426 (widget-create 'menu-choice
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	427 :tag "Choose"
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	428 :value "This"
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	429 :help-echo "Choose me, please!"
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	430 :notify (lambda (widget &rest ignore)
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	431 (message "%s is a good choice!"
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	432 (widget-value widget)))
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	433 '(item :tag "This option" :value "This")
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	434 '(choice-item "That option")
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	435 '(editable-field :menu-tag "No option" "Thus option"))
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	436 (widget-create 'editable-field
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	437 :format "Address: %v"
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	438 "Some Place\nIn some City\nSome country.")
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	439 (widget-insert "\nSee also ")
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	440 (widget-create 'link
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	441 :notify (lambda (&rest ignore)
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	442 (widget-value-set widget-example-repeat
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	443 '("En" "To" "Tre"))
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	444 (widget-setup))
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	445 "other work")
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	446 (widget-insert
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	447 " for more information.\n\nNumbers: count to three below\n")
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	448 (setq widget-example-repeat
440 8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	449 (widget-create 'editable-list
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	450 :entry-format "%i %d %v"
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	451 :notify (lambda (widget &rest ignore)
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	452 (let ((old (widget-get widget
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	453 ':example-length))
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	454 (new (length (widget-value widget))))
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	455 (unless (eq old new)
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	456 (widget-put widget ':example-length new)
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	457 (message "You can count to %d." new))))
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	458 :value '("One" "Eh, two?" "Five!")
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	459 '(editable-field :value "three")))
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	460 (widget-insert "\n\nSelect multiple:\n\n")
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	461 (widget-create 'checkbox t)
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	462 (widget-insert " This\n")
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	463 (widget-create 'checkbox nil)
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	464 (widget-insert " That\n")
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	465 (widget-create 'checkbox
440 8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	466 :notify (lambda (&rest ignore) (message "Tickle"))
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	467 t)
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	468 (widget-insert " Thus\n\nSelect one:\n\n")
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	469 (widget-create 'radio-button-choice
440 8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	470 :value "One"
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	471 :notify (lambda (widget &rest ignore)
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	472 (message "You selected %s"
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	473 (widget-value widget)))
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	474 '(item "One") '(item "Another One.") '(item "A Final One."))
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	475 (widget-insert "\n")
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	476 (widget-create 'push-button
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	477 :notify (lambda (&rest ignore)
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	478 (if (= (length (widget-value widget-example-repeat))
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	479 3)
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	480 (message "Congratulation!")
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	481 (error "Three was the count!")))
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	482 "Apply Form")
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	483 (widget-insert " ")
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	484 (widget-create 'push-button
440 8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	485 :notify (lambda (&rest ignore)
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	486 (widget-example))
8de8e3f6228a Import from CVS: tag r21-2-28 cvs parents: 434 diff changeset	487 "Reset Form")
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	488 (widget-insert "\n")
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	489 (use-local-map widget-keymap)
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	490 (widget-setup))
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	491 @end lisp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	492
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	493 @node Setting Up the Buffer, Basic Types, Programming Example, Top
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	494 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	495 @chapter Setting Up the Buffer
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	496
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	497 Widgets are created with @code{widget-create}, which returns a
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	498 @dfn{widget} object. This object can be queried and manipulated by
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	499 other widget functions, until it is deleted with @code{widget-delete}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	500 After the widgets have been created, @code{widget-setup} must be called
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	501 to enable them.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	502
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	503 @defun widget-create type [ keyword argument ]@dots{}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	504 Create and return a widget of type @var{type}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	505 The syntax for the @var{type} argument is described in @ref{Basic Types}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	506
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	507 The keyword arguments can be used to overwrite the keyword arguments
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	508 that are part of @var{type}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	509 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	510
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	511 @defun widget-delete widget
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	512 Delete @var{widget} and remove it from the buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	513 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	514
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	515 @defun widget-setup
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	516 Set up a buffer to support widgets.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	517
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	518 This should be called after creating all the widgets and before allowing
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	519 the user to edit them.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	520 @refill
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	521 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	522
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	523 If you want to insert text outside the widgets in the form, the
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	524 recommended way to do that is with @code{widget-insert}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	525
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	526 @defun widget-insert
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	527 Insert the arguments, either strings or characters, at point.
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	528 The inserted text will be read-only.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	529 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	530
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	531 There is a standard widget keymap which you might find useful.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	532
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	533 @findex widget-button-press
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	534 @findex widget-button-click
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	535 @defvr Const widget-keymap
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	536 A keymap with the global keymap as its parent.@*
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	537 @key{TAB} and @kbd{C-@key{TAB}} are bound to @code{widget-forward} and
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	538 @code{widget-backward}, respectively. @key{RET} and @kbd{Mouse-2}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	539 are bound to @code{widget-button-press} and
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	540 @code{widget-button-click}.@refill
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	541 @end defvr
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	542
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	543 @defvar widget-global-map
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	544 Keymap used by @code{widget-button-press} and @code{widget-button-click}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	545 when not on a button. By default this is @code{global-map}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	546 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	547
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	548 @node Basic Types, Sexp Types, Setting Up the Buffer, Top
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	549 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	550 @chapter Basic Types
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	551
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	552 This is the general syntax of a type specification:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	553
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	554 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	555 @var{name} ::= (@var{name} [@var{keyword} @var{argument}]... @var{args})
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	556 \| @var{name}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	557 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	558
444 576fb035e263 Import from CVS: tag r21-2-37 cvs parents: 440 diff changeset	559 where @var{name} is a widget name, @var{keyword} is the name of a
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	560 property, @var{argument} is the value of the property, and @var{args}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	561 are interpreted in a widget specific way.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	562
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	563 @cindex keyword arguments
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	564 The following keyword arguments apply to all widgets:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	565
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	566 @table @code
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	567 @vindex value@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	568 @item :value
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	569 The initial value for widgets of this type.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	570
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	571 @vindex format@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	572 @item :format
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	573 This string will be inserted in the buffer when you create a widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	574 The following @samp{%} escapes are available:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	575
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	576 @table @samp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	577 @item %[
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	578 @itemx %]
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	579 The text inside will be marked as a button.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	580
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	581 By default, the text will be shown in @code{widget-button-face}, and
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	582 surrounded by brackets.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	583
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	584 @defopt widget-button-prefix
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	585 String to prefix buttons.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	586 @end defopt
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	587
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	588 @defopt widget-button-suffix
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	589 String to suffix buttons.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	590 @end defopt
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	591
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	592 @item %@{
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	593 @itemx %@}
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	594 The text inside will be displayed in the face specified by
9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	595 @code{:sample-face}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	596
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	597 @item %v
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	598 This will be replaced with the buffer representation of the widget's
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	599 value. What this is depends on the widget type.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	600
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	601 @strong{Warning:} In an @code{editable-field} widget, the @samp{%v} escape
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	602 must be preceded by some other text in the format string (if specified).
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	603
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	604 @item %d
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	605 Insert the string specified by @code{:doc} here.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	606
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	607 @item %h
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	608 Like @samp{%d}, with the following modifications: If the documentation
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	609 string is more than one line, it will add a button which will toggle
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	610 between showing only the first line, and showing the full text.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	611 Furthermore, if there is no @code{:doc} property in the widget, it will
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	612 instead examine the @code{:documentation-property} property. If it is a
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	613 lambda expression, it will be called with the widget's value as an
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	614 argument, and the result will be used as the documentation text.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	615
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	616 @item %t
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	617 Insert the string specified by @code{:tag} here, or the @code{princ}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	618 representation of the value if there is no tag.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	619
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	620 @item %%
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	621 Insert a literal @samp{%}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	622 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	623
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	624 @vindex button-face@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	625 @item :button-face
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	626 Face used to highlight text inside %[ %] in the format.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	627
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	628 @vindex button-prefix@r{ keyword}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	629 @vindex button-suffix@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	630 @item :button-prefix
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	631 @itemx :button-suffix
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	632 Text around %[ %] in the format.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	633
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	634 These can be
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	635 @table @emph
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	636 @item nil
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	637 No text is inserted.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	638
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	639 @item a string
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	640 The string is inserted literally.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	641
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	642 @item a symbol
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	643 The value of the symbol is expanded according to this table.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	644 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	645
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	646 @vindex doc@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	647 @item :doc
444 576fb035e263 Import from CVS: tag r21-2-37 cvs parents: 440 diff changeset	648 The string inserted by the @samp{%d} or @samp{%h} escape in the format
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	649 string.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	650
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	651 @vindex tag@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	652 @item :tag
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	653 The string inserted by the @samp{%t} escape in the format
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	654 string.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	655
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	656 @vindex tag-glyph@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	657 @item :tag-glyph
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	658 Name of image to use instead of the string specified by @code{:tag} on
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	659 Emacsen that supports it.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	660
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	661 @vindex help-echo@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	662 @item :help-echo
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	663 Specifies how to display a message whenever you move to the widget with
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	664 either @code{widget-forward} or @code{widget-backward} or move the mouse
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	665 over it (using the standard @code{help-echo} mechanism). The argument
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	666 is either a string to display, a function of one argument, the widget,
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	667 which should return a string to display, or a form that evaluates to
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	668 such a string.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	669
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	670 @vindex follow-link@r{ keyword}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	671 @item :follow-link
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	672 Specifies how to interpret a @key{mouse-1} click on the widget.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	673 @xref{Clickable Text,, Defining Clickable Text, elisp, the Emacs Lisp Reference Manual}.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	674
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	675 @vindex indent@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	676 @item :indent
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	677 An integer indicating the absolute number of spaces to indent children
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	678 of this widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	679
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	680 @vindex offset@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	681 @item :offset
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	682 An integer indicating how many extra spaces to add to the widget's
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	683 grandchildren compared to this widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	684
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	685 @vindex extra-offset@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	686 @item :extra-offset
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	687 An integer indicating how many extra spaces to add to the widget's
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	688 children compared to this widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	689
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	690 @vindex notify@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	691 @item :notify
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	692 A function called each time the widget or a nested widget is changed.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	693 The function is called with two or three arguments. The first argument
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	694 is the widget itself, the second argument is the widget that was
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	695 changed, and the third argument is the event leading to the change, if
652 2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent] stephent parents: 444 diff changeset	696 any. In editable fields, this includes all insertions, deletions,
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent] stephent parents: 444 diff changeset	697 @emph{etc}. To watch only for ``final'' actions, redefine the
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent] stephent parents: 444 diff changeset	698 @code{:action} callback.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	699
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	700 @vindex menu-tag@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	701 @item :menu-tag
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	702 Tag used in the menu when the widget is used as an option in a
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	703 @code{menu-choice} widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	704
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	705 @vindex menu-tag-get@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	706 @item :menu-tag-get
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	707 Function used for finding the tag when the widget is used as an option
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	708 in a @code{menu-choice} widget. By default, the tag used will be either the
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	709 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	710 representation of the @code{:value} property if not.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	711
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	712 @vindex match@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	713 @item :match
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	714 Should be a function called with two arguments, the widget and a value,
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	715 and returning non-@code{nil} if the widget can represent the specified value.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	716
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	717 @vindex validate@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	718 @item :validate
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	719 A function which takes a widget as an argument, and returns @code{nil}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	720 if the widget's current value is valid for the widget. Otherwise it
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	721 should return the widget containing the invalid data, and set that
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	722 widget's @code{:error} property to a string explaining the error.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	723
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	724 The following predefined function can be used:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	725
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	726 @defun widget-children-validate widget
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	727 All the @code{:children} of @var{widget} must be valid.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	728 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	729
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	730 @vindex tab-order@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	731 @item :tab-order
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	732 Specify the order in which widgets are traversed with
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	733 @code{widget-forward} or @code{widget-backward}. This is only partially
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	734 implemented.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	735
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	736 @enumerate a
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	737 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	738 Widgets with tabbing order @code{-1} are ignored.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	739
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	740 @item
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	741 (Unimplemented) When on a widget with tabbing order @var{n}, go to the
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	742 next widget in the buffer with tabbing order @var{n+1} or @code{nil},
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	743 whichever comes first.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	744
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	745 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	746 When on a widget with no tabbing order specified, go to the next widget
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	747 in the buffer with a positive tabbing order, or @code{nil}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	748 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	749
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	750 @vindex parent@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	751 @item :parent
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	752 The parent of a nested widget (e.g.@: a @code{menu-choice} item or an
904 47c30044fc4e [xemacs-hg @ 2002-07-06 18:56:24 by adrian] adrian parents: 901 diff changeset	753 element of an @code{editable-list} widget).
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	754
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	755 @vindex sibling-args@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	756 @item :sibling-args
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	757 This keyword is only used for members of a @code{radio-button-choice} or
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	758 @code{checklist}. The value should be a list of extra keyword
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	759 arguments, which will be used when creating the @code{radio-button} or
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	760 @code{checkbox} associated with this item.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	761
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	762 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	763
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	764 @deffn {User Option} widget-glyph-directory
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	765 Directory where glyphs are found.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	766 Widget will look here for a file with the same name as specified for the
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	767 image, with either a @file{.xpm} (if supported) or @file{.xbm} extension.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	768 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	769
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	770 @deffn{User Option} widget-glyph-enable
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	771 If non-@code{nil}, allow glyphs to appear on displays where they are supported.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	772 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	773
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	774
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	775 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	776 * link::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	777 * url-link::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	778 * info-link::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	779 * push-button::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	780 * editable-field::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	781 * text::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	782 * menu-choice::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	783 * radio-button-choice::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	784 * item::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	785 * choice-item::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	786 * toggle::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	787 * checkbox::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	788 * checklist::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	789 * editable-list::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	790 * group::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	791 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	792
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	793 @node link, url-link, Basic Types, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	794 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	795 @section The @code{link} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	796 @findex link@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	797
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	798 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	799
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	800 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	801 @var{type} ::= (link [@var{keyword} @var{argument}]... [ @var{value} ])
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	802 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	803
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	804 The @var{value}, if present, is used to initialize the @code{:value}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	805 property. The value should be a string, which will be inserted in the
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	806 buffer.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	807
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	808 By default the link will be shown in brackets.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	809
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	810 @defopt widget-link-prefix
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	811 String to prefix links.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	812 @end defopt
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	813
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	814 @defopt widget-link-suffix
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	815 String to suffix links.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	816 @end defopt
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	817
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	818 @node url-link, info-link, link, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	819 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	820 @section The @code{url-link} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	821 @findex url-link@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	822
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	823 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	824
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	825 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	826 @var{type} ::= (url-link [@var{keyword} @var{argument}]... @var{url})
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	827 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	828
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	829 @findex browse-url-browser-function@r{, and @code{url-link} widget}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	830 When this link is invoked, the @acronym{WWW} browser specified by
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	831 @code{browse-url-browser-function} will be called with @var{url}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	832
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	833 @node info-link, push-button, url-link, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	834 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	835 @section The @code{info-link} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	836 @findex info-link@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	837
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	838 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	839
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	840 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	841 @var{type} ::= (info-link [@var{keyword} @var{argument}]... @var{address})
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	842 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	843
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	844 When this link is invoked, the built-in Info reader is started on
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	845 @var{address}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	846
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	847 @node push-button, editable-field, info-link, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	848 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	849 @section The @code{push-button} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	850 @findex push-button@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	851
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	852 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	853
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	854 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	855 @var{type} ::= (push-button [@var{keyword} @var{argument}]... [ @var{value} ])
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	856 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	857
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	858 The @var{value}, if present, is used to initialize the @code{:value}
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	859 property. The value should be a string, which will be inserted in the
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	860 buffer.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	861
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	862 By default the tag will be shown in brackets.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	863
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	864 @defopt widget-push-button-prefix
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	865 String to prefix push buttons.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	866 @end defopt
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	867
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	868 @defopt widget-push-button-suffix
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	869 String to suffix push buttons.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	870 @end defopt
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	871
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	872 @node editable-field, text, push-button, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	873 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	874 @section The @code{editable-field} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	875 @findex editable-field@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	876
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	877 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	878
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	879 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	880 @var{type} ::= (editable-field [@var{keyword} @var{argument}]... [ @var{value} ])
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	881 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	882
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	883 The @var{value}, if present, is used to initialize the @code{:value}
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	884 property. The value should be a string, which will be inserted in the
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	885 field. This widget will match all string values.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	886
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	887 The following extra properties are recognized:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	888
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	889 @table @code
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	890 @vindex size@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	891 @item :size
444 576fb035e263 Import from CVS: tag r21-2-37 cvs parents: 440 diff changeset	892 The minimum width of the editable field.@*
576fb035e263 Import from CVS: tag r21-2-37 cvs parents: 440 diff changeset	893 By default the field will reach to the end of the line. If the
576fb035e263 Import from CVS: tag r21-2-37 cvs parents: 440 diff changeset	894 content is too large, the displayed representation will expand to
576fb035e263 Import from CVS: tag r21-2-37 cvs parents: 440 diff changeset	895 contain it. The content is not truncated to size.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	896
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	897 @vindex value-face@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	898 @item :value-face
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	899 Face used for highlighting the editable field. Default is
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	900 @code{widget-field-face}, see @ref{User Interface}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	901
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	902 @vindex secret@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	903 @item :secret
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	904 Character used to display the value. You can set this to e.g.@: @code{?*}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	905 if the field contains a password or other secret information. By
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	906 default, this is @code{nil}, and the value is not secret.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	907
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	908 @vindex valid-regexp@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	909 @item :valid-regexp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	910 By default the @code{:validate} function will match the content of the
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	911 field with the value of this attribute. The default value is @code{""}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	912 which matches everything.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	913
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	914 @vindex keymap@r{ keyword}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	915 @vindex widget-field-keymap
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	916 @item :keymap
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	917 Keymap used in the editable field. The default value is
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	918 @code{widget-field-keymap}, which allows you to use all the normal
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	919 editing commands, even if the buffer's major mode suppresses some of
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	920 them. Pressing @key{RET} invokes the function specified by
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	921 @code{:action}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	922 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	923
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	924 @node text, menu-choice, editable-field, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	925 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	926 @section The @code{text} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	927 @findex text@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	928
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	929 @vindex widget-text-keymap
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	930 This is just like @code{editable-field}, but intended for multiline text
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	931 fields. The default @code{:keymap} is @code{widget-text-keymap}, which
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	932 does not rebind the @key{RET} key.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	933
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	934 @node menu-choice, radio-button-choice, text, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	935 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	936 @section The @code{menu-choice} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	937 @findex menu-choice@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	938
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	939 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	940
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	941 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	942 @var{type} ::= (menu-choice [@var{keyword} @var{argument}]... @var{type} ... )
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	943 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	944
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	945 The @var{type} argument represents each possible choice. The widget's
9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	946 value will be that of the chosen @var{type} argument. This widget will
9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	947 match any value matching at least one of the specified @var{type}
9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	948 arguments.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	949
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	950 @table @code
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	951 @vindex void@r{ keyword}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	952 @item :void
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	953 Widget type used as a fallback when the value does not match any of the
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	954 specified @var{type} arguments.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	955
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	956 @vindex case-fold@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	957 @item :case-fold
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	958 Set this to @code{nil} if you don't want to ignore case when prompting for a
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	959 choice through the minibuffer.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	960
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	961 @vindex children@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	962 @item :children
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	963 A list whose @sc{car} is the widget representing the currently chosen
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	964 type in the buffer.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	965
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	966 @vindex choice@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	967 @item :choice
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	968 The current chosen type.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	969
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	970 @vindex args@r{ keyword}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	971 @item :args
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	972 The list of types.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	973 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	974
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	975 @node radio-button-choice, item, menu-choice, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	976 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	977 @section The @code{radio-button-choice} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	978 @findex radio-button-choice@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	979
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	980 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	981
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	982 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	983 @var{type} ::= (radio-button-choice [@var{keyword} @var{argument}]... @var{type} ... )
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	984 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	985
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	986 The component types specify the choices, with one radio button for
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	987 each. The widget's value will be that of the chosen @var{type}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	988 argument. This widget matches any value that matches at least one of
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	989 the specified @var{type} arguments.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	990
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	991 The following extra properties are recognized.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	992
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	993 @table @code
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	994 @vindex entry-format@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	995 @item :entry-format
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	996 This string will be inserted for each entry in the list.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	997 The following @samp{%} escapes are available:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	998 @table @samp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	999 @item %v
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1000 Replace with the buffer representation of the @var{type} widget.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1001 @item %b
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1002 Replace with the radio button.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1003 @item %%
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1004 Insert a literal @samp{%}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1005 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1006
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1007 @vindex button-args@r{ keyword}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1008 @item :button-args
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1009 A list of keywords to pass to the radio buttons. Useful for setting
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1010 e.g.@: the @samp{:help-echo} for each button.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1011
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1012 @vindex buttons@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1013 @item :buttons
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1014 The widgets representing the radio buttons.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1015
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1016 @vindex children@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1017 @item :children
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1018 The widgets representing each type.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1019
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1020 @vindex choice@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1021 @item :choice
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1022 The current chosen type
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1023
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1024 @vindex args@r{ keyword}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1025 @item :args
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1026 The list of types.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1027 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1028
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1029 You can add extra radio button items to a @code{radio-button-choice}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1030 widget after it has been created with the function
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1031 @code{widget-radio-add-item}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1032
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1033 @defun widget-radio-add-item widget type
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1034 Add to @code{radio-button-choice} widget @var{widget} a new radio button
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1035 item of type @var{type}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1036 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1037
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1038 Please note that such items added after the @code{radio-button-choice}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1039 widget has been created will @strong{not} be properly destructed when
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1040 you call @code{widget-delete}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1041
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1042 @node item, choice-item, radio-button-choice, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1043 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1044 @section The @code{item} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1045 @findex item@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1046
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1047 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1048
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1049 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1050 @var{item} ::= (item [@var{keyword} @var{argument}]... @var{value})
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1051 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1052
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1053 The @var{value}, if present, is used to initialize the @code{:value}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1054 property. The value should be a string, which will be inserted in the
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1055 buffer. This widget will only match the specified value.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1056
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1057 @node choice-item, toggle, item, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1058 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1059 @section The @code{choice-item} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1060 @findex choice-item@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1061
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1062 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1063
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1064 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1065 @var{item} ::= (choice-item [@var{keyword} @var{argument}]... @var{value})
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1066 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1067
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1068 The @var{value}, if present, is used to initialize the @code{:value}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1069 property. The value should be a string, which will be inserted in the
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1070 buffer as a button. Activating the button of a @code{choice-item} is
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1071 equivalent to activating the parent widget. This widget will only match
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1072 the specified value.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1073
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1074 @node toggle, checkbox, choice-item, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1075 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1076 @section The @code{toggle} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1077 @findex toggle@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1078
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1079 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1080
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1081 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1082 @var{type} ::= (toggle [@var{keyword} @var{argument}]...)
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1083 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1084
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1085 The widget has two possible states, @samp{on} and @samp{off}, which
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1086 correspond to a @code{t} or @code{nil} value, respectively.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1087
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1088 The following extra properties are recognized:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1089
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1090 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1091 @item :on
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1092 A string representing the @samp{on} state. By default the string
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1093 @samp{on}.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1094 @item :off
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1095 A string representing the @samp{off} state. By default the string
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1096 @samp{off}.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1097 @vindex on-glyph@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1098 @item :on-glyph
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1099 Name of a glyph to be used instead of the @samp{:on} text string, on
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1100 emacsen that supports this.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1101 @vindex off-glyph@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1102 @item :off-glyph
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1103 Name of a glyph to be used instead of the @samp{:off} text string, on
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1104 emacsen that supports this.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1105 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1106
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1107 @node checkbox, checklist, toggle, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1108 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1109 @section The @code{checkbox} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1110 @findex checkbox@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1111
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1112 This widget has two possible states, @samp{selected} and
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1113 @samp{unselected}, which corresponds to a @code{t} or @code{nil} value.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1114
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1115 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1116
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1117 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1118 @var{type} ::= (checkbox [@var{keyword} @var{argument}]...)
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1119 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1120
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1121 @node checklist, editable-list, checkbox, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1122 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1123 @section The @code{checklist} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1124 @findex checklist@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1125
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1126 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1127
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1128 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1129 @var{type} ::= (checklist [@var{keyword} @var{argument}]... @var{type} ... )
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1130 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1131
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1132 The @var{type} arguments represent each checklist item. The widget's
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1133 value will be a list containing the values of all checked @var{type}
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1134 arguments. The checklist widget will match a list whose elements all
9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1135 match at least one of the specified @var{type} arguments.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1136
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1137 The following extra properties are recognized:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1138
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1139 @table @code
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1140 @vindex entry-format@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1141 @item :entry-format
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1142 This string will be inserted for each entry in the list.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1143 The following @samp{%} escapes are available:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1144 @table @samp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1145 @item %v
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1146 Replaced with the buffer representation of the @var{type} widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1147 @item %b
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1148 Replace with the checkbox.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1149 @item %%
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1150 Insert a literal @samp{%}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1151 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1152
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1153 @vindex greedy@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1154 @item :greedy
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1155 Usually a checklist will only match if the items are in the exact
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1156 sequence given in the specification. By setting @code{:greedy} to
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1157 non-@code{nil}, it will allow the items to appear in any sequence.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1158 However, if you extract the value they will be in the sequence given
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1159 in the checklist, i.e.@: the original sequence is forgotten.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1160
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1161 @vindex button-args@r{ keyword}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1162 @item :button-args
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1163 A list of keywords to pass to the checkboxes. Useful for setting
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1164 e.g.@: the @samp{:help-echo} for each checkbox.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1165
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1166 @vindex buttons@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1167 @item :buttons
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1168 The widgets representing the checkboxes.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1169
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1170 @vindex children@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1171 @item :children
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1172 The widgets representing each type.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1173
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1174 @vindex args@r{ keyword}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1175 @item :args
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1176 The list of types.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1177 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1178
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1179 @node editable-list, group, checklist, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1180 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1181 @section The @code{editable-list} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1182 @findex editable-list@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1183
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1184 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1185
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1186 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1187 @var{type} ::= (editable-list [@var{keyword} @var{argument}]... @var{type})
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1188 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1189
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1190 The value is a list, where each member represents one widget of type
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1191 @var{type}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1192
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1193 The following extra properties are recognized:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1194
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1195 @table @code
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1196 @vindex entry-format@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1197 @item :entry-format
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1198 This string will be inserted for each entry in the list.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1199 The following @samp{%} escapes are available:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1200 @table @samp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1201 @item %v
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1202 This will be replaced with the buffer representation of the @var{type}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1203 widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1204 @item %i
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1205 Insert the @b{[INS]} button.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1206 @item %d
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1207 Insert the @b{[DEL]} button.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1208 @item %%
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1209 Insert a literal @samp{%}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1210 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1211
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1212 @vindex insert-button-args@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1213 @item :insert-button-args
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1214 A list of keyword arguments to pass to the insert buttons.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1215
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1216 @vindex delete-button-args@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1217 @item :delete-button-args
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1218 A list of keyword arguments to pass to the delete buttons.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1219
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1220 @vindex append-button-args@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1221 @item :append-button-args
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1222 A list of keyword arguments to pass to the trailing insert button.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1223
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1224 @vindex buttons@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1225 @item :buttons
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1226 The widgets representing the insert and delete buttons.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1227
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1228 @vindex children@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1229 @item :children
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1230 The widgets representing the elements of the list.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1231
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1232 @vindex args@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1233 @item :args
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1234 List whose @sc{car} is the type of the list elements.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1235 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1236
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1237 @node group, , editable-list, Basic Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1238 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1239 @section The @code{group} Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1240 @findex group@r{ widget}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1241
904 47c30044fc4e [xemacs-hg @ 2002-07-06 18:56:24 by adrian] adrian parents: 901 diff changeset	1242 This widget simply groups other widgets together.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1243
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1244 Syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1245
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1246 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1247 @var{type} ::= (group [@var{keyword} @var{argument}]... @var{type}...)
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1248 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1249
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1250 The value is a list, with one member for each @var{type}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1251
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1252 @node Sexp Types, Widget Properties, Basic Types, Top
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1253 @comment
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1254 @chapter Sexp Types
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1255 @cindex sexp types
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1256
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1257 A number of widgets for editing @dfn{s-expressions} (Lisp types), sexp
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1258 for short, are also available. These basically fall in several
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1259 categories described in this section.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1260
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1261 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1262 * constants::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1263 * generic::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1264 * atoms::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1265 * composite::
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1266 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1267
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1268 @node constants, generic, Sexp Types, Sexp Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1269 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1270 @section The Constant Widgets
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1271 @cindex constant widgets
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1272
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1273 The @code{const} widget can contain any Lisp expression, but the user is
785 955603004a04 [xemacs-hg @ 2002-03-19 22:48:03 by adrian] adrian parents: 652 diff changeset	1274 prohibited from editing it, which is mainly useful as a component of one
955603004a04 [xemacs-hg @ 2002-03-19 22:48:03 by adrian] adrian parents: 652 diff changeset	1275 of the composite widgets.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1276
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1277 The syntax for the @code{const} widget is:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1278
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1279 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1280 @var{type} ::= (const [@var{keyword} @var{argument}]... [ @var{value} ])
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1281 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1282
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1283 The @var{value}, if present, is used to initialize the @code{:value}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1284 property and can be any s-expression.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1285
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1286 @deffn Widget const
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1287 This will display any valid s-expression in an immutable part of the
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1288 buffer.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1289 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1290
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1291 There are two variations of the @code{const} widget, namely
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1292 @code{variable-item} and @code{function-item}. These should contain a
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1293 symbol with a variable or function binding. The major difference from
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1294 the @code{const} widget is that they will allow the user to see the
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1295 variable or function documentation for the symbol.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1296
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1297 @deffn Widget variable-item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1298 An immutable symbol that is bound as a variable.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1299 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1300
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1301 @deffn Widget function-item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1302 An immutable symbol that is bound as a function.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1303 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1304
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1305 @node generic, atoms, constants, Sexp Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1306 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1307 @section Generic Sexp Widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1308 @cindex generic sexp widget
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1309
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1310 The @code{sexp} widget can contain any Lisp expression, and allows the
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1311 user to edit it inline in the buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1312
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1313 The syntax for the @code{sexp} widget is:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1314
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1315 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1316 @var{type} ::= (sexp [@var{keyword} @var{argument}]... [ @var{value} ])
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1317 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1318
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1319 @deffn Widget sexp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1320 This will allow you to edit any valid s-expression in an editable buffer
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1321 field.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1322
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1323 The @code{sexp} widget takes the same keyword arguments as the
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1324 @code{editable-field} widget. @xref{editable-field}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1325 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1326
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1327 @node atoms, composite, generic, Sexp Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1328 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1329 @section Atomic Sexp Widgets
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1330 @cindex atomic sexp widget
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1331
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1332 The atoms are s-expressions that do not consist of other s-expressions.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1333 For example, a string, a file name, or a symbol are atoms, while a list
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1334 is a composite type. You can edit the value of an atom with the
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1335 following widgets.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1336
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1337 The syntax for all the atoms are:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1338
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1339 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1340 @var{type} ::= (@var{construct} [@var{keyword} @var{argument}]... [ @var{value} ])
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1341 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1342
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1343 The @var{value}, if present, is used to initialize the @code{:value}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1344 property and must be an expression of the same type as the widget.
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1345 That is, the string widget can only be initialized with a string.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1346
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1347 All the atom widgets take the same keyword arguments as the
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1348 @code{editable-field} widget. @xref{editable-field}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1349
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1350 @deffn Widget string
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1351 Allows you to edit a string in an editable field.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1352 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1353
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1354 @deffn Widget regexp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1355 Allows you to edit a regular expression in an editable field.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1356 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1357
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1358 @deffn Widget character
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1359 Allows you to enter a character in an editable field.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1360 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1361
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1362 @deffn Widget file
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1363 Allows you to edit a file name in an editable field.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1364
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1365 Keywords:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1366 @table @code
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1367 @vindex must-match@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1368 @item :must-match
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1369 If this is set to non-@code{nil}, only existing file names will be
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1370 allowed in the minibuffer.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1371 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1372 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1373
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1374 @deffn Widget directory
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1375 Allows you to edit a directory name in an editable field.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1376 Similar to the @code{file} widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1377 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1378
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1379 @deffn Widget symbol
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1380 Allows you to edit a Lisp symbol in an editable field.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1381 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1382
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1383 @deffn Widget function
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1384 Allows you to edit a lambda expression, or a function name with completion.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1385 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1386
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1387 @deffn Widget variable
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1388 Allows you to edit a variable name, with completion.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1389 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1390
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1391 @deffn Widget integer
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1392 Allows you to edit an integer in an editable field.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1393 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1394
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1395 @deffn Widget number
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1396 Allows you to edit a number in an editable field.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1397 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1398
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1399 @deffn Widget boolean
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1400 Allows you to edit a boolean. In Lisp this means a variable which is
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1401 either @code{nil} meaning false, or non-@code{nil} meaning true.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1402 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1403
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1404
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1405 @node composite, , atoms, Sexp Types
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1406 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1407 @section Composite Sexp Widgets
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1408 @cindex composite sexp widgets
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1409
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1410 The syntax for the composite widget construct is:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1411
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1412 @example
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1413 @var{type} ::= (@var{construct} [@var{keyword} @var{argument}]... @var{component}...)
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1414 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1415
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1416 @noindent
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1417 where each @var{component} must be a widget type. Each component widget
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1418 will be displayed in the buffer, and will be editable by the user.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1419
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1420 @deffn Widget cons
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1421 The value of a @code{cons} widget must be a cons-cell whose @sc{car}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1422 and @sc{cdr} have two specified types. It uses this syntax:
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1423
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1424 @example
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1425 @var{type} ::= (cons [@var{keyword} @var{argument}]... @var{car-type} @var{cdr-type})
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1426 @end example
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1427 @end deffn
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1428
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1429 @deffn Widget choice
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1430 The value matched by a @code{choice} widget must have one of a fixed
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1431 set of types. The widget's syntax is as follows:
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1432
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1433 @example
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1434 @var{type} ::= (choice [@var{keyword} @var{argument}]... @var{type} ... )
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1435 @end example
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1436
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1437 The value of a @code{choice} widget can be anything that matches any of the
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1438 @var{types}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1439 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1440
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1441 @deffn Widget list
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1442 The value of a @code{list} widget must be a list whose element types
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1443 match the specified component types:
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1444
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1445 @example
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1446 @var{type} ::= (list [@var{keyword} @var{argument}]... @var{component-type}...)
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1447 @end example
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1448
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1449 Thus, @code{(list string number)} matches lists of two elements,
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1450 the first being a string and the second being a number.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1451 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1452
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1453 @deffn Widget vector
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1454 The @code{vector} widget is like the @code{list} widget but matches
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1455 vectors instead of lists. Thus, @code{(vector string number)} matches
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1456 vectors of two elements, the first being a string and the second being
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1457 a number.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1458 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1459
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1460 The above suffice for specifying fixed size lists and vectors. To get
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1461 variable length lists and vectors, you can use a @code{choice},
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1462 @code{set}, or @code{repeat} widget together with the @code{:inline}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1463 keyword. If any component of a composite widget has the
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1464 @code{:inline} keyword set, its value must be a list which will then
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1465 be spliced into the composite. For example, to specify a list whose
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1466 first element must be a file name, and whose remaining elements should
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1467 either be the symbol @code{t} or two strings (file names), you can use
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1468 the following widget specification:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1469
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1470 @example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1471 (list file
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1472 (choice (const t)
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1473 (list :inline t
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1474 :value ("foo" "bar")
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1475 string string)))
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1476 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1477
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1478 The value of a widget of this type will either have the form
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1479 @code{(file t)} or @code{(file @var{string} @var{string})}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1480
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1481 This concept of @code{:inline} may be hard to understand. It was
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1482 certainly hard to implement, so instead of confusing you more by
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1483 trying to explain it here, I'll just suggest you meditate over it for
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1484 a while.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1485
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1486 @deffn Widget set
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1487 Specifies a type whose values are the lists whose elements all belong
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1488 to a given set. The order of elements of the list is not significant.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1489 Here's the syntax:
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1490
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1491 @example
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1492 @var{type} ::= (set [@var{keyword} @var{argument}]... @var{permitted-element} ... )
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1493 @end example
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1494
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1495 Use @code{const} to specify each permitted element, like this:
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1496 @code{(set (const a) (const b))}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1497 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1498
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1499 @deffn Widget repeat
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1500 Specifies a list of any number of elements that fit a certain type.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1501
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1502 @example
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1503 @var{type} ::= (repeat [@var{keyword} @var{argument}]... @var{type})
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1504 @end example
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1505 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1506
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1507 @node Widget Properties, Defining New Widgets, Sexp Types, Top
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1508 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1509 @chapter Properties
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1510 @cindex properties of widgets
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1511 @cindex widget properties
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1512
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1513 You can examine or set the value of a widget by using the widget object
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1514 that was returned by @code{widget-create}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1515
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1516 @defun widget-value widget
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1517 Return the current value contained in @var{widget}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1518 It is an error to call this function on an uninitialized widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1519 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1520
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1521 @defun widget-value-set widget value
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1522 Set the value contained in @var{widget} to @var{value}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1523 It is an error to call this function with an invalid @var{value}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1524 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1525
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1526 @strong{Important:} You @emph{must} call @code{widget-setup} after
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1527 modifying the value of a widget before the user is allowed to edit the
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1528 widget again. It is enough to call @code{widget-setup} once if you
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1529 modify multiple widgets. This is currently only necessary if the widget
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1530 contains an editing field, but may be necessary for other widgets in the
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1531 future.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1532
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1533 If your application needs to associate some information with the widget
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1534 objects, for example a reference to the item being edited, it can be
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1535 done with @code{widget-put} and @code{widget-get}. The property names
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1536 must begin with a @samp{:}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1537
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1538 @defun widget-put widget property value
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1539 In @var{widget} set @var{property} to @var{value}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1540 @var{property} should be a symbol, while @var{value} can be anything.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1541 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1542
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1543 @defun widget-get widget property
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1544 In @var{widget} return the value for @var{property}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1545 @var{property} should be a symbol, the value is what was last set by
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1546 @code{widget-put} for @var{property}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1547 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1548
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1549 @defun widget-member widget property
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1550 Non-@code{nil} if @var{widget} has a value (even @code{nil}) for
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1551 property @var{property}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1552 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1553
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1554 Occasionally it can be useful to know which kind of widget you have,
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1555 i.e.@: the name of the widget type you gave when the widget was created.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1556
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1557 @defun widget-type widget
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1558 Return the name of @var{widget}, a symbol.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1559 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1560
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1561 @cindex active widget
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1562 @cindex inactive widget
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1563 @cindex activate a widget
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1564 @cindex deactivate a widget
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1565 Widgets can be in two states: active, which means they are modifiable by
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1566 the user, or inactive, which means they cannot be modified by the user.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1567 You can query or set the state with the following code:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1568
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1569 @lisp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1570 ;; Examine if @var{widget} is active or not.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1571 (if (widget-apply @var{widget} :active)
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1572 (message "Widget is active.")
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1573 (message "Widget is inactive.")
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1574
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1575 ;; Make @var{widget} inactive.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1576 (widget-apply @var{widget} :deactivate)
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1577
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1578 ;; Make @var{widget} active.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1579 (widget-apply @var{widget} :activate)
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1580 @end lisp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1581
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1582 A widget is inactive if it, or any of its ancestors (found by
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1583 following the @code{:parent} link), have been deactivated. To make sure
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1584 a widget is really active, you must therefore activate both it and
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1585 all its ancestors.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1586
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1587 @lisp
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1588 (while widget
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1589 (widget-apply widget :activate)
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1590 (setq widget (widget-get widget :parent)))
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1591 @end lisp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1592
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1593 You can check if a widget has been made inactive by examining the value
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1594 of the @code{:inactive} keyword. If this is non-@code{nil}, the widget itself
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1595 has been deactivated. This is different from using the @code{:active}
9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1596 keyword, in that the latter tells you if the widget @strong{or} any of
9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1597 its ancestors have been deactivated. Do not attempt to set the
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1598 @code{:inactive} keyword directly. Use the @code{:activate}
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1599 @code{:deactivate} keywords instead.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1600
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1601
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1602 @node Defining New Widgets, Widget Browser, Widget Properties, Top
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1603 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1604 @chapter Defining New Widgets
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1605 @cindex new widgets
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1606 @cindex defining new widgets
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1607
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1608 You can define specialized widgets with @code{define-widget}. It allows
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1609 you to create a shorthand for more complex widgets, including specifying
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1610 component widgets and new default values for the keyword
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1611 arguments.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1612
1183 c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1613 @defun define-widget name class doc &rest args
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1614 Define a new widget type named @var{name} from @code{class}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1615
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1616 @var{name} and class should both be symbols, @code{class} should be one
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1617 of the existing widget types.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1618
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1619 The third argument @var{doc} is a documentation string for the widget.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1620
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1621 After the new widget has been defined, the following two calls will
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1622 create identical widgets:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1623
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1624 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1625 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1626 @lisp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1627 (widget-create @var{name})
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1628 @end lisp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1629
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1630 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1631 @lisp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1632 (apply widget-create @var{class} @var{args})
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1633 @end lisp
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1634 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1635
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1636 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1637
1183 c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1638 Using @code{define-widget} just stores the definition of the widget type
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1639 in the @code{widget-type} property of @var{name}, which is what
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1640 @code{widget-create} uses.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1641
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1642 If you only want to specify defaults for keywords with no complex
1339 ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1643 conversions, you can use @code{identity} as your @code{:convert-widget}
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1644 function.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1645
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1646 The following additional keyword arguments are useful when defining new
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1647 widgets:
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1648 @table @code
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1649 @vindex convert-widget@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1650 @item :convert-widget
1339 ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1651 Method to convert type-specific components of a widget type before
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1652 instantiating a widget of that type. Not normally called from user
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1653 code, it is invoked by @code{widget-convert}. Typical operations
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1654 include converting types of child widgets to widget instances and
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1655 converting values from external format (@emph{i.e.}, as expected by the
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1656 calling code) to internal format (which is often different for the
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1657 convenience of widget manipulation). It takes a widget type as an
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1658 argument, and returns the converted widget type. When a widget is
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1659 created, the value of this property is called for the widget type, then
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1660 for all the widget's parent types, most derived first. (The property is
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1661 reevaluated for each parent type.)
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1662
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1663 The following predefined functions can be used here:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1664
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1665 @defun widget-types-convert-widget widget
1339 ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1666 Convert each member of @code{:args} in @var{widget} from a widget type
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1667 to a widget.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1668 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1669
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1670 @defun widget-value-convert-widget widget
1339 ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1671 Initialize @code{:value} from @code{(car :args)} in @var{widget}, and
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1672 reset @code{:args}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1673 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1674
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1675 @vindex copy@r{ keyword}
1339 ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1676 @item :copy
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1677 Function to deep copy a widget type. It takes a shallow copy of the
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1678 widget type as an argument (made by @code{copy-sequence}), and returns a
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1679 deep copy. The purpose of this is to avoid having different instances
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1680 of combined widgets share nested attributes. Any member of the
1339 ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1681 widget which might be changed in place (rather than replaced) should be
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1682 copied by this method. (@code{widget-copy} uses @code{copy-sequence} to
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1683 ensure that the top-level list is a copy.) This particularly applies to
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1684 child widgets.
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1685
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1686 The following predefined functions can be used here:
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1687
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1688 @defun widget-types-copy widget
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1689 Copy @code{:args} as widget types in @var{widget}.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1690 @end defun
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1691
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1692 @vindex value-to-internal@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1693 @item :value-to-internal
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1694 Function to convert the value to the internal format. The function
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1695 takes two arguments, a widget and an external value. It returns the
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1696 internal value. The function is called on the present @code{:value}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1697 when the widget is created, and on any value set later with
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1698 @code{widget-value-set}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1699
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1700 @vindex value-to-external@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1701 @item :value-to-external
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1702 Function to convert the value to the external format. The function
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1703 takes two arguments, a widget and an internal value, and returns the
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1704 external value. The function is called on the present @code{:value}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1705 when the widget is created, and on any value set later with
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1706 @code{widget-value-set}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1707
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1708 @vindex create@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1709 @item :create
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1710 Function to create a widget from scratch. The function takes one
1339 ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1711 argument, a widget, and inserts it in the buffer. Not normally called
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1712 from user code. Instead, call @code{widget-create} or related
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1713 functions, which take a type argument, (usually) convert it to a widget,
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1714 call the @code{:create} function to insert it in the buffer, and then
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1715 return the (possibly converted) widget.
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1716
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1717 The default, @code{widget-default-create}, is invariably appropriate.
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1718 (None of the standard widgets specify @code{:create}.)
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1719
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1720 @vindex delete@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1721 @item :delete
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1722 Function to delete a widget. The function takes one argument, a widget,
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1723 and should remove all traces of the widget from the buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1724
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1725 The default value is:
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1726
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1727 @defun widget-default-delete widget
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1728 Remove @var{widget} from the buffer.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1729 Delete all @code{:children} and @code{:buttons} in @var{widget}.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1730 @end defun
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1731
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1732 In most cases you should not change this value, but instead use
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1733 @code{:value-delete} to make any additional cleanup.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1734
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1735 @vindex value-create@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1736 @item :value-create
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1737 Function to expand the @samp{%v} escape in the format string. It will
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1738 be called with the widget as its argument and should insert a
9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1739 representation of the widget's value in the buffer.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1740
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1741 Nested widgets should be listed in @code{:children} or @code{:buttons}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1742 to make sure they are automatically deleted.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1743
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1744 @vindex value-delete@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1745 @item :value-delete
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1746 Should remove the representation of the widget's value from the buffer.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1747 It will be called with the widget as its argument. It doesn't have to
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1748 remove the text, but it should release markers and delete nested widgets
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1749 if these are not listed in @code{:children} or @code{:buttons}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1750
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1751 @vindex value-get@r{ keyword}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1752 @item :value-get
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1753 Function to extract the value of a widget, as it is displayed in the
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1754 buffer.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1755
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1756 The following predefined function can be used here:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1757
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1758 @defun widget-value-value-get widget
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1759 Return the @code{:value} property of @var{widget}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1760 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1761
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1762 @vindex format-handler@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1763 @item :format-handler
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1764 Function to handle unknown @samp{%} escapes in the format string. It
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1765 will be called with the widget and the character that follows the
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1766 @samp{%} as arguments. You can set this to allow your widget to handle
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1767 non-standard escapes.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1768
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1769 @findex widget-default-format-handler
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1770 You should end up calling @code{widget-default-format-handler} to handle
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1771 unknown escape sequences. It will handle the @samp{%h} and any future
9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1772 escape sequences as well as give an error for unknown escapes.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1773
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1774 @vindex action@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1775 @item :action
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1776 Function to handle user initiated events. By default, @code{:notify}
652 2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent] stephent parents: 444 diff changeset	1777 the parent. Actions normally do not include mere edits, but refer to
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent] stephent parents: 444 diff changeset	1778 things like invoking buttons or hitting enter in an editable field. To
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent] stephent parents: 444 diff changeset	1779 watch for any change, redefine the @code{:notify} callback.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1780
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1781 The following predefined function can be used here:
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1782
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1783 @defun widget-parent-action widget &optional event
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1784 Tell @code{:parent} of @var{widget} to handle the @code{:action}.@*
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1785 Optional @var{event} is the event that triggered the action.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1786 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1787
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1788 @vindex prompt-value@r{ keyword}
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1789 @item :prompt-value
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1790 Function to prompt for a value in the minibuffer. The function should
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1791 take four arguments, @var{widget}, @var{prompt}, @var{value}, and
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1792 @var{unbound} and should return a value for widget entered by the user.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1793 @var{prompt} is the prompt to use. @var{value} is the default value to
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1794 use, unless @var{unbound} is non-@code{nil}, in which case there is no default
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1795 value. The function should read the value using the method most natural
434 9d177e8d4150 Import from CVS: tag r21-2-25 cvs parents: 428 diff changeset	1796 for this widget and does not have to check whether it matches.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1797 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1798
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1799 If you want to define a new widget from scratch, use the @code{default}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1800 widget as its base.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1801
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1802 @deffn Widget default
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1803 Widget used as a base for other widgets.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1804
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1805 It provides most of the functionality that is referred to as ``by
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1806 default'' in this text.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1807 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1808
1339 ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1809 In implementing complex hierarchical widgets (@emph{e.g.}, using the
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1810 @samp{group} widget), the following functions may be useful.
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1811 The syntax for the @var{type} arguments to these functions is described
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1812 in @ref{Basic Types}.
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1813
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1814 @defun widget-create-child-and-convert parent type &rest args
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1815 As a child of @var{parent}, create a widget with type @var{type} and
4312 1094d6d400fb Spelling fixes. "Ville Skyttä <scop@xemacs.org>" parents: 2028 diff changeset	1816 value @var{value}. @var{type} is copied, and the @code{:widget-convert}
1339 ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1817 method is applied to the optional keyword arguments from @var{args}.
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1818 @end defun
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1819
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1820 @defun widget-create-child parent type
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1821 As a child of @var{parent}, create a widget with type @var{type}.
1347 8d350b095c21 [xemacs-hg @ 2003-03-09 12:59:36 by ben] ben parents: 1339 diff changeset	1822 @var{type} is copied, but no conversion method is applied.
1339 ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1823 @end defun
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1824
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1825 @defun widget-create-child-value parent type value
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1826 As a child of @var{parent}, create a widget with type @var{type} and
1347 8d350b095c21 [xemacs-hg @ 2003-03-09 12:59:36 by ben] ben parents: 1339 diff changeset	1827 value @var{value}. @var{type} is copied, but no conversion method is
1339 ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1828 applied.
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1829 @end defun
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1830
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1831 @defun widget-convert type &rest args
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1832 Convert @var{type} to a widget without inserting it in the buffer.
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1833 The optional @var{args} are additional keyword arguments.
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1834
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1835 The widget's @code{:args} property is set from the longest tail of
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1836 @var{args} whose @samp{cdr} is not a keyword, or if that is null, from
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1837 the longest tail of @var{type}'s @code{:args} property whose cdr is not
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1838 a keyword. Keyword arguments from @var{args} are set, and the
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1839 @code{:value} property (if any) is converted from external to internal
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1840 format.
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1841 @end defun
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1842
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1843 @code{widget-convert} is typically not called from user code; rather it
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1844 is called implicitly through the @samp{widget-create*} functions.
ffa6c90799b1 [xemacs-hg @ 2003-03-03 15:00:11 by stephent] stephent parents: 1183 diff changeset	1845
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1846 @node Widget Browser, Widget Minor Mode, Defining New Widgets, Top
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1847 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1848 @chapter Widget Browser
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1849 @cindex widget browser
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1850
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1851 There is a separate package to browse widgets. This is intended to help
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1852 programmers who want to examine the content of a widget. The browser
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1853 shows the value of each keyword, but uses links for certain keywords
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1854 such as @samp{:parent}, which avoids printing cyclic structures.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1855
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1856 @deffn Command widget-browse @var{widget}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1857 Create a widget browser for @var{widget}.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1858 When called interactively, prompt for @var{widget}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1859 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1860
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1861 @deffn Command widget-browse-other-window @var{widget}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1862 Create a widget browser for @var{widget} and show it in another window.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1863 When called interactively, prompt for @var{widget}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1864 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1865
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1866 @deffn Command widget-browse-at @var{pos}
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1867 Create a widget browser for the widget at @var{pos}.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1868 When called interactively, use the position of point.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1869 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1870
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1871 @node Widget Minor Mode, Utilities, Widget Browser, Top
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1872 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1873 @chapter Widget Minor Mode
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1874 @cindex widget minor mode
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1875
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1876 There is a minor mode for manipulating widgets in major modes that
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1877 don't provide any support for widgets themselves. This is mostly
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1878 intended to be useful for programmers doing experiments.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1879
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1880 @deffn Command widget-minor-mode
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1881 Toggle minor mode for traversing widgets.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1882 With arg, turn widget mode on if and only if arg is positive.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1883 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1884
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1885 @defvar widget-minor-mode-keymap
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1886 Keymap used in @code{widget-minor-mode}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1887 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1888
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1889 @node Utilities, Widget Wishlist, Widget Minor Mode, Top
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1890 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1891 @chapter Utilities
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1892 @cindex utility functions for widgets
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1893
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1894 @defun widget-prompt-value widget prompt [ value unbound ]
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1895 Prompt for a value matching @var{widget}, using @var{prompt}.@*
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1896 The current value is assumed to be @var{value}, unless @var{unbound} is
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1897 non-@code{nil}.@refill
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1898 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1899
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1900 @defun widget-get-sibling widget
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1901 Get the item which @var{widget} is assumed to toggle.@*
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1902 This is only meaningful for radio buttons or checkboxes in a list.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1903 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1904
1183 c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1905 @node Widget Wishlist, Widget Internals, Utilities, Top
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1906 @comment node-name, next, previous, up
5741 d11efddf3617 Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches Jerry James <james@xemacs.org> parents: 5507 diff changeset	1907 @chapter Wishlist
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1908 @cindex todo
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1909
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1910 @itemize @bullet
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1911 @item
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1912 It should be possible to add or remove items from a list with @kbd{C-k}
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1913 and @kbd{C-o} (suggested by @sc{rms}).
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1914
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1915 @item
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1916 The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1917 dash (@samp{-}). The dash should be a button that, when invoked, asks
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1918 whether you want to add or delete an item (@sc{rms} wanted to git rid of
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1919 the ugly buttons, the dash is my idea).
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1920
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1921 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1922 The @code{menu-choice} tag should be prettier, something like the abbreviated
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1923 menus in Open Look.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1924
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1925 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1926 Finish @code{:tab-order}.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1927
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1928 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1929 Make indentation work with glyphs and proportional fonts.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1930
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1931 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1932 Add commands to show overview of object and class hierarchies to the
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1933 browser.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1934
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1935 @item
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1936 Find a way to disable mouse highlight for inactive widgets.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1937
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1938 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1939 Find a way to make glyphs look inactive.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1940
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1941 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1942 Add @code{property-list} widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1943
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1944 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1945 Add @code{association-list} widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1946
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1947 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1948 Add @code{key-binding} widget.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1949
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1950 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1951 Add @code{widget} widget for editing widget specifications.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1952
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1953 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1954 Find clean way to implement variable length list.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1955 See @code{TeX-printer-list} for an explanation.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1956
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1957 @item
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1958 @kbd{C-h} in @code{widget-prompt-value} should give type specific help.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1959
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1960 @item
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1961 Add a @code{mailto} widget.
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1962
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1963 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1964 @kbd{C-e e} in a fixed size field should go to the end of the text in
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1965 the field, not the end of the field itself.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1966
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1967 @item
1183 c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1968 Use an overlay instead of markers to delimit the widget. Create
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1969 accessors for the end points.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1970
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1971 @item
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1972 Clicking on documentation links should call @code{describe-function} or
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1973 @code{widget-browse-other-window} and friends directly, instead of going
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1974 through @code{apropos}. If more than one function is valid for the
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1975 symbol, it should pop up a menu.
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1976 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	1977
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	1978 @node Widget Internals, GNU Free Documentation License, Widget Wishlist, Top
1183 c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1979 @section Internals
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1980
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1981 This (very brief!) section provides a few notes on the internal
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1982 structure and implementation of Emacs widgets. Avoid relying on this
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1983 information. (We intend to improve it, but this will take some time.)
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1984 To the extent that it actually describes APIs, the information will be
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1985 moved to appropriate sections of the manual in due course.
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1986
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1987 @subsection The @dfn{Widget} and @dfn{Type} Structures
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1988
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1989 Widgets and types are currently both implemented as lists.
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1990
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1991 A symbol may be defined as a @dfn{type name} using @code{define-widget}.
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1992 @xref{Defining New Widgets}. A @dfn{type} is a list whose car is a
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1993 previously defined type name, nil, or (recursively) a type. The car is
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1994 the @dfn{class} or parent type of the type, and properties which are not
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1995 specified in the new type will be inherited from ancestors. Probably
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1996 the only type without a class should be the @code{default} type. The
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1997 cdr of a type is a plist whose keys are widget property keywords.
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1998
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	1999 A type or type name may also be referred to as an @dfn{unconverted
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	2000 widget}.
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	2001
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	2002 A @dfn{converted widget} or @dfn{widget instance} is a list whose car is
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	2003 a type name or a type, and whose cdr is a property list. Furthermore,
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	2004 all children of the converted widget must be converted. Finally, in the
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	2005 process of appropriate parts of the list structure are copied to ensure
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	2006 that changes in values of one instance do not affect another's.
c1553814932e [xemacs-hg @ 2003-01-03 12:12:30 by stephent] stephent parents: 904 diff changeset	2007
5507 64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	2008 @node GNU Free Documentation License, Index, Widget Internals, Top
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	2009 @appendix GNU Free Documentation License
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	2010 @include doclicense.texi
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	2011
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	2012 @node Index, , GNU Free Documentation License, Top
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	2013 @comment node-name, next, previous, up
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	2014 @unnumbered Index
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	2015
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	2016 This is an alphabetical listing of all concepts, functions, commands,
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	2017 variables, and widgets described in this manual.
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	2018 @printindex cp
64be8a494bdc Backed out changeset a7da359711ce, restoring Ben's GPLv3 manual changes. Aidan Kehoe <kehoea@parhasard.net> parents: 5496 diff changeset	2019
428 3ecd8885ac67 Import from CVS: tag r21-2-22 cvs parents: diff changeset	2020 @bye

Mercurial > hg > xemacs-beta

annotate man/widget.texi @ 5903:5afddd952c46