Next: , Previous: , Up: Top   [Contents]

2 User Interface

A form consists of read only text for documentation and some fields, where each of the fields 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!

Select multiple:

[X] This
[ ] That
[X] Thus

Select one:

(*) One
( ) Another One.
( ) A Final One.

[Apply Form] [Reset Form]

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

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

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

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.

2.1.1 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:

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

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 a 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 it wit

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]’ ‘[Reset Form]’ buttons.

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

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 buttons when the mouse pointer is above it.

2.1.2 Navigation

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

Command: widget-forward &optional count

Move point count buttons or editing fields forward.

Command: widget-backward &optional count

Move point count buttons or editing fields backward.

Next: , Previous: , Up: Top   [Contents]