A keymap is suitable for menu use if it has an overall prompt
string, which is a string that appears as an element of the keymap.
(See section Format of Keymaps.) The string should describe the purpose of
the menu. The easiest way to construct a keymap with a prompt string is
to specify the string as an argument when you call make-keymap or
make-sparse-keymap (see section Creating Keymaps).
The order of items in the menu is the same as the order of bindings in
the keymap. Since define-key puts new bindings at the front, you
should define the menu items starting at the bottom of the menu and
moving to the top, if you care about the order. When you add an item to
an existing menu, you can specify its position in the menu using
define-key-after (see section Modifying Menus).
The individual bindings in the menu keymap should have item strings; these strings become the items displayed in the menu. A binding with an item string looks like this:
(string . real-binding)
The item string for a binding should be short--one or two words. It should describe the action of the command it corresponds to.
You can also supply a second string, called the help string, as follows:
(string help-string . real-binding)
Currently Emacs does not actually use help-string; it knows only how to ignore help-string in order to extract real-binding. In the future we may use help-string as extended documentation for the menu item, available on request.
As far as define-key is concerned, string and
help-string are part of the event's binding. However,
lookup-key returns just real-binding, and only
real-binding is used for executing the key.
If real-binding is nil, then string appears in the
menu but cannot be selected.
If real-binding is a symbol and has a non-nil
menu-enable property, that property is an expression that
controls whether the menu item is enabled. Every time the keymap is
used to display a menu, Emacs evaluates the expression, and it enables
the menu item only if the expression's value is non-nil. When a
menu item is disabled, it is displayed in a "fuzzy" fashion, and
cannot be selected with the mouse.
The menu bar does not recalculate which items are enabled every time you
look at a menu. This is because the X toolkit requires the whole tree
of menus in advance. To force recalculation of the menu bar, call
force-mode-line-update (see section Mode Line Format).
You've probably noticed that menu items show the equivalent keyboard key sequence (if any) to invoke the same command. To save time on recalculation, menu display caches this information in a sublist in the binding, like this:
(string [help-string] (key-binding-data) . real-binding)
Don't put these sublists in the menu item yourself; menu display calculates them automatically. Don't add keyboard equivalents to the item strings in a mouse menu, since that is redundant.
Sometimes it is useful to make menu items that use the "same" command
but with different enable conditions. You can do this by defining alias
commands. Here's an example that makes two aliases for
toggle-read-only and gives them different enable conditions:
(defalias 'make-read-only 'toggle-read-only) (put 'make-read-only 'menu-enable '(not buffer-read-only)) (defalias 'make-writable 'toggle-read-only) (put 'make-writable 'menu-enable 'buffer-read-only)
When using aliases in menus, often it is useful to display the
equivalent key bindings for the "real" command name, not the aliases
(which typically don't have any key bindings except for the menu
itself). To request this, give the alias symbol a non-nil
menu-alias property. Thus,
(put 'make-read-only 'menu-alias t) (put 'make-writable 'menu-alias t)
causes menu items for make-read-only and make-writable to
show the keyboard bindings for toggle-read-only.
Go to the first, previous, next, last section, table of contents.