Info Catalog elisp: Simple Menu Items elisp: Defining Menus elisp: Menu Separators

elisp: Extended Menu Items

 
 21.17.1.2 Extended Menu Items
 .............................
 
 An extended-format menu item is a more flexible and also cleaner
 alternative to the simple format.  You define an event type with a
 binding that’s a list starting with the symbol ‘menu-item’.  For a
 non-selectable string, the binding looks like this:
 
      (menu-item ITEM-NAME)
 
 A string starting with two or more dashes specifies a separator line;
 see Menu Separators.
 
    To define a real menu item which can be selected, the extended format
 binding looks like this:
 
      (menu-item ITEM-NAME REAL-BINDING
          . ITEM-PROPERTY-LIST)
 
 Here, ITEM-NAME is an expression which evaluates to the menu item
 string.  Thus, the string need not be a constant.  The third element,
 REAL-BINDING, is the command to execute.  The tail of the list,
 ITEM-PROPERTY-LIST, has the form of a property list which contains other
 information.
 
    Here is a table of the properties that are supported:
 
 ‘:enable FORM’
      The result of evaluating FORM determines whether the item is
      enabled (non-‘nil’ means yes).  If the item is not enabled, you
      can’t really click on it.
 
 ‘:visible FORM’
      The result of evaluating FORM determines whether the item should
      actually appear in the menu (non-‘nil’ means yes).  If the item
      does not appear, then the menu is displayed as if this item were
      not defined at all.
 
 ‘:help HELP’
      The value of this property, HELP, specifies a help-echo string to
      display while the mouse is on that item.  This is displayed in the
      same way as ‘help-echo’ text properties (Help display).
      Note that this must be a constant string, unlike the ‘help-echo’
      property for text and overlays.
 
 ‘:button (TYPE . SELECTED)’
      This property provides a way to define radio buttons and toggle
      buttons.  The CAR, TYPE, says which: it should be ‘:toggle’ or
      ‘:radio’.  The CDR, SELECTED, should be a form; the result of
      evaluating it says whether this button is currently selected.
 
      A “toggle” is a menu item which is labeled as either on or off
      according to the value of SELECTED.  The command itself should
      toggle SELECTED, setting it to ‘t’ if it is ‘nil’, and to ‘nil’ if
      it is ‘t’.  Here is how the menu item to toggle the
      ‘debug-on-error’ flag is defined:
 
           (menu-item "Debug on Error" toggle-debug-on-error
                      :button (:toggle
                               . (and (boundp 'debug-on-error)
                                      debug-on-error)))
 
      This works because ‘toggle-debug-on-error’ is defined as a command
      which toggles the variable ‘debug-on-error’.
 
      “Radio buttons” are a group of menu items, in which at any time one
      and only one is selected.  There should be a variable whose value
      says which one is selected at any time.  The SELECTED form for each
      radio button in the group should check whether the variable has the
      right value for selecting that button.  Clicking on the button
      should set the variable so that the button you clicked on becomes
      selected.
 
 ‘:key-sequence KEY-SEQUENCE’
      This property specifies which key sequence is likely to be bound to
      the same command invoked by this menu item.  If you specify the
      right key sequence, that makes preparing the menu for display run
      much faster.
 
      If you specify the wrong key sequence, it has no effect; before
      Emacs displays KEY-SEQUENCE in the menu, it verifies that
      KEY-SEQUENCE is really equivalent to this menu item.
 
 ‘:key-sequence nil’
      This property indicates that there is normally no key binding which
      is equivalent to this menu item.  Using this property saves time in
      preparing the menu for display, because Emacs does not need to
      search the keymaps for a keyboard equivalent for this menu item.
 
      However, if the user has rebound this item’s definition to a key
      sequence, Emacs ignores the ‘:keys’ property and finds the keyboard
      equivalent anyway.
 
 ‘:keys STRING’
      This property specifies that STRING is the string to display as the
      keyboard equivalent for this menu item.  You can use the ‘\\[...]’
      documentation construct in STRING.
 
 ‘:filter FILTER-FN’
      This property provides a way to compute the menu item dynamically.
      The property value FILTER-FN should be a function of one argument;
      when it is called, its argument will be REAL-BINDING.  The function
      should return the binding to use instead.
 
      Emacs can call this function at any time that it does redisplay or
      operates on menu data structures, so you should write it so it can
      safely be called at any time.
 

Info Catalog elisp: Simple Menu Items elisp: Defining Menus elisp: Menu Separators