@c %**end of header
@copying
-Copyright @copyright{} 2000, 2002 Free Software Foundation, Inc.
+Copyright @copyright{} 2000, 2002, 2003 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
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
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.
+
+An editable field must be surrounded by static text on both sides, that
+is, text that does not change in the lifetime of the widget. If the
+field extends to the end of the line, the terminating line-feed character
+will count as the necessary static text on that end, but you will have
+to provide the static text before the field yourself. The
+@code{:format} keyword is useful for generating the static text; for
+instance, if you give it a value of @code{"Name: %v"}, the "Name: " part
+will count as the static text.
The editing text fields are highlighted with the
@code{widget-field-face} face, making them easy to find.
(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
@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:
@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
HCoop / bpt / emacs.git / blobdiff