1.4 Basic Types

This is the general syntax of a type specification:

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

Warning: In an editable-field widget, the `%v' escape must be preceded by some other text in the format string (if specified).

`%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' or `%h' 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, a function of one argument, the widget, which should return a string to display, or a form that evaluates to such a string.

:follow-link

Specifies how to interpret a mouse-1 click on the widget. See section `Defining Clickable Text' in the Emacs Lisp Reference Manual.

: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. In editable fields, this includes all insertions, deletions, etc. To watch only for "final" actions, redefine the :action callback.

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

1. Widgets with tabbing order -1 are ignored.

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

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

@deffn{User Option}: widget-glyph-enable

If non-nil, allow glyphs to appear on displays where they are supported.

1.4.1 The link Widget

Syntax:

type ::= (link [keyword argument]...  [ value ])

The value, if present, is used to initialize the :value property. The value should be a string, which will be inserted in the buffer.

By default the link will be shown in brackets.

User Option: widget-link-prefix

String to prefix links.

User Option: widget-link-suffix

String to suffix links.

1.4.2 The url-link Widget

Syntax:

type ::= (url-link [keyword argument]...  url)

When this link is invoked, the WWW browser specified by browse-url-browser-function will be called with url.

1.4.3 The info-link Widget

Syntax:

type ::= (info-link [keyword argument]...  address)

When this link is invoked, the built-in Info reader is started on address.

1.4.4 The push-button Widget

Syntax:

type ::= (push-button [keyword argument]...  [ value ])

The value, if present, is used to initialize the :value property. The value should be a string, which will be inserted in the buffer.

By default the tag will be shown in brackets.

User Option: widget-push-button-prefix

String to prefix push buttons.

User Option: widget-push-button-suffix

String to suffix push buttons.

1.4.5 The editable-field Widget

Syntax:

type ::= (editable-field [keyword argument]... [ value ])

The value, if present, is used to initialize the :value property. The value should be a string, which will be inserted in the field. This widget will match all string values.

The following extra properties are recognized:

:size

The minimum width of the editable field.
By default the field will reach to the end of the line. If the content is too large, the displayed representation will expand to contain it. The content is not truncated to size.

:value-face

Face used for highlighting the editable field. Default is widget-field-face, see 1.1 User Interface.

:secret

Character used to display the value. You can set this to e.g. ?* if the field contains a password or other secret information. By default, this is nil, and the value is not secret.

:valid-regexp

By default the :validate function will match the content of the field with the value of this attribute. The default value is "" which matches everything.

:keymap

Keymap used in the editable field. The default value is widget-field-keymap, which allows you to use all the normal editing commands, even if the buffer's major mode suppresses some of them. Pressing RET invokes the function specified by :action.

1.4.6 The text Widget

This is just like editable-field, but intended for multiline text fields. The default :keymap is widget-text-keymap, which does not rebind the RET key.

1.4.7 The menu-choice Widget

Syntax:

type ::= (menu-choice [keyword argument]... type ... )

The type argument represents each possible choice. The widget's value will be that of the chosen type argument. This widget will match any value matching at least one of the specified type arguments.

:void

Widget type used as a fallback when the value does not match any of the specified type arguments.

:case-fold

Set this to nil if you don't want to ignore case when prompting for a choice through the minibuffer.

:children

A list whose CAR is the widget representing the currently chosen type in the buffer.

:choice

The current chosen type.

:args

The list of types.

1.4.8 The radio-button-choice Widget

Syntax:

type ::= (radio-button-choice [keyword argument]...  type ... )

The component types specify the choices, with one radio button for each. The widget's value will be that of the chosen type argument. This widget matches any value that matches at least one of the specified type arguments.

The following extra properties are recognized.

:entry-format

This string will be inserted for each entry in the list. The following `%' escapes are available:

`%v'

Replace with the buffer representation of the type widget.

`%b'

Replace with the radio button.

`%%'

Insert a literal `%'.

:button-args

A list of keywords to pass to the radio buttons. Useful for setting e.g. the `:help-echo' for each button.

:buttons

The widgets representing the radio buttons.

:children

The widgets representing each type.

:choice

The current chosen type

:args

The list of types.

You can add extra radio button items to a radio-button-choice widget after it has been created with the function widget-radio-add-item.

Function: widget-radio-add-item widget type

Add to radio-button-choice widget widget a new radio button item of type type.

Please note that such items added after the radio-button-choice widget has been created will not be properly destructed when you call widget-delete.

1.4.9 The item Widget

Syntax:

item ::= (item [keyword argument]... value)

The value, if present, is used to initialize the :value property. The value should be a string, which will be inserted in the buffer. This widget will only match the specified value.

1.4.10 The choice-item Widget

Syntax:

item ::= (choice-item [keyword argument]... value)

The value, if present, is used to initialize the :value property. The value should be a string, which will be inserted in the buffer as a button. Activating the button of a choice-item is equivalent to activating the parent widget. This widget will only match the specified value.

1.4.11 The toggle Widget

Syntax:

type ::= (toggle [keyword argument]...)

The widget has two possible states, `on' and `off', which correspond to a t or nil value, respectively.

The following extra properties are recognized:

:on

A string representing the `on' state. By default the string `on'.

:off

A string representing the `off' state. By default the string `off'.

:on-glyph

Name of a glyph to be used instead of the `:on' text string, on emacsen that supports this.

:off-glyph

Name of a glyph to be used instead of the `:off' text string, on emacsen that supports this.

1.4.12 The checkbox Widget

This widget has two possible states, `selected' and `unselected', which corresponds to a t or nil value.

Syntax:

type ::= (checkbox [keyword argument]...)

1.4.13 The checklist Widget

Syntax:

type ::= (checklist [keyword argument]...  type ... )

The type arguments represent each checklist item. The widget's value will be a list containing the values of all checked type arguments. The checklist widget will match a list whose elements all match at least one of the specified type arguments.

The following extra properties are recognized:

:entry-format

This string will be inserted for each entry in the list. The following `%' escapes are available:

`%v'

Replaced with the buffer representation of the type widget.

`%b'

Replace with the checkbox.

`%%'

Insert a literal `%'.

:greedy

Usually a checklist will only match if the items are in the exact sequence given in the specification. By setting :greedy to non-nil, it will allow the items to appear in any sequence. However, if you extract the value they will be in the sequence given in the checklist, i.e. the original sequence is forgotten.

:button-args

A list of keywords to pass to the checkboxes. Useful for setting e.g. the `:help-echo' for each checkbox.

:buttons

The widgets representing the checkboxes.

:children

The widgets representing each type.

:args

The list of types.

1.4.14 The editable-list Widget

Syntax:

type ::= (editable-list [keyword argument]... type)

The value is a list, where each member represents one widget of type type.

The following extra properties are recognized:

:entry-format

This string will be inserted for each entry in the list. The following `%' escapes are available:

`%v'

This will be replaced with the buffer representation of the type widget.

`%i'

Insert the [INS] button.

`%d'

Insert the [DEL] button.

`%%'

Insert a literal `%'.

:insert-button-args

A list of keyword arguments to pass to the insert buttons.

:delete-button-args

A list of keyword arguments to pass to the delete buttons.

:append-button-args

A list of keyword arguments to pass to the trailing insert button.

:buttons

The widgets representing the insert and delete buttons.

:children

The widgets representing the elements of the list.

:args

List whose CAR is the type of the list elements.

1.4.15 The group Widget

This widget simply groups other widgets together.

Syntax:

type ::= (group [keyword argument]... type...)

The value is a list, with one member for each type.