Next: Widget Browser, Previous: Widget Properties, Up: Top [Contents]
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.
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 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:
Convert each member of :args
in widget from a widget type
to a 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:
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:
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:
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.
Widget used as a base for other widgets.
It provides most of the functionality that is referred to as “by default” in this text.
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.
As a child of parent, create a widget with type type and
value value. type is copied, and the :widget-contvert
method is applied to the optional keyword arguments from args.
As a child of parent, create a widget with type type. type is copied, but no conversion method is applied.
As a child of parent, create a widget with type type and value value. type is copied, but no conversion method is applied.
Convert type to a widget without inserting it in the buffer. The optional args are additional keyword arguments.
The widget’s :args
property is set from the longest tail of
args whose ‘cdr’ is not a keyword, or if that is null, from
the longest tail of type’s :args
property whose cdr is not
a keyword. Keyword arguments from args are set, and the
:value
property (if any) is converted from external to internal
format.
widget-convert
is typically not called from user code; rather it
is called implicitly through the ‘widget-create*’ functions.
Next: Widget Browser, Previous: Widget Properties, Up: Top [Contents]