Go to the first, previous, next, last section, table of contents.
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.