From f04efd18cfd43a84ae4a83fbd4e5b2a5fbd2251c Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sat, 1 Mar 2025 06:34:00 +0100 Subject: [PATCH] keymaps.texi: Move "Changing Key Bindings" section up * doc/lispref/keymaps.texi (Changing Key Bindings): Move section up. (Bug#52821) (cherry picked from commit 526eeedf88941daf2a77ac5a6c2ba8237ed4814d) --- doc/lispref/keymaps.texi | 1258 +++++++++++++++++++------------------- 1 file changed, 629 insertions(+), 629 deletions(-) diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 1b3b1a5cceb..76c5528952d 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -15,6 +15,7 @@ is found. The whole process is called @dfn{key lookup}. @menu * Keymap Basics:: Basic concepts of keymaps. +* Changing Key Bindings:: Redefining a key in a keymap. * Format of Keymaps:: What a keymap looks like as a Lisp object. * Creating Keymaps:: Functions to create and copy keymaps. * Inheritance and Keymaps:: How one keymap can inherit the bindings @@ -28,7 +29,6 @@ is found. The whole process is called @dfn{key lookup}. A minor mode can also override them. * Key Lookup:: Finding a key's binding in one keymap. * Functions for Key Lookup:: How to request key lookup. -* Changing Key Bindings:: Redefining a key in a keymap. * Key Sequences:: Key sequences as Lisp objects. * Low-Level Key Binding:: Legacy key syntax description. * Remapping Commands:: A keymap can translate one command to another. @@ -90,303 +90,577 @@ precedence over) the corresponding global bindings. The minor mode keymaps shadow both local and global keymaps. @xref{Active Keymaps}, for details. -@node Format of Keymaps -@section Format of Keymaps -@cindex format of keymaps -@cindex keymap format -@cindex full keymap -@cindex sparse keymap +@node Changing Key Bindings +@section Changing Key Bindings +@cindex changing key bindings +@cindex rebinding - Each keymap is a list whose @sc{car} is the symbol @code{keymap}. The -remaining elements of the list define the key bindings of the keymap. -A symbol whose function definition is a keymap is also a keymap. Use -the function @code{keymapp} (see below) to test whether an object is a -keymap. + The way to rebind a key is to change its entry in a keymap. If you +change a binding in the global keymap, the change is effective in all +buffers (though it has no direct effect in buffers that shadow the +global binding with a local one). If you change the current buffer's +local map, that usually affects all buffers using the same major mode. +The @code{keymap-global-set} and @code{keymap-local-set} functions are +convenient interfaces for these operations (@pxref{Key Binding +Commands}). You can also use @code{keymap-set}, a more general +function; then you must explicitly specify the map to change. - Several kinds of elements may appear in a keymap, after the symbol -@code{keymap} that begins it: + When choosing the key sequences for Lisp programs to rebind, please +follow the Emacs conventions for use of various keys (@pxref{Key +Binding Conventions}). -@table @code -@item (@var{type} .@: @var{binding}) -This specifies one binding, for events of type @var{type}. Each -ordinary binding applies to events of a particular @dfn{event type}, -which is always a character or a symbol. @xref{Classifying Events}. -In this kind of binding, @var{binding} is a command. + The functions below signal an error if @var{keymap} is not a keymap, +or if @var{key} is not a valid key. -@item (@var{type} @var{item-name} .@: @var{binding}) -This specifies a binding which is also a simple menu item that -displays as @var{item-name} in the menu. @xref{Simple Menu Items}. +@var{key} is a string representing a single key or a series of key +strokes, and must satisfy @code{key-valid-p}. Key strokes are +separated by a single space character. -@item (@var{type} @var{item-name} @var{help-string} .@: @var{binding}) -This is a simple menu item with help string @var{help-string}. +Each key stroke is either a single character, or the name of an +event, surrounded by angle brackets. In addition, any key stroke +may be preceded by one or more modifier keys. Finally, a limited +number of characters have a special shorthand syntax. Here's some +example key sequences: -@item (@var{type} menu-item .@: @var{details}) -This specifies a binding which is also an extended menu item. This -allows use of other features. @xref{Extended Menu Items}. +@table @kbd +@item f +The key @kbd{f}. -@item (t .@: @var{binding}) -@cindex default key binding -This specifies a @dfn{default key binding}; any event not bound by other -elements of the keymap is given @var{binding} as its binding. Default -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, except for events -explicitly bound to @code{nil} (see below). +@item S o m +A three key sequence of the keys @kbd{S}, @kbd{o} and @kbd{m}. -@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}): the element whose index is @var{c} is the -binding for the character @var{c}. 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}. +@item C-c o +A two key sequence of the keys @kbd{c} with the control modifier and +then the key @kbd{o} -@item @var{vector} -This kind of element is similar to a char-table: the element whose -index is @var{c} is the binding for the character @var{c}. Since the -range of characters that can be bound this way is limited by the -vector size, and vector creation allocates space for all character -codes from 0 up, this format should not be used except for creating -menu keymaps (@pxref{Menu Keymaps}), where the bindings themselves -don't matter. +@item H- +The key named @kbd{left} with the hyper modifier. -@item @var{string} -@cindex keymap prompt string -@cindex overall prompt string -@cindex prompt string of keymap -Aside from elements that specify bindings for keys, a keymap can also -have a string as an element. This is called the @dfn{overall prompt -string} and makes it possible to use the keymap as a menu. -@xref{Defining Menus}. +@item M-RET +The @kbd{return} key with a meta modifier. -@item (keymap @dots{}) -If an element of a keymap is itself a keymap, it counts as if this inner keymap -were inlined in the outer keymap. This is used for multiple-inheritance, such -as in @code{make-composed-keymap}. +@item C-M- +The @kbd{space} key with both the control and meta modifiers. @end table -When the binding is @code{nil}, it doesn't constitute a definition -but it does take precedence over a default binding or a binding in the -parent keymap. On the other hand, 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. +The only keys that have a special shorthand syntax are @kbd{NUL}, +@kbd{RET}, @kbd{TAB}, @kbd{LFD}, @kbd{ESC}, @kbd{SPC} and @kbd{DEL}. -@cindex meta characters lookup - Keymaps do not directly record bindings for the meta characters. -Instead, meta characters are regarded for purposes of key lookup as -sequences of two characters, the first of which is @key{ESC} (or -whatever is currently the value of @code{meta-prefix-char}). Thus, the -key @kbd{M-a} is internally represented as @kbd{@key{ESC} a}, and its -global binding is found at the slot for @kbd{a} in @code{esc-map} -(@pxref{Prefix Keys}). +The modifiers have to be specified in alphabetical order: +@samp{A-C-H-M-S-s}, which is @samp{Alt-Control-Hyper-Meta-Shift-super}. - This conversion applies only to characters, not to function keys or -other input events; thus, @kbd{M-@key{end}} has nothing to do with -@kbd{@key{ESC} @key{end}}. +@findex keymap-set +@defun keymap-set keymap key binding +This function sets the binding for @var{key} in @var{keymap}. (If +@var{key} is more than one event long, the change is actually made +in another keymap reached from @var{keymap}.) The argument +@var{binding} can be any Lisp object, but only certain types are +meaningful. (For a list of meaningful types, see @ref{Key Lookup}.) +The value returned by @code{keymap-set} is @var{binding}. - Here as an example is the local keymap for Lisp mode, a sparse -keymap. It defines bindings for @key{DEL}, @kbd{C-c C-z}, -@kbd{C-M-q}, and @kbd{C-M-x} (the actual value also contains a menu -binding, which is omitted here for the sake of brevity). +If @var{key} is @kbd{}, this sets the default binding in +@var{keymap}. When an event has no binding of its own, the Emacs +command loop uses the keymap's default binding, if there is one. -@example +@cindex invalid prefix key error +@cindex key sequence error +Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap) +or undefined; otherwise an error is signaled. If some prefix of +@var{key} is undefined, then @code{keymap-set} defines it as a prefix +key so that the rest of @var{key} can be defined as specified. + +If there was previously no binding for @var{key} in @var{keymap}, the +new binding is added at the beginning of @var{keymap}. The order of +bindings in a keymap makes no difference for keyboard input, but it +does matter for menu keymaps (@pxref{Menu Keymaps}). +@end defun + +@findex keymap-unset +@defun keymap-unset keymap key &optional remove +This function is the inverse of @code{keymap-set}, it unsets the +binding for @var{key} in @var{keymap}, which is the same as setting +the binding to @code{nil}. In order to instead remove the binding +completely, specify @var{remove} as non-@code{nil}. This only makes a +difference if @var{keymap} has a parent keymap: if you just unset a key +in a child map, it will still shadow the same key in the parent +keymap; using @var{remove} instead will allow the key in the parent keymap +to be used. +@end defun + +Note: using @code{keymap-unset} with @var{remove} non-@code{nil} is +intended for users to put in their init file; Emacs packages should +avoid using it if possible, since they have complete control over +their own keymaps anyway, and they should not be altering other +packages' keymaps. + + This example creates a sparse keymap and makes a number of +bindings in it: + +@smallexample @group -lisp-mode-map -@result{} +(setq map (make-sparse-keymap)) + @result{} (keymap) @end group @group -(keymap - (3 keymap - ;; @kbd{C-c C-z} - (26 . run-lisp)) +(keymap-set map "C-f" 'forward-char) + @result{} forward-char @end group @group - (27 keymap - ;; @r{@kbd{C-M-x}, treated as @kbd{@key{ESC} C-x}} - (24 . lisp-send-defun)) +map + @result{} (keymap (6 . forward-char)) @end group + @group - ;; @r{This part is inherited from @code{lisp-mode-shared-map}.} - keymap - ;; @key{DEL} - (127 . backward-delete-char-untabify) +;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.} +(keymap-set map "C-x f" 'forward-word) + @result{} forward-word @end group @group - (27 keymap - ;; @r{@kbd{C-M-q}, treated as @kbd{@key{ESC} C-q}} - (17 . indent-sexp))) +map +@result{} (keymap + (24 keymap ; @kbd{C-x} + (102 . forward-word)) ; @kbd{f} + (6 . forward-char)) ; @kbd{C-f} @end group -@end example -@defun keymapp object -This function returns @code{t} if @var{object} is a keymap, @code{nil} -otherwise. More precisely, this function tests for a list whose -@sc{car} is @code{keymap}, or for a symbol whose function definition -satisfies @code{keymapp}. - -@example @group -(keymapp '(keymap)) - @result{} t +;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.} +(keymap-set map "C-p" ctl-x-map) +;; @code{ctl-x-map} +@result{} [nil @dots{} find-file @dots{} backward-kill-sentence] @end group + @group -(fset 'foo '(keymap)) -(keymapp 'foo) - @result{} t +;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.} +(keymap-set map "C-p C-f" 'foo) +@result{} 'foo @end group @group -(keymapp (current-global-map)) - @result{} t +map +@result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.} + (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence]) + (24 keymap + (102 . forward-word)) + (6 . forward-char)) @end group -@end example -@end defun +@end smallexample -@node Creating Keymaps -@section Creating Keymaps -@cindex creating keymaps +@noindent +Note that storing a new binding for @kbd{C-p C-f} actually works by +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. - Here we describe the functions for creating keymaps. +@code{keymap-set} is the general work horse for defining a key in a +keymap. When writing modes, however, you frequently have to bind a +large number of keys at once, and using @code{keymap-set} on them all +can be tedious and error-prone. Instead you can use +@code{define-keymap}, which creates a keymap and binds a number of +keys. @xref{Creating Keymaps}, for details. -@defun make-sparse-keymap &optional prompt -This function creates and returns a new sparse keymap with no entries. -(A sparse keymap is the kind of keymap you usually want.) The new -keymap does not contain a char-table, unlike @code{make-keymap}, and -does not bind any events. +The function @code{substitute-key-definition} scans a keymap for +keys that have a certain binding and rebinds them with a different +binding. Another feature which is cleaner and can often produce the +same results is to remap one command into another (@pxref{Remapping +Commands}). -@example +@defun substitute-key-definition olddef newdef keymap &optional oldmap +@cindex replace bindings +This function replaces @var{olddef} with @var{newdef} for any keys in +@var{keymap} that were bound to @var{olddef}. In other words, +@var{olddef} is replaced with @var{newdef} wherever it appears. The +function returns @code{nil}. + +For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with +standard bindings: + +@smallexample @group -(make-sparse-keymap) - @result{} (keymap) +(substitute-key-definition + 'find-file 'find-file-read-only (current-global-map)) @end group -@end example +@end smallexample -If you specify @var{prompt}, that becomes the overall prompt string -for the keymap. You should specify this only for menu keymaps -(@pxref{Defining Menus}). A keymap with an overall prompt string will -always present a mouse menu or a keyboard menu if it is active for -looking up the next input event. Don't specify an overall prompt string -for the main map of a major or minor mode, because that would cause -the command loop to present a keyboard menu every time. -@end defun +If @var{oldmap} is non-@code{nil}, that changes the behavior of +@code{substitute-key-definition}: the bindings in @var{oldmap} determine +which keys to rebind. The rebindings still happen in @var{keymap}, not +in @var{oldmap}. Thus, you can change one map under the control of the +bindings in another. For example, -@defun make-keymap &optional prompt -This function creates and returns a new full keymap. That keymap -contains a char-table (@pxref{Char-Tables}) with slots for all -characters without modifiers. The new keymap initially binds all -these characters to @code{nil}, and does not bind any other kind of -event. The argument @var{prompt} specifies a -prompt string, as in @code{make-sparse-keymap}. +@smallexample +(substitute-key-definition + 'delete-backward-char 'my-funny-delete + my-map global-map) +@end smallexample -@c This example seems kind of pointless, but I guess it serves -@c to contrast the result with make-sparse-keymap above. -@example +@noindent +puts the special deletion command in @code{my-map} for whichever keys +are globally bound to the standard deletion command. + +Here is an example showing a keymap before and after substitution: + +@smallexample @group -(make-keymap) - @result{} (keymap #^[nil nil keymap nil nil nil @dots{}]) +(setq map (list 'keymap + (cons ?1 olddef-1) + (cons ?2 olddef-2) + (cons ?3 olddef-1))) +@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1)) @end group -@end example -A full keymap is more efficient than a sparse keymap when it holds -lots of bindings; for just a few, the sparse keymap is better. +@group +(substitute-key-definition 'olddef-1 'newdef map) +@result{} nil +@end group +@group +map +@result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef)) +@end group +@end smallexample @end defun -@defun define-keymap &key options... &rest pairs... -You can create a keymap with the functions described above, and then -use @code{keymap-set} (@pxref{Changing Key Bindings}) to specify key -bindings in that map. When writing modes, however, you frequently -have to bind a large number of keys at once, and using -@code{keymap-set} on them all can be tedious and error-prone. Instead -you can use @code{define-keymap}, which creates a keymap and binds a -number of keys. Here's a very basic example: +@defun suppress-keymap keymap &optional nodigits +@cindex @code{self-insert-command} override +This function changes the contents of the full keymap @var{keymap} by +remapping @code{self-insert-command} to the command @code{undefined} +(@pxref{Remapping Commands}). This has the effect of undefining all +printing characters, thus making ordinary insertion of text impossible. +@code{suppress-keymap} returns @code{nil}. -@lisp -(define-keymap - "n" #'forward-line - "f" #'previous-line - "C-c C-c" #'quit-window) -@end lisp +If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines +digits to run @code{digit-argument}, and @kbd{-} to run +@code{negative-argument}. Otherwise it makes them undefined like the +rest of the printing characters. -This function creates a new sparse keymap, defines the keystrokes in -@var{pairs}, and returns the new keymap. It signals an error if there -are duplicate key bindings in @var{pairs}. +@cindex yank suppression +@cindex @code{quoted-insert} suppression +The @code{suppress-keymap} function does not make it impossible to +modify a buffer, as it does not suppress commands such as @code{yank} +and @code{quoted-insert}. To prevent any modification of a buffer, make +it read-only (@pxref{Read Only Buffers}). -@var{pairs} is a list of alternating key bindings and key definitions, -as accepted by @code{keymap-set}. In addition, the key can be the -special symbol @code{:menu}, in which case the definition should be a -menu definition as accepted by @code{easy-menu-define} (@pxref{Easy -Menu}). Here's a brief example of this usage: +Since this function modifies @var{keymap}, you would normally use it +on a newly created keymap. Operating on an existing keymap +that is used for some other purpose is likely to cause trouble; for +example, suppressing @code{global-map} would make it impossible to use +most of Emacs. -@lisp -(define-keymap :full t - "g" #'eww-reload - :menu '("Eww" - ["Exit" quit-window t] - ["Reload" eww-reload t])) -@end lisp +This function can be used to initialize the local keymap of a major +mode for which insertion of text is not desirable. But usually such a +mode should be derived from @code{special-mode} (@pxref{Basic Major +Modes}); then its keymap will automatically inherit from +@code{special-mode-map}, which is already suppressed. Here is how +@code{special-mode-map} is defined: -A number of keywords can be used before the key/definition pairs to -change features of the new keymap. If any of the feature keywords is -missing from the @code{define-keymap} call, the default value for that -feature is @code{nil}. Here's a list of the available feature -keywords: +@smallexample +@group +(defvar special-mode-map + (let ((map (make-sparse-keymap))) + (suppress-keymap map) + (keymap-set map "q" 'quit-window) + @dots{} + map)) +@end group +@end smallexample +@end defun -@table @code -@item :full -If non-@code{nil}, create a char-table keymap (as from -@code{make-keymap}) instead of a sparse keymap (as from -@code{make-sparse-keymap} (@pxref{Creating Keymaps}). A sparse keymap -is the default. +@node Format of Keymaps +@section Format of Keymaps +@cindex format of keymaps +@cindex keymap format +@cindex full keymap +@cindex sparse keymap -@item :parent -If non-@code{nil}, the value should be a keymap to use as the parent -(@pxref{Inheritance and Keymaps}). + Each keymap is a list whose @sc{car} is the symbol @code{keymap}. The +remaining elements of the list define the key bindings of the keymap. +A symbol whose function definition is a keymap is also a keymap. Use +the function @code{keymapp} (see below) to test whether an object is a +keymap. -@item :keymap -If non-@code{nil}, the value should be a keymap. Instead of creating -a new keymap, the specified keymap is modified instead. + Several kinds of elements may appear in a keymap, after the symbol +@code{keymap} that begins it: -@item :suppress -If non-@code{nil}, the keymap will be suppressed with -@code{suppress-keymap} (@pxref{Changing Key Bindings}). By default, -digits and the minus sign are exempt from suppressing, but if the -value is @code{nodigits}, this suppresses digits and minus-sign like -it does with other characters. +@table @code +@item (@var{type} .@: @var{binding}) +This specifies one binding, for events of type @var{type}. Each +ordinary binding applies to events of a particular @dfn{event type}, +which is always a character or a symbol. @xref{Classifying Events}. +In this kind of binding, @var{binding} is a command. -@item :name -If non-@code{nil}, the value should be a string to use as the menu for -the keymap if you use it as a menu with @code{x-popup-menu} -(@pxref{Pop-Up Menus}). +@item (@var{type} @var{item-name} .@: @var{binding}) +This specifies a binding which is also a simple menu item that +displays as @var{item-name} in the menu. @xref{Simple Menu Items}. -@item :prefix -If non-@code{nil}, the value should be a symbol to be used as a prefix -command (@pxref{Prefix Keys}). If this is the case, this symbol is -returned by @code{define-keymap} instead of the map itself. -@end table +@item (@var{type} @var{item-name} @var{help-string} .@: @var{binding}) +This is a simple menu item with help string @var{help-string}. -@end defun +@item (@var{type} menu-item .@: @var{details}) +This specifies a binding which is also an extended menu item. This +allows use of other features. @xref{Extended Menu Items}. -@defmac defvar-keymap name &key options... &rest pairs... -By far, the most common thing to do with a keymap is to bind it to a -variable. This is what virtually all modes do---a mode called -@code{foo} almost always has a variable called @code{foo-mode-map}. +@item (t .@: @var{binding}) +@cindex default key binding +This specifies a @dfn{default key binding}; any event not bound by other +elements of the keymap is given @var{binding} as its binding. Default +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, except for events +explicitly bound to @code{nil} (see below). -This macro defines @var{name} as a variable, passes @var{options} -and @var{pairs} to @code{define-keymap}, and uses the result as the -default value for the variable. It signals an error if there are -duplicate key bindings in @var{pairs}. +@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}): the element whose index is @var{c} is the +binding for the character @var{c}. 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}. -@var{options} is like the keywords in @code{define-keymap}, but -there's an additional @code{:doc} keyword that provides the doc -string for the defined variable. +@item @var{vector} +This kind of element is similar to a char-table: the element whose +index is @var{c} is the binding for the character @var{c}. Since the +range of characters that can be bound this way is limited by the +vector size, and vector creation allocates space for all character +codes from 0 up, this format should not be used except for creating +menu keymaps (@pxref{Menu Keymaps}), where the bindings themselves +don't matter. -Here's an example: +@item @var{string} +@cindex keymap prompt string +@cindex overall prompt string +@cindex prompt string of keymap +Aside from elements that specify bindings for keys, a keymap can also +have a string as an element. This is called the @dfn{overall prompt +string} and makes it possible to use the keymap as a menu. +@xref{Defining Menus}. -@lisp -(defvar-keymap eww-textarea-map - :parent text-mode-map - :doc "Keymap for the eww text area." - "RET" #'forward-line +@item (keymap @dots{}) +If an element of a keymap is itself a keymap, it counts as if this inner keymap +were inlined in the outer keymap. This is used for multiple-inheritance, such +as in @code{make-composed-keymap}. +@end table + +When the binding is @code{nil}, it doesn't constitute a definition +but it does take precedence over a default binding or a binding in the +parent keymap. On the other hand, 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. + +@cindex meta characters lookup + Keymaps do not directly record bindings for the meta characters. +Instead, meta characters are regarded for purposes of key lookup as +sequences of two characters, the first of which is @key{ESC} (or +whatever is currently the value of @code{meta-prefix-char}). Thus, the +key @kbd{M-a} is internally represented as @kbd{@key{ESC} a}, and its +global binding is found at the slot for @kbd{a} in @code{esc-map} +(@pxref{Prefix Keys}). + + This conversion applies only to characters, not to function keys or +other input events; thus, @kbd{M-@key{end}} has nothing to do with +@kbd{@key{ESC} @key{end}}. + + Here as an example is the local keymap for Lisp mode, a sparse +keymap. It defines bindings for @key{DEL}, @kbd{C-c C-z}, +@kbd{C-M-q}, and @kbd{C-M-x} (the actual value also contains a menu +binding, which is omitted here for the sake of brevity). + +@example +@group +lisp-mode-map +@result{} +@end group +@group +(keymap + (3 keymap + ;; @kbd{C-c C-z} + (26 . run-lisp)) +@end group +@group + (27 keymap + ;; @r{@kbd{C-M-x}, treated as @kbd{@key{ESC} C-x}} + (24 . lisp-send-defun)) +@end group +@group + ;; @r{This part is inherited from @code{lisp-mode-shared-map}.} + keymap + ;; @key{DEL} + (127 . backward-delete-char-untabify) +@end group +@group + (27 keymap + ;; @r{@kbd{C-M-q}, treated as @kbd{@key{ESC} C-q}} + (17 . indent-sexp))) +@end group +@end example + +@defun keymapp object +This function returns @code{t} if @var{object} is a keymap, @code{nil} +otherwise. More precisely, this function tests for a list whose +@sc{car} is @code{keymap}, or for a symbol whose function definition +satisfies @code{keymapp}. + +@example +@group +(keymapp '(keymap)) + @result{} t +@end group +@group +(fset 'foo '(keymap)) +(keymapp 'foo) + @result{} t +@end group +@group +(keymapp (current-global-map)) + @result{} t +@end group +@end example +@end defun + +@node Creating Keymaps +@section Creating Keymaps +@cindex creating keymaps + + Here we describe the functions for creating keymaps. + +@defun make-sparse-keymap &optional prompt +This function creates and returns a new sparse keymap with no entries. +(A sparse keymap is the kind of keymap you usually want.) The new +keymap does not contain a char-table, unlike @code{make-keymap}, and +does not bind any events. + +@example +@group +(make-sparse-keymap) + @result{} (keymap) +@end group +@end example + +If you specify @var{prompt}, that becomes the overall prompt string +for the keymap. You should specify this only for menu keymaps +(@pxref{Defining Menus}). A keymap with an overall prompt string will +always present a mouse menu or a keyboard menu if it is active for +looking up the next input event. Don't specify an overall prompt string +for the main map of a major or minor mode, because that would cause +the command loop to present a keyboard menu every time. +@end defun + +@defun make-keymap &optional prompt +This function creates and returns a new full keymap. That keymap +contains a char-table (@pxref{Char-Tables}) with slots for all +characters without modifiers. The new keymap initially binds all +these characters to @code{nil}, and does not bind any other kind of +event. The argument @var{prompt} specifies a +prompt string, as in @code{make-sparse-keymap}. + +@c This example seems kind of pointless, but I guess it serves +@c to contrast the result with make-sparse-keymap above. +@example +@group +(make-keymap) + @result{} (keymap #^[nil nil keymap nil nil nil @dots{}]) +@end group +@end example + +A full keymap is more efficient than a sparse keymap when it holds +lots of bindings; for just a few, the sparse keymap is better. +@end defun + +@defun define-keymap &key options... &rest pairs... +You can create a keymap with the functions described above, and then +use @code{keymap-set} (@pxref{Changing Key Bindings}) to specify key +bindings in that map. When writing modes, however, you frequently +have to bind a large number of keys at once, and using +@code{keymap-set} on them all can be tedious and error-prone. Instead +you can use @code{define-keymap}, which creates a keymap and binds a +number of keys. Here's a very basic example: + +@lisp +(define-keymap + "n" #'forward-line + "f" #'previous-line + "C-c C-c" #'quit-window) +@end lisp + +This function creates a new sparse keymap, defines the keystrokes in +@var{pairs}, and returns the new keymap. It signals an error if there +are duplicate key bindings in @var{pairs}. + +@var{pairs} is a list of alternating key bindings and key definitions, +as accepted by @code{keymap-set}. In addition, the key can be the +special symbol @code{:menu}, in which case the definition should be a +menu definition as accepted by @code{easy-menu-define} (@pxref{Easy +Menu}). Here's a brief example of this usage: + +@lisp +(define-keymap :full t + "g" #'eww-reload + :menu '("Eww" + ["Exit" quit-window t] + ["Reload" eww-reload t])) +@end lisp + +A number of keywords can be used before the key/definition pairs to +change features of the new keymap. If any of the feature keywords is +missing from the @code{define-keymap} call, the default value for that +feature is @code{nil}. Here's a list of the available feature +keywords: + +@table @code +@item :full +If non-@code{nil}, create a char-table keymap (as from +@code{make-keymap}) instead of a sparse keymap (as from +@code{make-sparse-keymap} (@pxref{Creating Keymaps}). A sparse keymap +is the default. + +@item :parent +If non-@code{nil}, the value should be a keymap to use as the parent +(@pxref{Inheritance and Keymaps}). + +@item :keymap +If non-@code{nil}, the value should be a keymap. Instead of creating +a new keymap, the specified keymap is modified instead. + +@item :suppress +If non-@code{nil}, the keymap will be suppressed with +@code{suppress-keymap} (@pxref{Changing Key Bindings}). By default, +digits and the minus sign are exempt from suppressing, but if the +value is @code{nodigits}, this suppresses digits and minus-sign like +it does with other characters. + +@item :name +If non-@code{nil}, the value should be a string to use as the menu for +the keymap if you use it as a menu with @code{x-popup-menu} +(@pxref{Pop-Up Menus}). + +@item :prefix +If non-@code{nil}, the value should be a symbol to be used as a prefix +command (@pxref{Prefix Keys}). If this is the case, this symbol is +returned by @code{define-keymap} instead of the map itself. +@end table + +@end defun + +@defmac defvar-keymap name &key options... &rest pairs... +By far, the most common thing to do with a keymap is to bind it to a +variable. This is what virtually all modes do---a mode called +@code{foo} almost always has a variable called @code{foo-mode-map}. + +This macro defines @var{name} as a variable, passes @var{options} +and @var{pairs} to @code{define-keymap}, and uses the result as the +default value for the variable. It signals an error if there are +duplicate key bindings in @var{pairs}. + +@var{options} is like the keywords in @code{define-keymap}, but +there's an additional @code{:doc} keyword that provides the doc +string for the defined variable. + +Here's an example: + +@lisp +(defvar-keymap eww-textarea-map + :parent text-mode-map + :doc "Keymap for the eww text area." + "RET" #'forward-line "TAB" #'shr-next-link) @end lisp @@ -1205,436 +1479,162 @@ macro, a symbol that leads to one of them, or @code{nil}. Here are the functions and variables pertaining to key lookup. @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{keymap-lookup}. Here are examples: - -@example -@group -(keymap-lookup (current-global-map) "C-x C-f") - @result{} find-file -@end group -@group -(keymap-lookup (current-global-map) "C-x C-f 1 2 3 4 5") - @result{} 2 -@end group -@end example - -If the string or vector @var{key} is not a valid key sequence according -to the prefix keys specified in @var{keymap}, it must be too long -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{keymap-lookup} -considers default bindings as well as bindings for the specific events -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}.) - -If @var{key} contains a meta character (not a function key), that -character is implicitly replaced by a two-character sequence: the value -of @code{meta-prefix-char}, followed by the corresponding non-meta -character. Thus, the first example below is handled by conversion into -the second example. - -@example -@group -(keymap-lookup (current-global-map) "M-f") - @result{} forward-word -@end group -@group -(keymap-lookup (current-global-map) "ESC f") - @result{} forward-word -@end group -@end example - -The @var{keymap} argument can be @code{nil}, meaning to look up -@var{key} in the current keymaps (as returned by -@code{current-active-maps}, @pxref{Active Keymaps}); or it can be a -keymap or a list of keymaps, meaning to look up @var{key} only in the -specified keymaps. - -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 -command without remapping. - -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 -that position, instead of in @var{keymap}. @var{position} can also be -a number or a marker, in which case it is interpreted as a buffer -position, and the function uses the keymap properties at that position -instead of at point. -@end defun - -@deffn Command undefined -Used in keymaps to undefine keys. It calls @code{ding}, but does -not cause an error. -@end deffn - -@defun keymap-local-lookup key &optional accept-defaults -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{keymap-lookup} (above). -@end defun - -@defun keymap-global-lookup key &optional accept-defaults -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{keymap-lookup} (above). -@end defun - -@defun minor-mode-key-binding key &optional accept-defaults -This function returns a list of all the active minor mode bindings of -@var{key}. More precisely, it returns an alist of pairs -@code{(@var{modename} . @var{binding})}, where @var{modename} is the -variable that enables the minor mode, and @var{binding} is @var{key}'s -binding in that mode. If @var{key} has no minor-mode bindings, the -value is @code{nil}. - -If the first binding found is not a prefix definition (a keymap or a -symbol defined as a keymap), all subsequent bindings from other minor -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{keymap-lookup} (above). -@end defun - -@defopt meta-prefix-char -@cindex @key{ESC} -This variable is the meta-prefix character code. It is used for -translating a meta character to a two-character sequence so it can be -looked up in a keymap. For useful results, the value should be a -prefix event (@pxref{Prefix Keys}). The default value is 27, which is -the @acronym{ASCII} code for @key{ESC}. - -As long as the value of @code{meta-prefix-char} remains 27, key lookup -translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined -as the @code{backward-word} command. However, if you were to set -@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will -translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the -@code{switch-to-buffer} command. (Don't actually do this!) Here is an -illustration of what would happen: - -@smallexample -@group -meta-prefix-char ; @r{The default value.} - @result{} 27 -@end group -@group -(key-binding "\M-b") - @result{} backward-word -@end group -@group -?\C-x ; @r{The print representation} - @result{} 24 ; @r{of a character.} -@end group -@group -(setq meta-prefix-char 24) - @result{} 24 -@end group -@group -(key-binding "\M-b") - @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is} - ; @r{like typing @kbd{C-x b}.} - -(setq meta-prefix-char 27) ; @r{Avoid confusion!} - @result{} 27 ; @r{Restore the default value!} -@end group -@end smallexample - -This translation of one event into two happens only for characters, not -for other kinds of input events. Thus, @kbd{M-@key{F1}}, a function -key, is not converted into @kbd{@key{ESC} @key{F1}}. -@end defopt - -@node Changing Key Bindings -@section Changing Key Bindings -@cindex changing key bindings -@cindex rebinding - - The way to rebind a key is to change its entry in a keymap. If you -change a binding in the global keymap, the change is effective in all -buffers (though it has no direct effect in buffers that shadow the -global binding with a local one). If you change the current buffer's -local map, that usually affects all buffers using the same major mode. -The @code{keymap-global-set} and @code{keymap-local-set} functions are -convenient interfaces for these operations (@pxref{Key Binding -Commands}). You can also use @code{keymap-set}, a more general -function; then you must explicitly specify the map to change. - - When choosing the key sequences for Lisp programs to rebind, please -follow the Emacs conventions for use of various keys (@pxref{Key -Binding Conventions}). - - The functions below signal an error if @var{keymap} is not a keymap, -or if @var{key} is not a valid key. - -@var{key} is a string representing a single key or a series of key -strokes, and must satisfy @code{key-valid-p}. Key strokes are -separated by a single space character. - -Each key stroke is either a single character, or the name of an -event, surrounded by angle brackets. In addition, any key stroke -may be preceded by one or more modifier keys. Finally, a limited -number of characters have a special shorthand syntax. Here's some -example key sequences: - -@table @kbd -@item f -The key @kbd{f}. - -@item S o m -A three key sequence of the keys @kbd{S}, @kbd{o} and @kbd{m}. - -@item C-c o -A two key sequence of the keys @kbd{c} with the control modifier and -then the key @kbd{o} - -@item H- -The key named @kbd{left} with the hyper modifier. - -@item M-RET -The @kbd{return} key with a meta modifier. - -@item C-M- -The @kbd{space} key with both the control and meta modifiers. -@end table - -The only keys that have a special shorthand syntax are @kbd{NUL}, -@kbd{RET}, @kbd{TAB}, @kbd{LFD}, @kbd{ESC}, @kbd{SPC} and @kbd{DEL}. - -The modifiers have to be specified in alphabetical order: -@samp{A-C-H-M-S-s}, which is @samp{Alt-Control-Hyper-Meta-Shift-super}. - -@findex keymap-set -@defun keymap-set keymap key binding -This function sets the binding for @var{key} in @var{keymap}. (If -@var{key} is more than one event long, the change is actually made -in another keymap reached from @var{keymap}.) The argument -@var{binding} can be any Lisp object, but only certain types are -meaningful. (For a list of meaningful types, see @ref{Key Lookup}.) -The value returned by @code{keymap-set} is @var{binding}. - -If @var{key} is @kbd{}, this sets the default binding in -@var{keymap}. When an event has no binding of its own, the Emacs -command loop uses the keymap's default binding, if there is one. - -@cindex invalid prefix key error -@cindex key sequence error -Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap) -or undefined; otherwise an error is signaled. If some prefix of -@var{key} is undefined, then @code{keymap-set} defines it as a prefix -key so that the rest of @var{key} can be defined as specified. - -If there was previously no binding for @var{key} in @var{keymap}, the -new binding is added at the beginning of @var{keymap}. The order of -bindings in a keymap makes no difference for keyboard input, but it -does matter for menu keymaps (@pxref{Menu Keymaps}). -@end defun - -@findex keymap-unset -@defun keymap-unset keymap key &optional remove -This function is the inverse of @code{keymap-set}, it unsets the -binding for @var{key} in @var{keymap}, which is the same as setting -the binding to @code{nil}. In order to instead remove the binding -completely, specify @var{remove} as non-@code{nil}. This only makes a -difference if @var{keymap} has a parent keymap: if you just unset a key -in a child map, it will still shadow the same key in the parent -keymap; using @var{remove} instead will allow the key in the parent keymap -to be used. -@end defun - -Note: using @code{keymap-unset} with @var{remove} non-@code{nil} is -intended for users to put in their init file; Emacs packages should -avoid using it if possible, since they have complete control over -their own keymaps anyway, and they should not be altering other -packages' keymaps. - - This example creates a sparse keymap and makes a number of -bindings in it: +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{keymap-lookup}. Here are examples: -@smallexample -@group -(setq map (make-sparse-keymap)) - @result{} (keymap) -@end group +@example @group -(keymap-set map "C-f" 'forward-char) - @result{} forward-char +(keymap-lookup (current-global-map) "C-x C-f") + @result{} find-file @end group @group -map - @result{} (keymap (6 . forward-char)) +(keymap-lookup (current-global-map) "C-x C-f 1 2 3 4 5") + @result{} 2 @end group +@end example + +If the string or vector @var{key} is not a valid key sequence according +to the prefix keys specified in @var{keymap}, it must be too long +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{keymap-lookup} +considers default bindings as well as bindings for the specific events +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}.) + +If @var{key} contains a meta character (not a function key), that +character is implicitly replaced by a two-character sequence: the value +of @code{meta-prefix-char}, followed by the corresponding non-meta +character. Thus, the first example below is handled by conversion into +the second example. +@example @group -;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.} -(keymap-set map "C-x f" 'forward-word) +(keymap-lookup (current-global-map) "M-f") @result{} forward-word @end group @group -map -@result{} (keymap - (24 keymap ; @kbd{C-x} - (102 . forward-word)) ; @kbd{f} - (6 . forward-char)) ; @kbd{C-f} +(keymap-lookup (current-global-map) "ESC f") + @result{} forward-word @end group +@end example -@group -;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.} -(keymap-set map "C-p" ctl-x-map) -;; @code{ctl-x-map} -@result{} [nil @dots{} find-file @dots{} backward-kill-sentence] -@end group +The @var{keymap} argument can be @code{nil}, meaning to look up +@var{key} in the current keymaps (as returned by +@code{current-active-maps}, @pxref{Active Keymaps}); or it can be a +keymap or a list of keymaps, meaning to look up @var{key} only in the +specified keymaps. -@group -;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.} -(keymap-set map "C-p C-f" 'foo) -@result{} 'foo -@end group -@group -map -@result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.} - (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence]) - (24 keymap - (102 . forward-word)) - (6 . forward-char)) -@end group -@end smallexample +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. -@noindent -Note that storing a new binding for @kbd{C-p C-f} actually works by -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. +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 +command without remapping. -@code{keymap-set} is the general work horse for defining a key in a -keymap. When writing modes, however, you frequently have to bind a -large number of keys at once, and using @code{keymap-set} on them all -can be tedious and error-prone. Instead you can use -@code{define-keymap}, which creates a keymap and binds a number of -keys. @xref{Creating Keymaps}, for details. +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 +that position, instead of in @var{keymap}. @var{position} can also be +a number or a marker, in which case it is interpreted as a buffer +position, and the function uses the keymap properties at that position +instead of at point. +@end defun -The function @code{substitute-key-definition} scans a keymap for -keys that have a certain binding and rebinds them with a different -binding. Another feature which is cleaner and can often produce the -same results is to remap one command into another (@pxref{Remapping -Commands}). +@deffn Command undefined +Used in keymaps to undefine keys. It calls @code{ding}, but does +not cause an error. +@end deffn -@defun substitute-key-definition olddef newdef keymap &optional oldmap -@cindex replace bindings -This function replaces @var{olddef} with @var{newdef} for any keys in -@var{keymap} that were bound to @var{olddef}. In other words, -@var{olddef} is replaced with @var{newdef} wherever it appears. The -function returns @code{nil}. +@defun keymap-local-lookup key &optional accept-defaults +This function returns the binding for @var{key} in the current +local keymap, or @code{nil} if it is undefined there. -For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with -standard bindings: +The argument @var{accept-defaults} controls checking for default bindings, +as in @code{keymap-lookup} (above). +@end defun -@smallexample -@group -(substitute-key-definition - 'find-file 'find-file-read-only (current-global-map)) -@end group -@end smallexample +@defun keymap-global-lookup key &optional accept-defaults +This function returns the binding for command @var{key} in the +current global keymap, or @code{nil} if it is undefined there. -If @var{oldmap} is non-@code{nil}, that changes the behavior of -@code{substitute-key-definition}: the bindings in @var{oldmap} determine -which keys to rebind. The rebindings still happen in @var{keymap}, not -in @var{oldmap}. Thus, you can change one map under the control of the -bindings in another. For example, +The argument @var{accept-defaults} controls checking for default bindings, +as in @code{keymap-lookup} (above). +@end defun -@smallexample -(substitute-key-definition - 'delete-backward-char 'my-funny-delete - my-map global-map) -@end smallexample +@defun minor-mode-key-binding key &optional accept-defaults +This function returns a list of all the active minor mode bindings of +@var{key}. More precisely, it returns an alist of pairs +@code{(@var{modename} . @var{binding})}, where @var{modename} is the +variable that enables the minor mode, and @var{binding} is @var{key}'s +binding in that mode. If @var{key} has no minor-mode bindings, the +value is @code{nil}. -@noindent -puts the special deletion command in @code{my-map} for whichever keys -are globally bound to the standard deletion command. +If the first binding found is not a prefix definition (a keymap or a +symbol defined as a keymap), all subsequent bindings from other minor +modes are omitted, since they would be completely shadowed. Similarly, +the list omits non-prefix bindings that follow prefix bindings. -Here is an example showing a keymap before and after substitution: +The argument @var{accept-defaults} controls checking for default +bindings, as in @code{keymap-lookup} (above). +@end defun + +@defopt meta-prefix-char +@cindex @key{ESC} +This variable is the meta-prefix character code. It is used for +translating a meta character to a two-character sequence so it can be +looked up in a keymap. For useful results, the value should be a +prefix event (@pxref{Prefix Keys}). The default value is 27, which is +the @acronym{ASCII} code for @key{ESC}. + +As long as the value of @code{meta-prefix-char} remains 27, key lookup +translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined +as the @code{backward-word} command. However, if you were to set +@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will +translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the +@code{switch-to-buffer} command. (Don't actually do this!) Here is an +illustration of what would happen: @smallexample @group -(setq map (list 'keymap - (cons ?1 olddef-1) - (cons ?2 olddef-2) - (cons ?3 olddef-1))) -@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1)) +meta-prefix-char ; @r{The default value.} + @result{} 27 @end group - @group -(substitute-key-definition 'olddef-1 'newdef map) -@result{} nil +(key-binding "\M-b") + @result{} backward-word @end group @group -map -@result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef)) +?\C-x ; @r{The print representation} + @result{} 24 ; @r{of a character.} @end group -@end smallexample -@end defun - -@defun suppress-keymap keymap &optional nodigits -@cindex @code{self-insert-command} override -This function changes the contents of the full keymap @var{keymap} by -remapping @code{self-insert-command} to the command @code{undefined} -(@pxref{Remapping Commands}). This has the effect of undefining all -printing characters, thus making ordinary insertion of text impossible. -@code{suppress-keymap} returns @code{nil}. - -If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines -digits to run @code{digit-argument}, and @kbd{-} to run -@code{negative-argument}. Otherwise it makes them undefined like the -rest of the printing characters. - -@cindex yank suppression -@cindex @code{quoted-insert} suppression -The @code{suppress-keymap} function does not make it impossible to -modify a buffer, as it does not suppress commands such as @code{yank} -and @code{quoted-insert}. To prevent any modification of a buffer, make -it read-only (@pxref{Read Only Buffers}). - -Since this function modifies @var{keymap}, you would normally use it -on a newly created keymap. Operating on an existing keymap -that is used for some other purpose is likely to cause trouble; for -example, suppressing @code{global-map} would make it impossible to use -most of Emacs. - -This function can be used to initialize the local keymap of a major -mode for which insertion of text is not desirable. But usually such a -mode should be derived from @code{special-mode} (@pxref{Basic Major -Modes}); then its keymap will automatically inherit from -@code{special-mode-map}, which is already suppressed. Here is how -@code{special-mode-map} is defined: - -@smallexample @group -(defvar special-mode-map - (let ((map (make-sparse-keymap))) - (suppress-keymap map) - (keymap-set map "q" 'quit-window) - @dots{} - map)) +(setq meta-prefix-char 24) + @result{} 24 +@end group +@group +(key-binding "\M-b") + @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is} + ; @r{like typing @kbd{C-x b}.} + +(setq meta-prefix-char 27) ; @r{Avoid confusion!} + @result{} 27 ; @r{Restore the default value!} @end group @end smallexample -@end defun + +This translation of one event into two happens only for characters, not +for other kinds of input events. Thus, @kbd{M-@key{F1}}, a function +key, is not converted into @kbd{@key{ESC} @key{F1}}. +@end defopt @node Key Sequences @section Key Sequences -- 2.39.5