@c %**end of header
@copying
-Copyright @copyright{} 2000, 2002, 2003 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
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
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.
+@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
@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:
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