Widgets and the Buffer

This chapter describes commands that are specific to buffers that contain widgets.

Variable: widget-keymap

Keymap containing useful bindings for buffers containing widgets.

Binds TAB to widget-forward and both S-TAB and M-TAB to widget-backward. It also binds RET to widget-button-press and both down-mouse-1 and down-mouse-2 to widget-button-click.

There’s also a keymap for events that the Widget library doesn’t need to handle.

Variable: widget-global-map

Keymap used by widget-button-press and widget-button-click when not on a button. By default this is global-map.

In addition to these two keymaps, each widget might define a keymap of its own, active when events happen at that widget.

The following navigation commands are available:

TAB

Command: widget-forward count &optional suppress-echo

Move point count buttons or editing fields forward. The optional suppress-echo argument suppresses showing in the echo-area the help-echo text, if any, for the final position after the move; it is always nil in interactive invocations.

M-TAB

S-TAB

Command: widget-backward count &optional suppress-echo

Move point count buttons or editing fields backward. The optional suppress-echo argument suppresses showing in the echo-area the help-echo text, if any, for the final position after the move; it is always nil in interactive invocations.

By default, tabbing can put point on an inactive widget. To skip over inactive widgets when tabbing, set the user option widget-skip-inactive to a non-nil value. See Customization.

When editing an editable-field widget, the following commands are available:

C-e

Command: widget-end-of-line

Move point to the end of field or end of line, whichever is first.

C-k

Command: widget-kill-line

Kill to end of field or end of line, whichever is first.

M-TAB

C-M-i

Command: widget-complete

Complete the content of the editable field at point.

C-m

RET

Command: widget-field-activate

Invoke the editable field at point.

The following two commands can execute the action associated with a button widget (e.g., a radio button or checkbox):

RET

C-m

Command: widget-button-press pos &optional event

Invoke the button at pos, defaulting to point.

Invocation means to run the function stored in the :action property.

If point is not located on a button, invoke the binding in widget-global-map (by default the global map).

mouse-2

Command: widget-button-click event

Invoke the button at the location of the mouse pointer.

If the mouse pointer is located in an editable text field, invoke the binding in widget-global-map (by default the global map).

In case the mouse-click is on a widget, calls the function stored in the :mouse-down-action property.