@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
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.
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-<left>
+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-<space>
+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{<t>}, 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
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-<left>
-The key named @kbd{left} with the hyper modifier.
-
-@item M-RET
-The @kbd{return} key with a meta modifier.
-
-@item C-M-<space>
-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{<t>}, 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
projects / emacs.git / commitdiff