[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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  
1.4.2 The url-link Widget  
1.4.3 The info-link Widget  
1.4.4 The push-button Widget  
1.4.5 The editable-field Widget  
1.4.6 The text Widget  
1.4.7 The menu-choice Widget  
1.4.8 The radio-button-choice Widget  
1.4.9 The item Widget  
1.4.10 The choice-item Widget  
1.4.11 The toggle Widget  
1.4.12 The checkbox Widget  
1.4.13 The checklist Widget  
1.4.14 The editable-list Widget  
1.4.15 The group Widget  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by XEmacs Webmaster on August, 3 2012 using texi2html