GNU Info

(widget)User Interface

---

Next: Programming Example Prev: Introduction Up: Top

---

Enter node , (file) or (file)node

User Interface
==============

   A form consist 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 is 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.

   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.

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 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
     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]' `[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>'
      - Command: widget-backward &optional count
          Move point COUNT buttons or editing fields backward.