X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/acaf905b1130aae80fa59d2c861ffd4c8eb75486..0877d0dc24ee792b9b14592869ea1aa0934aee58:/doc/misc/widget.texi diff --git a/doc/misc/widget.texi b/doc/misc/widget.texi index 24fe3e63ac..f2c403a2c1 100644 --- a/doc/misc/widget.texi +++ b/doc/misc/widget.texi @@ -8,7 +8,7 @@ @c %**end of header @copying -Copyright @copyright{} 2000-2012 Free Software Foundation, Inc. +Copyright @copyright{} 2000--2013 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -19,8 +19,7 @@ and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled ``GNU Free Documentation License''. (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' +modify this GNU manual.'' @end quotation @end copying @@ -32,8 +31,7 @@ developing GNU and promoting software freedom.'' @contents -@node Top, Introduction, (dir), (dir) -@comment node-name, next, previous, up +@node Top @top The Emacs Widget Library @insertcopying @@ -55,9 +53,8 @@ developing GNU and promoting software freedom.'' * Index:: @end menu -@node Introduction, User Interface, Top, Top -@comment node-name, next, previous, up -@section Introduction +@node Introduction +@chapter Introduction Most graphical user interface toolkits provide a number of standard user interface controls (sometimes known as `widgets' or `gadgets'). @@ -136,9 +133,8 @@ extended to use the GUI features. This means that your code using the widget library will also use the new graphic features automatically. @end enumerate -@node User Interface, Programming Example, Introduction, Top -@comment node-name, next, previous, up -@section User Interface +@node User Interface +@chapter User Interface A form consists of read only text for documentation and some fields, where each field contains two parts, a tag and a value. The tags are @@ -184,7 +180,7 @@ The top level widgets in this example are tagged @samp{Name}, within a form, namely editing the editable text fields and activating the buttons. -@subsection Editable Text Fields +@section Editable Text Fields In the example, the value for the @samp{Name} is most likely displayed in an editable text field, and so are values for each of the members of @@ -221,7 +217,7 @@ The editing text fields are highlighted with the Face used for other editing fields. @end deffn -@subsection Buttons +@section Buttons @cindex widget buttons @cindex button widgets @@ -292,7 +288,7 @@ Face used for highlighting a button when the mouse pointer moves across it. @end defopt -@subsection Navigation +@section Navigation You can use all the normal Emacs commands to move around in a form buffer, plus you will have these additional commands: @@ -309,9 +305,8 @@ Move point @var{count} buttons or editing fields backward. @end deffn @end table -@node Programming Example, Setting Up the Buffer, User Interface, Top -@comment node-name, next, previous, up -@section Programming Example +@node Programming Example +@chapter Programming Example @cindex widgets, programming example @cindex example of using widgets @@ -365,13 +360,14 @@ Interface}). (setq widget-example-repeat (widget-create 'editable-list :entry-format "%i %d %v" - :notify (lambda (widget &rest ignore) - (let ((old (widget-get widget - ':example-length)) - (new (length (widget-value widget)))) - (unless (eq old new) - (widget-put widget ':example-length new) - (message "You can count to %d." new)))) + :notify + (lambda (widget &rest ignore) + (let ((old (widget-get widget + ':example-length)) + (new (length (widget-value widget)))) + (unless (eq old new) + (widget-put widget ':example-length new) + (message "You can count to %d." new)))) :value '("One" "Eh, two?" "Five!") '(editable-field :value "three"))) (widget-insert "\n\nSelect multiple:\n\n") @@ -388,11 +384,13 @@ Interface}). :notify (lambda (widget &rest ignore) (message "You selected %s" (widget-value widget))) - '(item "One") '(item "Another One.") '(item "A Final One.")) + '(item "One") '(item "Another One.") + '(item "A Final One.")) (widget-insert "\n") (widget-create 'push-button :notify (lambda (&rest ignore) - (if (= (length (widget-value widget-example-repeat)) + (if (= (length + (widget-value widget-example-repeat)) 3) (message "Congratulation!") (error "Three was the count!"))) @@ -407,9 +405,8 @@ Interface}). (widget-setup)) @end lisp -@node Setting Up the Buffer, Basic Types, Programming Example, Top -@comment node-name, next, previous, up -@section Setting Up the Buffer +@node Setting Up the Buffer +@chapter Setting Up the Buffer Widgets are created with @code{widget-create}, which returns a @dfn{widget} object. This object can be queried and manipulated by @@ -461,9 +458,8 @@ Keymap used by @code{widget-button-press} and @code{widget-button-click} when not on a button. By default this is @code{global-map}. @end defvar -@node Basic Types, Sexp Types, Setting Up the Buffer, Top -@comment node-name, next, previous, up -@section Basic Types +@node Basic Types +@chapter Basic Types This is the general syntax of a type specification: @@ -663,7 +659,7 @@ in the buffer with a positive tabbing order, or @code{nil} @vindex parent@r{ keyword} @item :parent -The parent of a nested widget (e.g.@: a @code{menu-choice} item or an +The parent of a nested widget (e.g., a @code{menu-choice} item or an element of a @code{editable-list} widget). @vindex sibling-args@r{ keyword} @@ -704,9 +700,8 @@ If non-@code{nil}, allow glyphs to appear on displays where they are supported. * group:: @end menu -@node link, url-link, Basic Types, Basic Types -@comment node-name, next, previous, up -@subsection The @code{link} Widget +@node link +@section The @code{link} Widget @findex link@r{ widget} Syntax: @@ -729,9 +724,8 @@ String to prefix links. String to suffix links. @end defopt -@node url-link, info-link, link, Basic Types -@comment node-name, next, previous, up -@subsection The @code{url-link} Widget +@node url-link +@section The @code{url-link} Widget @findex url-link@r{ widget} Syntax: @@ -744,9 +738,8 @@ Syntax: When this link is invoked, the @acronym{WWW} browser specified by @code{browse-url-browser-function} will be called with @var{url}. -@node info-link, push-button, url-link, Basic Types -@comment node-name, next, previous, up -@subsection The @code{info-link} Widget +@node info-link +@section The @code{info-link} Widget @findex info-link@r{ widget} Syntax: @@ -758,9 +751,8 @@ Syntax: When this link is invoked, the built-in Info reader is started on @var{address}. -@node push-button, editable-field, info-link, Basic Types -@comment node-name, next, previous, up -@subsection The @code{push-button} Widget +@node push-button +@section The @code{push-button} Widget @findex push-button@r{ widget} Syntax: @@ -783,9 +775,8 @@ String to prefix push buttons. String to suffix push buttons. @end defopt -@node editable-field, text, push-button, Basic Types -@comment node-name, next, previous, up -@subsection The @code{editable-field} Widget +@node editable-field +@section The @code{editable-field} Widget @findex editable-field@r{ widget} Syntax: @@ -813,7 +804,7 @@ Face used for highlighting the editable field. Default is @vindex secret@r{ keyword} @item :secret -Character used to display the value. You can set this to e.g.@: @code{?*} +Character used to display the value. You can set this to, e.g., @code{?*} if the field contains a password or other secret information. By default, this is @code{nil}, and the value is not secret. @@ -833,9 +824,8 @@ them. Pressing @key{RET} invokes the function specified by @code{:action}. @end table -@node text, menu-choice, editable-field, Basic Types -@comment node-name, next, previous, up -@subsection The @code{text} Widget +@node text +@section The @code{text} Widget @findex text@r{ widget} @vindex widget-text-keymap @@ -843,9 +833,8 @@ This is just like @code{editable-field}, but intended for multiline text fields. The default @code{:keymap} is @code{widget-text-keymap}, which does not rebind the @key{RET} key. -@node menu-choice, radio-button-choice, text, Basic Types -@comment node-name, next, previous, up -@subsection The @code{menu-choice} Widget +@node menu-choice +@section The @code{menu-choice} Widget @findex menu-choice@r{ widget} Syntax: @@ -884,9 +873,8 @@ The current chosen type. The list of types. @end table -@node radio-button-choice, item, menu-choice, Basic Types -@comment node-name, next, previous, up -@subsection The @code{radio-button-choice} Widget +@node radio-button-choice +@section The @code{radio-button-choice} Widget @findex radio-button-choice@r{ widget} Syntax: @@ -918,8 +906,8 @@ Insert a literal @samp{%}. @vindex button-args@r{ keyword} @item :button-args -A list of keywords to pass to the radio buttons. Useful for setting -e.g.@: the @samp{:help-echo} for each button. +A list of keywords to pass to the radio buttons. Useful for setting, +e.g., the @samp{:help-echo} for each button. @vindex buttons@r{ keyword} @item :buttons @@ -951,9 +939,8 @@ Please note that such items added after the @code{radio-button-choice} widget has been created will @strong{not} be properly destructed when you call @code{widget-delete}. -@node item, choice-item, radio-button-choice, Basic Types -@comment node-name, next, previous, up -@subsection The @code{item} Widget +@node item +@section The @code{item} Widget @findex item@r{ widget} Syntax: @@ -966,9 +953,8 @@ The @var{value}, if present, is used to initialize the @code{:value} property. The value should be a string, which will be inserted in the buffer. This widget will only match the specified value. -@node choice-item, toggle, item, Basic Types -@comment node-name, next, previous, up -@subsection The @code{choice-item} Widget +@node choice-item +@section The @code{choice-item} Widget @findex choice-item@r{ widget} Syntax: @@ -983,9 +969,8 @@ buffer as a button. Activating the button of a @code{choice-item} is equivalent to activating the parent widget. This widget will only match the specified value. -@node toggle, checkbox, choice-item, Basic Types -@comment node-name, next, previous, up -@subsection The @code{toggle} Widget +@node toggle +@section The @code{toggle} Widget @findex toggle@r{ widget} Syntax: @@ -1016,9 +1001,8 @@ Name of a glyph to be used instead of the @samp{:off} text string, on emacsen that supports this. @end table -@node checkbox, checklist, toggle, Basic Types -@comment node-name, next, previous, up -@subsection The @code{checkbox} Widget +@node checkbox +@section The @code{checkbox} Widget @findex checkbox@r{ widget} This widget has two possible states, @samp{selected} and @@ -1030,9 +1014,8 @@ Syntax: @var{type} ::= (checkbox [@var{keyword} @var{argument}]...) @end example -@node checklist, editable-list, checkbox, Basic Types -@comment node-name, next, previous, up -@subsection The @code{checklist} Widget +@node checklist +@section The @code{checklist} Widget @findex checklist@r{ widget} Syntax: @@ -1068,12 +1051,12 @@ Usually a checklist will only match if the items are in the exact sequence given in the specification. By setting @code{:greedy} to non-@code{nil}, it will allow the items to come in any sequence. However, if you extract the value they will be in the sequence given -in the checklist, i.e.@: the original sequence is forgotten. +in the checklist, i.e., the original sequence is forgotten. @vindex button-args@r{ keyword} @item :button-args -A list of keywords to pass to the checkboxes. Useful for setting -e.g.@: the @samp{:help-echo} for each checkbox. +A list of keywords to pass to the checkboxes. Useful for setting, +e.g., the @samp{:help-echo} for each checkbox. @vindex buttons@r{ keyword} @item :buttons @@ -1088,9 +1071,8 @@ The widgets representing each type. The list of types. @end table -@node editable-list, group, checklist, Basic Types -@comment node-name, next, previous, up -@subsection The @code{editable-list} Widget +@node editable-list +@section The @code{editable-list} Widget @findex editable-list@r{ widget} Syntax: @@ -1146,9 +1128,8 @@ The widgets representing the elements of the list. List whose @sc{car} is the type of the list elements. @end table -@node group, , editable-list, Basic Types -@comment node-name, next, previous, up -@subsection The @code{group} Widget +@node group +@section The @code{group} Widget @findex group@r{ widget} This widget simply group other widgets together. @@ -1161,9 +1142,8 @@ Syntax: The value is a list, with one member for each @var{type}. -@node Sexp Types, Widget Properties, Basic Types, Top -@comment -@section Sexp Types +@node Sexp Types +@chapter Sexp Types @cindex sexp types A number of widgets for editing @dfn{s-expressions} (Lisp types), sexp @@ -1177,9 +1157,8 @@ categories described in this section. * composite:: @end menu -@node constants, generic, Sexp Types, Sexp Types -@comment node-name, next, previous, up -@subsection The Constant Widgets +@node constants +@section The Constant Widgets @cindex constant widgets The @code{const} widget can contain any Lisp expression, but the user is @@ -1214,9 +1193,8 @@ An immutable symbol that is bound as a variable. An immutable symbol that is bound as a function. @end deffn -@node generic, atoms, constants, Sexp Types -@comment node-name, next, previous, up -@subsection Generic Sexp Widget +@node generic +@section Generic Sexp Widget @cindex generic sexp widget The @code{sexp} widget can contain any Lisp expression, and allows the @@ -1236,9 +1214,8 @@ The @code{sexp} widget takes the same keyword arguments as the @code{editable-field} widget. @xref{editable-field}. @end deffn -@node atoms, composite, generic, Sexp Types -@comment node-name, next, previous, up -@subsection Atomic Sexp Widgets +@node atoms +@section Atomic Sexp Widgets @cindex atomic sexp widget The atoms are s-expressions that do not consist of other s-expressions. @@ -1314,9 +1291,8 @@ either @code{nil} meaning false, or non-@code{nil} meaning true. @end deffn -@node composite, , atoms, Sexp Types -@comment node-name, next, previous, up -@subsection Composite Sexp Widgets +@node composite +@section Composite Sexp Widgets @cindex composite sexp widgets The syntax for the composite widget construct is: @@ -1416,9 +1392,8 @@ Specifies a list of any number of elements that fit a certain type. @end example @end deffn -@node Widget Properties, Defining New Widgets, Sexp Types, Top -@comment node-name, next, previous, up -@section Properties +@node Widget Properties +@chapter Properties @cindex properties of widgets @cindex widget properties @@ -1464,7 +1439,7 @@ property @var{property}. @end defun Occasionally it can be useful to know which kind of widget you have, -i.e.@: the name of the widget type you gave when the widget was created. +i.e., the name of the widget type you gave when the widget was created. @defun widget-type widget Return the name of @var{widget}, a symbol. @@ -1511,9 +1486,8 @@ its ancestors have been deactivated. Do not attempt to set the @code{:deactivate} keywords instead. -@node Defining New Widgets, Widget Browser, Widget Properties, Top -@comment node-name, next, previous, up -@section Defining New Widgets +@node Defining New Widgets +@chapter Defining New Widgets @cindex new widgets @cindex defining new widgets @@ -1696,9 +1670,8 @@ It provides most of the functionality that is referred to as ``by default'' in this text. @end deffn -@node Widget Browser, Widget Minor Mode, Defining New Widgets, Top -@comment node-name, next, previous, up -@section Widget Browser +@node Widget Browser +@chapter Widget Browser @cindex widget browser There is a separate package to browse widgets. This is intended to help @@ -1721,9 +1694,8 @@ Create a widget browser for the widget at @var{pos}. When called interactively, use the position of point. @end deffn -@node Widget Minor Mode, Utilities, Widget Browser, Top -@comment node-name, next, previous, up -@section Widget Minor Mode +@node Widget Minor Mode +@chapter Widget Minor Mode @cindex widget minor mode There is a minor mode for manipulating widgets in major modes that @@ -1739,9 +1711,8 @@ With arg, turn widget mode on if and only if arg is positive. Keymap used in @code{widget-minor-mode}. @end defvar -@node Utilities, Widget Wishlist, Widget Minor Mode, Top -@comment node-name, next, previous, up -@section Utilities. +@node Utilities +@chapter Utilities @cindex utility functions for widgets @defun widget-prompt-value widget prompt [ value unbound ] @@ -1755,9 +1726,8 @@ Get the item which @var{widget} is assumed to toggle. This is only meaningful for radio buttons or checkboxes in a list. @end defun -@node Widget Wishlist, GNU Free Documentation License, Utilities, Top -@comment node-name, next, previous, up -@section Wishlist +@node Widget Wishlist +@chapter Wishlist @cindex todo @itemize @bullet @@ -1814,12 +1784,11 @@ See @code{TeX-printer-list} for an explanation. Add a @code{mailto} widget. @end itemize -@node GNU Free Documentation License, Index, Widget Wishlist, Top +@node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi -@node Index, , GNU Free Documentation License, Top -@comment node-name, next, previous, up +@node Index @unnumbered Index This is an alphabetical listing of all concepts, functions, commands,