comparison lispref/keymaps.texi @ 90796:4ef881a120fe

Merge from emacs--devo--0 Patches applied: * emacs--devo--0 (patch 675-697) - Update from CVS - Merge from gnus--rel--5.10 - Release ERC 5.2. * gnus--rel--5.10 (patch 211-215) - Update from CVS - Merge from emacs--devo--0 Revision: [e-mail]/emacs--unicode--0--patch-189

90795:b9182b6a90c9

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.

  In the string representation, alphanumeric characters ordinarily
stand for themselves; for example, @code{"a"} represents @kbd{a} and
and @code{"2"} represents @kbd{2}.  Control character events are
prefixed by the substring @code{"\C-"}, and meta characters by
@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}.
In addition, the @key{TAB}, @key{RET}, @key{ESC}, and @key{DEL} events
are represented by @code{"\t"}, @code{"\r"}, @code{"\e"}, and

@end example
@end defun

@node Searching Keymaps
@section Searching the Active Keymaps

  After translation of event subsequences (@pxref{Translation
Keymaps}) Emacs looks for them in the active keymaps.  Here is a
pseudo-Lisp description of the order and conditions for searching
them:

new binding is added at the beginning of @var{keymap}.  The order of
bindings in a keymap makes no difference for keyboard input, but it
does matter for menu keymaps (@pxref{Menu Keymaps}).
@end defun

  Here is an example that creates a sparse keymap and makes a number of
bindings in it:

@smallexample
@group
(setq map (make-sparse-keymap))

@code{my-other-kill-line}.  If an ordinary key binding specifies
@code{kill-line}, this keymap will remap it to @code{my-kill-line};
if an ordinary binding specifies @code{my-kill-line}, this keymap will
remap it to @code{my-other-kill-line}.

@defun command-remapping command &optional position
This function returns the remapping for @var{command} (a symbol),
given the current active keymaps.  If @var{command} is not remapped
(which is the usual situation), or not a symbol, the function returns
@code{nil}.  @code{position} can optionally specify a buffer position
or an event position to determine the keymaps to use, as in
@code{key-binding}.
@end defun

@node Translation Keymaps
@section Keymaps for Translating Sequences of Events

  This section describes keymaps that are used during reading a key
sequence, to translate certain event sequences into others.
@code{read-key-sequence} checks every subsequence of the key sequence
being read, as it is read, against @code{function-key-map} and then

90796:4ef881a120fe

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.

  In the string representation, alphanumeric characters ordinarily
stand for themselves; for example, @code{"a"} represents @kbd{a}
and @code{"2"} represents @kbd{2}.  Control character events are
prefixed by the substring @code{"\C-"}, and meta characters by
@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}.
In addition, the @key{TAB}, @key{RET}, @key{ESC}, and @key{DEL} events
are represented by @code{"\t"}, @code{"\r"}, @code{"\e"}, and

@end example
@end defun

@node Searching Keymaps
@section Searching the Active Keymaps
@cindex searching active keymaps for keys

  After translation of event subsequences (@pxref{Translation
Keymaps}) Emacs looks for them in the active keymaps.  Here is a
pseudo-Lisp description of the order and conditions for searching
them:

new binding is added at the beginning of @var{keymap}.  The order of
bindings in a keymap makes no difference for keyboard input, but it
does matter for menu keymaps (@pxref{Menu Keymaps}).
@end defun

  This example creates a sparse keymap and makes a number of
bindings in it:

@smallexample
@group
(setq map (make-sparse-keymap))

@code{my-other-kill-line}.  If an ordinary key binding specifies
@code{kill-line}, this keymap will remap it to @code{my-kill-line};
if an ordinary binding specifies @code{my-kill-line}, this keymap will
remap it to @code{my-other-kill-line}.

@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
(which is the usual situation), or not a symbol, the function returns
@code{nil}.  @code{position} can optionally specify a buffer position
or an event position to determine the keymaps to use, as in
@code{key-binding}.

If the optional argument @code{keymaps} is non-@code{nil}, it
specifies a list of keymaps to search in.  This argument is ignored if
@code{position} is non-@code{nil}.
@end defun

@node Translation Keymaps
@section Keymaps for Translating Sequences of Events
@cindex keymaps for translating events

  This section describes keymaps that are used during reading a key
sequence, to translate certain event sequences into others.
@code{read-key-sequence} checks every subsequence of the key sequence
being read, as it is read, against @code{function-key-map} and then