1.1 User Interface

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
`foo field', meaning the field tagged with `Foo'. Here is an
example form:

Here is some documentation.
Name: My NameChoose: This option
Address: Some Place
In some City
Some country.
See also _other work_ for more information.
Numbers: count to three below
[INS][DEL]One[INS][DEL]Eh, two?[INS][DEL]Five![INS]
Select multiple:
[X] This
[ ] That
[X] Thus
Select one:
(*) One
( ) Another One.
( ) A Final One.
[Apply Form][Reset Form]

The top level widgets in this example are tagged `Name',
`Choose', `Address', `_other work_', `Numbers',
`Select multiple', `Select one', `[Apply Form]', and
`[Reset Form]'. There are basically two things the user can do
within a form, namely editing the editable text fields and activating
the buttons.

1.1.1 Editable Text Fields

In the example, the value for the `Name' is most likely displayed
in an editable text field, and so are values for each of the members of
the `Numbers' list. All the normal Emacs editing operations are
available for editing these fields. The only restriction is that each
change you make must be contained within a single editable text field.
For example, capitalizing all text from the middle of one field to the
middle of another field is prohibited.

Editable text fields are created by the editable-field widget.

Warning: In an 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 editable-field widget itself, or insert it with
widget-insert.

The :format keyword is useful for generating the necessary
text; for instance, if you give it a value of "Name: %v ",
the `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
:size keyword, the field will extend to the end of the
line, and the terminating newline will provide separation after.

Warning: In an editable-field widget, the `%v' escape
must be preceded by some other text in the :format string
(if specified).

The editing text fields are highlighted with the
widget-field-face face, making them easy to find.

1.1.2 Buttons

Some portions of the buffer have an associated action, which can
be invoked by a standard key or mouse command. These portions
are called buttons. The default commands for activating a button
are:

RET

Command:widget-button-presspos &optional event

Invoke the button at pos, defaulting to point.
If point is not located on a button, invoke the binding in
widget-global-map (by default the global map).

Mouse-2

Command:widget-button-clickevent

Invoke the button at the location of the mouse pointer. If the mouse
pointer is located in an editable text field, invoke the binding in
widget-global-map (by default the global map).

There are several different kind of buttons, all of which are present in
the example:

The Option Field Tags

When you invoke one of these buttons, you will be asked to choose
between a number of different options. This is how you edit an option
field. Option fields are created by the menu-choice widget. In
the example, `Choose' is an option field tag.

The `[INS]' and `[DEL]' buttons

Activating these will insert or delete elements from an editable list.
The list is created by the editable-list widget.

Embedded Buttons

The `_other work_' is an example of an embedded
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 link widget.

The `[ ]' and `[X]' buttons

Activating one of these will convert it to the other. This is useful
for implementing multiple-choice fields. You can create them with the
checkbox widget.

The `( )' and `(*)' buttons

Only one radio button in a 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.

The `[Apply Form]' and `[Reset Form]' buttons

These are explicit buttons made with the push-button widget. The
main difference from the link widget is that the buttons will be
displayed as GUI buttons when possible.

To make them easier to locate, buttons are emphasized in the buffer.

Face:widget-button-face

Face used for buttons.

User Option:widget-mouse-face

Face used for highlighting a button when the mouse pointer moves across
it.