This section describes keymaps that are used during reading a key
sequence, to translate certain event sequences into others.
read-key-sequence checks every subsequence of the key sequence
being read, as it is read, against
local-function-key-map, and then against
These keymaps have the same structure as other keymaps, but they are used differently: they specify translations to make while reading key sequences, rather than bindings for key sequences.
If one of these keymaps “binds” a key sequence k to a vector v, then when k appears as a subsequence anywhere in a key sequence, it is replaced with the events in v.
For example, VT100 terminals send <ESC> O P when the
keypad <PF1> key is pressed. Therefore, we want Emacs to translate
that sequence of events into the single event
pf1. We accomplish
this by “binding” <ESC> O P to
input-decode-map, when using a VT100.
Thus, typing C-c <PF1> sends the character sequence C-c
<ESC> O P; later the function
this back into C-c <PF1>, which it returns as the vector
This variable holds a keymap that describes the character sequences sent by function keys on an ordinary character terminal.
The value of
input-decode-mapis 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
input-decode-mapbeyond those that can be deduced from Termcap and Terminfo. See Terminal-Specific.
This variable holds a keymap similar to
input-decode-mapexcept that it describes key sequences which should be translated to alternative interpretations that are usually preferred. It applies after
local-function-key-mapare ignored if they conflict with bindings made in the minor mode, local, or global keymaps. I.e., the remapping only applies if the original key sequence would otherwise not have any binding.
function-key-map, but the latter should not be used directly.
This variable is another keymap used just like
input-decode-mapto translate input events into other events. It differs from
input-decode-mapin that it goes to work after
local-function-key-mapis finished rather than before; it receives the results of translation by
input-decode-map, but unlike
local-function-key-map, this keymap is applied regardless of whether the input key-sequence has a normal binding. Note however that actual key bindings can have an effect on
key-translation-map, even though they are overridden by it. Indeed, actual key bindings override
local-function-key-mapand thus may alter the key sequence that
key-translation-mapreceives. Clearly, it is better to avoid this type of situation.
The intent of
key-translation-mapis for users to map one character set to another, including ordinary characters normally bound to
You can use
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
The key translation function receives one argument, which is the prompt
that was specified in
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 C-c h to turn the character that follows into a Hyper character:
(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)))) (if (symbolp e) symbol (cons symbol (cdr e))))) (define-key local-function-key-map "\C-ch" 'hyperify)
If you have enabled keyboard character set decoding using
set-keyboard-coding-system, decoding is done before the
translations listed above. See Terminal I/O Encoding.
The end of a key sequence is detected when that key sequence either is bound to a command, or when Emacs determines that no additional event can lead to a sequence that is bound to a command.
This means that, while
apply regardless of whether the original key sequence would have a binding, the
presence of such a binding can still prevent translation from taking place.
For example, let us return to our VT100 example above and add a binding for
C-c <ESC> to the global map; now when the user hits C-c
<PF1> Emacs will fail to decode C-c <ESC> O P into C-c
<PF1> because it will stop reading keys right after C-x <ESC>,
leaving O P for later. This is in case the user really hit C-c
<ESC>, in which case Emacs should not sit there waiting for the next key
to decide whether the user really pressed <ESC> or <PF1>.
For that reason, it is better to avoid binding commands to key sequences where the end of the key sequence is a prefix of a key translation. The main such problematic suffixes/prefixes are <ESC>, M-O (which is really <ESC> O) and M-[ (which is really <ESC> [).