Next: Programming Example, Previous: Introduction, Up: Top

### 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 Name     Choose: 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.

#### 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.

— Face: widget-field-face

> Face used for other editing fields.

#### 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-press pos &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-click event

  > 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.

#### Navigation

You can use all the normal Emacs commands to move around in a form buffer, plus you will have these additional commands:

`<TAB>`
  — Command: widget-forward &optional count

  > Move point count buttons or editing fields forward.

`M-<TAB>`
`S-<TAB>`
  — Command: widget-backward &optional count

  > Move point count buttons or editing fields backward.