Defining New Widgets

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

Using define-widget just stores 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 :convert-widget function.

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

:convert-widget

Method to convert type-specific components of a widget type before instantiating a widget of that type. Not normally called from user code, it is invoked by widget-convert. Typical operations include converting types of child widgets to widget instances and converting values from external format (i.e., as expected by the calling code) to internal format (which is often different for the convenience of widget manipulation). It takes a widget type as an argument, and returns the converted widget type. When a widget is created, the value of this property is called for the widget type, then for all the widget's parent types, most derived first. (The property is reevaluated for each parent type.)

The following predefined functions can be used here:

— Function: widget-types-convert-widget widget

Convert each member of :args in widget from a widget type to a widget.

— Function: widget-value-convert-widget widget

Initialize :value from (car :args) in widget, and reset :args.

:copy

A method to implement deep copying of the type. Any member of the widget which might be changed in place (rather than replaced) should be copied by this method. (widget-copy uses copy-sequence to ensure that the top-level list is a copy.) This particularly applies to child widgets.

:value-to-internal

Function to convert the value to the internal format. The function takes two arguments, a widget and an external value. It 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, and inserts it in the buffer. Not normally called from user code. Instead, call widget-create or related functions, which take a type argument, (usually) convert it to a widget, call the :create function to insert it in the buffer, and then return the (possibly converted) widget.

The default, widget-default-create, is invariably appropriate. (None of the standard widgets specify :create.)

: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 and should insert a representation of the widget's value in the buffer.

:value-delete

Should remove the representation of the widget's 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 have 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. It 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. Actions normally do not include mere edits, but refer to things like invoking buttons or hitting enter in an editable field. To watch for any change, redefine the :notify callback.

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 this case there is no default value. The function should read the value using the method most natural for this widget and does not have to check whether it matches.

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

In implementing complex hierarchical widgets (e.g., using the ‘group’ widget), the following functions may be useful. The syntax for the type arguments to these functions is described in Basic Types.

widget-convert is typically not called from user code; rather it is called implicitly through the ‘widget-create*’ functions.