12 Utilities

Here we describe some utility functions that don’t really have a place earlier in this manual.

Function: widget-prompt-value widget prompt [ value unbound ]

Prompt for a value matching widget, using prompt. The current value is assumed to be value, unless unbound is non-nil.

Converts widget before prompting, and for prompting it uses the :prompt-value function. This function returns the user “answer”, and it’s an error if that answer doesn’t match the widget, as with the :match function.

If the answer matches the widget, returns the answer.

Function: widget-get-sibling widget

Get the item which widget should toggle. This is only meaningful for radio buttons or checkboxes in a list.

Function: widget-choose title items &optional event

Prompt the user to choose an item from a list of options.

title is the name of the list of options. items should be a menu, with its items in the simple format or in the extended format. See Defining Menus in the Emacs Lisp Reference Manual. Independently of the format, you don’t have to provide a title for the menu, just pass the desired title in title. The optional event is an input event. If event is a mouse event and the number of elements in items is less than the user option widget-menu-max-size, then widget-choose uses a popup menu to prompt the user. Otherwise, widget-choose uses the minibuffer.

When items is a keymap menu, the returned value is the symbol in the key vector, as in the argument of define-key (see Changing Key Bindings in the Emacs Lisp Reference Manual). When items is a list whose selectable items are of the form (name . value) (i.e., the simplified format), then the return value is the value of the chosen element.

Function: widget-image-find image

Create a graphical button from image, an image or a file name sans extension.

If image is a file name, the file should be in widget-image-directory, or in a place where find-image will find it.

Function: widget-image-insert widget tag image

As part of widget, insert the text tag or, if supported, the image image.

image should be as described in widget-image-find.

Function: widget-echo-help pos

Display help-echo text for the widget at pos.

Uses the value of :help-echo. If it is a function, it calls it to get a string. Otherwise, it evals it.