comparison lispref/keymaps.texi @ 72905:310304c34121

(Remapping Commands, Searching Keymaps) (Active Keymaps): Clean up previous change.

72904:425ede302504

the keymaps of any enabled minor modes, the current buffer's local
keymap, and the global keymap, in that order.  Emacs searches for each
input key sequence in all these keymaps.  @xref{Searching Keymaps},
for more details of this procedure.

This process is somewhat modified for mouse events: the local modes and
keymaps of the buffer corresponding to the mouse click position are
searched instead, text properties are taken from the mouse click
position in the buffer rather than point, and if the click happens on a
string embedded with a @code{display}, @code{before-string}, or
@code{after-string} text property (@pxref{Special Properties}) or
overlay property (@pxref{Overlay Properties}), any non-@code{nil} maps
specified with text properties of this string are searched instead of
those of the buffer.

  The @dfn{global keymap} holds the bindings of keys that are defined
regardless of the current buffer, such as @kbd{C-f}.  The variable
@code{global-map} holds this keymap, which is always active.

@code{overriding-terminal-local-map}, but if @var{olp} is
non-@code{nil} then it pays attention to them.
@end defun

@defun key-binding key &optional accept-defaults no-remap position
This function returns the binding for @var{key} according to the current
active keymaps.  The result is @code{nil} if @var{key} is undefined in
the keymaps.  If @var{key} is a key sequence started with the mouse, the
consulted maps will be changed accordingly.

@c Emacs 19 feature
The argument @var{accept-defaults} controls checking for default
bindings, as in @code{lookup-key} (above).

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,
if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
remappings and returns the binding directly specified for @var{key}.

If @var{position} is non-@code{nil}, it specifies either a buffer
position or a position like those returned from @code{event-start}.  In
this case, @var{position} instead of @var{key} determines the
click-specific maps.

An error is signaled if @var{key} is not a string or a vector.

@example
@group

              (@var{find-in} (current-local-map))))))
    (@var{find-in} (current-global-map)))
@end lisp

@noindent
The @var{find-in} and @var{find-in-any} are pseudo functions that search
in one keymap and in an alist of keymaps, respectively.  (Searching a
single keymap for a binding is called @dfn{key lookup}; see @ref{Key
Lookup}.)  Mouse events on strings will use text properties from the
string if non-@code{nil} instead of the buffer.  Also, point and current
buffer for mouse-based events are switched to correspond to the position
of the event start while performing the lookup.

@enumerate
@item
The function finally found may be remapped
(@pxref{Remapping Commands}).

@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 a position
like those returned from @code{event-start}: in that case, the active
maps are changed like they are in @code{key-binding}.
@end defun

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

72905:310304c34121

the keymaps of any enabled minor modes, the current buffer's local
keymap, and the global keymap, in that order.  Emacs searches for each
input key sequence in all these keymaps.  @xref{Searching Keymaps},
for more details of this procedure.

  When the key sequence starts with a mouse event (optionally preceded
by a symbolic prefix), the active keymaps are determined based on the
position in that event.  If the event happened on a string embedded
with a @code{display}, @code{before-string}, or @code{after-string}
property (@pxref{Special Properties}), the non-@code{nil} map
properties of the string override those of the buffer.

  The @dfn{global keymap} holds the bindings of keys that are defined
regardless of the current buffer, such as @kbd{C-f}.  The variable
@code{global-map} holds this keymap, which is always active.

@code{overriding-terminal-local-map}, but if @var{olp} is
non-@code{nil} then it pays attention to them.
@end defun

@defun key-binding key &optional accept-defaults no-remap position
This function returns the binding for @var{key} according to the
current active keymaps.  The result is @code{nil} if @var{key} is
undefined in the keymaps.

The argument @var{accept-defaults} controls checking for default
bindings, as in @code{lookup-key} (above).

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,
if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
remappings and returns the binding directly specified for @var{key}.

If @var{key} starts with a mouse event (perhaps following a prefix
event), the maps to be consulted are determined based on the event's
position.  Otherwise, they are determined based on the value of point.
However, you can override either of them by specifying @var{position}.
If @var{position} is non-@code{nil}, it should be either a buffer
position or an event position like the value of @code{event-start}.
Then the maps consulted are determined based on @var{position}.

An error is signaled if @var{key} is not a string or a vector.

@example
@group

              (@var{find-in} (current-local-map))))))
    (@var{find-in} (current-global-map)))
@end lisp

@noindent
The @var{find-in} and @var{find-in-any} are pseudo functions that
search in one keymap and in an alist of keymaps, respectively.
(Searching a single keymap for a binding is called @dfn{key lookup};
see @ref{Key Lookup}.)  If the key sequence starts with a mouse event,
or a symbolic prefix event followed by a mouse event, that event's
position is used instead of point and the current buffer.  Mouse
events on an embedded string use text properties from that string
instead of the buffer.

@enumerate
@item
The function finally found may be remapped
(@pxref{Remapping Commands}).

@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