---

8.1.1 The default Widget

The most basic widget in the Widget Library is the default widget. It provides the basic behavior for all other widgets, and all its properties are present by default in derived widgets. You’re seldom (if ever) going to effectively create a default widget, but here we describe its properties and behavior, so that we can describe other widgets only by mentioning the properties and behavior those other widgets specialize.

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. If you want to define a new widget from scratch, use the default widget as its base.

The following keyword arguments apply to all widgets:

: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.

By default, it inserts the widget at point, using the format provided in the :format property.

:delete

Function to delete a widget.

The function should take 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

The initial value for widgets of this type.

Typically, a widget represents its value in two formats: external and internal. The external format is the value as the rest of Emacs sees it, and the internal format is a representation that the widget defines and uses in a widget specific way.

Both formats might be the same for certain widgets and might differ for others, and there is no guarantee about which format the value stored in the :value property has. However, when creating a widget or defining a new one (see Defining New Widgets), the :value should be in the external format.

: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 value in the external format.

: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

A function that 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.

By default, it’s a no-op.

:value-get

Function to extract the value of a widget, as it is displayed in the buffer.

:value-set

Function that takes a widget and a value as arguments, and recreates it.

The value must already be in the internal format for widget. By default, it deletes the widget with the :delete function and creates it again with the :create function.

:value-inline

Function that takes a widget and returns its value, inlined.

Inlined means that if the widget is not inline (i.e., its :inline property is nil), the return value is wrapped in a list.

:default-get

Function that takes a widget and returns its default value.

By default, it just returns the value stored in :value.

:format

This string will be inserted in the buffer when you create a widget. The following ‘%’ escapes are available:

‘%[’

‘%]’

The text inside will be marked as a button.

By default, the text will be shown in widget-button-face, and surrounded by brackets.

‘%{’

‘%}’

The text inside will be displayed with the face specified by :sample-face.

‘%v’

This will be replaced with the buffer representation of the widget’s value. What this is depends on the widget type.

‘%d’

Insert the string specified by :doc here.

‘%h’

Like ‘%d’, with the following modifications: If the documentation string is more than one line, it will add a button which will toggle between showing only the first line, and showing the full text. Furthermore, if there is no :doc property in the widget, it will instead examine the :documentation-property property. If it is a lambda expression, it will be called with the widget’s value as an argument, and the result will be used as the documentation text.

‘%t’

Insert the string specified by :tag here, or the princ representation of the value if there is no tag.

‘%%’

Insert a literal ‘%’.

:button-face

Face used to highlight text inside %[ %] in the format.

:button-prefix

:button-suffix

Strings used as prefix and suffix for widgets that are buttons.

By default, the values are widget-button-prefix and widget-button-suffix.

Text around %[ %] in the format.

These can be

nil

No text is inserted.

a string

The string is inserted literally.

a symbol

The value of the symbol is expanded according to this table.

:doc

The string inserted by the ‘%d’ escape in the format string.

:tag

The string inserted by the ‘%t’ escape in the format string.

:tag-glyph

Name of image to use instead of the string specified by :tag on Emacsen that supports it.

:help-echo

Specifies how to display a message whenever you move to the widget with either widget-forward or widget-backward or move the mouse over it (using the standard help-echo mechanism).

The value is either a string to display, or a function of one argument, the widget. If a function, it should return a string to display, or a form that evaluates to such a string.

:follow-link

Specifies how to interpret a mouse-1 click on the widget. See Defining Clickable Text in the Emacs Lisp Reference Manual.

:indent

An integer indicating the absolute number of spaces to indent children of this widget. Its value might be nil too, which corresponds to a value of 0.

The default :create functions and the functions that create the value per se use this property as a rudimentary layout mechanism for the widgets.

:offset

An integer indicating how many extra spaces to add to the widget’s grandchildren compared to this widget.

:extra-offset

An integer indicating how many extra spaces to add to the widget’s children compared to this widget.

:menu-tag

Tag used in the menu when the widget is used as an option in a menu-choice widget.

:menu-tag-get

Function that takes a widget and returns the tag when the widget is used as an option in a menu-choice widget.

By default, the tag used will be either the :menu-tag or :tag property if present, or the princ representation of the :value property if not.

:match

Should be a function called with two arguments, the widget and an external value, and should return non-nil if the widget can represent the specified value.

:validate

A function which takes a widget as an argument, and returns nil if the widget’s current value is valid for the widget.

Otherwise, it should return the widget containing the invalid data, and set that widget’s :error property to a string explaining the error.

By default, it always returns nil.

:tab-order

Specify the order in which widgets are traversed with widget-forward or widget-backward. This is only partially implemented.

1. Widgets with tabbing order -1 are ignored.
2. (Unimplemented) When on a widget with tabbing order n, go to the next widget in the buffer with tabbing order n+1 or nil, whichever comes first.
3. When on a widget with no tabbing order specified, go to the next widget in the buffer with a positive tabbing order, or nil

:parent

The parent of a nested widget (e.g., a menu-choice item or an element of a editable-list widget).

:sibling-args

This keyword is only used for members of a radio-button-choice or checklist. The value should be a list of extra keyword arguments, which will be used when creating the radio-button or checkbox associated with this item.

:completions-function

Function that takes a widget and returns completion data for that widget, like completion-at-point-functions would. See Completion in the Emacs Lisp Reference Manual. It’s used by editable-field widgets to provide completions.

By default, it looks into the property :completions, which should be a completion table. If :completions is nil, then it calls the function stored either in the :complete or :complete-function property.

:format-handler

Function to handle unknown ‘%’ escapes in the format string.

It takes a widget and the character that follows the ‘%’ as arguments. You can set this to allow your widget to handle non-standard escapes in your own specialized widgets.

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.

:button-face-get

Function to return the face used to fontify a widget button.

Takes a widget and returns an appropriate face for the widget. By default, it either returns the face stored in the :button-face property, or calls the :button-face-get function from the parent of the widget, if it has one.

:mouse-face-get

Function to return the face used to fontify a widget when the mouse pointer hovers over it.

Takes a widget and returns an appropriate face. By default, it either returns the face stored in the :mouse-face property, or calls the :button-face-get function from the parent of the widget, if it has one.

: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.

Its value by default is identity.

:active

Function that takes a widget and returns t if it is active.

A widget might be effectively always active, if its :always-active property is t.

Widgets can be in two states: active, which means they are modifiable by the user, or inactive, which means they cannot be modified by the user. You can query or set the state with the following code:

;; Examine if widget is active or not.
(if (widget-apply widget :active)
    (message "Widget is active.")
  (message "Widget is inactive.")

;; Make widget inactive.
(widget-apply widget :deactivate)

;; Make widget active.
(widget-apply widget :activate)

A widget is inactive if it, or any of its ancestors (found by following the :parent link), have been deactivated. To make sure a widget is really active, you must therefore activate both it and all its ancestors.

(while widget
  (widget-apply widget :activate)
  (setq widget (widget-get widget :parent)))

You can check if a widget has been made inactive by examining the value of the :inactive keyword. If this is non-nil, the widget itself has been deactivated. This is different from using the :active keyword, in that the latter tells you if the widget or any of its ancestors have been deactivated. Do not attempt to set the :inactive keyword directly. Use the :activate :deactivate functions instead.

:activate

Function that takes a widget and makes it active for user modifications.

:deactivate

Function that takes a widget and makes it inactive for user modifications.

:action

Function that takes a widget and optionally an event, and handles a user initiated event.

By default, uses the :notify function to notify the widget’s parent about the event.

:mouse-down-action

Function that takes a widget and optionally an event, and handles a mouse click on the widget.

By default, it does nothing.

:notify

A function called each time the widget or a nested widget is changed.

The function is called with two or three arguments. The first argument is the widget itself, the second argument is the widget that was changed, and the third argument is the event leading to the change, if any.

By default, it passes the notification to the widget’s parent.

:prompt-value

Function to prompt for a value in the minibuffer.

The function should take four arguments, a widget, a prompt (a string), a value and a boolean, and should return a value for the widget, entered by the user.

The prompt is the prompt to use. The value is the default value to use, unless the fourtha argument 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.