widget: Defining New Widgets
8 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 new default values for the keyword arguments.
-- Function: define-widget 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:
• (widget-create NAME)
• (apply widget-create CLASS ARGS)
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 only 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 widget’s 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.
‘:copy’
Function to deep copy a widget type. It takes a shallow copy of
the widget type as an argument (made by ‘copy-sequence’), and
returns a deep copy. The purpose of this is to avoid having
different instances of combined widgets share nested attributes.
The following predefined functions can be used here:
-- Function: widget-types-copy widget
Copy ‘:args’ as widget types 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 external 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 creates a widget of that type, inserts
it in the buffer, and returns 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.
The default value is:
-- Function: widget-default-delete widget
Remove WIDGET from the buffer. Delete all ‘:children’ and
‘:buttons’ in WIDGET.
In most cases you should not change this value, but instead use
‘:value-delete’ to make any additional cleanup.
‘: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.
Nested widgets should be listed in ‘:children’ or ‘:buttons’ to
make sure they are automatically deleted.
‘: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 these are not listed in ‘:children’ or
‘:buttons’.
‘: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 character that follows the
‘%’ 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 is 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.
Info Catalog
widget: Widget Properties
widget: Top
widget: Widget Browser