widget: User Interface
2 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.
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.
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.
2.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-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.
2.3 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.
Info Catalog
widget: Introduction
widget: Top
widget: Programming Example