diff options
Diffstat (limited to 'lispref/keymaps.texi')
| -rw-r--r-- | lispref/keymaps.texi | 158 |
1 files changed, 36 insertions, 122 deletions
diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi index 826f90d5a0..b6170b3a8f 100644 --- a/lispref/keymaps.texi +++ b/lispref/keymaps.texi @@ -28,7 +28,6 @@ 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. @@ -125,24 +124,27 @@ 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{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 @@ -528,8 +530,7 @@ 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. 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 @@ -713,16 +714,6 @@ 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 @@ -927,7 +918,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 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. @@ -936,12 +927,6 @@ 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 @@ -1165,12 +1150,6 @@ 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 @@ -1205,6 +1184,13 @@ 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 @@ -1273,56 +1259,6 @@ 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 @@ -1552,7 +1488,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 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 @@ -1583,13 +1519,6 @@ 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) @@ -2341,26 +2270,15 @@ 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 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 @@ -2453,7 +2371,3 @@ menu of Shell mode, after the item @code{break}: [work] '("Work" . work-command) 'break) @end example @end defun - -@ignore - arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794 -@end ignore |