Commit 13bdd945 authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

(System Interface): Fix menu descriptions of some nodes.

(Translating Input): Node deleted.
parent 160ab7f9
......@@ -28,8 +28,8 @@ pertaining to the terminal and the screen.
* Processor Run Time:: Getting the run time used by Emacs.
* Time Calculations:: Adding, subtracting, comparing times, etc.
* Timers:: Setting a timer to call a function at a certain time.
* Terminal Input:: Recording terminal input for debugging.
* Terminal Output:: Recording terminal output for debugging.
* Terminal Input:: Accessing and recording terminal input.
* Terminal Output:: Controlling and recording terminal output.
* Sound Output:: Playing sounds on the computer's speaker.
* X11 Keysyms:: Operating on key symbols for X Windows
* Batch Mode:: Running Emacs without terminal interaction.
......@@ -1521,8 +1521,6 @@ functions.
* Input Modes:: Options for how input is processed.
* Translating Input:: Low level conversion of some characters or events
into others.
* Recording Input:: Saving histories of recent or all input events.
@end menu
......@@ -1587,204 +1585,6 @@ is the character Emacs currently uses for quitting, usually @kbd{C-g}.
@end table
@end defun
@node Translating Input
@subsection Translating Input Events
@cindex 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 @code{extra-keyboard-modifiers},
then translated through @code{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
@code{function-key-map} and then with @code{key-translation-map}.
@c Emacs 19 feature
@defvar extra-keyboard-modifiers
This variable lets Lisp programs ``press'' the modifier keys on the
keyboard. The value is a character. Only the modifiers of the
character matter. Each time the user types a keyboard key, it is
altered as if those modifier keys were held down. For instance, if
you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all
keyboard input characters typed during the scope of the binding will
have the control and meta modifiers applied to them. The character
@code{?\C-@@}, equivalent to the integer 0, does not count as a control
character for this purpose, but as a character with no modifiers.
Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
When using a window system, the program can ``press'' any of the
modifier keys in this way. Otherwise, only the @key{CTL} and @key{META}
keys can be virtually pressed.
Note that this variable applies only to events that really come from
the keyboard, and has no effect on mouse events or any other events.
@end defvar
@defvar 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 @code{nil}.
(It can also be a string or vector, but this is considered obsolete.)
If @code{keyboard-translate-table} is a char-table
(@pxref{Char-Tables}), then each character read from the keyboard is
looked up in this char-table. If the value found there is
non-@code{nil}, then it is used instead of the actual input character.
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 @code{recent-keys} and dribble files record the characters after
Note also that this translation is done before the characters are
supplied to input methods (@pxref{Input Methods}). Use
@code{translation-table-for-input} (@pxref{Translation of Characters}),
if you want to translate characters after input methods operate.
@end defvar
@defun keyboard-translate from to
This function modifies @code{keyboard-translate-table} to translate
character code @var{from} into character code @var{to}. It creates
the keyboard translate table if necessary.
@end defun
Here's an example of using the @code{keyboard-translate-table} to
make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste
(keyboard-translate ?\C-x 'control-x)
(keyboard-translate ?\C-c 'control-c)
(keyboard-translate ?\C-v 'control-v)
(global-set-key [control-x] 'kill-region)
(global-set-key [control-c] 'kill-ring-save)
(global-set-key [control-v] 'yank)
@end example
On a graphical terminal that supports extended @acronym{ASCII} input,
you can still get the standard Emacs meanings of one of those
characters by typing it with the shift key. That makes it a different
character as far as keyboard translation is concerned, but it has the
same usual meaning.
The remaining translation features translate subsequences of key
sequences being read. They are implemented in @code{read-key-sequence}
and have no effect on input read with @code{read-event}.
@defvar 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 @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
key sequence, it is replaced with the events in @var{v}.
For example, VT100 terminals send @kbd{@key{ESC} O P} when the
keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate
that sequence of events into the single event @code{pf1}. We accomplish
this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
@code{function-key-map}, when using a VT100.
Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
@key{ESC} O P}; later the function @code{read-key-sequence} translates
this back into @kbd{C-c @key{PF1}}, which it returns as the vector
@code{[?\C-c pf1]}.
Entries in @code{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 @code{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 @code{function-key-map} beyond those that can be
deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
@end defvar
@defvar key-translation-map
This variable is another keymap used just like @code{function-key-map}
to translate input events into other events. It differs from
@code{function-key-map} in two ways:
@itemize @bullet
@code{key-translation-map} goes to work after @code{function-key-map} is
finished; it receives the results of translation by
Non-prefix bindings in @code{key-translation-map} override actual key
bindings. For example, if @kbd{C-x f} has a non-prefix binding in
@code{key-translation-map}, that translation takes effect even though
@kbd{C-x f} also has a key binding in the global map.
@end itemize
Note however that actual key bindings can have an effect on
@code{key-translation-map}, even though they are overridden by it.
Indeed, actual key bindings override @code{function-key-map} and thus
may alter the key sequence that @code{key-translation-map} receives.
Clearly, it is better to avoid this type of situation.
The intent of @code{key-translation-map} is for users to map one
character set to another, including ordinary characters normally bound
to @code{self-insert-command}.
@end defvar
@cindex key translation function
You can use @code{function-key-map} or @code{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 @code{read-key-sequence}---or @code{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 @kbd{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))
(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))))
@end group
(if (symbolp e)
(cons symbol (cdr e)))))
(define-key function-key-map "\C-ch" 'hyperify)
@end group
@end example
Finally, if you have enabled keyboard character set decoding using
@code{set-keyboard-coding-system}, decoding is done after the
translations listed above. @xref{Terminal I/O Encoding}. In future
Emacs versions, character set decoding may be done before the other
@node Recording Input
@subsection Recording Input
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment