Info Catalog elisp: Modifying Menus elisp: Menu Keymaps

elisp: Easy Menu

 
 21.17.8 Easy Menu
 -----------------
 
 The following macro provides a convenient way to define pop-up menus
 and/or menu bar menus.
 
  -- Macro: easy-menu-define symbol maps doc menu
      This macro defines a pop-up menu and/or menu bar submenu, whose
      contents are given by MENU.
 
      If SYMBOL is non-‘nil’, it should be a symbol; then this macro
      defines SYMBOL as a function for popping up the menu (Pop-Up
      Menus), with DOC as its documentation string.  SYMBOL should not
      be quoted.
 
      Regardless of the value of SYMBOL, if MAPS is a keymap, the menu is
      added to that keymap, as a top-level menu for the menu bar (
      Menu Bar).  It can also be a list of keymaps, in which case the
      menu is added separately to each of those keymaps.
 
      The first element of MENU must be a string, which serves as the
      menu label.  It may be followed by any number of the following
      keyword-argument pairs:
 
      ‘:filter FUNCTION’
           FUNCTION must be a function which, if called with one
           argument—the list of the other menu items—returns the actual
           items to be displayed in the menu.
 
      ‘:visible INCLUDE’
           INCLUDE is an expression; if it evaluates to ‘nil’, the menu
           is made invisible.  ‘:included’ is an alias for ‘:visible’.
 
      ‘:active ENABLE’
           ENABLE is an expression; if it evaluates to ‘nil’, the menu is
           not selectable.  ‘:enable’ is an alias for ‘:active’.
 
      The remaining elements in MENU are menu items.
 
      A menu item can be a vector of three elements, ‘[NAME CALLBACK
      ENABLE]’.  NAME is the menu item name (a string).  CALLBACK is a
      command to run, or an expression to evaluate, when the item is
      chosen.  ENABLE is an expression; if it evaluates to ‘nil’, the
      item is disabled for selection.
 
      Alternatively, a menu item may have the form:
 
              [ NAME CALLBACK [ KEYWORD ARG ]... ]
 
      where NAME and CALLBACK have the same meanings as above, and each
      optional KEYWORD and ARG pair should be one of the following:
 
      ‘:keys KEYS’
           KEYS is a keyboard equivalent to the menu item (a string).
           This is normally not needed, as keyboard equivalents are
           computed automatically.  KEYS is expanded with
           ‘substitute-command-keys’ before it is displayed (Keys
           in Documentation).
 
      ‘:key-sequence KEYS’
           KEYS is a hint for speeding up Emacs’s first display of the
           menu.  It should be ‘nil’ if you know that the menu item has
           no keyboard equivalent; otherwise it should be a string or
           vector specifying a keyboard equivalent for the menu item.
 
      ‘:active ENABLE’
           ENABLE is an expression; if it evaluates to ‘nil’, the item is
           make unselectable..  ‘:enable’ is an alias for ‘:active’.
 
      ‘:visible INCLUDE’
           INCLUDE is an expression; if it evaluates to ‘nil’, the item
           is made invisible.  ‘:included’ is an alias for ‘:visible’.
 
      ‘:label FORM’
           FORM is an expression that is evaluated to obtain a value
           which serves as the menu item’s label (the default is NAME).
 
      ‘:suffix FORM’
           FORM is an expression that is dynamically evaluated and whose
           value is concatenated with the menu entry’s label.
 
      ‘:style STYLE’
           STYLE is a symbol describing the type of menu item; it should
           be ‘toggle’ (a checkbox), or ‘radio’ (a radio button), or
           anything else (meaning an ordinary menu item).
 
      ‘:selected SELECTED’
           SELECTED is an expression; the checkbox or radio button is
           selected whenever the expression’s value is non-‘nil’.
 
      ‘:help HELP’
           HELP is a string describing the menu item.
 
      Alternatively, a menu item can be a string.  Then that string
      appears in the menu as unselectable text.  A string consisting of
      dashes is displayed as a separator (Menu Separators).
 
      Alternatively, a menu item can be a list with the same format as
      MENU.  This is a submenu.
 
    Here is an example of using ‘easy-menu-define’ to define a menu
 similar to the one defined in the example in Menu Bar:
 
      (easy-menu-define words-menu global-map
        "Menu for word navigation commands."
        '("Words"
           ["Forward word" forward-word]
           ["Backward word" backward-word]))
 

Info Catalog elisp: Modifying Menus elisp: Menu Keymaps