Next: Key Binding Commands, Previous: Remapping Commands, Up: Keymaps
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 function-key-map and then
against key-translation-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
function-key-map“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[pf1]infunction-key-map, when using a VT100.Thus, typing C-c <PF1> sends the character sequence C-c <ESC> O P; later the function
read-key-sequencetranslates this back into C-c <PF1>, which it returns as the vector[?\C-c pf1].Entries in
function-key-mapare 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
function-key-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 infunction-key-mapbeyond those that can be deduced from Termcap and Terminfo. See Terminal-Specific.
This variable is another keymap used just like
function-key-mapto translate input events into other events. It differs fromfunction-key-mapin two ways:
key-translation-mapgoes to work afterfunction-key-mapis finished; it receives the results of translation byfunction-key-map.- Non-prefix bindings in
key-translation-mapoverride actual key bindings. For example, if C-x f has a non-prefix binding inkey-translation-map, that translation takes effect even though C-x f also has a key binding in the global map.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 overridefunction-key-mapand thus may alter the key sequence thatkey-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 toself-insert-command.
You can use function-key-map or 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 read-key-sequence—or 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 function-key-map "\C-ch" 'hyperify)
If you have enabled keyboard character set decoding using
set-keyboard-coding-system, decoding is done after the
translations listed above. See Terminal I/O Encoding. However, in
future Emacs versions, character set decoding may be done at an
earlier stage.