21.17.1.2 Extended Menu Items

An extended-format menu item is a more flexible and also cleaner alternative to the simple format. You define an event type with a binding that’s a list starting with the symbol menu-item. For a non-selectable string, the binding looks like this:

(menu-item item-name)

A string starting with two or more dashes specifies a separator line; see Menu Separators.

To define a real menu item which can be selected, the extended format binding looks like this:

(menu-item item-name real-binding
    . item-property-list)

Here, item-name is an expression which evaluates to the menu item string. Thus, the string need not be a constant. The third element, real-binding, is the command to execute. The tail of the list, item-property-list, has the form of a property list which contains other information.

Here is a table of the properties that are supported:

:enable form

The result of evaluating form determines whether the item is enabled (non-nil means yes). If the item is not enabled, you can’t really click on it.

:visible form

The result of evaluating form determines whether the item should actually appear in the menu (non-nil means yes). If the item does not appear, then the menu is displayed as if this item were not defined at all.

:help help

The value of this property, help, specifies a “help-echo” string to display while the mouse is on that item. This is displayed in the same way as help-echo text properties (see Help display). Note that this must be a constant string, unlike the help-echo property for text and overlays.

:button (type . selected)

This property provides a way to define radio buttons and toggle buttons. The CAR, type, says which: it should be :toggle or :radio. The CDR, selected, should be a form; the result of evaluating it says whether this button is currently selected.

A toggle is a menu item which is labeled as either “on” or “off” according to the value of selected. The command itself should toggle selected, setting it to t if it is nil, and to nil if it is t. Here is how the menu item to toggle the debug-on-error flag is defined:

(menu-item "Debug on Error" toggle-debug-on-error
           :button (:toggle
                    . (and (boundp 'debug-on-error)
                           debug-on-error)))

This works because toggle-debug-on-error is defined as a command which toggles the variable debug-on-error.

Radio buttons are a group of menu items, in which at any time one and only one is “selected”. There should be a variable whose value says which one is selected at any time. The selected form for each radio button in the group should check whether the variable has the right value for selecting that button. Clicking on the button should set the variable so that the button you clicked on becomes selected.

:key-sequence key-sequence

This property specifies which key sequence is likely to be bound to the same command invoked by this menu item. If you specify the right key sequence, that makes preparing the menu for display run much faster.

If you specify the wrong key sequence, it has no effect; before Emacs displays key-sequence in the menu, it verifies that key-sequence is really equivalent to this menu item.

:key-sequence nil

This property indicates that there is normally no key binding which is equivalent to this menu item. Using this property saves time in preparing the menu for display, because Emacs does not need to search the keymaps for a keyboard equivalent for this menu item.

However, if the user has rebound this item’s definition to a key sequence, Emacs ignores the :keys property and finds the keyboard equivalent anyway.

:keys string

This property specifies that string is the string to display as the keyboard equivalent for this menu item. You can use the ‘\\[...]’ documentation construct in string.

:filter filter-fn

This property provides a way to compute the menu item dynamically. The property value filter-fn should be a function of one argument; when it is called, its argument will be real-binding. The function should return the binding to use instead.

Emacs can call this function at any time that it does redisplay or operates on menu data structures, so you should write it so it can safely be called at any time.