xemacs-beta: man/widget.texi annotate

annotate man/widget.texi @ 5727:86d33ddc7fd6

Avoid EOVERFLOW from stat() calls due to overflowing inode numbers. The btrfs filesystem now uses 64-bit inode numbers even on 32-bit systems. This can lead to spurious stat() failures, where EOVERFLOW is returned because the inode number does not fit into the 32-bit stat structure, even when the caller is not interested in the inode number. This patch builds with _FILE_OFFSET_BITS == 64 when possible, and deals with integers that may be too large to fit into a Lisp fixnum. For more information, see xemacs-patches message <CAHCOHQk_mPM6WgFChBsGafqhuazep6VED7swFoqfFXOV1r8org@mail.gmail.com>.

author	Jerry James <james@xemacs.org>
date	Wed, 06 Mar 2013 08:32:17 -0700
parents	64be8a494bdc
children	d11efddf3617

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

Mercurial > hg > xemacs-beta

annotate man/widget.texi @ 5727:86d33ddc7fd6