@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990-1994, 1998-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/keymaps
-@node Keymaps, Modes, Command Loop, Top
+@node Keymaps
@chapter Keymaps
@cindex keymap
A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one
or more input events that form a unit. Input events include
-characters, function keys, and mouse actions (@pxref{Input Events}).
+characters, function keys, mouse actions, or system events external to
+Emacs, such as @code{iconify-frame} (@pxref{Input Events}).
The Emacs Lisp representation for a key sequence is a string or
vector. Unless otherwise stated, any Emacs Lisp function that accepts
a key sequence as an argument can handle both representations.
constituent events; thus, @code{"\C-xl"} represents the key sequence
@kbd{C-x l}.
- Key sequences containing function keys, mouse button events, or
-non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be
-represented as strings; they have to be represented as vectors.
+ Key sequences containing function keys, mouse button events, system
+events, or non-@acronym{ASCII} characters such as @kbd{C-=} or
+@kbd{H-a} cannot be represented as strings; they have to be
+represented as vectors.
In the vector representation, each element of the vector represents
an input event, in its Lisp form. @xref{Input Events}. For example,
@node Inheritance and Keymaps
@section Inheritance and Keymaps
@cindex keymap inheritance
-@cindex inheriting a keymap's bindings
+@cindex inheritance, keymap
A keymap can inherit the bindings of another keymap, which we call the
@dfn{parent keymap}. Such a keymap looks like this:
@example
(defvar help-mode-map
(let ((map (make-sparse-keymap)))
- (set-keymap-parent map (make-composed-keymap button-buffer-map
- special-mode-map))
+ (set-keymap-parent map
+ (make-composed-keymap button-buffer-map special-mode-map))
... map) ... )
@end example
@defun current-local-map
This function returns the current buffer's local keymap, or @code{nil}
if it has none. In the following example, the keymap for the
-@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
+@file{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse
keymap.
This feature permits you to define one key as an alias for another key.
For example, an entry whose @sc{car} is the keymap called @code{esc-map}
and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
-binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
+binding of @kbd{Meta-@key{SPC}}, whatever that may be''.
@end itemize
@item @var{symbol}
@end defvar
@cindex key translation function
-You can use @code{input-decode-map}, @code{local-function-key-map}, or
-@code{key-translation-map} for more than simple aliases, by using a
-function, instead of a key sequence, as the ``translation'' of a key.
-Then this function is called to compute the translation of that key.
+You can use @code{input-decode-map}, @code{local-function-key-map},
+and @code{key-translation-map} for more than simple aliases, by using
+a function, instead of a key sequence, as the ``translation'' of a
+key. Then this function is called to compute the translation of that
+key.
The key translation function receives one argument, which is the prompt
that was specified in @code{read-key-sequence}---or @code{nil} if the
is a list of keymaps, only those keymaps are searched.
Usually it's best to use @code{overriding-local-map} as the expression
-for @var{keymap}. Then @code{where-is-internal} searches precisely the
-keymaps that are active. To search only the global map, pass
-@code{(keymap)} (an empty keymap) as @var{keymap}.
+for @var{keymap}. Then @code{where-is-internal} searches precisely
+the keymaps that are active. To search only the global map, pass the
+value @code{(keymap)} (an empty keymap) as @var{keymap}.
If @var{firstonly} is @code{non-ascii}, then the value is a single
vector representing the first key sequence found, rather than a list of
follow indirect keymap bindings. This makes it possible to search for
an indirect definition itself.
-When command remapping is in effect (@pxref{Remapping Commands}),
-@code{where-is-internal} figures out when a command will be run due to
-remapping and reports keys accordingly. It also returns @code{nil} if
-@var{command} won't really be run because it has been remapped to some
-other command. However, if @var{no-remap} is non-@code{nil}.
-@code{where-is-internal} ignores remappings.
+The fifth argument, @var{no-remap}, determines how this function
+treats command remappings (@pxref{Remapping Commands}). There are two
+cases of interest:
-@smallexample
-@group
-(where-is-internal 'describe-function)
- @result{} ([8 102] [f1 102] [help 102]
- [menu-bar help-menu describe describe-function])
-@end group
-@end smallexample
+@table @asis
+@item If a command @var{other-command} is remapped to @var{command}:
+If @var{no-remap} is @code{nil}, find the bindings for
+@var{other-command} and treat them as though they are also bindings
+for @var{command}. If @var{no-remap} is non-@code{nil}, include the
+vector @code{[remap @var{other-command}]} in the list of possible key
+sequences, instead of finding those bindings.
+
+@item If @var{command} is remapped to @var{other-command}:
+If @var{no-remap} is @code{nil}, return the bindings for
+@var{other-command} rather than @var{command}. If @var{no-remap} is
+non-@code{nil}, return the bindings for @var{command}, ignoring the
+fact that it is remapped.
+@end table
@end defun
@deffn Command describe-bindings &optional prefix buffer-or-name
This function creates a listing of all current key bindings, and
-displays it in a buffer named @samp{*Help*}. The text is grouped by
+displays it in a buffer named @file{*Help*}. The text is grouped by
modes---minor modes first, then the major mode, then global bindings.
If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
which toggles the variable @code{debug-on-error}.
@dfn{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
+and only one is ``selected''. There should be a variable whose value
says which one is selected at any time. The @var{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
Note the symbols which the bindings are ``made for''; these appear
inside square brackets, in the key sequence being defined. In some
cases, this symbol is the same as the command name; sometimes it is
-different. These symbols are treated as ``function keys,'' but they are
+different. These symbols are treated as ``function keys'', but they are
not real function keys on the keyboard. They do not affect the
functioning of the menu itself, but they are ``echoed'' in the echo area
when the user selects from the menu, and they appear in the output of
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.
+@code{:advertised-binding} symbol property to the command. @xref{Keys
+in Documentation}.
@node Tool Bar
@subsection Tool bars