@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 Copyright (C) 1990-1994, 1998-2011 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
When commands are remapped (@pxref{Remapping Commands}),
@code{key-binding} normally processes command remappings so as to
-returns the remapped command that will actually be executed. However,
+return the remapped command that will actually be executed. However,
if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
remappings and returns the binding directly specified for @var{key}.
The @code{global-set-key} and @code{local-set-key} functions are
convenient interfaces for these operations (@pxref{Key Binding
Commands}). You can also use @code{define-key}, a more general
-function; then you must specify explicitly the map to change.
+function; then you must explicitly specify the map to change.
When choosing the key sequences for Lisp programs to rebind, please
follow the Emacs conventions for use of various keys (@pxref{Key
if an ordinary binding specifies @code{my-kill-line}, this keymap will
remap it to @code{my-other-kill-line}.
+To undo the remapping of a command, remap it to @code{nil}; e.g.
+
+@smallexample
+(define-key my-mode-map [remap kill-line] nil)
+@end smallexample
+
@defun command-remapping command &optional position keymaps
This function returns the remapping for @var{command} (a symbol),
given the current active keymaps. If @var{command} is not remapped
@noindent
and your language environment is multibyte Latin-1, these commands
-actually bind the multibyte character with code 2294, not the unibyte
-Latin-1 character with code 246 (@kbd{M-v}). In order to use this
-binding, you need to enter the multibyte Latin-1 character as keyboard
-input. One way to do this is by using an appropriate input method
-(@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}).
-
- If you want to use a unibyte character in the key binding, you can
-construct the key sequence string using @code{multibyte-char-to-unibyte}
-or @code{string-make-unibyte} (@pxref{Converting Representations}).
+actually bind the multibyte character with code 246, not the byte
+code 246 (@kbd{M-v}) sent by a Latin-1 terminal. In order to use this
+binding, you need to teach Emacs how to decode the keyboard by using an
+appropriate input method (@pxref{Input Methods, , Input Methods, emacs, The GNU
+Emacs Manual}).
@deffn Command global-set-key key binding
This function sets the binding of @var{key} in the current global map
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
@cindex defining menus
@cindex menu prompt string
@cindex prompt string (of menu)
+@cindex menu item
A keymap acts as a menu if it has an @dfn{overall prompt string},
which is a string that appears as an element of the keymap.
of menus in advance. To force recalculation of the menu bar, call
@code{force-mode-line-update} (@pxref{Mode Line Format}).
- You've probably noticed that menu items show the equivalent keyboard key
-sequence (if any) to invoke the same command. To save time on
-recalculation, menu display caches this information in a sublist in the
-binding, like this:
-
-@c This line is not too long--rms.
-@example
-(@var{item-string} @r{[}@var{help}@r{]} (@var{key-binding-data}) . @var{real-binding})
-@end example
-
-@noindent
-Don't put these sublists in the menu item yourself; menu display
-calculates them automatically. Don't mention keyboard equivalents in
-the item strings themselves, since that is redundant.
-
@node Extended Menu Items
@subsubsection Extended Menu Items
@kindex menu-item
+@cindex extended menu item
An extended-format menu item is a more flexible and also cleaner
alternative to the simple format. You define an event type with a
@var{item-property-list}, has the form of a property list which contains
other information.
- When an equivalent keyboard key binding is cached, the extended menu
-item binding looks like this:
-
-@example
-(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data})
- . @var{item-property-list})
-@end example
-
Here is a table of the properties that are supported:
@table @code
@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
[work] '("Work" . work-command) 'break)
@end example
@end defun
-
-@ignore
- arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794
-@end ignore