GNU Info

(elisp)Menu Bar

---

Next: Tool Bar Prev: Menu Example Up: Menu Keymaps

---

Enter node , (file) or (file)node

The Menu Bar
------------

   Most window systems allow each frame to have a "menu bar"--a
permanently displayed menu stretching horizontally across the top of the
frame.  The items of the menu bar are the subcommands of the fake
"function key" `menu-bar', as defined by all the active keymaps.

   To add an item to the menu bar, invent a fake "function key" of your
own (let's call it KEY), and make a binding for the key sequence
`[menu-bar KEY]'.  Most often, the binding is a menu keymap, so that
pressing a button on the menu bar item leads to another menu.

   When more than one active keymap defines the same fake function key
for the menu bar, the item appears just once.  If the user clicks on
that menu bar item, it brings up a single, combined menu containing all
the subcommands of that item--the global subcommands, the local
subcommands, and the minor mode subcommands.

   The variable `overriding-local-map' is normally ignored when
determining the menu bar contents.  That is, the menu bar is computed
from the keymaps that would be active if `overriding-local-map' were
`nil'.  Note: Active Keymaps.

   In order for a frame to display a menu bar, its `menu-bar-lines'
parameter must be greater than zero.  Emacs uses just one line for the
menu bar itself; if you specify more than one line, the other lines
serve to separate the menu bar from the windows in the frame.  We
recommend 1 or 2 as the value of `menu-bar-lines'.  Note: Window Frame
Parameters.

   Here's an example of setting up a menu bar item:

     (modify-frame-parameters (selected-frame)
                              '((menu-bar-lines . 2)))
     
     ;; Make a menu keymap (with a prompt string)
     ;; and make it the menu bar item's definition.
     (define-key global-map [menu-bar words]
       (cons "Words" (make-sparse-keymap "Words")))
     
     ;; Define specific subcommands in this menu.
     (define-key global-map
       [menu-bar words forward]
       '("Forward word" . forward-word))
     (define-key global-map
       [menu-bar words backward]
       '("Backward word" . backward-word))

   A local keymap can cancel a menu bar item made by the global keymap
by rebinding the same fake function key with `undefined' as the
binding.  For example, this is how Dired suppresses the `Edit' menu bar
item:

     (define-key dired-mode-map [menu-bar edit] 'undefined)

`edit' is the fake function key used by the global map for the `Edit'
menu bar item.  The main reason to suppress a global menu bar item is
to regain space for mode-specific items.

 - Variable: menu-bar-final-items
     Normally the menu bar shows global items followed by items defined
     by the local maps.

     This variable holds a list of fake function keys for items to
     display at the end of the menu bar rather than in normal sequence.
     The default value is `(help-menu)'; thus, the `Help' menu item
     normally appears at the end of the menu bar, following local menu
     items.

 - Variable: menu-bar-update-hook
     This normal hook is run whenever the user clicks on the menu bar,
     before displaying a submenu.  You can use it to update submenus
     whose contents should vary.