elisp: Mouse Menus
21.17.2 Menus and the Mouse
---------------------------
The usual way to make a menu keymap produce a menu is to make it the
definition of a prefix key. (A Lisp program can explicitly pop up a
menu and receive the user’s choice—see 
Pop-Up Menus.)
If the prefix key ends with a mouse event, Emacs handles the menu
keymap by popping up a visible menu, so that the user can select a
choice with the mouse. When the user clicks on a menu item, the event
generated is whatever character or symbol has the binding that brought
about that menu item. (A menu item may generate a series of events if
the menu has multiple levels or comes from the menu bar.)
It’s often best to use a button-down event to trigger the menu. Then
the user can select a menu item by releasing the button.
If the menu keymap contains a binding to a nested keymap, the nested
keymap specifies a “submenu”. There will be a menu item, labeled by the
nested keymap’s item string, and clicking on this item automatically
pops up the specified submenu. As a special exception, if the menu
keymap contains a single nested keymap and no other menu items, the menu
shows the contents of the nested keymap directly, not as a submenu.
However, if Emacs is compiled without X toolkit support, or on text
terminals, submenus are not supported. Each nested keymap is shown as a
menu item, but clicking on it does not automatically pop up the submenu.
If you wish to imitate the effect of submenus, you can do that by giving
a nested keymap an item string which starts with ‘@’. This causes Emacs
to display the nested keymap using a separate “menu pane”; the rest of
the item string after the ‘@’ is the pane label. If Emacs is compiled
without X toolkit support, or if a menu is displayed on a text terminal,
menu panes are not used; in that case, a ‘@’ at the beginning of an item
string is omitted when the menu label is displayed, and has no other
effect.
Info Catalog
elisp: Defining Menus
elisp: Menu Keymaps
elisp: Keyboard Menus