[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

40.8.2 Translating Input Events

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.

Variable: extra-keyboard-modifiers
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.

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 is normally a char-table, or else nil.

If keyboard-translate-table is a char-table (see section 6.6 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 section 40.12 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.

Function: keyboard-translate from to
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.

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 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] 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--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 in function-key-map beyond those that can be deduced from Termcap and Terminfo. See section 40.1.3 Terminal-Specific Initialization.

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 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 section 33.10.6 Specifying a Coding System for One Operation. In future Emacs versions, character set decoding may be done before the other translations.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated on May 2, 2002 using texi2html