Otherwise, the command is added only if it uses the minibuffer to read
an argument. @xref{Command History}.
-The argument @var{keys}, if given, specifies the sequence of events to
-supply if the command inquires which events were used to invoke it.
-If @var{keys} is omitted or @code{nil}, the return value of
-@code{this-command-keys} is used. @xref{Definition of this-command-keys}.
+The argument @var{keys}, if given, should be a vector which specifies
+the sequence of events to supply if the command inquires which events
+were used to invoke it. If @var{keys} is omitted or @code{nil}, the
+default is the return value of @code{this-command-keys-vector}.
+@xref{Definition of this-command-keys-vector}.
@end defun
@defun command-execute command &optional record-flag keys special
@end defvar
@defun this-command-keys
-@anchor{Definition of this-command-keys}
This function returns a string or vector containing the key sequence
that invoked the present command, plus any previous commands that
-generated the prefix argument for this command. However, if the
-command has called @code{read-key-sequence}, it returns the last read
-key sequence. @xref{Key Sequence Input}. The value is a string if
-all events in the sequence were characters that fit in a string.
-@xref{Input Events}.
+generated the prefix argument for this command. Any events read by the
+command using @code{read-event} without a timeout get tacked on to the end.
+
+However, if the command has called @code{read-key-sequence}, it
+returns the last read key sequence. @xref{Key Sequence Input}. The
+value is a string if all events in the sequence were characters that
+fit in a string. @xref{Input Events}.
@example
@group
@end defun
@defun this-command-keys-vector
+@anchor{Definition of this-command-keys-vector}
Like @code{this-command-keys}, except that it always returns the events
in a vector, so you don't need to deal with the complexities of storing
input events in a string (@pxref{Strings of Events}).
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
parameters are used to display the help-echo text are described in
@ref{Text help-echo}.
-@cindex @code{usr1-signal} event
-@cindex @code{usr2-signal} event
-@item usr1-signal
-@itemx usr2-signal
-These events are generated when the Emacs process receives the signals
-@code{SIGUSR1} and @code{SIGUSR2}. They contain no additional data
-because signals do not carry additional information.
+@cindex @code{signal usr1} event
+@cindex @code{signal usr2} event
+@cindex user signals
+@item signal usr1
+@itemx signal usr2
+These event sequences are generated when the Emacs process receives
+the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no
+additional data because signals do not carry additional information.
@end table
If one of these events arrives in the middle of a key sequence---that
-453816))
@end smallexample
+To handle a SIGUSR1 signal, define an interactive function, and
+bind it to the @code{signal usr1} event sequence:
+
+@smallexample
+(defun usr1-handler ()
+ (interactive)
+ (message "Got USR1 signal"))
+(global-set-key [signal usr1] 'usr1-handler)
+@end smallexample
+
@node Classifying Events
@subsection Classifying Events
@cindex event type
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.
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.
If @var{seconds} is @code{nil}, @code{read-event} waits as long as
necessary for input to arrive.
+If @var{seconds} is @code{nil}, Emacs is considered idle while waiting
+for user input to arrive. Idle timers---those created with
+@code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this
+period. However, if @var{seconds} is non-@code{nil}, the state of
+idleness remains unchanged. If Emacs is non-idle when
+@code{read-event} is called, it remains non-idle throughout the
+operation of @code{read-event}; if Emacs is idle (which can happen if
+the call happens inside an idle timer), it remains idle.
+
If @code{read-event} gets an event that is defined as a help character,
then in some cases @code{read-event} processes the event directly without
returning. @xref{Help Functions}. Certain other events, called
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
Normally you add events to the front of this list, so that the events
most recently unread will be reread first.
+
+Events read from this list are not normally added to the current
+command's key sequence (as returned by e.g. @code{this-command-keys}),
+as the events will already have been added once as they were read for
+the first time. An element of the form @code{(@code{t} . @var{event})}
+forces @var{event} to be added to the current command's key sequence.
+
@end defvar
@defun listify-key-sequence key
editing. When called from a Lisp program, it enters a recursive editing
level.
- In the following example, the function @code{simple-rec} first
+If the current buffer is not the same as the selected window's buffer,
+@code{recursive-edit} saves and restores the current buffer. Otherwise,
+if you switch buffers, the buffer you switched to is current after
+@code{recursive-edit} returns.
+
+In the following example, the function @code{simple-rec} first
advances point one word, then enters a recursive edit, printing out a
message in the echo area. The user can then do any editing desired, and
then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.