GNU Info
(elisp)Translating Input
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 (Note:
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.
(Note: 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. Note: Terminal-Specific.
- 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:
* `key-translation-map' goes to work after `function-key-map' is
finished; it receives the results of translation by
`function-key-map'.
* `key-translation-map' overrides actual key bindings. For
example, if `C-x f' has a binding in `key-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 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. Note: Specifying Coding Systems. In future Emacs
versions, character set decoding may be done before the other
translations.
automatically generated by info2www version 1.2.2.9