-* Menu Format:: Format of a menu description.
-* Menubar Format:: How to specify a menubar.
-* Menubar:: Functions for controlling the menubar.
-* Modifying Menus:: Modifying a menu description.
-* Pop-Up Menus:: Functions for specifying pop-up menus.
-* Menu Filters:: Filter functions for the default menubar.
-* Menu Accelerators:: Using and controlling menu accelerator keys
-* Buffers Menu:: The menu that displays the list of buffers.
-
-\1f
-File: lispref.info, Node: Menu Format, Next: Menubar Format, Up: Menus
-
-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. *Note 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. *Note Menu
- Accelerators::.
-
- - Variable: menubar-configuration
- This variable holds a list of symbols, against which the value of
- the `:config' tag for each menubar item will be compared. If a
- menubar item has a `:config' tag, then it is omitted from the
- menubar if that tag is not a member of the `menubar-configuration'
- list.
-
- 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 ]
- )
-
-\1f
-File: lispref.info, Node: Menubar Format, Next: Menubar, Prev: Menu Format, Up: Menus
-
-Format of the Menubar
-=====================
-
- A menubar is a list of menus, menu items, and strings. The format is
-similar to that of a menu, except:
-
- * The first item need not be a string, and is not treated specially.
-
- * A string consisting solely of hyphens is not treated specially.
-
- * If an element of a menubar is `nil', then it is used to represent
- the division between the set of menubar items which are flush-left
- and those which are flush-right. (Note: this isn't completely
- implemented yet.)
-
-\1f
-File: lispref.info, Node: Menubar, Next: Modifying Menus, Prev: Menubar Format, Up: Menus
-
-Menubar
-=======
-
- - Variable: current-menubar
- This variable holds the description of the current menubar. This
- may be buffer-local. When the menubar is changed, the function
- `set-menubar-dirty-flag' has to be called in order for the menubar
- to be updated on the screen.
-
- - Constant: default-menubar
- This variable holds the menubar description of the menubar that is
- visible at startup. This is the value that `current-menubar' has
- at startup.
-
- - Function: set-menubar-dirty-flag
- This function tells XEmacs that the menubar widget has to be
- updated. Changes to the menubar will generally not be visible
- until this function is called.
-
- The following convenience functions are provided for setting the
-menubar. They are equivalent to doing the appropriate action to change
-`current-menubar', and then calling `set-menubar-dirty-flag'. Note
-that these functions copy their argument using `copy-sequence'.
-
- - Function: set-menubar menubar
- This function sets the default menubar to be MENUBAR (*note Menu
- Format::). This is the menubar that will be visible in buffers
- that have not defined their own, buffer-local menubar.
-
- - Function: set-buffer-menubar menubar
- This function sets the buffer-local menubar to be MENUBAR. This
- does not change the menubar in any buffers other than the current
- one.
-
- Miscellaneous:
-
- - Variable: menubar-show-keybindings
- If true, the menubar will display keyboard equivalents. If false,
- only the command names will be displayed.
-
- - Variable: activate-menubar-hook
- Function or functions called before a menubar menu is pulled down.
- These functions are called with no arguments, and should
- interrogate and modify the value of `current-menubar' as desired.
-
- The functions on this hook are invoked after the mouse goes down,
- but before the menu is mapped, and may be used to activate,
- deactivate, add, or delete items from the menus. However, using a
- filter (with the `:filter' keyword in a menu description) is
- generally a more efficient way of accomplishing the same thing,
- because the filter is invoked only when the actual menu goes down.
- With a complex menu, there can be a quite noticeable and
- sometimes aggravating delay if all menu modification is
- implemented using the `activate-menubar-hook'. See above.
-
- These functions may return the symbol `t' to assert that they have
- made no changes to the menubar. If any other value is returned,
- the menubar is recomputed. If `t' is returned but the menubar has
- been changed, then the changes may not show up right away.
- Returning `nil' when the menubar has not changed is not so bad;
- more computation will be done, but redisplay of the menubar will
- still be performed optimally.
-
- - Variable: menu-no-selection-hook
- Function or functions to call when a menu or dialog box is
- dismissed without a selection having been made.
-
-\1f
-File: lispref.info, Node: Modifying Menus, Next: Pop-Up Menus, Prev: Menubar, Up: Menus
-
-Modifying Menus
-===============
-
- The following functions are provided to modify the menubar of one of
-its submenus. Note that these functions modify the menu in-place,
-rather than copying it and making a new menu.
-
- Some of these functions take a "menu path", which is a list of
-strings identifying the menu to be modified. For example, `("File")'
-names the top-level "File" menu. `("File" "Foo")' names a hypothetical
-submenu of "File".
-
- Others take a "menu item path", which is similar to a menu path but
-also specifies a particular item to be modified. For example, `("File"
-"Save")' means the menu item called "Save" under the top-level "File"
-menu. `("Menu" "Foo" "Item")' means the menu item called "Item" under
-the "Foo" submenu of "Menu".
-
- - Function: add-submenu menu-path submenu &optional before
- This function adds a menu to the menubar or one of its submenus.
- If the named menu exists already, it is changed.
-
- MENU-PATH identifies the menu under which the new menu should be
- inserted. If MENU-PATH is `nil', then the menu will be added to
- the menubar itself.
-
- SUBMENU is the new menu to add (*note Menu Format::).
-
- BEFORE, if provided, is the name of a menu before which this menu
- should be added, if this menu is not on its parent already. If
- the menu is already present, it will not be moved.
-
- - Function: add-menu-button menu-path menu-leaf &optional before
- This function adds a menu item to some menu, creating the menu
- first if necessary. If the named item exists already, it is
- changed.
-
- MENU-PATH identifies the menu under which the new menu item should
- be inserted.
-
- MENU-LEAF is a menubar leaf node (*note Menu Format::).
-
- BEFORE, if provided, is the name of a menu before which this item
- should be added, if this item is not on the menu already. If the
- item is already present, it will not be moved.
-
- - Function: delete-menu-item menu-item-path
- This function removes the menu item specified by MENU-ITEM-PATH
- from the menu hierarchy.
-
- - Function: enable-menu-item menu-item-path
- This function makes the menu item specified by MENU-ITEM-PATH be
- selectable.
-
- - Function: disable-menu-item menu-item-path
- This function makes the menu item specified by MENU-ITEM-PATH be
- unselectable.
-
- - Function: relabel-menu-item menu-item-path new-name
- This function changes the string of the menu item specified by
- MENU-ITEM-PATH. NEW-NAME is the string that the menu item will be
- printed as from now on.
-
- The following function can be used to search for a particular item in
-a menubar specification, given a path to the item.
-
- - Function: find-menu-item menubar menu-item-path &optional parent
- This function searches MENUBAR for the item given by
- MENU-ITEM-PATH starting from PARENT (`nil' means start at the top
- of MENUBAR). This function returns `(ITEM . PARENT)', where
- PARENT is the immediate parent of the item found (a menu
- description), and ITEM is either a vector, list, or string,
- depending on the nature of the menu item.
-
- This function signals an error if the item is not found.
-
- The following deprecated functions are also documented, so that
-existing code can be understood. You should not use these functions in
-new code.
-
- - Function: add-menu menu-path menu-name menu-items &optional before
- This function adds a menu to the menubar or one of its submenus.
- If the named menu exists already, it is changed. This is
- obsolete; use `add-submenu' instead.
-
- MENU-PATH identifies the menu under which the new menu should be
- inserted. If MENU-PATH is `nil', then the menu will be added to
- the menubar itself.
-
- MENU-NAME is the string naming the menu to be added; MENU-ITEMS is
- a list of menu items, strings, and submenus. These two arguments
- are the same as the first and following elements of a menu
- description (*note Menu Format::).
-
- BEFORE, if provided, is the name of a menu before which this menu
- should be added, if this menu is not on its parent already. If the
- menu is already present, it will not be moved.
-
- - Function: add-menu-item menu-path item-name function enabled-p
- &optional before
- This function adds a menu item to some menu, creating the menu
- first if necessary. If the named item exists already, it is
- changed. This is obsolete; use `add-menu-button' instead.
-
- MENU-PATH identifies the menu under which the new menu item should
- be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first,
- second, and third elements of a menu item vector (*note Menu
- Format::).
-
- BEFORE, if provided, is the name of a menu item before which this
- item should be added, if this item is not on the menu already. If
- the item is already present, it will not be moved.
-
-\1f
-File: lispref.info, Node: Menu Filters, Next: Menu Accelerators, Prev: Pop-Up Menus, Up: Menus
-
-Menu Filters
-============
-
- The following filter functions are provided for use in
-`default-menubar'. You may want to use them in your own menubar
-description.
-
- - Function: file-menu-filter menu-items
- This function changes the arguments and sensitivity of these File
- menu items:
-
- `Delete Buffer'
- Has the name of the current buffer appended to it.
-
- `Print Buffer'
- Has the name of the current buffer appended to it.
-
- `Pretty-Print Buffer'
- Has the name of the current buffer appended to it.
-
- `Save Buffer'
- Has the name of the current buffer appended to it, and is
- sensitive only when the current buffer is modified.
-
- `Revert Buffer'
- Has the name of the current buffer appended to it, and is
- sensitive only when the current buffer has a file.
-
- `Delete Frame'
- Sensitive only when there is more than one visible frame.
-
- - Function: edit-menu-filter menu-items
- This function changes the arguments and sensitivity of these Edit
- menu items:
-
- `Cut'
- Sensitive only when XEmacs owns the primary X Selection (if
- `zmacs-regions' is `t', this is equivalent to saying that
- there is a region selected).
-
- `Copy'
- Sensitive only when XEmacs owns the primary X Selection.
-
- `Clear'
- Sensitive only when XEmacs owns the primary X Selection.
-
- `Paste'
- Sensitive only when there is an owner for the X Clipboard
- Selection.
-
- `Undo'
- Sensitive only when there is undo information. While in the
- midst of an undo, this is changed to `Undo More'.
-
- - Function: buffers-menu-filter menu-items
- This function sets up the Buffers menu. *Note Buffers Menu::, for
- more information.