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
* Functions for Key Lookup:: How to request key lookup.
* Changing Key Bindings:: Redefining a key in a keymap.
* Remapping Commands:: Bindings that translate one command to another.
+* 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
+@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
keymaps shadow both local and global keymaps. @xref{Active Keymaps},
for details.
- The Emacs Lisp representation for a key sequence is a string or vector.
-You can enter key sequence constants using the ordinary string or vector
-representation; it is also convenient to use @code{kbd}:
-
-@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 the 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}).
-
-@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
-@end defmac
-
@node Format of Keymaps
@section Format of Keymaps
@cindex format of keymaps
@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.
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
(@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))
+ (if (get-text-property (point) 'local-map)
(@var{find-in} (get-text-property (point) 'local-map))
(@var{find-in} (current-local-map))))))
(@var{find-in} (current-global-map)))
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.
@node Searching Keymaps
@section Searching the Active Keymaps
- After translation of the input events (@pxref{Translating Input})
+ 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 in which the active keymaps are searched:
(@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)
- (@var{find-in} (get-text-property (point) 'local-map))
- (@var{find-in} (current-local-map)))))
+ (if (get-text-property (point) 'local-map)
+ (@var{find-in} (get-text-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
-searches in one keymap respectively an alist of keymaps.
+search in one keymap and in an alist of keymaps, respectively.
@enumerate
@item
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 @code{kbd} macro (@pxref{Keymap Terminology}) is
-a convenient way to specify the key sequence.
+ 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
@code{nil}.
@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
@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
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
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
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 be located by
@end defun
@defun tool-bar-add-item-from-menu command icon &optional map &rest props
-@tindex tool-bar-add-item-from-menu
This function is a convenience for defining tool bar items which are
consistent with existing menu bar bindings. The binding of
@var{command} is looked up in the menu bar in @var{map} (default
@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-buttons
@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-button-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 4.
@end defvar
-@tindex tool-bar-button-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 1.
@end defvar
-@tindex tool-bar-border
@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.