@c %**end of header
@copying
-Copyright @copyright{} 2000, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+Copyright @copyright{} 2000, 2001, 2002, 2003, 2004, 2005,
+2006, 2007, 2008 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
* Widget Minor Mode::
* Utilities::
* Widget Wishlist::
+* GNU Free Documentation License::
* Index::
@end menu
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
-@code{define-widget}, and autoload the function @code{widget-create}.
-@item wid-edit.el
-Everything else is here, there is no reason to load it explicitly, as
-it will be autoloaded when needed.
-@end table
-
@node User Interface, Programming Example, Introduction, Top
@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
@code{:size} keyword, the field will extend to the end of the
line, and the terminating newline will provide separation after.
+@strong{Warning:} In an @code{editable-field} widget, the @samp{%v} escape
+must be preceded by some other text in the @code{:format} string
+(if specified).
+
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
(let ((inhibit-read-only t))
(erase-buffer))
(remove-overlays)
- (widget-insert "Here is some documentation.\n\nName: ")
+ (widget-insert "Here is some documentation.\n\n")
(widget-create 'editable-field
:size 13
- :format "%v " ; Text after the field!
+ :format "Name: %v " ; Text after the field!
"My Name")
(widget-create 'menu-choice
:tag "Choose"
'(item :tag "This option" :value "This")
'(choice-item "That option")
'(editable-field :menu-tag "No option" "Thus option"))
- (widget-insert "Address: ")
(widget-create 'editable-field
+ :format "Address: %v"
"Some Place\nIn some City\nSome country.")
(widget-insert "\nSee also ")
(widget-create 'link
@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}
This will be replaced with the buffer representation of the widget's
value. What this is depends on the widget type.
+@strong{Warning:} In an @code{editable-field} widget, the @samp{%v} escape
+must be preceded by some other text in the format string (if specified).
+
@item %d
Insert the string specified by @code{:doc} here.
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}
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:
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
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
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
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}.
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}
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}
@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 @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.
+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)}.
-
-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.
+@code{(file t)} or @code{(file @var{string} @var{string})}.
-@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
This is only meaningful for radio buttons or checkboxes in a list.
@end defun
-@node Widget Wishlist, Index, Utilities, Top
+@node Widget Wishlist, GNU Free Documentation License, Utilities, Top
@comment node-name, next, previous, up
@section Wishlist
@cindex todo
Add a @code{mailto} widget.
@end itemize
-@node Index, , Widget Wishlist, Top
+@node GNU Free Documentation License, Index, Widget Wishlist, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index, , GNU Free Documentation License, Top
@comment node-name, next, previous, up
@unnumbered Index