Commit 229644e7 authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

(Format of Keymaps): Keymaps contain char tables, not vectors.

(Active Keymaps): Add emulation-mode-map-alists.
(Functions for Key Lookup): key-binding has new arg no-remap.
(Remapping Commands): New node.
(Scanning Keymaps): where-is-internal has new arg no-remap.
(Tool Bar): Add tool-bar-local-item-from-menu.
Clarify when to use tool-bar-add-item-from-menu.
parent 041b0e7b
......@@ -28,6 +28,7 @@ found. The whole process is called @dfn{key lookup}.
* Key Lookup:: How extracting elements from keymaps works.
* Functions for Key Lookup:: How to request key lookup.
* Changing Key Bindings:: Redefining a key in a keymap.
* Remapping Commands:: Bindings that translate one command to another.
* 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.
......@@ -124,27 +125,24 @@ bindings allow a keymap to bind all possible event types without having
to enumerate all of them. A keymap that has a default binding
completely masks any lower-precedence keymap.
@item @var{vector}
If an element of a keymap is a vector, the vector counts as bindings for
all the @sc{ascii} characters, codes 0 through 127; vector element
@var{n} is the binding for the character with code @var{n}. This is a
compact way to record lots of bindings. A keymap with such a vector is
called a @dfn{full keymap}. Other keymaps are called @dfn{sparse
keymaps}.
A @code{nil} binding is used to mean that a key is explicitly not bound.
Just like any other binding, it takes precedence over a default binding
or a binding in the parent keymap, but on the other hand, it does not
take precedence over keymaps of lower priority.
When a keymap contains a vector, it always defines a binding for each
@sc{ascii} character, even if the vector contains @code{nil} for that
character. Such a binding of @code{nil} overrides any default key
binding in the keymap, for @sc{ascii} characters. However, default
bindings are still meaningful for events other than @sc{ascii}
characters. A binding of @code{nil} does @emph{not} override
lower-precedence keymaps; thus, if the local map gives a binding of
@code{nil}, Emacs uses the binding from the global map.
@item @var{char-table}
If an element of a keymap is a char-table, it counts as holding
bindings for all character events with no modifier bits
(@pxref{modifier bits}): element @var{n} is the binding for the
character with code @var{n}. This is a compact way to record lots of
bindings. A keymap with such a char-table is called a @dfn{full
keymap}. Other keymaps are called @dfn{sparse keymaps}.
When a keymap contains a char-table vector, it always defines a
binding for each character without modifiers. However, if the binding
is @code{nil}, it doesn't constitute a definition. @code{nil} takes
precedence over a default binding or a binding in the parent keymap.
So in a full keymap, default bindings are not meaningful for
characters without modifiers. They can still apply to characters with
modifier bits and to non-character events. A binding of @code{nil}
does @emph{not} override lower-precedence keymaps; thus, if the local
map gives a binding of @code{nil}, Emacs uses the binding from the
global map.
@item @var{string}
@cindex keymap prompt string
......@@ -530,7 +528,8 @@ when the minor mode is enabled.
The variable @code{overriding-local-map}, if non-@code{nil}, specifies
another local keymap that overrides the buffer's local map and all the
minor mode keymaps.
minor mode keymaps. Modes for emulation can specify additional
active keymaps through the variable @code{emulation-mode-map-alists}.
All the active keymaps are used together to determine what command to
execute when a key is entered. Emacs searches these maps one by one, in
......@@ -714,6 +713,16 @@ binding in this keymap, then it is special, and the binding for the
event is run directly by @code{read-event}. @xref{Special Events}.
@end defvar
@defvar emulation-mode-map-alists
This variable holds a list of keymap alists to use for emulations
modes. It is intended for modes or packages using multiple minor-mode
keymaps. Each element is a keymap alist which has the same format and
meaning as @code{minor-mode-map-alist}, or a symbol with a variable
binding which is such an alist. The ``active'' keymaps in each alist
are used before @code{minor-mode-map-alist} and
@code{minor-mode-overriding-map-alist}.
@end defvar
@node Key Lookup
@section Key Lookup
@cindex key lookup
......@@ -918,7 +927,7 @@ Used in keymaps to undefine keys. It calls @code{ding}, but does
not cause an error.
@end deffn
@defun key-binding key &optional accept-defaults
@defun key-binding key &optional accept-defaults no-remap
This function returns the binding for @var{key} in the current
keymaps, trying all the active keymaps. The result is @code{nil} if
@var{key} is undefined in the keymaps.
......@@ -927,6 +936,12 @@ keymaps, trying all the active keymaps. The result is @code{nil} if
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}.
An error is signaled if @var{key} is not a string or a vector.
@example
......@@ -1150,6 +1165,12 @@ changing an entry in @code{ctl-x-map}, and this has the effect of
changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
default global map.
The function @code{substitute-key-definition} scans a keymap for
keys that have a certain binding and rebind them with a different
binding. Another feature you can use for similar effects, but which
is often cleaner, is to add a binding that remaps a command
(@pxref{Remapping Commands}).
@defun substitute-key-definition olddef newdef keymap &optional oldmap
@cindex replace bindings
This function replaces @var{olddef} with @var{newdef} for any keys in
......@@ -1184,13 +1205,6 @@ bindings in another. For example,
puts the special deletion command in @code{my-map} for whichever keys
are globally bound to the standard deletion command.
@ignore
@c Emacs 18 only
Prefix keymaps that appear within @var{keymap} are not checked
recursively for keys bound to @var{olddef}; they are not changed at all.
Perhaps it would be better to check nested keymaps recursively.
@end ignore
Here is an example showing a keymap before and after substitution:
@smallexample
......@@ -1259,6 +1273,56 @@ Dired mode is set up:
@end smallexample
@end defun
@node Remapping Commands
@section Remapping Commands
@cindex remapping commands
A special kind of key binding, using a special ``key sequence''
which includes a command name, has the effect of @dfn{remapping} that
command into another. Here's how it works. You make a key binding
for a key sequence tha starts with the dummy event @code{remap},
followed by the command name you want to remap. Specify the remapped
definition as the definition in this binding. The remapped definition
is usually a command name, but it can be any valid definition for
a key binding.
Here's an example. Suppose that My mode uses special commands
@code{my-kill-line} and @code{my-kill-word}, which should be invoked
instead of @code{kill-line} and @code{kill-word}. It can establish
this by making these two command-remapping bindings in its keymap:
@example
(define-key my-mode-map [remap kill-line] 'my-kill-line)
(define-key my-mode-map [remap kill-word] 'my-kill-word)
@end example
Whenever @code{my-mode-map} is an active keymap, if the user types
@kbd{C-k}, Emacs will find the standard global binding of
@code{kill-line} (assuming nobody has changed it). But
@code{my-mode-map} remaps @code{kill-line} to @code{my-mode-map},
so instead of running @code{kill-line}, Emacs runs
@code{my-kill-line}.
Remapping only works through a single level. In other words,
@example
(define-key my-mode-map [remap kill-line] 'my-kill-line)
(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)
@end example
@noindent
does not have the effect of remapping @code{kill-line} into
@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
This function returns the remapping for @var{command}, given the
current active keymaps. If @var{command} is not remapped (which is
the usual situation), the function returns @code{nil}.
@end defun
@node Key Binding Commands
@section Commands for Binding Keys
......@@ -1488,7 +1552,7 @@ This function is the cleanest way to examine all the bindings
in a keymap.
@end defun
@defun where-is-internal command &optional keymap firstonly noindirect
@defun where-is-internal command &optional keymap firstonly noindirect no-remap
This function is a subroutine used by the @code{where-is} command
(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list
of key sequences (of any length) that are bound to @var{command} in a
......@@ -1519,6 +1583,13 @@ If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
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.
@smallexample
@group
(where-is-internal 'describe-function)
......@@ -2270,15 +2341,26 @@ To define items in some local map, bind @code{`tool-bar-map} with
@defun tool-bar-add-item-from-menu command icon &optional map &rest props
@tindex tool-bar-add-item-from-menu
This command is a convenience for defining tool bar items which are
This function is a convenience for defining tool bar items which are
consistent with existing menu bar bindings. The binding of
@var{command} is looked up in the menu bar in @var{map} (default
@code{global-map}) and modified to add an image specification for
@var{icon}, which is looked for in the same way as by
@var{icon}, which is found in the same way as by
@code{tool-bar-add-item}. The resulting binding is then placed in
@code{tool-bar-map}. @var{map} must contain an appropriate keymap bound
to @code{[menu-bar]}. The remaining arguments @var{props} are
additional property list elements to add to the menu item specification.
@code{tool-bar-map}, so use this function only for global tool bar
items.
@var{map} must contain an appropriate keymap bound to
@code{[menu-bar]}. The remaining arguments @var{props} are additional
property list elements to add to the menu item specification.
@end defun
@defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props
This function is used for making non-global tool bar items. Use it
like @code{tool-bar-add-item-from-menu} except that @var{in-map}
specifies the local map to make the definition in. The argument
@var{from-map} si like the @var{map} argument of
@code{tool-bar-add-item-from-menu}.
@end defun
@tindex auto-resize-tool-bar
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment