@end iftex
@c %**end of header
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex ky cp
+
@dircategory Emacs
@direntry
* Widget: (widget). Documenting the "widget" package used by the
* Widget Minor Mode::
* Utilities::
* Widget Wishlist::
+* Index::
@end menu
@node Introduction, User Interface, Top, Top
Most graphical user interface toolkits, such as Motif and XView, provide
a number of standard user interface controls (sometimes known as
`widgets' or `gadgets'). Emacs doesn't really support anything like
-this, except for an incredible powerful text ``widget''. On the other
+this, except for an incredibly powerful text ``widget''. On the other
hand, Emacs does provide the necessary primitives to implement many
other widgets within a text buffer. The @code{widget} package
simplifies this task.
+@cindex basic widgets
+@cindex widgets, basic types
The basic widgets are:
@table @code
A simple constant widget intended to be used in the @code{menu-choice} and
@code{radio-button-choice} widgets.
@item choice-item
-An button item only intended for use in choices. When invoked, the user
+A button item only intended for use in choices. When invoked, the user
will be asked to select another option from the choice widget.
@item toggle
A simple @samp{on}/@samp{off} switch.
list. Each list item is itself a widget.
@end table
-Now of what possible use can support for widgets be in a text editor?
+Now, of what possible use can support for widgets be in a text editor?
I'm glad you asked. The answer is that widgets are useful for
implementing forms. A @dfn{form} in Emacs is a buffer where the user is
supposed to fill out a number of fields, each of which has a specific
package (of course), the customize buffers, the mail and news compose
modes, and the @sc{html} form support in the @file{w3} browser.
+@cindex widget library, why use it
The advantages for a programmer of using the @code{widget} package to
implement forms are:
@enumerate
@item
-More complex field than just editable text are supported.
+More complex fields than just editable text are supported.
@item
-You can give the user immediate feedback if he enters invalid data in a
+You can give the users immediate feedback if they enter invalid data in a
text field, and sometimes prevent entering invalid data.
@item
-You can have fixed sized fields, thus allowing multiple field to be
+You can have fixed sized fields, thus allowing multiple fields to be
lined up in columns.
@item
It is simple to query or set the value of a field.
@item
-Editing happens in buffer, not in the mini-buffer.
+Editing happens in the buffer, not in the mini-buffer.
@item
Packages using the library get a uniform look, making them easier for
the user to learn.
@item
-As support for embedded graphics improve, the widget library will
-extended to support it. This means that your code using the widget
-library will also use the new graphic features by automatic.
+As support for embedded graphics improve, the widget library will be
+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
In order to minimize the code that is loaded by users who does not
create any widgets, the code has been split in two files:
+@cindex widget library, files
@table @file
@item widget.el
This will declare the user variables, define the function
@section User Interface
A form consist of read only text for documentation and some fields,
-where each the fields contain two parts, as tag and a value. The tags
-are used to identify the fields, so the documentation can refer to the
-foo field, meaning the field tagged with @samp{Foo}. Here is an example
-form:
+where each field contains two parts, a tag and a value. The tags are
+used to identify the fields, so the documentation can refer to the
+@samp{foo field}, meaning the field tagged with @samp{Foo}. Here is an
+example form:
@example
Here is some documentation.
The top level widgets in is example are tagged @samp{Name},
@samp{Choose}, @samp{Address}, @samp{_other work_}, @samp{Numbers},
@samp{Select multiple}, @samp{Select one}, @samp{[Apply Form]}, and
-@samp{[Reset Form]}. There are basically two thing the user can do within
-a form, namely editing the editable text fields and activating the
-buttons.
+@samp{[Reset Form]}. There are basically two things the user can do
+within a form, namely editing the editable text fields and activating
+the buttons.
@subsection Editable Text Fields
@subsection Buttons
+@cindex widget buttons
+@cindex button widgets
Some portions of the buffer have an associated @dfn{action}, which can
be @dfn{invoked} by a standard key or mouse command. These portions
are called @dfn{buttons}. The default commands for activating a button
@code{widget-global-map} (by default the global map).
@end deffn
+@kindex mouse-2, on button widgets
@item mouse-2
@deffn Command widget-button-click @var{event}
Invoke the button at the location of the mouse pointer. If the mouse
the example:
@table @emph
-@item The Option Field Tags.
+@cindex option field tag
+@item The Option Field Tags
When you invoke one of these buttons, you will be asked to choose
between a number of different options. This is how you edit an option
field. Option fields are created by the @code{menu-choice} widget. In
the example, @samp{@b{Choose}} is an option field tag.
-@item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons.
-Activating these will insert or delete elements from a editable list.
+@item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons
+Activating these will insert or delete elements from an editable list.
The list is created by the @code{editable-list} widget.
-@item Embedded Buttons.
+@cindex embedded buttons
+@item Embedded Buttons
The @samp{@b{_other work_}} is an example of an embedded
-button. Embedded buttons are not associated with a fields, but can serve
+button. Embedded buttons are not associated with a fields, but can serve
any purpose, such as implementing hypertext references. They are
usually created by the @code{link} widget.
-@item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons.
+@item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons
Activating one of these will convert it to the other. This is useful
-for implementing multiple-choice fields. You can create it wit
-@item The @samp{@b{( )}} and @samp{@b{(*)}} buttons.
+for implementing multiple-choice fields. You can create it with the
+@code{checkbox} widget.
+@item The @samp{@b{( )}} and @samp{@b{(*)}} buttons
Only one radio button in a @code{radio-button-choice} widget can be
selected at any time. When you invoke one of the unselected radio
buttons, it will be selected and the previous selected radio button will
become unselected.
-@item The @samp{@b{[Apply Form]}} @samp{@b{[Reset Form]}} buttons.
-These are explicit buttons made with the @code{push-button} widget. The main
-difference from the @code{link} widget is that the buttons are will be
+@item The @samp{@b{[Apply Form]}} @samp{@b{[Reset Form]}} buttons
+These are explicit buttons made with the @code{push-button} widget. The
+main difference from the @code{link} widget is that the buttons will be
displayed as GUI buttons when possible.
-enough.
@end table
To make them easier to locate, buttons are emphasized in the buffer.
@end deffn
@defopt widget-mouse-face
-Face used for buttons when the mouse pointer is above it.
+Face used for highlighting a button when the mouse pointer moves across
+it.
@end defopt
@subsection Navigation
@comment node-name, next, previous, up
@section Programming Example
+@cindex widgets, programming example
+@cindex example of using widgets
Here is the code to implement the user interface example (@pxref{User
Interface}).
@end defun
@defun widget-setup
-Setup a buffer to support widgets.
+Set up a buffer to support widgets.
This should be called after creating all the widgets and before allowing
the user to edit them.
@defun widget-insert
Insert the arguments, either strings or characters, at point.
-The inserted text will be read only.
+The inserted text will be read-only.
@end defun
There is a standard widget keymap which you might find useful.
+@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. @kbd{@key{RET}} and @kbd{mouse-2}
are bound to @code{widget-button-press} and
-@code{widget-button-}.@refill
+@code{widget-button-click}.@refill
@end defvr
@defvar widget-global-map
property, @var{argument} is the value of the property, and @var{args}
are interpreted in a widget specific way.
-There following keyword arguments that apply to all widgets:
+@cindex keyword arguments
+The following keyword arguments that apply to all widgets:
@table @code
+@vindex value@r{ keyword}
@item :value
The initial value for widgets of this type.
+@vindex format@r{ keyword}
@item :format
This string will be inserted in the buffer when you create a widget.
The following @samp{%} escapes are available:
Insert a literal @samp{%}.
@end table
+@vindex button-face@r{ keyword}
@item :button-face
Face used to highlight text inside %[ %] in the format.
+@vindex button-prefix@r{ keyword}
+@vindex button-suffix@r{ keyword}
@item :button-prefix
@itemx :button-suffix
-
Text around %[ %] in the format.
These can be
The value of the symbol is expanded according to this table.
@end table
+@vindex doc@r{ keyword}
@item :doc
The string inserted by the @samp{%d} escape in the format
string.
+@vindex tag@r{ keyword}
@item :tag
The string inserted by the @samp{%t} escape in the format
string.
+@vindex tag-glyph@r{ keyword}
@item :tag-glyph
-Name of image to use instead of the string specified by `:tag' on
+Name of image to use instead of the string specified by @code{:tag} on
Emacsen that supports it.
+@vindex help-echo@r{ keyword}
@item :help-echo
Message displayed whenever you move to the widget with either
@code{widget-forward} or @code{widget-backward}.
+@vindex indent@r{ keyword}
@item :indent
An integer indicating the absolute number of spaces to indent children
of this widget.
+@vindex offset@r{ keyword}
@item :offset
An integer indicating how many extra spaces to add to the widget's
grandchildren compared to this widget.
+@vindex extra-offset@r{ keyword}
@item :extra-offset
An integer indicating how many extra spaces to add to the widget's
children compared to this widget.
+@vindex notify@r{ keyword}
@item :notify
A function called each time the widget or a nested widget is changed.
The function is called with two or three arguments. The first argument
changed, and the third argument is the event leading to the change, if
any.
+@vindex menu-tag@r{ keyword}
@item :menu-tag
Tag used in the menu when the widget is used as an option in a
@code{menu-choice} widget.
+@vindex menu-tag-get@r{ keyword}
@item :menu-tag-get
Function used for finding the tag when the widget is used as an option
in a @code{menu-choice} widget. By default, the tag used will be either the
@code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
representation of the @code{:value} property if not.
+@vindex match@r{ keyword}
@item :match
Should be a function called with two arguments, the widget and a value,
and returning non-nil if the widget can represent the specified value.
+@vindex validate@r{ keyword}
@item :validate
-A function which takes a widget as an argument, and return nil if the
-widget's current value is valid for the widget. Otherwise it should
-return the widget containing the invalid data, and set that widget's
-@code{:error} property to a string explaining the error.
+A function which takes a widget as an argument, and returns @code{nil}
+if the widget's current value is valid for the widget. Otherwise it
+should return the widget containing the invalid data, and set that
+widget's @code{:error} property to a string explaining the error.
The following predefined function can be used:
All the @code{:children} of @var{widget} must be valid.
@end defun
+@vindex tab-order@r{ keyword}
@item :tab-order
Specify the order in which widgets are traversed with
@code{widget-forward} or @code{widget-backward}. This is only partially
in the buffer with a positive tabbing order, or @code{nil}
@end enumerate
+@vindex parent@r{ keyword}
@item :parent
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}
@item :sibling-args
This keyword is only used for members of a @code{radio-button-choice} or
@code{checklist}. The value should be a list of extra keyword
@deffn {User Option} widget-glyph-directory
Directory where glyphs are found.
Widget will look here for a file with the same name as specified for the
-image, with either a @samp{.xpm} (if supported) or @samp{.xbm} extension.
+image, with either a @file{.xpm} (if supported) or @file{.xbm} extension.
@end deffn
@deffn{User Option} widget-glyph-enable
@node link, url-link, Basic Types, Basic Types
@comment node-name, next, previous, up
@subsection The @code{link} Widget
+@findex link@r{ widget}
Syntax:
@node url-link, info-link, link, Basic Types
@comment node-name, next, previous, up
@subsection The @code{url-link} Widget
+@findex url-link@r{ widget}
Syntax:
TYPE ::= (url-link [KEYWORD ARGUMENT]... URL)
@end example
+@findex browse-url-browser-function@r{, and @code{url-link} widget}
When this link is invoked, the @sc{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
+@findex info-link@r{ widget}
Syntax:
TYPE ::= (info-link [KEYWORD ARGUMENT]... ADDRESS)
@end example
-When this link is invoked, the built-in info browser is started on
+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
+@findex push-button@r{ widget}
Syntax:
@end example
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
+property. The value should be a string, which will be inserted in the
buffer.
By default the tag will be shown in brackets.
@node editable-field, text, push-button, Basic Types
@comment node-name, next, previous, up
@subsection The @code{editable-field} Widget
+@findex editable-field@r{ widget}
Syntax:
property. The value should be a string, which will be inserted in
field. This widget will match all string values.
-The following extra properties are recognized.
+The following extra properties are recognized:
@table @code
+@vindex size@r{ keyword}
@item :size
The width of the editable field.@*
By default the field will reach to the end of the line.
+@vindex value-face@r{ keyword}
@item :value-face
Face used for highlighting the editable field. Default is
-@code{widget-field-face}.
+@code{widget-field-face}, see @ref{User Interface}.
+@vindex secret@r{ keyword}
@item :secret
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, the value is not secret.
+default, this is nil, and the value is not secret.
+@vindex valid-regexp@r{ keyword}
@item :valid-regexp
By default the @code{:validate} function will match the content of the
field with the value of this attribute. The default value is @code{""}
which matches everything.
+@vindex keymap@r{ keyword}
+@vindex widget-field-keymap
@item :keymap
Keymap used in the editable field. The default value is
@code{widget-field-keymap}, which allows you to use all the normal
-editing commands, even if the buffers major mode suppress some of them.
-Pressing return invokes the function specified by @code{:action}.
+editing commands, even if the buffer's major mode suppresses some of
+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
+@findex text@r{ widget}
+@vindex widget-text-keymap
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 return key.
+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
+@findex menu-choice@r{ widget}
Syntax:
arguments.
@table @code
+@vindex void@r{ keyword}
@item :void
Widget type used as a fallback when the value does not match any of the
specified @var{type} arguments.
+@vindex case-fold@r{ keyword}
@item :case-fold
Set this to nil if you don't want to ignore case when prompting for a
choice through the minibuffer.
+@vindex children@r{ keyword}
@item :children
-A list whose car is the widget representing the currently chosen type in
-the buffer.
+A list whose @code{car} is the widget representing the currently chosen
+type in the buffer.
+@vindex choice@r{ keyword}
@item :choice
-The current chosen type
+The current chosen type.
+@vindex args@r{ keyword}
@item :args
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
+@findex radio-button-choice@r{ widget}
Syntax:
The following extra properties are recognized.
@table @code
+@vindex entry-format@r{ keyword}
@item :entry-format
This string will be inserted for each entry in the list.
The following @samp{%} escapes are available:
@table @samp
@item %v
-Replaced with the buffer representation of the @var{type} widget.
+Replace with the buffer representation of the @var{type} widget.
@item %b
Replace with the radio button.
@item %%
Insert a literal @samp{%}.
@end table
-@item button-args
+@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.
+@vindex buttons@r{ keyword}
@item :buttons
The widgets representing the radio buttons.
+@vindex children@r{ keyword}
@item :children
The widgets representing each type.
+@vindex choice@r{ keyword}
@item :choice
The current chosen type
+@vindex args@r{ keyword}
@item :args
The list of types.
@end table
@code{widget-radio-add-item}.
@defun widget-radio-add-item widget type
-Add to @code{radio-button-choice} widget @var{widget} a new radio button item of type
-@var{type}.
+Add to @code{radio-button-choice} widget @var{widget} a new radio button
+item of type @var{type}.
@end defun
Please note that such items added after the @code{radio-button-choice}
@node item, choice-item, radio-button-choice, Basic Types
@comment node-name, next, previous, up
@subsection The @code{item} Widget
+@findex item@r{ widget}
Syntax:
@node choice-item, toggle, item, Basic Types
@comment node-name, next, previous, up
@subsection The @code{choice-item} Widget
+@findex choice-item@r{ widget}
Syntax:
@node toggle, checkbox, choice-item, Basic Types
@comment node-name, next, previous, up
@subsection The @code{toggle} Widget
+@findex toggle@r{ widget}
Syntax:
TYPE ::= (toggle [KEYWORD ARGUMENT]...)
@end example
-The widget has two possible states, `on' and `off', which correspond to
-a @code{t} or @code{nil} value respectively.
+The widget has two possible states, @samp{on} and @samp{off}, which
+correspond to a @code{t} or @code{nil} value, respectively.
-The following extra properties are recognized.
+The following extra properties are recognized:
@table @code
@item :on
-String representing the `on' state. By default the string @samp{on}.
+A string representing the @samp{on} state. By default the string
+@samp{on}.
@item :off
-String representing the `off' state. By default the string @samp{off}.
+A string representing the @samp{off} state. By default the string
+@samp{off}.
+@vindex on-glyph@r{ keyword}
@item :on-glyph
-Name of a glyph to be used instead of the `:on' text string, on emacsen
-that supports it.
+Name of a glyph to be used instead of the @samp{:on} text string, on
+emacsen that supports this.
+@vindex off-glyph@r{ keyword}
@item :off-glyph
-Name of a glyph to be used instead of the `:off' text string, on emacsen
-that supports it.
+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
+@findex checkbox@r{ widget}
-The widget has two possible states, `selected' and `unselected', which
-corresponds to a @code{t} or @code{nil} value.
+This widget has two possible states, @samp{selected} and
+@samp{unselected}, which corresponds to a @code{t} or @code{nil} value.
Syntax:
@node checklist, editable-list, checkbox, Basic Types
@comment node-name, next, previous, up
@subsection The @code{checklist} Widget
+@findex checklist@r{ widget}
Syntax:
TYPE ::= (checklist [KEYWORD ARGUMENT]... TYPE ... )
@end example
-The @var{type} arguments represents each checklist item. The widget's
-value will be a list containing the values of all ticked @var{type}
+The @var{type} arguments represent each checklist item. The widget's
+value will be a list containing the values of all checked @var{type}
arguments. The checklist widget will match a list whose elements all
match at least one of the specified @var{type} arguments.
-The following extra properties are recognized.
+The following extra properties are recognized:
@table @code
+@vindex entry-format@r{ keyword}
@item :entry-format
This string will be inserted for each entry in the list.
The following @samp{%} escapes are available:
Insert a literal @samp{%}.
@end table
+@vindex greedy@r{ keyword}
@item :greedy
Usually a checklist will only match if the items are in the exact
sequence given in the specification. By setting @code{:greedy} to
you extract the value they will be in the sequence given 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.
+@vindex buttons@r{ keyword}
@item :buttons
The widgets representing the checkboxes.
+@vindex children@r{ keyword}
@item :children
The widgets representing each type.
+@vindex args@r{ keyword}
@item :args
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
+@findex editable-list@r{ widget}
Syntax:
The value is a list, where each member represents one widget of type
@var{type}.
-The following extra properties are recognized.
+The following extra properties are recognized:
@table @code
+@vindex entry-format@r{ keyword}
@item :entry-format
This string will be inserted for each entry in the list.
The following @samp{%} escapes are available:
Insert a literal @samp{%}.
@end table
+@vindex insert-button-args@r{ keyword}
@item :insert-button-args
A list of keyword arguments to pass to the insert buttons.
+@vindex delete-button-args@r{ keyword}
@item :delete-button-args
A list of keyword arguments to pass to the delete buttons.
+@vindex append-button-args@r{ keyword}
@item :append-button-args
A list of keyword arguments to pass to the trailing insert button.
-
+@vindex buttons@r{ keyword}
@item :buttons
The widgets representing the insert and delete buttons.
+@vindex children@r{ keyword}
@item :children
The widgets representing the elements of the list.
+@vindex args@r{ keyword}
@item :args
-List whose car is the type of the list elements.
-
+List whose @code{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
+@findex group@r{ widget}
-This widget simply group other widget together.
+This widget simply group other widgets together.
Syntax:
@node Sexp Types, Widget Properties, Basic Types, Top
@comment
@section Sexp Types
+@cindex sexp types
-A number of widgets for editing s-expressions (lisp types) are also
-available. These basically fall in the following categories.
+A number of widgets for editing @dfn{s-expressions} (lisp types), sexp
+for short, are also available. These basically fall in several
+categories described in this section.
@menu
* constants::
@node constants, generic, Sexp Types, Sexp Types
@comment node-name, next, previous, up
-@subsection The Constant Widgets.
+@subsection The Constant Widgets
+@cindex constant widgets
The @code{const} widget can contain any lisp expression, but the user is
-prohibited from editing edit it, which is mainly useful as a component
-of one of the composite widgets.
+prohibited from editing it, which is mainly useful as a component of one
+of the composite widgets.
-The syntax for the @code{const} widget is
+The syntax for the @code{const} widget is:
@example
TYPE ::= (const [KEYWORD ARGUMENT]... [ VALUE ])
@node generic, atoms, constants, Sexp Types
@comment node-name, next, previous, up
-@subsection Generic Sexp Widget.
+@subsection Generic Sexp Widget
+@cindex generic sexp widget
The @code{sexp} widget can contain any lisp expression, and allows the
user to edit it inline in the buffer.
-The syntax for the @code{sexp} widget is
+The syntax for the @code{sexp} widget is:
@example
TYPE ::= (sexp [KEYWORD ARGUMENT]... [ VALUE ])
field.
The @code{sexp} widget takes the same keyword arguments as the
-@code{editable-field} widget.
+@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.
+@subsection Atomic Sexp Widgets
+@cindex atomic sexp widget
-The atoms are s-expressions that does not consist of other
-s-expressions. A string is an atom, while a list is a composite type.
-You can edit the value of an atom with the following widgets.
+The atoms are s-expressions that do not consist of other s-expressions.
+For example, a string, a file name, or a symbol are atoms, while a list
+is a composite type. You can edit the value of an atom with the
+following widgets.
-The syntax for all the atoms are
+The syntax for all the atoms are:
@example
TYPE ::= (NAME [KEYWORD ARGUMENT]... [ VALUE ])
The @var{value}, if present, is used to initialize the @code{:value}
property and must be an expression of the same type as the widget.
-I.e. the string widget can only be initialized with a string.
+That is, the string widget can only be initialized with a string.
All the atom widgets take the same keyword arguments as the
-@code{editable-field} widget.
+@code{editable-field} widget. @xref{editable-field}.
@deffn Widget string
Allows you to edit a string in an editable field.
Keywords:
@table @code
+@vindex must-match@r{ keyword}
@item :must-match
If this is set to non-nil, only existing file names will be allowed in
the minibuffer.
@node composite, , atoms, Sexp Types
@comment node-name, next, previous, up
-@subsection Composite Sexp Widgets.
+@subsection Composite Sexp Widgets
+@cindex composite sexp widgets
-The syntax for the composite are
+The syntax for the composite widget is:
@example
TYPE ::= (NAME [KEYWORD ARGUMENT]... COMPONENT...)
@end example
-Where each @var{component} must be a widget type. Each component widget
-will be displayed in the buffer, and be editable to the user.
+@noindent
+where each @var{component} must be a widget type. Each component widget
+will be displayed in the buffer, and will be editable by the user.
@deffn Widget cons
-The value of a @code{cons} widget is a cons-cell where the car is the
-value of the first component and the cdr is the value of the second
-component. There must be exactly two components.
+The value of a @code{cons} widget is a cons-cell where the @code{car} is
+the value of the first component and the @code{cdr} is the value of the
+second component. There must be exactly two components.
@end deffn
@deffn Widget list
The above suffice for specifying fixed size lists and vectors. To get
variable length lists and vectors, you can use a @code{choice},
-@code{set} or @code{repeat} widgets together with the @code{:inline}
+@code{set}, or @code{repeat} widgets together with the @code{:inline}
keywords. If any component of a composite widget has the @code{:inline}
keyword set, its value must be a list which will then be spliced into
the composite. For example, to specify a list whose first element must
@end example
The value of a widget of this type will either have the form
-@samp{(file t)} or @code{(file string string)}.
+@code{(file t)} or @code{(file string string)}.
This concept of inline is probably hard to understand. It was certainly
-hard to implement so instead of confusing you more by trying to explain
+hard to implement, so instead of confusing you more by trying to explain
it here, I'll just suggest you meditate over it for a while.
@deffn Widget choice
@deffn Widget set
Allows you to specify a type which must be a list whose elements all
-belong to given set. The elements of the list is not significant. This
-is implemented on top of the @code{checklist} basic widget, and has a
-similar syntax.
+belong to given set. The elements of the list are not significant.
+This is implemented on top of the @code{checklist} basic widget, and has
+a similar syntax.
@end deffn
@deffn Widget repeat
Allows you to specify a variable length list whose members are all of
-the same type. Implemented on top of the `editable-list' basic widget,
-and has a similar syntax.
+the same type. Implemented on top of the @code{editable-list} basic
+widget, and has a similar syntax.
@end deffn
@node Widget Properties, Defining New Widgets, Sexp Types, Top
@comment node-name, next, previous, up
@section Properties
+@cindex properties of widgets
+@cindex widget properties
You can examine or set the value of a widget by using the widget object
that was returned by @code{widget-create}.
Return the name of @var{widget}, a symbol.
@end defun
+@cindex active widget
+@cindex inactive widget
+@cindex activate a widget
+@cindex deactivate a widget
Widgets can be in two states: active, which means they are modifiable by
the user, or inactive, which means they cannot be modified by the user.
You can query or set the state with the following code:
@node Defining New Widgets, Widget Browser, Widget Properties, Top
@comment node-name, next, previous, up
@section Defining New Widgets
+@cindex new widgets
+@cindex defining new widgets
-You can define specialized widgets with @code{define-widget}. It allows
+You can define specialized widgets with @code{widget-define}. It allows
you to create a shorthand for more complex widgets, including specifying
component widgets and new default values for the keyword
arguments.
in the @code{widget-type} property of @var{name}, which is what
@code{widget-create} uses.
-If you just want to specify defaults for keywords with no complex
+If you only want to specify defaults for keywords with no complex
conversions, you can use @code{identity} as your conversion function.
The following additional keyword arguments are useful when defining new
widgets:
@table @code
+@vindex convert-widget@r{ keyword}
@item :convert-widget
Function to convert a widget type before creating a widget of that
type. It takes a widget type as an argument, and returns the converted
Initialize @code{:value} from @code{:args} in @var{widget}.
@end defun
+@vindex value-to-internal@r{ keyword}
@item :value-to-internal
Function to convert the value to the internal format. The function
takes two arguments, a widget and an external value, and returns the
when the widget is created, and on any value set later with
@code{widget-value-set}.
+@vindex value-to-external@r{ keyword}
@item :value-to-external
Function to convert the value to the external format. The function
takes two arguments, a widget and an internal value, and returns the
-internal value. The function is called on the present @code{:value}
+external value. The function is called on the present @code{:value}
when the widget is created, and on any value set later with
@code{widget-value-set}.
+@vindex create@r{ keyword}
@item :create
Function to create a widget from scratch. The function takes one
argument, a widget type, and creates a widget of that type, inserts it
in the buffer, and returns a widget object.
+@vindex delete@r{ keyword}
@item :delete
Function to delete a widget. The function takes one argument, a widget,
and should remove all traces of the widget from the buffer.
+@vindex value-create@r{ keyword}
@item :value-create
Function to expand the @samp{%v} escape in the format string. It will
be called with the widget as its argument and should insert a
representation of the widget's value in the buffer.
+@vindex value-delete@r{ keyword}
@item :value-delete
Should remove the representation of the widget's value from the buffer.
It will be called with the widget as its argument. It doesn't have to
Delete all @code{:children} and @code{:buttons} in @var{widget}.
@end defun
+@vindex value-get@r{ keyword}
@item :value-get
Function to extract the value of a widget, as it is displayed in the
buffer.
Return the @code{:value} property of @var{widget}.
@end defun
+@vindex format-handler@r{ keyword}
@item :format-handler
Function to handle unknown @samp{%} escapes in the format string. It
-will be called with the widget and the escape character as arguments.
-You can set this to allow your widget to handle non-standard escapes.
+will be called with the widget and the character that follows the
+@samp{%} as arguments. You can set this to allow your widget to handle
+non-standard escapes.
+@findex widget-default-format-handler
You should end up calling @code{widget-default-format-handler} to handle
unknown escape sequences, which will handle the @samp{%h} and any future
escape sequences, as well as give an error for unknown escapes.
+@vindex action@r{ keyword}
@item :action
Function to handle user initiated events. By default, @code{:notify}
the parent.
Optional @var{event} is the event that triggered the action.
@end defun
+@vindex prompt-value@r{ keyword}
@item :prompt-value
Function to prompt for a value in the minibuffer. The function should
take four arguments, @var{widget}, @var{prompt}, @var{value}, and
@node Widget Browser, Widget Minor Mode, Defining New Widgets, Top
@comment node-name, next, previous, up
@section Widget Browser
+@cindex widget browser
There is a separate package to browse widgets. This is intended to help
programmers who want to examine the content of a widget. The browser
shows the value of each keyword, but uses links for certain keywords
-such as `:parent', which avoids printing cyclic structures.
+such as @samp{:parent}, which avoids printing cyclic structures.
@deffn Command widget-browse WIDGET
Create a widget browser for WIDGET.
@node Widget Minor Mode, Utilities, Widget Browser, Top
@comment node-name, next, previous, up
@section Widget Minor Mode
+@cindex widget minor mode
There is a minor mode for manipulating widgets in major modes that
-doesn't provide any support for widgets themselves. This is mostly
+don't provide any support for widgets themselves. This is mostly
intended to be useful for programmers doing experiments.
@deffn Command widget-minor-mode
@node Utilities, Widget Wishlist, Widget Minor Mode, Top
@comment node-name, next, previous, up
@section Utilities.
+@cindex utility functions for widgets
@defun widget-prompt-value widget prompt [ value unbound ]
Prompt for a value matching @var{widget}, using @var{prompt}.
@end defun
@defun widget-get-sibling widget
-Get the item @var{widget} is assumed to toggle.
+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, , Utilities, Top
+@node Widget Wishlist, Index, Utilities, Top
@comment node-name, next, previous, up
@section Wishlist
+@cindex todo
@itemize @bullet
@item
@item
The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single
-dash (@samp{-}). The dash should be a button that, when invoked, ask
+dash (@samp{-}). The dash should be a button that, when invoked, asks
whether you want to add or delete an item (@sc{rms} wanted to git rid of
the ugly buttons, the dash is my idea).
@kbd{C-h} in @code{widget-prompt-value} should give type specific help.
@item
-A mailto widget.
-
+Add a @code{mailto} widget.
@end itemize
+@node Index, , Widget Wishlist, Top
+@comment node-name, next, previous, up
+@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
projects / emacs.git / commitdiff