GNU Info

(widget)Basic Types

---

Next: Sexp Types Prev: Setting Up the Buffer Up: Top

---

Enter node , (file) or (file)node

Basic Types
===========

   The syntax of a type specification is given below:

     NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
          |   NAME

   Where, NAME is a widget name, KEYWORD is the name of a property,
ARGUMENT is the value of the property, and ARGS are interpreted in a
widget specific way.

   The following keyword arguments that apply to all widgets:

`:value'
     The initial value for widgets of this type.

`:format'
     This string will be inserted in the buffer when you create a
     widget.  The following `%' escapes are available:

    `%['
    `%]'
          The text inside will be marked as a button.

          By default, the text will be shown in `widget-button-face',
          and surrounded by brackets.

           - User Option: widget-button-prefix
               String to prefix buttons.

           - User Option: widget-button-suffix
               String to suffix buttons.

    `%{'
    `%}'
          The text inside will be displayed with the face specified by
          `:sample-face'.

    `%v'
          This will be replaced with the buffer representation of the
          widget's value.  What this is depends on the widget type.

    `%d'
          Insert the string specified by `:doc' here.

    `%h'
          Like `%d', with the following modifications: If the
          documentation string is more than one line, it will add a
          button which will toggle between showing only the first line,
          and showing the full text.  Furthermore, if there is no
          `:doc' property in the widget, it will instead examine the
          `:documentation-property' property.  If it is a lambda
          expression, it will be called with the widget's value as an
          argument, and the result will be used as the documentation
          text.

    `%t'
          Insert the string specified by `:tag' here, or the `princ'
          representation of the value if there is no tag.

    `%%'
          Insert a literal `%'.

`:button-face'
     Face used to highlight text inside %[ %] in the format.

`:button-prefix'
`:button-suffix'
     Text around %[ %] in the format.

     These can be
    _nil_
          No text is inserted.

    _a string_
          The string is inserted literally.

    _a symbol_
          The value of the symbol is expanded according to this table.

`:doc'
     The string inserted by the `%d' escape in the format string.

`:tag'
     The string inserted by the `%t' escape in the format string.

`:tag-glyph'
     Name of image to use instead of the string specified by `:tag' on
     Emacsen that supports it.

`:help-echo'
     Specifies how to display a message whenever you move to the widget
     with either `widget-forward' or `widget-backward' or move the mouse
     over it (using the standard `help-echo' mechanism).  The argument
     is either a string to display or a function of one argument, the
     widget, which should return a string to display.

`:indent'
     An integer indicating the absolute number of spaces to indent
     children of this widget.

`:offset'
     An integer indicating how many extra spaces to add to the widget's
     grandchildren compared to this widget.

`:extra-offset'
     An integer indicating how many extra spaces to add to the widget's
     children compared to this widget.

`:notify'
     A function called each time the widget or a nested widget is
     changed.  The function is called with two or three arguments.  The
     first argument is the widget itself, the second argument is the
     widget that was changed, and the third argument is the event
     leading to the change, if any.

`:menu-tag'
     Tag used in the menu when the widget is used as an option in a
     `menu-choice' widget.

`:menu-tag-get'
     Function used for finding the tag when the widget is used as an
     option in a `menu-choice' widget.  By default, the tag used will
     be either the `:menu-tag' or `:tag' property if present, or the
     `princ' representation of the `:value' property if not.

`:match'
     Should be a function called with two arguments, the widget and a
     value, and returning non-nil if the widget can represent the
     specified value.

`:validate'
     A function which takes a widget as an argument, and returns `nil'
     if the widget's current value is valid for the widget.  Otherwise
     it should return the widget containing the invalid data, and set
     that widget's `:error' property to a string explaining the error.

     The following predefined function can be used:

      - Function: widget-children-validate widget
          All the `:children' of WIDGET must be valid.

`:tab-order'
     Specify the order in which widgets are traversed with
     `widget-forward' or `widget-backward'.  This is only partially
     implemented.

       a. Widgets with tabbing order `-1' are ignored.

       b. (Unimplemented) When on a widget with tabbing order N, go to
          the next widget in the buffer with tabbing order N+1 or `nil',
          whichever comes first.

       c. When on a widget with no tabbing order specified, go to the
          next widget in the buffer with a positive tabbing order, or
          `nil'

`:parent'
     The parent of a nested widget (e.g. a `menu-choice' item or an
     element of a `editable-list' widget).

`:sibling-args'
     This keyword is only used for members of a `radio-button-choice' or
     `checklist'.  The value should be a list of extra keyword
     arguments, which will be used when creating the `radio-button' or
     `checkbox' associated with this item.

 - User Option: widget-glyph-directory
     Directory where glyphs are found.  Widget will look here for a
     file with the same name as specified for the image, with either a
     `.xpm' (if supported) or `.xbm' extension.

 - User Option: widget-glyph-enable
     If non-nil, allow glyphs to appear on displays where they are
     supported.

link

url-link

info-link

push-button

editable-field

text

menu-choice

radio-button-choice

item

choice-item

toggle

checkbox

checklist

editable-list

group