procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document `keymap-lookup' in the lipsref manual

Browse source 
* doc/lispref/keymaps.texi (Functions for Key Lookup): Document
`keymap-lookup' instead of `lookup-key' (bug#52820).
This commit is contained in:
Lars Ingebrigtsen 2021-12-29 17:11:31 +01:00
parent ef344cc55c
commit 2970dbaa32
1 changed files with 24 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
doc/lispref/keymaps.texi
View file

@ -1183,22 +1183,18 @@ macro, a symbol that leads to one of them, or @code{nil}.
Here are the functions and variables pertaining to key lookup.
@defun lookup-key keymap key &optional accept-defaults
@defun keymap-lookup keymap key &optional accept-defaults no-remap position
This function returns the definition of @var{key} in @var{keymap}. All
the other functions described in this chapter that look up keys use
@code{lookup-key}. Here are examples:
@code{keymap-lookup}. Here are examples:
@example
@group
(lookup-key (current-global-map) "\C-x\C-f")
(keymap-lookup (current-global-map) "C-x C-f")
@result{} find-file
@end group
@group
(lookup-key (current-global-map) (kbd "C-x C-f"))
@result{} find-file
@end group
@group
(lookup-key (current-global-map) "\C-x\C-f12345")
(keymap-lookup (current-global-map) "C-x C-f 1 2 3 4 5")
@result{} 2
@end group
@end example
@ -1209,9 +1205,9 @@ and have extra events at the end that do not fit into a single key
sequence. Then the value is a number, the number of events at the front
of @var{key} that compose a complete key.
If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
If @var{accept-defaults} is non-@code{nil}, then @code{keymap-lookup}
considers default bindings as well as bindings for the specific events
in @var{key}. Otherwise, @code{lookup-key} reports only bindings for
in @var{key}. Otherwise, @code{keymap-lookup} reports only bindings for
the specific sequence @var{key}, ignoring default bindings except when
you explicitly ask about them. (To do this, supply @code{t} as an
element of @var{key}; see @ref{Format of Keymaps}.)
@ -1224,11 +1220,11 @@ the second example.
@example
@group
(lookup-key (current-global-map) "\M-f")
(keymap-lookup (current-global-map) "M-f")
@result{} forward-word
@end group
@group
(lookup-key (current-global-map) "\ef")
(keymap-lookup (current-global-map) "ESC f")
@result{} forward-word
@end group
@end example
@ -1239,6 +1235,19 @@ Unlike @code{read-key-sequence}, this function does not modify the
specified events in ways that discard information (@pxref{Key Sequence
Input}). In particular, it does not convert letters to lower case and
it does not change drag events to clicks.
Like the normal command loop, @code{keymap-lookup} will remap the
command resulting from looking up @var{key} by looking up the command
in the current keymaps. However, if the optional third argument
@var{no-remap} is non-@code{nil}, @code{keymap-lookup} returns the
unmapped command.
If the optional argument @var{position} is non-@code{nil}, it
specifies a mouse position as returned by @code{event-start} and
@code{event-end}, and the lookup occurs in the keymaps associated with
it instead of @var{key}. It can also be a number or marker, in which
case the keymap properties at the specified buffer position instead of
point are used.
@end defun
@deffn Command undefined
@ -1251,7 +1260,7 @@ This function returns the binding for @var{key} in the current
local keymap, or @code{nil} if it is undefined there.
The argument @var{accept-defaults} controls checking for default bindings,
as in @code{lookup-key} (above).
as in @code{keymap-lookup} (above).
@end defun
@defun keymap-global-binding key &optional accept-defaults
@ -1259,7 +1268,7 @@ This function returns the binding for command @var{key} in the
current global keymap, or @code{nil} if it is undefined there.
The argument @var{accept-defaults} controls checking for default bindings,
as in @code{lookup-key} (above).
as in @code{keymap-lookup} (above).
@end defun
@defun minor-mode-key-binding key &optional accept-defaults
@ -1276,7 +1285,7 @@ modes are omitted, since they would be completely shadowed. Similarly,
the list omits non-prefix bindings that follow prefix bindings.
The argument @var{accept-defaults} controls checking for default
bindings, as in @code{lookup-key} (above).
bindings, as in @code{keymap-lookup} (above).
@end defun
@defopt meta-prefix-char