@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2002, 2003,
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/keymaps
@node Keymaps, Modes, Command Loop, Top
@chapter Keymaps
@cindex keymap
- The bindings between input events and commands are recorded in data
-structures called @dfn{keymaps}. Each binding in a keymap associates
-(or @dfn{binds}) an individual event type either to another keymap or to
-a command. When an event type is bound to a keymap, that keymap is used
-to look up the next input event; this continues until a command is
-found. The whole process is called @dfn{key lookup}.
+ The command bindings of input events are recorded in data structures
+called @dfn{keymaps}. Each entry in a keymap associates (or
+@dfn{binds}) an individual event type, either to another keymap or to
+a command. When an event type is bound to a keymap, that keymap is
+used to look up the next input event; this continues until a command
+is found. The whole process is called @dfn{key lookup}.
@menu
-* Keymap Terminology:: Definitions of terms pertaining to keymaps.
+* Key Sequences:: Key sequences as Lisp objects.
+* Keymap Basics:: Basic concepts of keymaps.
* 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
of another keymap.
* Prefix Keys:: Defining a key with a keymap as its definition.
-* Active Keymaps:: Each buffer has a local keymap
+* Active Keymaps:: How Emacs searches the active keymaps
+ for a key binding.
+* Searching Keymaps:: A pseudo-Lisp summary of searching active maps.
+* Controlling Active Maps:: Each buffer has a local keymap
to override the standard (global) bindings.
A minor mode can also override them.
-* Key Lookup:: How extracting elements from keymaps works.
+* 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.
+* Remapping Commands:: A keymap can translate one command to another.
+* Translation Keymaps:: Keymaps for translating sequences of events.
* Key Binding Commands:: Interactive interfaces for redefining keys.
* Scanning Keymaps:: Looking through all keymaps, for printing help.
* Menu Keymaps:: Defining a menu as a keymap.
@end menu
-@node Keymap Terminology
-@section Keymap Terminology
+@node Key Sequences
+@section Key Sequences
@cindex key
@cindex keystroke
+@cindex key sequence
+
+ A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one
+or more input events that form a unit. Input events include
+characters, function keys, and mouse actions (@pxref{Input Events}).
+The Emacs Lisp representation for a key sequence is a string or
+vector. Unless otherwise stated, any Emacs Lisp function that accepts
+a key sequence as an argument can handle both representations.
+
+ In the string representation, alphanumeric characters ordinarily
+stand for themselves; for example, @code{"a"} represents @kbd{a} and
+and @code{"2"} represents @kbd{2}. Control character events are
+prefixed by the substring @code{"\C-"}, and meta characters by
+@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}.
+In addition, the @key{TAB}, @key{RET}, @key{ESC}, and @key{DEL} events
+are represented by @code{"\t"}, @code{"\r"}, @code{"\e"}, and
+@code{"\d"} respectively. The string representation of a complete key
+sequence is the concatenation of the string representations of the
+constituent events; thus, @code{"\C-xl"} represents the key sequence
+@kbd{C-x l}.
+
+ Key sequences containing function keys, mouse button events, or
+non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be
+represented as strings; they have to be represented as vectors.
+
+ In the vector representation, each element of the vector represents
+an input event, in its Lisp form. @xref{Input Events}. For example,
+the vector @code{[?\C-x ?l]} represents the key sequence @kbd{C-x l}.
+
+ For examples of key sequences written in string and vector
+representations, @ref{Init Rebinding,,, emacs, The GNU Emacs Manual}.
+
+@defmac kbd keyseq-text
+This macro converts the text @var{keyseq-text} (a string constant)
+into a key sequence (a string or vector constant). The contents of
+@var{keyseq-text} should describe the key sequence using almost the same
+syntax used in this manual. More precisely, it uses the same syntax
+that Edit Macro mode uses for editing keyboard macros (@pxref{Edit
+Keyboard Macro,,, emacs, The GNU Emacs Manual}); you must surround
+function key names with @samp{<@dots{}>}.
+
+@example
+(kbd "C-x") @result{} "\C-x"
+(kbd "C-x C-f") @result{} "\C-x\C-f"
+(kbd "C-x 4 C-f") @result{} "\C-x4\C-f"
+(kbd "X") @result{} "X"
+(kbd "RET") @result{} "\^M"
+(kbd "C-c SPC") @result{} "\C-c@ "
+(kbd "<f1> SPC") @result{} [f1 32]
+(kbd "C-M-<down>") @result{} [C-M-down]
+@end example
+
+This macro is not meant for use with arguments that vary---only
+with string constants.
+@end defmac
+
+@node Keymap Basics
+@section Keymap Basics
@cindex key binding
@cindex binding of a key
@cindex complete key
@cindex undefined key
- A @dfn{keymap} is a table mapping event types to definitions (which
-can be any Lisp objects, though only certain types are meaningful for
-execution by the command loop). Given an event (or an event type) and a
-keymap, Emacs can get the event's definition. Events include
-characters, function keys, and mouse actions (@pxref{Input Events}).
-
- A sequence of input events that form a unit is called a
-@dfn{key sequence}, or @dfn{key} for short. A sequence of one event
-is always a key sequence, and so are some multi-event sequences.
+ A keymap is a Lisp data structure that specifies @dfn{key bindings}
+for various key sequences.
- A keymap determines a binding or definition for any key sequence. If
-the key sequence is a single event, its binding is the definition of the
-event in the keymap. The binding of a key sequence of more than one
-event is found by an iterative process: the binding of the first event
-is found, and must be a keymap; then the second event's binding is found
-in that keymap, and so on until all the events in the key sequence are
-used up.
+ A single keymap directly specifies definitions for individual
+events. When a key sequence consists of a single event, its binding
+in a keymap is the keymap's definition for that event. The binding of
+a longer key sequence is found by an iterative process: first find the
+definition of the first event (which must itself be a keymap); then
+find the second event's definition in that keymap, and so on until all
+the events in the key sequence have been processed.
If the binding of a key sequence is a keymap, we call the key sequence
a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because
@cindex full keymap
@cindex sparse keymap
- A keymap is a list whose @sc{car} is the symbol @code{keymap}. The
+ 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.
-Use the function @code{keymapp} (see below) to test whether an object is
-a 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.
Several kinds of elements may appear in a keymap, after the symbol
@code{keymap} that begins it:
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 (@var{type} @var{item-name} @r{[}@var{cache}@r{]} .@: @var{binding})
+This specifies a binding which is also a simple menu item that
+displays as @var{item-name} in the menu. @var{cache}, if present,
+caches certain information for display in the menu. @xref{Simple Menu
+Items}.
+
+@item (@var{type} @var{item-name} @var{help-string} @r{[}@var{cache}@r{]} .@: @var{binding})
+This is a simple menu item with help string @var{help-string}.
+
+@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}.
@item (t .@: @var{binding})
@cindex default key binding
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.
-
-@item @var{vector}
-If an element of a keymap is a vector, the vector counts as bindings for
-all the @sc{ascii} characters, codes 0 through 127; vector element
-@var{n} is the binding for the character with code @var{n}. This is a
-compact way to record lots of bindings. A keymap with such a vector is
-called a @dfn{full keymap}. Other keymaps are called @dfn{sparse
-keymaps}.
-
-When a keymap contains a vector, it always defines a binding for each
-@sc{ascii} character, even if the vector contains @code{nil} for that
-character. Such a binding of @code{nil} overrides any default key
-binding in the keymap, for @sc{ascii} characters. However, default
-bindings are still meaningful for events other than @sc{ascii}
-characters. A binding of @code{nil} does @emph{not} override
-lower-precedence keymaps; thus, if the local map gives a binding of
-@code{nil}, Emacs uses the binding from the global map.
+completely masks any lower-precedence keymap, except for events
+explicitly bound to @code{nil} (see below).
+
+@item @var{char-table}
+If an element of a keymap is a char-table, it counts as holding
+bindings for all character events with no modifier bits
+(@pxref{modifier bits}): element @var{n} is the binding for the
+character with code @var{n}. This is a compact way to record lots of
+bindings. A keymap with such a char-table is called a @dfn{full
+keymap}. Other keymaps are called @dfn{sparse keymaps}.
@item @var{string}
@cindex keymap prompt string
@cindex overall prompt string
@cindex prompt string of keymap
-Aside from bindings, 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}.
+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}.
@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
@example
@group
lisp-mode-map
-@result{}
+@result{}
@end group
@group
-(keymap
- ;; @key{TAB}
- (9 . lisp-indent-line)
+(keymap
+ (3 keymap
+ ;; @kbd{C-c C-z}
+ (26 . run-lisp))
@end group
@group
- ;; @key{DEL}
- (127 . backward-delete-char-untabify)
+ (27 keymap
+ ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
+ (24 . lisp-send-defun)
+ keymap
+ ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
+ (17 . indent-sexp)))
@end group
@group
- (3 keymap
- ;; @kbd{C-c C-l}
- (12 . run-lisp))
+ ;; @r{This part is inherited from @code{lisp-mode-shared-map}.}
+ keymap
+ ;; @key{DEL}
+ (127 . backward-delete-char-untabify)
@end group
@group
- (27 keymap
+ (27 keymap
;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
- (17 . indent-sexp)
- ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
- (24 . lisp-send-defun)))
+ (17 . indent-sexp))
+ (9 . lisp-indent-line))
@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}.
+@sc{car} is @code{keymap}, or for a symbol whose function definition
+satisfies @code{keymapp}.
@example
@group
@result{} t
@end group
@group
+(fset 'foo '(keymap))
+(keymapp 'foo)
+ @result{} t
+@end group
+@group
(keymapp (current-global-map))
@result{} t
@end group
Here we describe the functions for creating keymaps.
-@c ??? This should come after make-sparse-keymap
-@defun make-keymap &optional prompt
-This function creates and returns a new full keymap (i.e., one
-containing a vector of length 128 for defining all the @sc{ascii}
-characters). The new keymap initially binds all @sc{ascii} characters
-to @code{nil}, and does not bind any other kind of event.
+@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-keymap)
- @result{} (keymap [nil nil nil @dots{} nil nil])
+(make-sparse-keymap)
+ @result{} (keymap)
@end group
@end example
-If you specify @var{prompt}, that becomes the overall prompt string for
-the keymap. The prompt string should be provided for menu keymaps
-(@pxref{Defining Menus}).
+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-sparse-keymap &optional prompt
-This function creates and returns a new sparse keymap with no entries.
-The new keymap does not bind any events. The argument @var{prompt}
-specifies a prompt string, as in @code{make-keymap}.
+@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}.
@example
@group
-(make-sparse-keymap)
- @result{} (keymap)
+(make-keymap)
+ @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap])
@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 copy-keymap keymap
@end group
@group
;; @r{(This implements meta characters.)}
- (27 keymap
+ (27 keymap
(83 . center-paragraph)
(115 . center-line))
(9 . tab-to-tab-stop))
@dfn{parent keymap}. Such a keymap looks like this:
@example
-(keymap @var{bindings}@dots{} . @var{parent-keymap})
+(keymap @var{elements}@dots{} . @var{parent-keymap})
@end example
@noindent
The effect is that this keymap inherits all the bindings of
@var{parent-keymap}, whatever they may be at the time a key is looked up,
-but can add to them or override them with @var{bindings}.
+but can add to them or override them with @var{elements}.
-If you change the bindings in @var{parent-keymap} using @code{define-key}
-or other key-binding functions, these changes are visible in the
-inheriting keymap unless shadowed by @var{bindings}. The converse is
-not true: if you use @code{define-key} to change the inheriting keymap,
-that affects @var{bindings}, but has no effect on @var{parent-keymap}.
+If you change the bindings in @var{parent-keymap} using
+@code{define-key} or other key-binding functions, these changed
+bindings are visible in the inheriting keymap, unless shadowed by the
+bindings made by @var{elements}. The converse is not true: if you use
+@code{define-key} to change bindings in the inheriting keymap, these
+changes are recorded in @var{elements}, but have no effect on
+@var{parent-keymap}.
The proper way to construct a keymap with a parent is to use
@code{set-keymap-parent}; if you have code that directly constructs a
prefix keys.
@end defun
-Here is an example showing how to make a keymap that inherits
+ Here is an example showing how to make a keymap that inherits
from @code{text-mode-map}:
@example
map)
@end example
+ A non-sparse keymap can have a parent too, but this is not very
+useful. A non-sparse keymap always specifies something as the binding
+for every numeric character code without modifier bits, even if it is
+@code{nil}, so these character's bindings are never inherited from
+the parent keymap.
+
@node Prefix Keys
@section Prefix Keys
@cindex prefix key
key.
@item
-@cindex @kbd{M-g}
+@cindex @kbd{M-o}
@vindex facemenu-keymap
-@code{facemenu-keymap} is the global keymap used for the @kbd{M-g}
+@code{facemenu-keymap} is the global keymap used for the @kbd{M-o}
prefix key.
@c Emacs 19 feature
@item
-The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x
-@key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps that have no
-special names.
+The other Emacs prefix keys are @kbd{M-g}, @kbd{C-x @@}, @kbd{C-x a i},
+@kbd{C-x @key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps
+that have no special names.
@end itemize
The keymap binding of a prefix key is used for looking up the event
@defun define-prefix-command symbol &optional mapvar prompt
@cindex prefix command
+@anchor{Definition of define-prefix-command}
This function prepares @var{symbol} for use as a prefix key's binding:
it creates a sparse keymap and stores it as @var{symbol}'s function
definition. Subsequently binding a key sequence to @var{symbol} will
@cindex global keymap
@cindex local keymap
- Emacs normally contains many keymaps; at any given time, just a few of
-them are @dfn{active} in that they participate in the interpretation
-of user input. These are the global keymap, the current buffer's
-local keymap, and the keymaps of any enabled minor modes.
+ Emacs normally contains many keymaps; at any given time, just a few
+of them are @dfn{active}, meaning that they participate in the
+interpretation of user input. All the active keymaps are used
+together to determine what command to execute when a key is entered.
+
+ Normally the active keymaps are the @code{keymap} property keymap,
+the keymaps of any enabled minor modes, the current buffer's local
+keymap, and the global keymap, in that order. Emacs searches for each
+input key sequence in all these keymaps. @xref{Searching Keymaps},
+for more details of this procedure.
+
+ When the key sequence starts with a mouse event (optionally preceded
+by a symbolic prefix), the active keymaps are determined based on the
+position in that event. If the event happened on a string embedded
+with a @code{display}, @code{before-string}, or @code{after-string}
+property (@pxref{Special Properties}), the non-@code{nil} map
+properties of the string override those of the buffer.
The @dfn{global keymap} holds the bindings of keys that are defined
regardless of the current buffer, such as @kbd{C-f}. The variable
@code{global-map} holds this keymap, which is always active.
- Each buffer may have another keymap, its @dfn{local keymap}, which may
-contain new or overriding definitions for keys. The current buffer's
-local keymap is always active except when @code{overriding-local-map}
-overrides it. Text properties can specify an alternative local map for
-certain parts of the buffer; see @ref{Special Properties}.
+ Each buffer may have another keymap, its @dfn{local keymap}, which
+may contain new or overriding definitions for keys. The current
+buffer's local keymap is always active except when
+@code{overriding-local-map} overrides it. The @code{local-map} text
+or overlay property can specify an alternative local keymap for certain
+parts of the buffer; see @ref{Special Properties}.
Each minor mode can have a keymap; if it does, the keymap is active
-when the minor mode is enabled.
-
- The variable @code{overriding-local-map}, if non-@code{nil}, specifies
-another local keymap that overrides the buffer's local map and all the
-minor mode keymaps.
-
- All the active keymaps are used together to determine what command to
-execute when a key is entered. Emacs searches these maps one by one, in
-order of decreasing precedence, until it finds a binding in one of the
-maps. The procedure for searching a single keymap is called @dfn{key
-lookup}; see @ref{Key Lookup}.
-
- Normally, Emacs first searches for the key in the minor mode maps, in
-the order specified by @code{minor-mode-map-alist}; if they do not
-supply a binding for the key, Emacs searches the local map; if that too
-has no binding, Emacs then searches the global map. However, if
-@code{overriding-local-map} is non-@code{nil}, Emacs searches that map
-first, before the global map.
+when the minor mode is enabled. Modes for emulation can specify
+additional active keymaps through the variable
+@code{emulation-mode-map-alists}.
+
+ The highest precedence normal keymap comes from the @code{keymap}
+text or overlay property. If that is non-@code{nil}, it is the first
+keymap to be processed, in normal circumstances.
+
+ However, there are also special ways for programs to substitute
+other keymaps for some of those. The variable
+@code{overriding-local-map}, if non-@code{nil}, specifies a keymap
+that replaces all the usual active keymaps except the global keymap.
+Another way to do this is with @code{overriding-terminal-local-map};
+it operates on a per-terminal basis. These variables are documented
+below.
@cindex major mode keymap
Since every buffer that uses the same major mode normally uses the
example) is seen also in the other buffers that share that keymap.
The local keymaps that are used for Lisp mode and some other major
-modes exist even if they have not yet been used. These local maps are
+modes exist even if they have not yet been used. These local keymaps are
the values of variables such as @code{lisp-mode-map}. For most major
modes, which are less frequently used, the local keymap is constructed
only when the mode is used for the first time in a session.
and exit commands. @xref{Intro to Minibuffers}.
Emacs has other keymaps that are used in a different way---translating
-events within @code{read-key-sequence}. @xref{Translating Input}.
+events within @code{read-key-sequence}. @xref{Translation Keymaps}.
@xref{Standard Keymaps}, for a list of standard keymaps.
+@defun current-active-maps &optional olp
+This returns the list of active keymaps that would be used by the
+command loop in the current circumstances to look up a key sequence.
+Normally it ignores @code{overriding-local-map} and
+@code{overriding-terminal-local-map}, but if @var{olp} is
+non-@code{nil} then it pays attention to them.
+@end defun
+
+@defun key-binding key &optional accept-defaults no-remap position
+This function returns the binding for @var{key} according to the
+current active keymaps. The result is @code{nil} if @var{key} is
+undefined in the keymaps.
+
+The argument @var{accept-defaults} controls checking for default
+bindings, as in @code{lookup-key} (above).
+
+When commands are remapped (@pxref{Remapping Commands}),
+@code{key-binding} normally processes command remappings so as to
+returns the remapped command that will actually be executed. However,
+if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
+remappings and returns the binding directly specified for @var{key}.
+
+If @var{key} starts with a mouse event (perhaps following a prefix
+event), the maps to be consulted are determined based on the event's
+position. Otherwise, they are determined based on the value of point.
+However, you can override either of them by specifying @var{position}.
+If @var{position} is non-@code{nil}, it should be either a buffer
+position or an event position like the value of @code{event-start}.
+Then the maps consulted are determined based on @var{position}.
+
+An error is signaled if @var{key} is not a string or a vector.
+
+@example
+@group
+(key-binding "\C-x\C-f")
+ @result{} find-file
+@end group
+@end example
+@end defun
+
+@node Searching Keymaps
+@section Searching the Active Keymaps
+
+ After translation of event subsequences (@pxref{Translation
+Keymaps}) Emacs looks for them in the active keymaps. Here is a
+pseudo-Lisp description of the order and conditions for searching
+them:
+
+@lisp
+(or (if overriding-terminal-local-map
+ (@var{find-in} overriding-terminal-local-map)
+ (if overriding-local-map
+ (@var{find-in} overriding-local-map)
+ (or (@var{find-in} (get-char-property (point) 'keymap))
+ (@var{find-in-any} emulation-mode-map-alists)
+ (@var{find-in-any} minor-mode-overriding-map-alist)
+ (@var{find-in-any} minor-mode-map-alist)
+ (if (get-text-property (point) 'local-map)
+ (@var{find-in} (get-char-property (point) 'local-map))
+ (@var{find-in} (current-local-map))))))
+ (@var{find-in} (current-global-map)))
+@end lisp
+
+@noindent
+The @var{find-in} and @var{find-in-any} are pseudo functions that
+search in one keymap and in an alist of keymaps, respectively.
+(Searching a single keymap for a binding is called @dfn{key lookup};
+see @ref{Key Lookup}.) If the key sequence starts with a mouse event,
+or a symbolic prefix event followed by a mouse event, that event's
+position is used instead of point and the current buffer. Mouse
+events on an embedded string use non-@code{nil} text properties from
+that string instead of the buffer.
+
+@enumerate
+@item
+The function finally found may be remapped
+(@pxref{Remapping Commands}).
+
+@item
+Characters that are bound to @code{self-insert-command} are translated
+according to @code{translation-table-for-input} before insertion.
+
+@item
+@code{current-active-maps} returns a list of the
+currently active keymaps at point.
+
+@item
+When a match is found (@pxref{Key Lookup}), if the binding in the
+keymap is a function, the search is over. However if the keymap entry
+is a symbol with a value or a string, Emacs replaces the input key
+sequences with the variable's value or the string, and restarts the
+search of the active keymaps.
+@end enumerate
+
+@node Controlling Active Maps
+@section Controlling the Active Keymaps
+
@defvar global-map
This variable contains the default global keymap that maps Emacs
-keyboard input to commands. The global keymap is normally this keymap.
-The default global keymap is a full keymap that binds
+keyboard input to commands. The global keymap is normally this
+keymap. The default global keymap is a full keymap that binds
@code{self-insert-command} to all of the printing characters.
-It is normal practice to change the bindings in the global map, but you
+It is normal practice to change the bindings in the global keymap, but you
should not assign this variable any value other than the keymap it starts
out with.
@end defvar
@example
@group
(current-global-map)
-@result{} (keymap [set-mark-command beginning-of-line @dots{}
+@result{} (keymap [set-mark-command beginning-of-line @dots{}
delete-backward-char])
@end group
@end example
This function returns the current buffer's local keymap, or @code{nil}
if it has none. In the following example, the keymap for the
@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
-in which the entry for @key{ESC}, @sc{ascii} code 27, is another sparse
+in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse
keymap.
@example
@group
(current-local-map)
-@result{} (keymap
- (10 . eval-print-last-sexp)
- (9 . lisp-indent-line)
- (127 . backward-delete-char-untabify)
+@result{} (keymap
+ (10 . eval-print-last-sexp)
+ (9 . lisp-indent-line)
+ (127 . backward-delete-char-untabify)
@end group
@group
- (27 keymap
- (24 . eval-defun)
+ (27 keymap
+ (24 . eval-defun)
(17 . indent-sexp)))
@end group
@end example
@c Emacs 19 feature
@defvar minor-mode-map-alist
+@anchor{Definition of minor-mode-map-alist}
This variable is an alist describing keymaps that may or may not be
active according to the values of certain variables. Its elements look
like this:
not do. The @sc{cdr} can be either a keymap (a list) or a symbol whose
function definition is a keymap.
-When more than one minor mode keymap is active, their order of priority
-is the order of @code{minor-mode-map-alist}. But you should design
+When more than one minor mode keymap is active, the earlier one in
+@code{minor-mode-map-alist} takes priority. But you should design
minor modes so that they don't interfere with each other. If you do
this properly, the order will not matter.
@defvar overriding-local-map
If non-@code{nil}, this variable holds a keymap to use instead of the
-buffer's local keymap and instead of all the minor mode keymaps. This
-keymap, if any, overrides all other maps that would have been active,
-except for the current global map.
+buffer's local keymap, any text property or overlay keymaps, and any
+minor mode keymaps. This keymap, if specified, overrides all other
+maps that would have been active, except for the current global map.
@end defvar
@defvar overriding-terminal-local-map
If non-@code{nil}, this variable holds a keymap to use instead of
-@code{overriding-local-map}, the buffer's local keymap and all the minor
-mode keymaps.
+@code{overriding-local-map}, the buffer's local keymap, text property
+or overlay keymaps, and all the minor mode keymaps.
This variable is always local to the current terminal and cannot be
buffer-local. @xref{Multiple Displays}. It is used to implement
event is run directly by @code{read-event}. @xref{Special Events}.
@end defvar
+@defvar emulation-mode-map-alists
+This variable holds a list of keymap alists to use for emulations
+modes. It is intended for modes or packages using multiple minor-mode
+keymaps. Each element is a keymap alist which has the same format and
+meaning as @code{minor-mode-map-alist}, or a symbol with a variable
+binding which is such an alist. The ``active'' keymaps in each alist
+are used before @code{minor-mode-map-alist} and
+@code{minor-mode-overriding-map-alist}.
+@end defvar
+
@node Key Lookup
@section Key Lookup
@cindex key lookup
@cindex keymap entry
@dfn{Key lookup} is the process of finding the binding of a key
-sequence from a given keymap. Actual execution of the binding is not
-part of key lookup.
+sequence from a given keymap. The execution or use of the binding is
+not part of key lookup.
Key lookup uses just the event type of each event in the key sequence;
the rest of the event is ignored. In fact, a key sequence used for key
-lookup may designate mouse events with just their types (symbols)
-instead of with entire mouse events (lists). @xref{Input Events}. Such
-a ``key-sequence'' is insufficient for @code{command-execute} to run,
+lookup may designate a mouse event with just its types (a symbol)
+instead of the entire event (a list). @xref{Input Events}. Such
+a ``key sequence'' is insufficient for @code{command-execute} to run,
but it is sufficient for looking up or rebinding a key.
When the key sequence consists of multiple events, key lookup
Let's use the term @dfn{keymap entry} to describe the value found by
looking up an event type in a keymap. (This doesn't include the item
-string and other extra elements in menu key bindings, because
+string and other extra elements in a keymap element for a menu item, because
@code{lookup-key} and other key lookup functions don't include them in
-the returned value.) While any Lisp object may be stored in a keymap as
-a keymap entry, not all make sense for key lookup. Here is a table of
-the meaningful kinds of keymap entries:
+the returned value.) While any Lisp object may be stored in a keymap
+as a keymap entry, not all make sense for key lookup. Here is a table
+of the meaningful types of keymap entries:
@table @asis
@item @code{nil}
@item @var{list}
@cindex list in keymap
-The meaning of a list depends on the types of the elements of the list.
+The meaning of a list depends on what it contains:
@itemize @bullet
@item
@item
@cindex @code{lambda} in keymap
If the @sc{car} of @var{list} is @code{lambda}, then the list is a
-lambda expression. This is presumed to be a command, and is treated as
-such (see above).
+lambda expression. This is presumed to be a function, and is treated
+as such (see above). In order to execute properly as a key binding,
+this function must be a command---it must have an @code{interactive}
+specification. @xref{Defining Commands}.
@item
If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
@result{} find-file
@end group
@group
+(lookup-key (current-global-map) (kbd "C-x C-f"))
+ @result{} find-file
+@end group
+@group
(lookup-key (current-global-map) "\C-x\C-f12345")
@result{} 2
@end group
not cause an error.
@end deffn
-@defun key-binding key &optional accept-defaults
-This function returns the binding for @var{key} in the current
-keymaps, trying all the active keymaps. The result is @code{nil} if
-@var{key} is undefined in the keymaps.
-
-@c Emacs 19 feature
-The argument @var{accept-defaults} controls checking for default
-bindings, as in @code{lookup-key} (above).
-
-An error is signaled if @var{key} is not a string or a vector.
-
-@example
-@group
-(key-binding "\C-x\C-f")
- @result{} find-file
-@end group
-@end example
-@end defun
-
@defun local-key-binding 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.
@defvar meta-prefix-char
@cindex @key{ESC}
-This variable is the meta-prefix character code. It is used when
+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
-@sc{ascii} code for @key{ESC}.
+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
@end group
@group
(setq meta-prefix-char 24)
- @result{} 24
+ @result{} 24
@end group
@group
(key-binding "\M-b")
Commands}). You can also use @code{define-key}, a more general
function; then you must specify explicitly 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}).
+
@cindex meta character key constants
@cindex control character key constants
In writing the key sequence to rebind, it is good to use the special
@code{C-H-left}. One advantage of such lists is that the precise
numeric codes for the modifier bits don't appear in compiled files.
- For the functions below, an error is signaled if @var{keymap} is not a
-keymap or if @var{key} is not a string or vector representing a key
-sequence. You can use event types (symbols) as shorthand for events
-that are lists.
+ The functions below signal an error if @var{keymap} is not a keymap,
+or if @var{key} is not a string or vector representing a key sequence.
+You can use event types (symbols) as shorthand for events that are
+lists. The @code{kbd} macro (@pxref{Key Sequences}) is a convenient
+way to specify the key sequence.
@defun define-key keymap key binding
This function sets the binding for @var{key} in @var{keymap}. (If
meaningful. (For a list of meaningful types, see @ref{Key Lookup}.)
The value returned by @code{define-key} is @var{binding}.
+If @var{key} is @code{[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)
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 in most cases, but it does
-matter for menu keymaps (@pxref{Menu Keymaps}).
+bindings in a keymap makes no difference for keyboard input, but it
+does matter for menu keymaps (@pxref{Menu Keymaps}).
@end defun
Here is an example that creates a sparse keymap and makes a number of
@group
;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
-(define-key map "\C-xf" 'forward-word)
+(define-key map (kbd "C-x f") 'forward-word)
@result{} forward-word
@end group
@group
map
-@result{} (keymap
+@result{} (keymap
(24 keymap ; @kbd{C-x}
(102 . forward-word)) ; @kbd{f}
(6 . forward-char)) ; @kbd{C-f}
@group
;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
-(define-key map "\C-p" ctl-x-map)
+(define-key map (kbd "C-p") ctl-x-map)
;; @code{ctl-x-map}
-@result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
+@result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
@end group
@group
;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
-(define-key map "\C-p\C-f" 'foo)
+(define-key map (kbd "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
+ (24 keymap
(102 . forward-word))
(6 . forward-char))
@end group
changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
default global map.
+ The function @code{substitute-key-definition} scans a keymap for
+keys that have a certain binding and rebinds them with a different
+binding. Another feature which is cleaner and can often produce the
+same results to remap one command into another (@pxref{Remapping
+Commands}).
+
@defun substitute-key-definition olddef newdef keymap &optional oldmap
@cindex replace bindings
This function replaces @var{olddef} with @var{newdef} for any keys in
@smallexample
@group
-(substitute-key-definition
+(substitute-key-definition
'find-file 'find-file-read-only (current-global-map))
@end group
@end smallexample
puts the special deletion command in @code{my-map} for whichever keys
are globally bound to the standard deletion command.
-@ignore
-@c Emacs 18 only
-Prefix keymaps that appear within @var{keymap} are not checked
-recursively for keys bound to @var{olddef}; they are not changed at all.
-Perhaps it would be better to check nested keymaps recursively.
-@end ignore
-
Here is an example showing a keymap before and after substitution:
@smallexample
@group
-(setq map '(keymap
- (?1 . olddef-1)
- (?2 . olddef-2)
+(setq map '(keymap
+ (?1 . olddef-1)
+ (?2 . olddef-2)
(?3 . olddef-1)))
@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
@end group
@defun suppress-keymap keymap &optional nodigits
@cindex @code{self-insert-command} override
This function changes the contents of the full keymap @var{keymap} by
-making all the printing characters undefined. More precisely, it binds
-them to the command @code{undefined}. This makes ordinary insertion of
-text impossible. @code{suppress-keymap} returns @code{nil}.
+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
+@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
@end smallexample
@end defun
+@node Remapping Commands
+@section Remapping Commands
+@cindex remapping commands
+
+ A special kind of key binding, using a special ``key sequence''
+which includes a command name, has the effect of @dfn{remapping} that
+command into another. Here's how it works. You make a key binding
+for a key sequence that starts with the dummy event @code{remap},
+followed by the command name you want to remap. Specify the remapped
+definition as the definition in this binding. The remapped definition
+is usually a command name, but it can be any valid definition for
+a key binding.
+
+ Here's an example. Suppose that My mode uses special commands
+@code{my-kill-line} and @code{my-kill-word}, which should be invoked
+instead of @code{kill-line} and @code{kill-word}. It can establish
+this by making these two command-remapping bindings in its keymap:
+
+@smallexample
+(define-key my-mode-map [remap kill-line] 'my-kill-line)
+(define-key my-mode-map [remap kill-word] 'my-kill-word)
+@end smallexample
+
+Whenever @code{my-mode-map} is an active keymap, if the user types
+@kbd{C-k}, Emacs will find the standard global binding of
+@code{kill-line} (assuming nobody has changed it). But
+@code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line},
+so instead of running @code{kill-line}, Emacs runs
+@code{my-kill-line}.
+
+Remapping only works through a single level. In other words,
+
+@smallexample
+(define-key my-mode-map [remap kill-line] 'my-kill-line)
+(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)
+@end smallexample
+
+@noindent
+does not have the effect of remapping @code{kill-line} into
+@code{my-other-kill-line}. If an ordinary key binding specifies
+@code{kill-line}, this keymap will remap it to @code{my-kill-line};
+if an ordinary binding specifies @code{my-kill-line}, this keymap will
+remap it to @code{my-other-kill-line}.
+
+@defun command-remapping command &optional position
+This function returns the remapping for @var{command} (a symbol),
+given the current active keymaps. If @var{command} is not remapped
+(which is the usual situation), or not a symbol, the function returns
+@code{nil}. @code{position} can optionally specify a buffer position
+or an event position to determine the keymaps to use, as in
+@code{key-binding}.
+@end defun
+
+@node Translation Keymaps
+@section Keymaps for Translating Sequences of Events
+
+ This section describes keymaps that are used during reading a key
+sequence, to translate certain event sequences into others.
+@code{read-key-sequence} checks every subsequence of the key sequence
+being read, as it is read, against @code{function-key-map} and then
+against @code{key-translation-map}.
+
+@defvar function-key-map
+This variable holds a keymap that describes the character sequences sent
+by function keys on an ordinary character terminal. This keymap has the
+same structure as other keymaps, but is used differently: it specifies
+translations to make while reading key sequences, rather than bindings
+for key sequences.
+
+If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
+@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
+key sequence, it is replaced with the events in @var{v}.
+
+For example, VT100 terminals send @kbd{@key{ESC} O P} when the
+keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate
+that sequence of events into the single event @code{pf1}. We accomplish
+this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
+@code{function-key-map}, when using a VT100.
+
+Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
+@key{ESC} O P}; later the function @code{read-key-sequence} translates
+this back into @kbd{C-c @key{PF1}}, which it returns as the vector
+@code{[?\C-c pf1]}.
+
+Entries in @code{function-key-map} are ignored if they conflict with
+bindings made in the minor mode, local, or global keymaps. The intent
+is that the character sequences that function keys send should not have
+command bindings in their own right---but if they do, the ordinary
+bindings take priority.
+
+The value of @code{function-key-map} is usually set up automatically
+according to the terminal's Terminfo or Termcap entry, but sometimes
+those need help from terminal-specific Lisp files. Emacs comes with
+terminal-specific files for many common terminals; their main purpose is
+to make entries in @code{function-key-map} beyond those that can be
+deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
+@end defvar
+
+@defvar key-translation-map
+This variable is another keymap used just like @code{function-key-map}
+to translate input events into other events. It differs from
+@code{function-key-map} in two ways:
+
+@itemize @bullet
+@item
+@code{key-translation-map} goes to work after @code{function-key-map} is
+finished; it receives the results of translation by
+@code{function-key-map}.
+
+@item
+Non-prefix bindings in @code{key-translation-map} override actual key
+bindings. For example, if @kbd{C-x f} has a non-prefix binding in
+@code{key-translation-map}, that translation takes effect even though
+@kbd{C-x f} also has a key binding in the global map.
+@end itemize
+
+Note however that actual key bindings can have an effect on
+@code{key-translation-map}, even though they are overridden by it.
+Indeed, actual key bindings override @code{function-key-map} and thus
+may alter the key sequence that @code{key-translation-map} receives.
+Clearly, it is better to avoid this type of situation.
+
+The intent of @code{key-translation-map} is for users to map one
+character set to another, including ordinary characters normally bound
+to @code{self-insert-command}.
+@end defvar
+
+@cindex key translation function
+You can use @code{function-key-map} or @code{key-translation-map} for
+more than simple aliases, by using a function, instead of a key
+sequence, as the ``translation'' of a key. Then this function is called
+to compute the translation of that key.
+
+The key translation function receives one argument, which is the prompt
+that was specified in @code{read-key-sequence}---or @code{nil} if the
+key sequence is being read by the editor command loop. In most cases
+you can ignore the prompt value.
+
+If the function reads input itself, it can have the effect of altering
+the event that follows. For example, here's how to define @kbd{C-c h}
+to turn the character that follows into a Hyper character:
+
+@example
+@group
+(defun hyperify (prompt)
+ (let ((e (read-event)))
+ (vector (if (numberp e)
+ (logior (lsh 1 24) e)
+ (if (memq 'hyper (event-modifiers e))
+ e
+ (add-event-modifier "H-" e))))))
+
+(defun add-event-modifier (string e)
+ (let ((symbol (if (symbolp e) e (car e))))
+ (setq symbol (intern (concat string
+ (symbol-name symbol))))
+@end group
+@group
+ (if (symbolp e)
+ symbol
+ (cons symbol (cdr e)))))
+
+(define-key function-key-map "\C-ch" 'hyperify)
+@end group
+@end example
+
+ If you have enabled keyboard character set decoding using
+@code{set-keyboard-coding-system}, decoding is done after the
+translations listed above. @xref{Terminal I/O Encoding}. However, in
+future Emacs versions, character set decoding may be done at an
+earlier stage.
+
@node Key Binding Commands
@section Commands for Binding Keys
(@pxref{Init File}) for simple customization. For example,
@smallexample
-(global-set-key "\C-x\C-\\" 'next-line)
+(global-set-key (kbd "C-x C-\\") 'next-line)
@end smallexample
@noindent
@end smallexample
@noindent
-redefines the first (leftmost) mouse button, typed with the Meta key, to
+redefines the first (leftmost) mouse button, entered with the Meta key, to
set point where you click.
-@cindex non-@sc{ascii} text in keybindings
- Be careful when using non-@sc{ascii} text characters in Lisp
+@cindex non-@acronym{ASCII} text in keybindings
+ Be careful when using non-@acronym{ASCII} text characters in Lisp
specifications of keys to bind. If these are read as multibyte text, as
they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
must type the keys as multibyte too. For instance, if you use this:
Latin-1 character with code 246 (@kbd{M-v}). In order to use this
binding, you need to enter the multibyte Latin-1 character as keyboard
input. One way to do this is by using an appropriate input method
-(@pxref{Input Methods, , Input Methods, emacs,The GNU Emacs Manual}).
+(@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}).
If you want to use a unibyte character in the key binding, you can
construct the key sequence string using @code{multibyte-char-to-unibyte}
or @code{string-make-unibyte} (@pxref{Converting Representations}).
-@deffn Command global-set-key key definition
+@deffn Command global-set-key key binding
This function sets the binding of @var{key} in the current global map
-to @var{definition}.
+to @var{binding}.
@smallexample
@group
-(global-set-key @var{key} @var{definition})
+(global-set-key @var{key} @var{binding})
@equiv{}
-(define-key (current-global-map) @var{key} @var{definition})
+(define-key (current-global-map) @var{key} @var{binding})
@end group
@end smallexample
@end deffn
@end smallexample
@end deffn
-@deffn Command local-set-key key definition
+@deffn Command local-set-key key binding
This function sets the binding of @var{key} in the current local
-keymap to @var{definition}.
+keymap to @var{binding}.
@smallexample
@group
-(local-set-key @var{key} @var{definition})
+(local-set-key @var{key} @var{binding})
@equiv{}
-(define-key (current-local-map) @var{key} @var{definition})
+(define-key (current-local-map) @var{key} @var{binding})
@end group
@end smallexample
@end deffn
@var{keymap} is @var{map}.
The elements of the alist are ordered so that the @var{key} increases
-in length. The first element is always @code{("" .@: @var{keymap})},
+in length. The first element is always @code{([] .@: @var{keymap})},
because the specified keymap is accessible from itself with a prefix of
no events.
@smallexample
@group
(accessible-keymaps (current-local-map))
-@result{}(("" keymap
+@result{}(([] keymap
(27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.}
(83 . center-paragraph)
(115 . center-line))
@end group
@group
- ("^[" keymap
- (83 . center-paragraph)
+ ("^[" keymap
+ (83 . center-paragraph)
(115 . foo)))
@end group
@end smallexample
@smallexample
@group
(accessible-keymaps (current-global-map))
-@result{} (("" keymap [set-mark-command beginning-of-line @dots{}
+@result{} (([] keymap [set-mark-command beginning-of-line @dots{}
delete-backward-char])
@end group
@group
These are not all the keymaps you would see in actuality.
@end defun
-@defun where-is-internal command &optional keymap firstonly noindirect
+@defun map-keymap function keymap
+The function @code{map-keymap} calls @var{function} once
+for each binding in @var{keymap}. It passes two arguments,
+the event type and the value of the binding. If @var{keymap}
+has a parent, the parent's bindings are included as well.
+This works recursively: if the parent has itself a parent, then the
+grandparent's bindings are also included and so on.
+
+This function is the cleanest way to examine all the bindings
+in a keymap.
+@end defun
+
+@defun where-is-internal command &optional keymap firstonly noindirect no-remap
This function is a subroutine used by the @code{where-is} command
(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list
-of key sequences (of any length) that are bound to @var{command} in a
+of all key sequences (of any length) that are bound to @var{command} in a
set of keymaps.
The argument @var{command} can be any object; it is compared with all
If @var{keymap} is @code{nil}, then the maps used are the current active
keymaps, disregarding @code{overriding-local-map} (that is, pretending
-its value is @code{nil}). If @var{keymap} is non-@code{nil}, then the
-maps searched are @var{keymap} and the global keymap.
+its value is @code{nil}). If @var{keymap} is a keymap, then the
+maps searched are @var{keymap} and the global keymap. If @var{keymap}
+is a list of keymaps, only those keymaps are searched.
Usually it's best to use @code{overriding-local-map} as the expression
for @var{keymap}. Then @code{where-is-internal} searches precisely the
@code{(keymap)} (an empty keymap) as @var{keymap}.
If @var{firstonly} is @code{non-ascii}, then the value is a single
-string representing the first key sequence found, rather than a list of
+vector representing the first key sequence found, rather than a list of
all possible key sequences. If @var{firstonly} is @code{t}, then the
value is the first key sequence, except that key sequences consisting
-entirely of @sc{ascii} characters (or meta variants of @sc{ascii}
-characters) are preferred to all other key sequences.
+entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII}
+characters) are preferred to all other key sequences and that the
+return value can never be a menu binding.
If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
follow indirect keymap bindings. This makes it possible to search for
an indirect definition itself.
+When command remapping is in effect (@pxref{Remapping Commands}),
+@code{where-is-internal} figures out when a command will be run due to
+remapping and reports keys accordingly. It also returns @code{nil} if
+@var{command} won't really be run because it has been remapped to some
+other command. However, if @var{no-remap} is non-@code{nil}.
+@code{where-is-internal} ignores remappings.
+
@smallexample
@group
(where-is-internal 'describe-function)
@end smallexample
@end defun
-@deffn Command describe-bindings &optional prefix
+@deffn Command describe-bindings &optional prefix buffer-or-name
This function creates a listing of all current key bindings, and
displays it in a buffer named @samp{*Help*}. The text is grouped by
modes---minor modes first, then the major mode, then global bindings.
The listing describes meta characters as @key{ESC} followed by the
corresponding non-meta character.
-When several characters with consecutive @sc{ascii} codes have the
+When several characters with consecutive @acronym{ASCII} codes have the
same definition, they are shown together, as
@samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to
-know the @sc{ascii} codes to understand which characters this means.
+know the @acronym{ASCII} codes to understand which characters this means.
For example, in the default global map, the characters @samp{@key{SPC}
-..@: ~} are described by a single line. @key{SPC} is @sc{ascii} 32,
-@kbd{~} is @sc{ascii} 126, and the characters between them include all
+..@: ~} are described by a single line. @key{SPC} is @acronym{ASCII} 32,
+@kbd{~} is @acronym{ASCII} 126, and the characters between them include all
the normal printing characters, (e.g., letters, digits, punctuation,
etc.@:); all these characters are bound to @code{self-insert-command}.
+
+If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a
+buffer name. Then @code{describe-bindings} lists that buffer's bindings,
+instead of the current buffer's.
@end deffn
@node Menu Keymaps
@section Menu Keymaps
@cindex menu keymaps
-@c Emacs 19 feature
-A keymap can define a menu as well as bindings for keyboard keys and
-mouse button. Menus are usually actuated with the mouse, but they can
-work with the keyboard also.
+A keymap can operate as a menu as well as defining bindings for
+keyboard keys and mouse buttons. Menus are usually actuated with the
+mouse, but they can function with the keyboard also. If a menu keymap
+is active for the next input event, that activates the keyboard menu
+feature.
@menu
* Defining Menus:: How to make a keymap that defines a menu.
* Mouse Menus:: How users actuate the menu with the mouse.
-* Keyboard Menus:: How they actuate it with the keyboard.
+* Keyboard Menus:: How users actuate the menu with the keyboard.
* Menu Example:: Making a simple menu.
* Menu Bar:: How to customize the menu bar.
* Tool Bar:: A tool bar is a row of images.
@cindex menu prompt string
@cindex prompt string (of menu)
-A keymap is suitable for menu use if it has an @dfn{overall prompt
-string}, which is a string that appears as an element of the keymap.
+A keymap acts as a menu if it has an @dfn{overall prompt string},
+which is a string that appears as an element of the keymap.
(@xref{Format of Keymaps}.) The string should describe the purpose of
the menu's commands. Emacs displays the overall prompt string as the
menu title in some cases, depending on the toolkit (if any) used for
displaying menus.@footnote{It is required for menus which do not use a
-toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the overall
-prompt string.
+toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the
+overall prompt string.
+
+The easiest way to construct a keymap with a prompt string is to
+specify the string as an argument when you call @code{make-keymap},
+@code{make-sparse-keymap} (@pxref{Creating Keymaps}), or
+@code{define-prefix-command} (@pxref{Definition of
+define-prefix-command}). If you do not want the keymap to operate as
+a menu, don't specify a prompt string for it.
+
+@defun keymap-prompt keymap
+This function returns the overall prompt string of @var{keymap},
+or @code{nil} if it has none.
+@end defun
-The easiest way to construct a keymap with a prompt string is to specify
-the string as an argument when you call @code{make-keymap},
-@code{make-sparse-keymap} or @code{define-prefix-command}
-(@pxref{Creating Keymaps}).
+The menu's items are the bindings in the keymap. Each binding
+associates an event type to a definition, but the event types have no
+significance for the menu appearance. (Usually we use pseudo-events,
+symbols that the keyboard cannot generate, as the event types for menu
+item bindings.) The menu is generated entirely from the bindings that
+correspond in the keymap to these events.
The order of items in the menu is the same as the order of bindings in
the keymap. Since @code{define-key} puts new bindings at the front, you
@node Simple Menu Items
@subsubsection Simple Menu Items
- The simpler and older way to define a menu keymap binding
-looks like this:
+ The simpler (and original) way to define a menu item is to bind some
+event type (it doesn't matter what event type) to a binding like this:
@example
(@var{item-string} . @var{real-binding})
@noindent
The @sc{car}, @var{item-string}, is the string to be displayed in the
menu. It should be short---preferably one to three words. It should
-describe the action of the command it corresponds to.
+describe the action of the command it corresponds to. Note that it is
+not generally possible to display non-@acronym{ASCII} text in menus. It will
+work for keyboard menus and will work to a large extent when Emacs is
+built with the Gtk+ toolkit.@footnote{In this case, the text is first
+encoded using the @code{utf-8} coding system and then rendered by the
+toolkit as it sees fit.}
-You can also supply a second string, called the help string, as follows:
+ You can also supply a second string, called the help string, as follows:
@example
(@var{item-string} @var{help} . @var{real-binding})
@end example
+@noindent
@var{help} specifies a ``help-echo'' string to display while the mouse
is on that item in the same way as @code{help-echo} text properties
(@pxref{Help display}).
-As far as @code{define-key} is concerned, @var{item-string} and
+ As far as @code{define-key} is concerned, @var{item-string} and
@var{help-string} are part of the event's binding. However,
@code{lookup-key} returns just @var{real-binding}, and only
@var{real-binding} is used for executing the key.
-If @var{real-binding} is @code{nil}, then @var{item-string} appears in
+ If @var{real-binding} is @code{nil}, then @var{item-string} appears in
the menu but cannot be selected.
-If @var{real-binding} is a symbol and has a non-@code{nil}
+ If @var{real-binding} is a symbol and has a non-@code{nil}
@code{menu-enable} property, that property is an expression that
controls whether the menu item is enabled. Every time the keymap is
used to display a menu, Emacs evaluates the expression, and it enables
menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
cannot be selected.
-The menu bar does not recalculate which items are enabled every time you
+ The menu bar does not recalculate which items are enabled every time you
look at a menu. This is because the X toolkit requires the whole tree
of menus in advance. To force recalculation of the menu bar, call
@code{force-mode-line-update} (@pxref{Mode Line Format}).
-You've probably noticed that menu items show the equivalent keyboard key
+ You've probably noticed that menu items show the equivalent keyboard key
sequence (if any) to invoke the same command. To save time on
recalculation, menu display caches this information in a sublist in the
binding, like this:
@c This line is not too long--rms.
@example
-(@var{item-string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
+(@var{item-string} @r{[}@var{help}@r{]} (@var{key-binding-data}) . @var{real-binding})
@end example
@noindent
@kindex menu-item
An extended-format menu item is a more flexible and also cleaner
-alternative to the simple format. It consists of a list that starts
-with the symbol @code{menu-item}. To define a non-selectable string,
-the item looks like this:
+alternative to the simple format. You define an event type with a
+binding that's a list starting with the symbol @code{menu-item}.
+For a non-selectable string, the binding looks like this:
@example
(menu-item @var{item-name})
see @ref{Menu Separators}.
To define a real menu item which can be selected, the extended format
-item looks like this:
+binding looks like this:
@example
(menu-item @var{item-name} @var{real-binding}
The property value @var{filter-fn} should be a function of one argument;
when it is called, its argument will be @var{real-binding}. The
function should return the binding to use instead.
+
+Emacs can call this function at any time that it does redisplay or
+operates on menu data structures, so you should write it so it can
+safely be called at any time.
@end table
+ When an equivalent key binding is cached, the binding looks like this.
+
+@example
+(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data})
+ . @var{item-property-list})
+@end example
+
@node Menu Separators
@subsubsection Menu Separators
@cindex menu separators
A menu separator is a kind of menu item that doesn't display any
-text--instead, it divides the menu into subparts with a horizontal line.
+text---instead, it divides the menu into subparts with a horizontal line.
A separator looks like this in the menu keymap:
@example
That specifies the default kind of separator. (For compatibility,
@code{""} and @code{-} also count as separators.)
- Starting in Emacs 21, certain other values of @var{separator-type}
-specify a different style of separator. Here is a table of them:
+ Certain other values of @var{separator-type} specify a different
+style of separator. Here is a table of them:
@table @code
@item "--no-line"
special about @samp{@@} at the beginning of an item string is that the
@samp{@@} doesn't appear in the menu item.
- You can also produce multiple panes or submenus from separate keymaps.
-The full definition of a prefix key always comes from merging the
-definitions supplied by the various active keymaps (minor mode, local,
-and global). When more than one of these keymaps is a menu, each of
-them makes a separate pane or panes (when Emacs does not use an
-X-toolkit) or a separate submenu (when using an X-toolkit).
-@xref{Active Keymaps}.
+ Multiple keymaps that define the same menu prefix key produce
+separate panes or separate submenus.
@node Keyboard Menus
@subsection Menus and the Keyboard
-When a prefix key ending with a keyboard event (a character or function
-key) has a definition that is a menu keymap, the user can use the
-keyboard to choose a menu item.
+ When a prefix key ending with a keyboard event (a character or
+function key) has a definition that is a menu keymap, the keymap
+operates as a keyboard menu; the user specifies the next event by
+choosing a menu item with the keyboard.
-Emacs displays the menu's overall prompt string followed by the
-alternatives (the item strings of the bindings) in the echo area. If
-the bindings don't all fit at once, the user can type @key{SPC} to see
-the next line of alternatives. Successive uses of @key{SPC} eventually
-get to the end of the menu and then cycle around to the beginning. (The
-variable @code{menu-prompt-more-char} specifies which character is used
-for this; @key{SPC} is the default.)
+ Emacs displays the keyboard menu with the map's overall prompt
+string, followed by the alternatives (the item strings of the map's
+bindings), in the echo area. If the bindings don't all fit at once,
+the user can type @key{SPC} to see the next line of alternatives.
+Successive uses of @key{SPC} eventually get to the end of the menu and
+then cycle around to the beginning. (The variable
+@code{menu-prompt-more-char} specifies which character is used for
+this; @key{SPC} is the default.)
-When the user has found the desired alternative from the menu, he or she
-should type the corresponding character---the one whose binding is that
-alternative.
+ When the user has found the desired alternative from the menu, he or
+she should type the corresponding character---the one whose binding is
+that alternative.
@ignore
In a menu intended for keyboard use, each menu item must clearly
key for each alternative.
@end ignore
-This way of using menus in an Emacs-like editor was inspired by the
+ This way of using menus in an Emacs-like editor was inspired by the
Hierarkey system.
@defvar menu-prompt-more-char
@cindex menu definition example
Here is a complete example of defining a menu keymap. It is the
-definition of the @samp{Print} submenu in the @samp{Tools} menu in the
-menu bar, and it uses the simple menu item format (@pxref{Simple Menu
-Items}). First we create the keymap, and give it a name:
+definition of the @samp{Replace} submenu in the @samp{Edit} menu in
+the menu bar, and it uses the extended menu item format
+(@pxref{Extended Menu Items}). First we create the keymap, and give
+it a name:
-@example
-(defvar menu-bar-print-menu (make-sparse-keymap "Print"))
-@end example
+@smallexample
+(defvar menu-bar-replace-menu (make-sparse-keymap "Replace"))
+@end smallexample
@noindent
Next we define the menu items:
-@example
-(define-key menu-bar-print-menu [ps-print-region]
- '("Postscript Print Region" . ps-print-region-with-faces))
-(define-key menu-bar-print-menu [ps-print-buffer]
- '("Postscript Print Buffer" . ps-print-buffer-with-faces))
-(define-key menu-bar-print-menu [separator-ps-print]
- '("--"))
-(define-key menu-bar-print-menu [print-region]
- '("Print Region" . print-region))
-(define-key menu-bar-print-menu [print-buffer]
- '("Print Buffer" . print-buffer))
-@end example
+@smallexample
+(define-key menu-bar-replace-menu [tags-repl-continue]
+ '(menu-item "Continue Replace" tags-loop-continue
+ :help "Continue last tags replace operation"))
+(define-key menu-bar-replace-menu [tags-repl]
+ '(menu-item "Replace in tagged files" tags-query-replace
+ :help "Interactively replace a regexp in all tagged files"))
+(define-key menu-bar-replace-menu [separator-replace-tags]
+ '(menu-item "--"))
+;; @r{@dots{}}
+@end smallexample
@noindent
Note the symbols which the bindings are ``made for''; these appear
inside square brackets, in the key sequence being defined. In some
cases, this symbol is the same as the command name; sometimes it is
-different. These symbols are treated as ``function keys'', but they are
+different. These symbols are treated as ``function keys,'' but they are
not real function keys on the keyboard. They do not affect the
functioning of the menu itself, but they are ``echoed'' in the echo area
when the user selects from the menu, and they appear in the output of
@code{where-is} and @code{apropos}.
+ The menu in this example is intended for use with the mouse. If a
+menu is intended for use with the keyboard, that is, if it is bound to
+a key sequence ending with a keyboard event, then the menu items
+should be bound to characters or ``real'' function keys, that can be
+typed with the keyboard.
+
The binding whose definition is @code{("--")} is a separator line.
Like a real menu item, the separator has a key symbol, in this case
-@code{separator-ps-print}. If one menu has two separators, they must
-have two different key symbols.
-
- Here is code to define enable conditions for two of the commands in
-the menu:
-
-@example
-(put 'print-region 'menu-enable 'mark-active)
-(put 'ps-print-region-with-faces 'menu-enable 'mark-active)
-@end example
+@code{separator-replace-tags}. If one menu has two separators, they
+must have two different key symbols.
Here is how we make this menu appear as an item in the parent menu:
@example
-(define-key menu-bar-tools-menu [print]
- (cons "Print" menu-bar-print-menu))
+(define-key menu-bar-edit-menu [replace]
+ (list 'menu-item "Replace" menu-bar-replace-menu))
@end example
@noindent
Note that this incorporates the submenu keymap, which is the value of
-the variable @code{menu-bar-print-menu}, rather than the symbol
-@code{menu-bar-print-menu} itself. Using that symbol in the parent menu
-item would be meaningless because @code{menu-bar-print-menu} is not a
-command.
+the variable @code{menu-bar-replace-menu}, rather than the symbol
+@code{menu-bar-replace-menu} itself. Using that symbol in the parent
+menu item would be meaningless because @code{menu-bar-replace-menu} is
+not a command.
- If you wanted to attach the same print menu to a mouse click, you
+ If you wanted to attach the same replace menu to a mouse click, you
can do it this way:
@example
(define-key global-map [C-S-down-mouse-1]
- menu-bar-print-menu)
-@end example
-
- We could equally well use an extended menu item (@pxref{Extended Menu
-Items}) for @code{print-region}, like this:
-
-@example
-(define-key menu-bar-print-menu [print-region]
- '(menu-item "Print Region" print-region
- :enable mark-active))
-@end example
-
-@noindent
-With the extended menu item, the enable condition is specified
-inside the menu item itself. If we wanted to make this
-item disappear from the menu entirely when the mark is inactive,
-we could do it this way:
-
-@example
-(define-key menu-bar-print-menu [print-region]
- '(menu-item "Print Region" print-region
- :visible mark-active))
+ menu-bar-replace-menu)
@end example
@node Menu Bar
Most window systems allow each frame to have a @dfn{menu bar}---a
permanently displayed menu stretching horizontally across the top of the
frame. The items of the menu bar are the subcommands of the fake
-``function key'' @code{menu-bar}, as defined by all the active keymaps.
+``function key'' @code{menu-bar}, as defined in the active keymaps.
To add an item to the menu bar, invent a fake ``function key'' of your
own (let's call it @var{key}), and make a binding for the key sequence
parameter must be greater than zero. Emacs uses just one line for the
menu bar itself; if you specify more than one line, the other lines
serve to separate the menu bar from the windows in the frame. We
-recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{Window Frame
+recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{Layout
Parameters}.
Here's an example of setting up a menu bar item:
@end defvar
@defvar menu-bar-update-hook
-This normal hook is run whenever the user clicks on the menu bar, before
-displaying a submenu. You can use it to update submenus whose contents
-should vary.
+This normal hook is run by redisplay to update the menu bar contents,
+before redisplaying the menu bar. You can use it to update submenus
+whose contents should vary. Since this hook is run frequently, we
+advise you to ensure that the functions it calls do not take much time
+in the usual case.
@end defvar
@node Tool Bar
A @dfn{tool bar} is a row of icons at the top of a frame, that execute
commands when you click on them---in effect, a kind of graphical menu
-bar. Emacs supports tool bars starting with version 21.
+bar.
The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
controls how many lines' worth of height to reserve for the tool bar. A
using an indirection through @code{tool-bar-map}.
@defvar tool-bar-map
-@tindex tool-bar-map
By default, the global map binds @code{[tool-bar]} as follows:
@example
(global-set-key [tool-bar]
follows.
@defun tool-bar-add-item icon def key &rest props
-@tindex tool-bar-add-item
This function adds an item to the tool bar by modifying
@code{tool-bar-map}. The image to use is defined by @var{icon}, which
-is the base name of an XPM, XBM or PBM image file to located by
+is the base name of an XPM, XBM or PBM image file to be located by
@code{find-image}. Given a value @samp{"exit"}, say, @file{exit.xpm},
@file{exit.pbm} and @file{exit.xbm} would be searched for in that order
on a color display. On a monochrome display, the search order is
prefix keymap. The remaining arguments @var{props} are additional
property list elements to add to the menu item specification.
-To define items in some local map, bind @code{`tool-bar-map} with
+To define items in some local map, bind @code{tool-bar-map} with
@code{let} around calls of this function:
@example
-(defvar foo-tool-bar-map
+(defvar foo-tool-bar-map
(let ((tool-bar-map (make-sparse-keymap)))
(tool-bar-add-item @dots{})
@dots{}
@end defun
@defun tool-bar-add-item-from-menu command icon &optional map &rest props
-@tindex tool-bar-add-item-from-menu
-This command is a convenience for defining tool bar items which are
+This function is a convenience for defining tool bar items which are
consistent with existing menu bar bindings. The binding of
@var{command} is looked up in the menu bar in @var{map} (default
@code{global-map}) and modified to add an image specification for
-@var{icon}, which is looked for in the same way as by
+@var{icon}, which is found in the same way as by
@code{tool-bar-add-item}. The resulting binding is then placed in
-@code{tool-bar-map}. @var{map} must contain an appropriate keymap bound
-to @code{[menu-bar]}. The remaining arguments @var{props} are
-additional property list elements to add to the menu item specification.
+@code{tool-bar-map}, so use this function only for global tool bar
+items.
+
+@var{map} must contain an appropriate keymap bound to
+@code{[menu-bar]}. The remaining arguments @var{props} are additional
+property list elements to add to the menu item specification.
+@end defun
+
+@defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props
+This function is used for making non-global tool bar items. Use it
+like @code{tool-bar-add-item-from-menu} except that @var{in-map}
+specifies the local map to make the definition in. The argument
+@var{from-map} is like the @var{map} argument of
+@code{tool-bar-add-item-from-menu}.
@end defun
-@tindex auto-resize-tool-bar
@defvar auto-resize-tool-bar
If this variable is non-@code{nil}, the tool bar automatically resizes to
show all defined tool bar items---but not larger than a quarter of the
frame's height.
@end defvar
-@tindex auto-raise-tool-bar-items
-@defvar auto-raise-tool-bar-items
+@defvar auto-raise-tool-bar-buttons
If this variable is non-@code{nil}, tool bar items display
in raised form when the mouse moves over them.
@end defvar
-@tindex tool-bar-item-margin
-@defvar tool-bar-item-margin
+@defvar tool-bar-button-margin
This variable specifies an extra margin to add around tool bar items.
-The value is an integer, a number of pixels. The default is 1.
+The value is an integer, a number of pixels. The default is 4.
@end defvar
-@tindex tool-bar-item-relief
-@defvar tool-bar-item-relief
+@defvar tool-bar-button-relief
This variable specifies the shadow width for tool bar items.
-The value is an integer, a number of pixels. The default is 3.
+The value is an integer, a number of pixels. The default is 1.
+@end defvar
+
+@defvar tool-bar-border
+This variable specifies the height of the border drawn below the tool
+bar area. An integer value specifies height as a number of pixels.
+If the value is one of @code{internal-border-width} (the default) or
+@code{border-width}, the tool bar border height corresponds to the
+corresponding frame parameter.
@end defvar
You can define a special meaning for clicking on a tool bar item with
[work] '("Work" . work-command) 'break)
@end example
@end defun
+
+@ignore
+ arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794
+@end ignore