Next: , Previous: Remapping Commands, Up: Keymaps

22.14 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. read-key-sequence checks every subsequence of the key sequence being read, as it is read, against input-decode-map, then local-function-key-map, and then against key-translation-map.

— Variable: input-decode-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 input-decode-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] in input-decode-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].

The value of input-decode-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 input-decode-map beyond those that can be deduced from Termcap and Terminfo. See Terminal-Specific.

— Variable: local-function-key-map

This variable holds a keymap similar to input-decode-map except that it describes key sequences which should be translated to alternative interpretations that are usually preferred. It applies after input-decode-map and before key-translation-map.

Entries in local-function-key-map are 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.

local-function-key-map inherits from function-key-map, but the latter should not be used directly.

— Variable: key-translation-map

This variable is another keymap used just like input-decode-map to translate input events into other events. It differs from input-decode-map in that it goes to work after local-function-key-map is finished rather than before; it receives the results of translation by local-function-key-map.

Just like 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-map and thus may alter the key sequence that key-translation-map receives. Clearly, it is better to avoid this type of situation.

The intent of key-translation-map is for users to map one character set to another, including ordinary characters normally bound to self-insert-command.

You can use input-decode-map, local-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 local-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.