\input texinfo.tex
-
@c %**start of header
@setfilename ../../info/widget
@settitle The Emacs Widget Library
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
-@afourpaper
@c %**end of header
@copying
-Copyright @copyright{} 2000, 2001, 2002, 2003, 2004, 2005,
-2006, 2007, 2008 Free Software Foundation, Inc.
+Copyright @copyright{} 2000--2013 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
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
-@dircategory Emacs
+@dircategory Emacs lisp libraries
@direntry
-* Widget: (widget). The "widget" package used by the Emacs Customization
- facility.
+* Widget: (widget). The "widget" package used by the Emacs
+ Customization facility.
@end direntry
-@node Top, Introduction, (dir), (dir)
-@comment node-name, next, previous, up
+@contents
+
+@node Top
@top The Emacs Widget Library
+@insertcopying
+
@menu
* Introduction::
* User Interface::
* 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').
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
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
Face used for other editing fields.
@end deffn
-@subsection Buttons
+@section Buttons
@cindex widget buttons
@cindex button widgets
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:
@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
(remove-overlays)
(widget-insert "Here is some documentation.\n\n")
(widget-create 'editable-field
- :size 13
- :format "Name: %v " ; Text after the field!
- "My Name")
+ :size 13
+ :format "Name: %v " ; Text after the field!
+ "My Name")
(widget-create 'menu-choice
- :tag "Choose"
- :value "This"
- :help-echo "Choose me, please!"
- :notify (lambda (widget &rest ignore)
- (message "%s is a good choice!"
- (widget-value widget)))
- '(item :tag "This option" :value "This")
- '(choice-item "That option")
- '(editable-field :menu-tag "No option" "Thus option"))
+ :tag "Choose"
+ :value "This"
+ :help-echo "Choose me, please!"
+ :notify (lambda (widget &rest ignore)
+ (message "%s is a good choice!"
+ (widget-value widget)))
+ '(item :tag "This option" :value "This")
+ '(choice-item "That option")
+ '(editable-field :menu-tag "No option" "Thus option"))
(widget-create 'editable-field
- :format "Address: %v"
- "Some Place\nIn some City\nSome country.")
+ :format "Address: %v"
+ "Some Place\nIn some City\nSome country.")
(widget-insert "\nSee also ")
(widget-create 'link
- :notify (lambda (&rest ignore)
- (widget-value-set widget-example-repeat
- '("En" "To" "Tre"))
- (widget-setup))
- "other work")
+ :notify (lambda (&rest ignore)
+ (widget-value-set widget-example-repeat
+ '("En" "To" "Tre"))
+ (widget-setup))
+ "other work")
(widget-insert
" for more information.\n\nNumbers: count to three below\n")
(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))))
- :value '("One" "Eh, two?" "Five!")
- '(editable-field :value "three")))
+ (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))))
+ :value '("One" "Eh, two?" "Five!")
+ '(editable-field :value "three")))
(widget-insert "\n\nSelect multiple:\n\n")
(widget-create 'checkbox t)
(widget-insert " This\n")
(widget-create 'checkbox nil)
(widget-insert " That\n")
(widget-create 'checkbox
- :notify (lambda (&rest ignore) (message "Tickle"))
- t)
+ :notify (lambda (&rest ignore) (message "Tickle"))
+ t)
(widget-insert " Thus\n\nSelect one:\n\n")
(widget-create 'radio-button-choice
- :value "One"
- :notify (lambda (widget &rest ignore)
- (message "You selected %s"
- (widget-value widget)))
- '(item "One") '(item "Another One.") '(item "A Final One."))
+ :value "One"
+ :notify (lambda (widget &rest ignore)
+ (message "You selected %s"
+ (widget-value widget)))
+ '(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))
- 3)
- (message "Congratulation!")
- (error "Three was the count!")))
- "Apply Form")
+ :notify (lambda (&rest ignore)
+ (if (= (length
+ (widget-value widget-example-repeat))
+ 3)
+ (message "Congratulation!")
+ (error "Three was the count!")))
+ "Apply Form")
(widget-insert " ")
(widget-create 'push-button
- :notify (lambda (&rest ignore)
- (widget-example))
- "Reset Form")
+ :notify (lambda (&rest ignore)
+ (widget-example))
+ "Reset Form")
(widget-insert "\n")
(use-local-map widget-keymap)
(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
@findex widget-button-press
@findex widget-button-click
@defvr Const widget-keymap
-A keymap with the global keymap as its parent.@*
@key{TAB} and @kbd{C-@key{TAB}} are bound to @code{widget-forward} and
@code{widget-backward}, respectively. @key{RET} and @kbd{Mouse-2}
are bound to @code{widget-button-press} and
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:
@vindex follow-link@r{ keyword}
@item :follow-link
Specifies how to interpret a @key{mouse-1} click on the widget.
-@xref{Links and Mouse-1,,, elisp, the Emacs Lisp Reference Manual}.
+@xref{Clickable Text,, Defining Clickable Text, elisp, the Emacs Lisp Reference Manual}.
@vindex indent@r{ keyword}
@item :indent
@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}
* 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:
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:
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:
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:
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:
@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.
@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
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:
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:
@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
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:
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:
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:
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
@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:
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
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:
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.
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
* 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
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
@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.
@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:
@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
@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.
@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
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
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
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 ]
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
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,
variables, and widgets described in this manual.
@printindex cp
-@setchapternewpage odd
-@contents
@bye
-
-@ignore
- arch-tag: 2b427731-4c61-4e72-85de-5ccec9c623f0
-@end ignore