* 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.
to enumerate all of them. A keymap that has a default binding
completely masks any lower-precedence keymap.
-@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{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{string}
@cindex keymap prompt string
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. Modes for emulation can specify additional
-active keymaps through the variable @code{emulation-mode-map-alists}.
+minor mode keymaps.
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
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
not cause an error.
@end deffn
-@defun key-binding key &optional accept-defaults no-remap
+@defun key-binding key &optional accept-defaults
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.
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
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
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
@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
in a keymap.
@end defun
-@defun where-is-internal command &optional keymap firstonly noindirect no-remap
+@defun where-is-internal command &optional keymap firstonly noindirect
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
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)
@defun tool-bar-add-item-from-menu command icon &optional map &rest props
@tindex tool-bar-add-item-from-menu
-This function is a convenience for defining tool bar items which are
+This command 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 found in the same way as by
+@var{icon}, which is looked for in the same way as by
@code{tool-bar-add-item}. The resulting binding is then placed in
-@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}.
+@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.
@end defun
@tindex auto-resize-tool-bar
[work] '("Work" . work-command) 'break)
@end example
@end defun
-
-@ignore
- arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794
-@end ignore
HCoop / bpt / emacs.git / blobdiff