22.17.1.1 Simple Menu Items

The simpler (and original) way to define a menu item is to bind some event type (it doesn't matter what event type) to a binding 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. Note that it is not generally possible to display non-ASCII text in menus. It will work for keyboard menus and will work to a large extent when Emacs is built with the Gtk+ toolkit.(7)

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 (voir 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 (voir la 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:

(item-string [help] (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.

Ce document a été généré par Eric Reinbold le 13 Octobre 2007 en utilisant texi2html 1.78.