27.1 Format of Menus

A menu is described using a menu description, which is a list of menu items, keyword-value pairs, strings, and submenus. The menu description specifies which items are present in the menu, what function each item invokes, and whether the item is selectable or not. Pop-up menus are directly described with a menu description, while menubars are described slightly differently (see below).

The first element of a menu must be a string, which is the name of the menu. This is the string that will be displayed in the parent menu or menubar, if any. This string is not displayed in the menu itself, except in the case of the top level pop-up menu, where there is no parent. In this case, the string will be displayed at the top of the menu if popup-menu-titles is non-nil.

Immediately following the first element there may optionally be up to four keyword-value pairs, as follows:

:included form

This can be used to control the visibility of a menu. The form is evaluated and the menu will be omitted if the result is nil.

:config symbol

This is an efficient shorthand for :included (memq symbol menubar-configuration). See the variable menubar-configuration.

:filter function

A menu filter is used to sensitize or incrementally create a submenu only when it is selected by the user and not every time the menubar is activated. The filter function is passed the list of menu items in the submenu and must return a list of menu items to be used for the menu. It is called only when the menu is about to be displayed, so other menus may already be displayed. Vile and terrible things will happen if a menu filter function changes the current buffer, window, or frame. It also should not raise, lower, or iconify any frames. Basically, the filter function should have no side-effects.

:accelerator key

A menu accelerator is a keystroke which can be pressed while the menu is visible which will immediately activate the item. key must be a char or the symbol name of a key. See Menu Accelerators.

The rest of the menu consists of elements as follows:

• A menu item, which is a vector in the following form:

            [ name callback :keyword value :keyword value ... ]
  

  name is a string, the name of the menu item; it is the string to display on the menu. It is filtered through the resource database, so it is possible for resources to override what string is actually displayed.

  callback is a form that will be invoked when the menu item is selected. If the callback of a menu item is a symbol, then it must name a command. It will be invoked with call-interactively. If it is a list, then it is evaluated with eval.

  The valid keywords and their meanings are described below.

  Note that for compatibility purposes, the form

            [ name callback active-p ]
  

  is also accepted and is equivalent to

            [ name callback :active active-p ]
  

  and the form

            [ name callback active-p suffix]
  

  is accepted and is equivalent to

            [ name callback :active active-p :suffix suffix]
  

  However, these older forms are deprecated and should generally not be used.

• If an element of a menu is a string, then that string will be presented in the menu as unselectable text.
• If an element of a menu is a string consisting solely of hyphens, then that item will be presented as a solid horizontal line.
• If an element of a menu is a string beginning with ‘--:’, then a particular sort of horizontal line will be displayed, as follows:

  ‘"--:singleLine"’

  A solid horizontal line. This is equivalent to a string consisting solely of hyphens.
  

  ‘"--:doubleLine"’

  A solid double horizontal line.
  

  ‘"--:singleDashedLine"’

  A dashed horizontal line.
  

  ‘"--:doubleDashedLine"’

  A dashed double horizontal line.
  

  ‘"--:noLine"’

  No line (but a small space is left).
  

  ‘"--:shadowEtchedIn"’

  A solid horizontal line with a 3-d recessed appearance.
  

  ‘"--:shadowEtchedOut"’

  A solid horizontal line with a 3-d pushed-out appearance.
  

  ‘"--:shadowDoubleEtchedIn"’

  A solid double horizontal line with a 3-d recessed appearance.
  

  ‘"--:shadowDoubleEtchedOut"’

  A solid double horizontal line with a 3-d pushed-out appearance.
  

  ‘"--:shadowEtchedInDash"’

  A dashed horizontal line with a 3-d recessed appearance.
  

  ‘"--:shadowEtchedOutDash"’

  A dashed horizontal line with a 3-d pushed-out appearance.
  

  ‘"--:shadowDoubleEtchedInDash"’

  A dashed double horizontal line with a 3-d recessed appearance.
  

  ‘"--:shadowDoubleEtchedOutDash"’

  A dashed double horizontal line with a 3-d pushed-out appearance.

• If an element of a menu is a list, it is treated as a submenu. The name of that submenu (the first element in the list) will be used as the name of the item representing this menu on the parent.

The possible keywords are as follows:

:active form

form will be evaluated when the menu that this item is a part of is about to be displayed, and the item will be selectable only if the result is non-nil. If the item is unselectable, it will usually be displayed grayed-out to indicate this.

:suffix form

form will be evaluated when the menu that this item is a part of is about to be displayed, and the resulting string is appended to the displayed name. This provides a convenient way of adding the name of a command's “argument” to the menu, like ‘Kill Buffer NAME’.

:keys string

Normally, the keyboard equivalents of commands in menus are displayed when the “callback” is a symbol. This can be used to specify keys for more complex menu items. It is passed through substitute-command-keys first.

:style style

Specifies what kind of object this menu item is. style be one of the symbols

nil

A normal menu item.

toggle

A toggle button.

radio

A radio button.

button

A menubar button.

The only difference between toggle and radio buttons is how they are displayed. But for consistency, a toggle button should be used when there is one option whose value can be turned on or off, and radio buttons should be used when there is a set of mutually exclusive options. When using a group of radio buttons, you should arrange for no more than one to be marked as selected at a time.

:selected form

Meaningful only when style is toggle, radio or button. This specifies whether the button will be in the selected or unselected state. form is evaluated, as for :active.

:included form

This can be used to control the visibility of a menu item. The form is evaluated and the menu item is only displayed if the result is non-nil. Note that this is different from :active: If :active evaluates to nil, the item will be displayed grayed out, while if :included evaluates to nil, the item will be omitted entirely.

:config symbol

This is an efficient shorthand for :included (memq symbol menubar-configuration). See the variable menubar-configuration.

:accelerator key

A menu accelerator is a keystroke which can be pressed while the menu is visible which will immediately activate the item. key must be a char or the symbol name of a key. See Menu Accelerators.

For example:

      ("File"
       :filter file-menu-filter      ; file-menu-filter is a function that takes
                                     ; one argument (a list of menu items) and
                                     ; returns a list of menu items
       [ "Save As..."    write-file]
       [ "Revert Buffer" revert-buffer :active (buffer-modified-p) ]
       [ "Read Only"     toggle-read-only :style toggle :selected buffer-read-only ]
       )