GNU Info

(elisp)Simple Menu Items

---

Next: Extended Menu Items Up: Defining Menus

---

Enter node , (file) or (file)node

Simple Menu Items
.................

   The simpler and older way to define a menu keymap binding looks like
this:

     (ITEM-STRING . REAL-BINDING)

The CAR, ITEM-STRING, is the string to be displayed in the menu.  It
should be short--preferably one to three 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:

     (ITEM-STRING HELP . REAL-BINDING)

   HELP specifies a "help-echo" string to display while the mouse is on
that item in the same way as `help-echo' text properties (Note: Help
display).

   As far as `define-key' is concerned, ITEM-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 ITEM-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.

   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' (Note: 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:

     (ITEM-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 mention keyboard equivalents in
the item strings themselves, since that is redundant.