@c %**end of header
@copying
-Copyright @copyright{} 2000, 2002 Free Software Foundation, Inc.
+Copyright @copyright{} 2000, 2002, 2003, 2004, 2005,
+2006 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.1 or
+under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
meaning. The user is not supposed to change or delete any of the text
between the fields. Examples of forms in Emacs are the @file{forms}
package (of course), the customize buffers, the mail and news compose
-modes, and the @sc{html} form support in the @file{w3} browser.
+modes, and the @acronym{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
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
+In order to minimize the code that is loaded by users who do not
create any widgets, the code has been split in two files:
@cindex widget library, files
@comment node-name, next, previous, up
@section User Interface
-A form consist of read only text for documentation and some fields,
+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
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
@b{[Apply Form]} @b{[Reset Form]}
@end example
-The top level widgets in is example are tagged @samp{Name},
+The top level widgets in this 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 things the user can do
For example, capitalizing all text from the middle of one field to the
middle of another field is prohibited.
-Editing text fields are created by the @code{editable-field} widget.
+Editable text fields are created by the @code{editable-field} widget.
+
+@strong{Warning:} In an @code{editable-field} widget, the editable
+field must not be adjacent to another widget---that won't work.
+You must put some text in between. Either make this text part of
+the @code{editable-field} widget itself, or insert it with
+@code{widget-insert}.
+
+The @code{:format} keyword is useful for generating the necessary
+text; for instance, if you give it a value of @code{"Name: %v "},
+the @samp{Name: } part will provide the necessary separating text
+before the field and the trailing space will provide the
+separating text after the field. If you don't include the
+@code{:size} keyword, the field will extend to the end of the
+line, and the terminating newline will provide separation after.
The editing text fields are highlighted with the
@code{widget-field-face} face, making them easy to find.
@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 any 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
Activating one of these will convert it to the other. This is useful
-for implementing multiple-choice fields. You can create it with the
+for implementing multiple-choice fields. You can create them 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
+@item The @samp{@b{[Apply Form]}} and @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.
@deffn Command widget-forward &optional count
Move point @var{count} buttons or editing fields forward.
@end deffn
-@item @key{M-TAB}
+@item @kbd{M-@key{TAB}}
+@itemx @kbd{S-@key{TAB}}
@deffn Command widget-backward &optional count
Move point @var{count} buttons or editing fields backward.
@end deffn
(make-local-variable 'widget-example-repeat)
(let ((inhibit-read-only t))
(erase-buffer))
+ (remove-overlays)
(widget-insert "Here is some documentation.\n\nName: ")
(widget-create 'editable-field
:size 13
+ :format "%v " ; Text after the field!
"My Name")
(widget-create 'menu-choice
:tag "Choose"
@comment node-name, next, previous, up
@section Basic Types
-The syntax of a type specification is given below:
+This is the general syntax of a type specification:
@example
-NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
- | NAME
+@var{name} ::= (@var{name} [@var{keyword} @var{argument}]... @var{args})
+ | @var{name}
@end example
Where, @var{name} is a widget name, @var{keyword} is the name of a
are interpreted in a widget specific way.
@cindex keyword arguments
-The following keyword arguments that apply to all widgets:
+The following keyword arguments apply to all widgets:
@table @code
@vindex value@r{ keyword}
which should return a string to display, or a form that evaluates to
such a string.
+@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}.
+
@vindex indent@r{ keyword}
@item :indent
An integer indicating the absolute number of spaces to indent children
@end deffn
@deffn{User Option} widget-glyph-enable
-If non-nil, allow glyphs to appear on displays where they are supported.
+If non-@code{nil}, allow glyphs to appear on displays where they are supported.
@end deffn
Syntax:
@example
-TYPE ::= (link [KEYWORD ARGUMENT]... [ VALUE ])
+@var{type} ::= (link [@var{keyword} @var{argument}]... [ @var{value} ])
@end example
The @var{value}, if present, is used to initialize the @code{:value}
Syntax:
@example
-TYPE ::= (url-link [KEYWORD ARGUMENT]... URL)
+@var{type} ::= (url-link [@var{keyword} @var{argument}]... @var{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
+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
Syntax:
@example
-TYPE ::= (info-link [KEYWORD ARGUMENT]... ADDRESS)
+@var{type} ::= (info-link [@var{keyword} @var{argument}]... @var{address})
@end example
When this link is invoked, the built-in Info reader is started on
Syntax:
@example
-TYPE ::= (push-button [KEYWORD ARGUMENT]... [ VALUE ])
+@var{type} ::= (push-button [@var{keyword} @var{argument}]... [ @var{value} ])
@end example
The @var{value}, if present, is used to initialize the @code{:value}
Syntax:
@example
-TYPE ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ])
+@var{type} ::= (editable-field [@var{keyword} @var{argument}]... [ @var{value} ])
@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
+property. The value should be a string, which will be inserted in the
field. This widget will match all string values.
The following extra properties are recognized:
@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, this is nil, and the value is not secret.
+default, this is @code{nil}, and the value is not secret.
@vindex valid-regexp@r{ keyword}
@item :valid-regexp
Syntax:
@example
-TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... )
+@var{type} ::= (menu-choice [@var{keyword} @var{argument}]... @var{type} ... )
@end example
The @var{type} argument represents each possible choice. The widget's
@vindex case-fold@r{ keyword}
@item :case-fold
-Set this to nil if you don't want to ignore case when prompting for a
+Set this to @code{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 @code{car} is the widget representing the currently chosen
+A list whose @sc{car} is the widget representing the currently chosen
type in the buffer.
@vindex choice@r{ keyword}
Syntax:
@example
-TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]... TYPE ... )
+@var{type} ::= (radio-button-choice [@var{keyword} @var{argument}]... @var{type} ... )
@end example
-The @var{type} argument represents each possible choice. The widget's
-value will be that of the chosen @var{type} argument. This widget will
-match any value matching at least one of the specified @var{type}
-arguments.
+The component types specify the choices, with one radio button for
+each. The widget's value will be that of the chosen @var{type}
+argument. This widget matches any value that matches at least one of
+the specified @var{type} arguments.
The following extra properties are recognized.
Syntax:
@example
-ITEM ::= (item [KEYWORD ARGUMENT]... VALUE)
+@var{item} ::= (item [@var{keyword} @var{argument}]... @var{value})
@end example
The @var{value}, if present, is used to initialize the @code{:value}
Syntax:
@example
-ITEM ::= (choice-item [KEYWORD ARGUMENT]... VALUE)
+@var{item} ::= (choice-item [@var{keyword} @var{argument}]... @var{value})
@end example
The @var{value}, if present, is used to initialize the @code{:value}
Syntax:
@example
-TYPE ::= (toggle [KEYWORD ARGUMENT]...)
+@var{type} ::= (toggle [@var{keyword} @var{argument}]...)
@end example
The widget has two possible states, @samp{on} and @samp{off}, which
Syntax:
@example
-TYPE ::= (checkbox [KEYWORD ARGUMENT]...)
+@var{type} ::= (checkbox [@var{keyword} @var{argument}]...)
@end example
@node checklist, editable-list, checkbox, Basic Types
Syntax:
@example
-TYPE ::= (checklist [KEYWORD ARGUMENT]... TYPE ... )
+@var{type} ::= (checklist [@var{keyword} @var{argument}]... @var{type} ... )
@end example
The @var{type} arguments represent each checklist item. The widget's
@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
-non-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.
+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.
@vindex button-args@r{ keyword}
@item :button-args
Syntax:
@example
-TYPE ::= (editable-list [KEYWORD ARGUMENT]... TYPE)
+@var{type} ::= (editable-list [@var{keyword} @var{argument}]... @var{type})
@end example
The value is a list, where each member represents one widget of type
@vindex args@r{ keyword}
@item :args
-List whose @code{car} is the type of the list elements.
+List whose @sc{car} is the type of the list elements.
@end table
@node group, , editable-list, Basic Types
Syntax:
@example
-TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...)
+@var{type} ::= (group [@var{keyword} @var{argument}]... @var{type}...)
@end example
The value is a list, with one member for each @var{type}.
@section Sexp Types
@cindex sexp types
-A number of widgets for editing @dfn{s-expressions} (lisp types), sexp
+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.
@subsection The Constant Widgets
@cindex constant widgets
-The @code{const} widget can contain any lisp expression, but the user is
+The @code{const} widget can contain any Lisp expression, but the user is
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:
@example
-TYPE ::= (const [KEYWORD ARGUMENT]... [ VALUE ])
+@var{type} ::= (const [@var{keyword} @var{argument}]... [ @var{value} ])
@end example
The @var{value}, if present, is used to initialize the @code{:value}
@subsection Generic Sexp Widget
@cindex generic sexp widget
-The @code{sexp} widget can contain any lisp expression, and allows the
+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:
@example
-TYPE ::= (sexp [KEYWORD ARGUMENT]... [ VALUE ])
+@var{type} ::= (sexp [@var{keyword} @var{argument}]... [ @var{value} ])
@end example
@deffn Widget sexp
The syntax for all the atoms are:
@example
-TYPE ::= (NAME [KEYWORD ARGUMENT]... [ VALUE ])
+@var{type} ::= (@var{construct} [@var{keyword} @var{argument}]... [ @var{value} ])
@end example
The @var{value}, if present, is used to initialize the @code{:value}
@end deffn
@deffn Widget file
-Allows you to edit a file name in an editable field. If you invoke
-the tag button, you can edit the file name in the mini-buffer with
-completion.
+Allows you to edit a file name 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.
+If this is set to non-@code{nil}, only existing file names will be
+allowed in the minibuffer.
@end table
@end deffn
@end deffn
@deffn Widget symbol
-Allows you to edit a lisp symbol in an editable field.
+Allows you to edit a Lisp symbol in an editable field.
@end deffn
@deffn Widget function
@end deffn
@deffn Widget boolean
-Allows you to edit a boolean. In lisp this means a variable which is
-either nil meaning false, or non-nil meaning true.
+Allows you to edit a boolean. In Lisp this means a variable which is
+either @code{nil} meaning false, or non-@code{nil} meaning true.
@end deffn
@subsection Composite Sexp Widgets
@cindex composite sexp widgets
-The syntax for the composite widget is:
+The syntax for the composite widget construct is:
@example
-TYPE ::= (NAME [KEYWORD ARGUMENT]... COMPONENT...)
+@var{type} ::= (@var{construct} [@var{keyword} @var{argument}]... @var{component}...)
@end example
@noindent
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 @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.
+The value of a @code{cons} widget must be a cons-cell whose @sc{car}
+and @sc{cdr} have two specified types. It uses this syntax:
+
+@example
+@var{type} ::= (cons [@var{keyword} @var{argument}]... @var{car-type} @var{cdr-type})
+@end example
+@end deffn
+
+@deffn Widget choice
+The value matched by a @code{choice} widget must have one of a fixed
+set of types. The widget's syntax is as follows:
+
+@example
+@var{type} ::= (choice [@var{keyword} @var{argument}]... @var{type} ... )
+@end example
+
+The value of a @code{choice} widget can be anything that matches any of the
+@var{types}.
@end deffn
@deffn Widget list
-The value of a @code{list} widget is a list containing the value of
-each of its component.
+The value of a @code{list} widget must be a list whose element types
+match the specified component types:
+
+@example
+@var{type} ::= (list [@var{keyword} @var{argument}]... @var{component-type}...)
+@end example
+
+Thus, @code{(list string number)} matches lists of two elements,
+the first being a string and the second being a number.
@end deffn
@deffn Widget vector
-The value of a @code{vector} widget is a vector containing the value of
-each of its component.
+The @code{vector} widget is like the @code{list} widget but matches
+vectors instead of lists. Thus, @code{(vector string number)} matches
+vectors of two elements, the first being a string and the second being
+a number.
@end deffn
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}
-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
-be a file name, and whose remaining arguments should either by the
-symbol @code{t} or two files, you can use the following widget
-specification:
+@code{set}, or @code{repeat} widget together with the @code{:inline}
+keyword. 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 be a file name, and whose remaining elements should
+either be the symbol @code{t} or two strings (file names), you can use
+the following widget specification:
@example
(list file
@end example
The value of a widget of this type will either have the form
-@code{(file t)} or @code{(file string string)}.
+@code{(file t)} or @code{(file @var{string} @var{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
-it here, I'll just suggest you meditate over it for a while.
-
-@deffn Widget choice
-Allows you to edit a sexp which may have one of a fixed set of types.
-It is currently implemented with the @code{choice-menu} basic widget,
-and has a similar syntax.
-@end deffn
+This concept of @code{:inline} may be hard to understand. It was
+certainly 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 set
-Allows you to specify a type which must be a list whose elements all
-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.
+Specifies a type whose values are the lists whose elements all belong
+to a given set. The order of elements of the list is not significant.
+Here's the syntax:
+
+@example
+@var{type} ::= (set [@var{keyword} @var{argument}]... @var{permitted-element} ... )
+@end example
+
+Use @code{const} to specify each permitted element, like this:
+@code{(set (const a) (const b))}.
@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 @code{editable-list} basic
-widget, and has a similar syntax.
+Specifies a list of any number of elements that fit a certain type.
+
+@example
+@var{type} ::= (repeat [@var{keyword} @var{argument}]... @var{type})
+@end example
@end deffn
@node Widget Properties, Defining New Widgets, Sexp Types, Top
@end defun
@defun widget-member widget property
-Non-nil if @var{widget} has a value (even nil) for property @var{property}.
+Non-@code{nil} if @var{widget} has a value (even @code{nil}) for
+property @var{property}.
@end defun
Occasionally it can be useful to know which kind of widget you have,
@end lisp
You can check if a widget has been made inactive by examining the value
-of the @code{:inactive} keyword. If this is non-nil, the widget itself
+of the @code{:inactive} keyword. If this is non-@code{nil}, the widget itself
has been deactivated. This is different from using the @code{:active}
keyword, in that the latter tells you if the widget @strong{or} any of
its ancestors have been deactivated. Do not attempt to set the
@var{name} and class should both be symbols, @code{class} should be one
of the existing widget types.
-The third argument @var{DOC} is a documentation string for the widget.
+The third argument @var{doc} is a documentation string for the widget.
After the new widget has been defined, the following two calls will
create identical widgets:
Function to delete a widget. The function takes one argument, a widget,
and should remove all traces of the widget from the buffer.
+The default value is:
+
+@defun widget-default-delete widget
+Remove @var{widget} from the buffer.
+Delete all @code{:children} and @code{:buttons} in @var{widget}.
+@end defun
+
+In most cases you should not change this value, but instead use
+@code{:value-delete} to make any additional cleanup.
+
@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.
+Nested widgets should be listed in @code{:children} or @code{:buttons}
+to make sure they are automatically deleted.
+
@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
remove the text, but it should release markers and delete nested widgets
-if such have been used.
-
-The following predefined function can be used here:
-
-@defun widget-children-value-delete widget
-Delete all @code{:children} and @code{:buttons} in @var{widget}.
-@end defun
+if these are not listed in @code{:children} or @code{:buttons}.
@vindex value-get@r{ keyword}
@item :value-get
take four arguments, @var{widget}, @var{prompt}, @var{value}, and
@var{unbound} and should return a value for widget entered by the user.
@var{prompt} is the prompt to use. @var{value} is the default value to
-use, unless @var{unbound} is non-nil, in which case there is no default
+use, unless @var{unbound} is non-@code{nil}, in which case there is no default
value. The function should read the value using the method most natural
for this widget, and does not have to check that it matches.
@end table
@defun widget-prompt-value widget prompt [ value unbound ]
Prompt for a value matching @var{widget}, using @var{prompt}.
The current value is assumed to be @var{value}, unless @var{unbound} is
-non-nil.@refill
+non-@code{nil}.@refill
@end defun
@defun widget-get-sibling widget
@setchapternewpage odd
@contents
@bye
+
+@ignore
+ arch-tag: 2b427731-4c61-4e72-85de-5ccec9c623f0
+@end ignore