Go to the first, previous, next, last section, table of contents.


Defining New Widgets

You can define specialized widgets with define-widget. It allows you to create a shorthand for more complex widgets, including specifying component widgets and default new default values for the keyword arguments.

Function: widget-define name class doc &rest args
Define a new widget type named name from class.

name and class should both be symbols, class should be one of the existing widget types.

The third argument DOC is a documentation string for the widget.

After the new widget has been defined, the following two calls will create identical widgets:

Using widget-define does just store the definition of the widget type in the widget-type property of name, which is what widget-create uses.

If you just want to specify defaults for keywords with no complex conversions, you can use identity as your conversion function.

The following additional keyword arguments are useful when defining new widgets:

:convert-widget
Function to convert a widget type before creating a widget of that type. It takes a widget type as an argument, and returns the converted widget type. When a widget is created, this function is called for the widget type and all the widgets parent types, most derived first. The following predefined functions can be used here:
Function: widget-types-convert-widget widget
Convert :args as widget types in widget.
Function: widget-value-convert-widget widget
Initialize :value from :args in widget.
:value-to-internal
Function to convert the value to the internal format. The function takes two arguments, a widget and an external value, and returns the internal value. The function is called on the present :value when the widget is created, and on any value set later with widget-value-set.
:value-to-external
Function to convert the value to the external format. The function takes two arguments, a widget and an internal value, and returns the internal value. The function is called on the present :value when the widget is created, and on any value set later with widget-value-set.
:create
Function to create a widget from scratch. The function takes one argument, a widget type, and create a widget of that type, insert it in the buffer, and return a widget object.
:delete
Function to delete a widget. The function takes one argument, a widget, and should remove all traces of the widget from the buffer.
:value-create
Function to expand the `%v' escape in the format string. It will be called with the widget as its argument. Should insert a representation of the widgets value in the buffer.
:value-delete
Should remove the representation of the widgets value from the buffer. It will be called with the widget as its argument. It doesn't have to remove the text, but it should release markers and delete nested widgets if such has been used. The following predefined function can be used here:
Function: widget-children-value-delete widget
Delete all :children and :buttons in widget.
:value-get
Function to extract the value of a widget, as it is displayed in the buffer. The following predefined function can be used here:
Function: widget-value-value-get widget
Return the :value property of widget.
:format-handler
Function to handle unknown `%' escapes in the format string. It will be called with the widget and the escape character as arguments. You can set this to allow your widget to handle non-standard escapes. You should end up calling widget-default-format-handler to handle unknown escape sequences, which will handle the `%h' and any future escape sequences, as well as give an error for unknown escapes.
:action
Function to handle user initiated events. By default, :notify the parent. The following predefined function can be used here:
Function: widget-parent-action widget &optional event
Tell :parent of widget to handle the :action. Optional event is the event that triggered the action.
:prompt-value
Function to prompt for a value in the minibuffer. The function should take four arguments, widget, prompt, value, and unbound and should return a value for widget entered by the user. prompt is the prompt to use. value is the default value to use, unless unbound is non-nil in which case there are no default value. The function should read the value using the method most natural for this widget, and does not have to check that it matches.

If you want to define a new widget from scratch, use the default widget as its base.

Widget: default
Widget used as a base for other widgets.

It provides most of the functionality that is referred to as "by default" in this text.


Go to the first, previous, next, last section, table of contents.