@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/keymaps
@node Keymaps, Modes, Command Loop, Top
is found. The whole process is called @dfn{key lookup}.
@menu
-* Key Sequences:: Key sequences as Lisp objects.
+* Key Sequences:: Key sequences as Lisp objects.
* Keymap Basics:: Basic concepts of keymaps.
-* Format of Keymaps:: What a keymap looks like as a Lisp object.
-* Creating Keymaps:: Functions to create and copy keymaps.
-* Inheritance and Keymaps:: How one keymap can inherit the bindings
- of another keymap.
+* Format of Keymaps:: What a keymap looks like as a Lisp object.
+* Creating Keymaps:: Functions to create and copy keymaps.
+* Inheritance and Keymaps:: How one keymap can inherit the bindings
+ of another keymap.
* Prefix Keys:: Defining a key with a keymap as its definition.
* Active Keymaps:: How Emacs searches the active keymaps
for a key binding.
* Searching Keymaps:: A pseudo-Lisp summary of searching active maps.
* Controlling Active Maps:: Each buffer has a local keymap
to override the standard (global) bindings.
- A minor mode can also override them.
+ A minor mode can also override them.
* Key Lookup:: Finding a key's binding in one keymap.
* Functions for Key Lookup:: How to request key lookup.
* Changing Key Bindings:: Redefining a key in a keymap.
* Translation Keymaps:: Keymaps for translating sequences of events.
* Key Binding Commands:: Interactive interfaces for redefining keys.
* Scanning Keymaps:: Looking through all keymaps, for printing help.
-* Menu Keymaps:: Defining a menu as a keymap.
+* Menu Keymaps:: Defining a menu as a keymap.
@end menu
@node Key Sequences
feature.
@menu
-* Defining Menus:: How to make a keymap that defines a menu.
-* Mouse Menus:: How users actuate the menu with the mouse.
-* Keyboard Menus:: How users actuate the menu with the keyboard.
-* Menu Example:: Making a simple menu.
-* Menu Bar:: How to customize the menu bar.
+* Defining Menus:: How to make a keymap that defines a menu.
+* Mouse Menus:: How users actuate the menu with the mouse.
+* Keyboard Menus:: How users actuate the menu with the keyboard.
+* Menu Example:: Making a simple menu.
+* Menu Bar:: How to customize the menu bar.
* Tool Bar:: A tool bar is a row of images.
* Modifying Menus:: How to add new items to a menu.
@end menu
@smallexample
(define-key menu-bar-replace-menu [tags-repl-continue]
'(menu-item "Continue Replace" tags-loop-continue
- :help "Continue last tags replace operation"))
+ :help "Continue last tags replace operation"))
(define-key menu-bar-replace-menu [tags-repl]
'(menu-item "Replace in tagged files" tags-query-replace
- :help "Interactively replace a regexp in all tagged files"))
+ :help "Interactively replace a regexp in all tagged files"))
(define-key menu-bar-replace-menu [separator-replace-tags]
'(menu-item "--"))
;; @r{@dots{}}
@cindex menu bar
Most window systems allow each frame to have a @dfn{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'' @code{menu-bar}, as defined in the active keymaps.
+permanently displayed menu stretching horizontally across the top of
+the frame. (In order for a frame to display a menu bar, its
+@code{menu-bar-lines} parameter must be greater than zero.
+@xref{Layout Parameters}.)
+
+ The items of the menu bar are the subcommands of the fake ``function
+key'' @code{menu-bar}, as defined in the active keymaps.
To add an item to the menu bar, invent a fake ``function key'' of your
own (let's call it @var{key}), and make a binding for the key sequence
from the keymaps that would be active if @code{overriding-local-map}
were @code{nil}. @xref{Active Keymaps}.
- In order for a frame to display a menu bar, its @code{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 @code{menu-bar-lines}. @xref{Layout
-Parameters}.
-
Here's an example of setting up a menu bar item:
@example
@end example
@noindent
-@code{edit} is the fake function key used by the global map for the
-@samp{Edit} menu bar item. The main reason to suppress a global
+Here, @code{edit} is the fake function key used by the global map for
+the @samp{Edit} menu bar item. The main reason to suppress a global
menu bar item is to regain space for mode-specific items.
@defvar menu-bar-final-items
in the usual case.
@end defvar
+Next to every menu bar item, Emacs displays a key binding that runs
+the same command (if such a key binding exists). This serves as a
+convenient hint for users who do not know the key binding. If a
+command has multiple bindings, Emacs normally displays the first one
+it finds. You can specify one particular key binding by assigning an
+@code{:advertised-binding} symbol property to the command. For
+instance, the following tells Emacs to show @kbd{C-/} for the
+@code{undo} menu item:
+
+@smallexample
+(put 'undo :advertised-binding [?\C-/])
+@end smallexample
+
+@noindent
+If the @code{:advertised-binding} property specifies a key binding
+that the command does not actually have, it is ignored.
+
@node Tool Bar
@subsection Tool bars
@cindex tool bar
By default, the global map binds @code{[tool-bar]} as follows:
@example
(global-set-key [tool-bar]
- '(menu-item "tool bar" ignore
- :filter (lambda (ignore) tool-bar-map)))
+ '(menu-item "tool bar" ignore
+ :filter (lambda (ignore) tool-bar-map)))
@end example
@noindent
Thus the tool bar map is derived dynamically from the value of variable