Here we describe some utility functions that don’t really have a place earlier in this manual.
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.
Get the item which widget should toggle. This is only meaningful for radio buttons or checkboxes in a list.
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.
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.
As part of widget, insert the text tag or, if supported, the image image.
image should be as described in widget-image-find.
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.