From: Richard M. Stallman Date: Mon, 31 Jul 2006 18:41:58 +0000 (+0000) Subject: Update xrefs. X-Git-Tag: emacs-pretest-22.0.90~1164 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=160ab7f94edfc632d89cea3cf149bdefb0adb825;p=emacs.git Update xrefs. (Event Mod): New node, cut out from old Translating Input. --- diff --git a/lispref/commands.texi b/lispref/commands.texi index 10cd97400f8..8e34fe360bf 100644 --- a/lispref/commands.texi +++ b/lispref/commands.texi @@ -1087,7 +1087,7 @@ Lisp programs by representing the former as the integer 9, and the latter as the symbol @code{tab}. Most of the time, it's not useful to distinguish the two. So normally -@code{function-key-map} (@pxref{Translating Input}) is set up to map +@code{function-key-map} (@pxref{Translation Keymaps}) is set up to map @code{tab} into 9. Thus, a key binding for character code 9 (the character @kbd{C-i}) also applies to @code{tab}. Likewise for the other symbols in this group. The function @code{read-char} likewise converts @@ -2051,14 +2051,14 @@ functions for event input are also available for use in Lisp programs. See also @code{momentary-string-display} in @ref{Temporary Displays}, and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for functions and variables for controlling terminal input modes and -debugging terminal input. @xref{Translating Input}, for features you -can use for translating or modifying input events while reading them. +debugging terminal input. For higher-level input facilities, see @ref{Minibuffers}. @menu * Key Sequence Input:: How to read one key sequence. * Reading One Event:: How to read just one event. +* Event Mod:: How Emacs modifies events as they are read. * Invoking the Input Method:: How reading an event uses the input method. * Quoted Character Input:: Asking the user to specify a character. * Event Input Misc:: How to reread or throw away input events. @@ -2088,7 +2088,7 @@ events---characters, symbols, and lists. The elements of the string or vector are the events in the key sequence. Reading a key sequence includes translating the events in various -ways. @xref{Translating Input}. +ways. @xref{Translation Keymaps}. The argument @var{prompt} is either a string to be displayed in the echo area as a prompt, or @code{nil}, meaning not to display a prompt. @@ -2290,6 +2290,87 @@ This variable holds the total number of input events received so far from the terminal---not counting those generated by keyboard macros. @end defvar +@node Event Mod +@subsection Modifying and Translating Input Events + + Emacs modifies every event it reads according to +@code{extra-keyboard-modifiers}, then translates it through +@code{keyboard-translate-table} (if applicable), before returning it +from @code{read-event}. + +@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 +modification. + +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 +translation. + +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 +operations: + +@example +(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 + +@noindent +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. + + @xref{Translation Keymaps}, for mechanisms that translate event sequences +at the level of @code{read-key-sequence}. + @node Invoking the Input Method @subsection Invoking the Input Method