You can now define menus conveniently as keymaps. Menus are normally used with the mouse, but they can work with the keyboard also.
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. It
should describes 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 run make-keymap or make-sparse-keymap.
The individual bindings in the menu keymap should also have prompt strings; these strings are the items in the menu. A binding with a prompt string looks like this:
(char string . real-binding)
As far as define-key is concerned, the string is part of the
character's binding--the binding looks like this:
(string . real-binding).
However, only real-binding is used for executing the key.
You can also supply a second string, called the help string, as follows:
(char 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 hope to make help-string serve as longer documentation for the menu item, available on request.
The prompt string for a binding should be short--one or two words. Its meaning should describe the command it corresponds to.
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 which
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 way to make a menu keymap produce a menu is to make it the definition of a prefix key.
When the prefix key ends with a mouse event, Emacs handles the menu keymap by popping up a visible menu that you can select from with the mouse. When you click on a menu item, the event generated is whatever character or symbol has the binding which brought about that menu item.
A single keymap can appear as multiple panes, if you explicitly arrange for this. The way to do this is to make a keymap for each pane, then create a binding for each of those maps in the main keymap of the menu. Give each of these bindings a prompt string that starts with `@'. The rest of the prompt string becomes the name of the pane. See the file `lisp/mouse.el' for an example of this. Any ordinary bindings with prompt strings are grouped into one pane, which appears along with the other panes explicitly created for the submaps.
You can also get multiple panes from separate keymaps. The full definition of a prefix key always comes from merging the definitions supplied by the various active keymaps (minor modes, local, and global). When more than one of these keymaps is a menu, each of them makes a separate pane or panes.
When a prefix key ending with a keyboard event (a character or function key) has a definition that is a menu keymap, you can use the keyboard to choose a menu item.
Emacs displays the menu alternatives in the echo area. If they don't all fit at once, type SPC to see the next line of alternatives. If you keep typing SPC, you eventually get to the end of the menu and then cycle around to the beginning again.
When you have found the alternative you want, type the corresponding character--the one whose binding is that alternative.
In a menu intended for keyboard use, each menu item must clearly indicate what character to type. The best convention to use is to make the character the first letter of the menu item prompt string. That is something users will understand without being told.
Under X Windows, each frame can have a menu bar---a permanently
displayed menu stretching horizontally across the top of the frame. The
items of the menu bar are the subcommands of the fake "function key"
menu-bar, as defined by all the active keymaps.
To add an item to the menu bar, invent a fake "function key" of your
own (let's call it key), and make a binding for the key sequence
[menu-bar key]. Most often, the binding is a menu keymap,
so that pressing a button on the menu bar item leads to another menu.
In order for a frame to display a menu bar, its menu-bar-lines
property must be greater than zero. Emacs uses just one line for the
menu bar itself; if you specify more than one line, the other lines
serve to separate the menu bar from the windows in the frame. We
recommend you try one or two as the menu-bar-lines value.