@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
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.
@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"
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
@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
@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
@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}
@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
@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
@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.
@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:
@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
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
+The value of a @code{cons} widget is a cons-cell where the @sc{car} is
+the value of the first component and the @sc{cdr} is the value of the
second component. There must be exactly two components.
@end deffn
@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