Next: , Previous: Input Modes, Up: Terminal Input

58.8.2 Translating Input Events

This section describes features for translating input events into other input events before they become part of key sequences.

— Variable: keyboard-translate-table

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 must be a string or nil.

If keyboard-translate-table is a string, then each character read from the keyboard is looked up in this string and the character in the string is used instead. If the string is of length n, character codes n and up are untranslated.

In the example below, we set keyboard-translate-table to a string of 128 characters. 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. 

          (defun evade-flow-control ()
            "Replace C-s with C-\ and C-q with C-^."
            (interactive)
            (let ((the-table (make-string 128 0)))
              (let ((i 0))
                (while (< i 128)
                  (aset the-table i i)
                  (setq i (1+ i))))
              ;; Swap C-s and C-\.
              (aset the-table ?\034 ?\^s)
              (aset the-table ?\^s ?\034)
              ;; Swap C-q and C-^.
              (aset the-table ?\036 ?\^q)
              (aset the-table ?\^q ?\036)
              (setq keyboard-translate-table the-table)))

Note: 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.

— Function: keyboard-translate &rest pairs

This function modifies keyboard-translate-table to translate character code from into character code to. It creates or enlarges the translate table if necessary. Multiple from-to pairs may be specified.

— Variable: function-key-map

This variable holds a keymap that describes the character sequences sent by function keys on an ordinary character terminal. This keymap uses the same data structure as other keymaps, but is used differently: it specifies translations to make while reading events.

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 SXEmacs to translate that sequence of events into the single event pf1. We accomplish this by “binding” <ESC> O P to [pf1] in function-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.

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. SXEmacs comes with terminal-specific files for many common terminals; their main purpose is to make entries in function-key-map beyond those that can be deduced from Termcap and Terminfo. See Terminal-Specific.

Note: Emacs versions 18 and earlier used totally different means of detecting the character sequences that represent function keys.

— Variable: key-translation-map

This variable is another keymap used just like function-key-map to translate input events into other events. It differs from function-key-map in two ways:

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 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 20) 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)

The iso-transl library uses this feature to provide a way of inputting non-ASCII Latin-1 characters.