Next: Recording Input, Previous: Input Modes, Up: Terminal Input
This section describes features for translating input events into
other input events before they become part of key sequences. These
features apply to each event in the order they are described here: each
event is first modified according to extra-keyboard-modifiers
,
then translated through keyboard-translate-table
(if applicable),
and finally decoded with the specified keyboard coding system. If it is
being read as part of a key sequence, it is then added to the sequence
being read; then subsequences containing it are checked first with
function-key-map
and then with key-translation-map
.
This variable lets Lisp programs “press” the modifier keys on the keyboard. The value is a bit mask:
- 1
- The <SHIFT> key.
- 2
- The <LOCK> key.
- 4
- The <CTL> key.
- 8
- The <META> key.
Each time the user types a keyboard key, it is altered as if the modifier keys specified in the bit mask were held down.
When using a window system, the program can “press” any of the modifier keys in this way. Otherwise, only the <CTL> and <META> keys can be virtually pressed.
This variable is the translate table for keyboard characters. It lets you reshuffle the keys on the keyboard without changing any command bindings. Its value is normally a char-table, or else
nil
.If
keyboard-translate-table
is a char-table (see Char-Tables), then each character read from the keyboard is looked up in this char-table. If the value found there is non-nil
, then it is used instead of the actual input character.In the example below, we set
keyboard-translate-table
to a char-table. Then we fill it in to swap the characters C-s and C-\ and the characters C-q and C-^. Subsequently, typing C-\ has all the usual effects of typing C-s, and vice versa. (See Flow Control, for more information on this subject.)(defun evade-flow-control () "Replace C-s with C-\ and C-q with C-^." (interactive) (setq keyboard-translate-table (make-char-table 'keyboard-translate-table nil)) ;; Swap C-s and C-\. (aset keyboard-translate-table ?\034 ?\^s) (aset keyboard-translate-table ?\^s ?\034) ;; Swap C-q and C-^. (aset keyboard-translate-table ?\036 ?\^q) (aset keyboard-translate-table ?\^q ?\036))Note that this translation is the first thing that happens to a character after it is read from the terminal. Record-keeping features such as
recent-keys
and dribble files record the characters after translation.
This function modifies
keyboard-translate-table
to translate character code from into character code to. It creates the keyboard translate table if necessary.
The remaining translation features translate subsequences of key
sequences being read. They are implemented in read-key-sequence
and have no effect on input read with read-event
.
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-sequence
translates this back into C-c <PF1>, which it returns as the vector[?\C-c pf1]
.Entries in
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
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 infunction-key-map
beyond those that can be deduced from Termcap and Terminfo. See Terminal-Specific.
This variable is another keymap used just like
function-key-map
to translate input events into other events. It differs fromfunction-key-map
in two ways:
key-translation-map
goes to work afterfunction-key-map
is finished; it receives the results of translation byfunction-key-map
.key-translation-map
overrides actual key bindings. For example, if C-x f has a binding inkey-translation-map
, that translation takes effect even though C-x f also has a key binding in the global map.The intent of
key-translation-map
is 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)
Finally, if you have enabled keyboard character set decoding using
set-keyboard-coding-system
, decoding is done after the
translations listed above. See Specifying Coding Systems. In future
Emacs versions, character set decoding may be done before the other
translations.