@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
arguments. This leads quickly to an error if the command requires one
or more arguments.
-@item
-It may be a Lisp expression that is not a string; then it should be a
-form that is evaluated to get a list of arguments to pass to the
-command.
-@cindex argument evaluation form
-
-If this expression reads keyboard input (this includes using the
-minibuffer), keep in mind that the integer value of point or the mark
-before reading input may be incorrect after reading input. This is
-because the current buffer may be receiving subprocess output;
-if subprocess output arrives while the command is waiting for input,
-it could relocate point and the mark.
-
-Here's an example of what @emph{not} to do:
-
-@smallexample
-(interactive
- (list (region-beginning) (region-end)
- (read-string "Foo: " nil 'my-history)))
-@end smallexample
-
-@noindent
-Here's how to avoid the problem, by examining point and the mark only
-after reading the keyboard input:
-
-@smallexample
-(interactive
- (let ((string (read-string "Foo: " nil 'my-history)))
- (list (region-beginning) (region-end) string)))
-@end smallexample
-
@item
@cindex argument prompt
It may be a string; then its contents should consist of a code character
Actual reading of arguments is controlled by the rest of the prompt
string (starting with the first character that is not @samp{*} or
@samp{@@}).
+
+@item
+It may be a Lisp expression that is not a string; then it should be a
+form that is evaluated to get a list of arguments to pass to the
+command. Usually this form will call various functions to read input
+from the user, most often through the minibuffer (@pxref{Minibuffers})
+or directly from the keyboard (@pxref{Reading Input}).
+@cindex argument evaluation form
+
+Providing point or the mark as an argument value is also common, but
+if you do this @emph{and} read input (whether using the minibuffer or
+not), be sure to get the integer values of point or the mark after
+reading. The current buffer may be receiving subprocess output; if
+subprocess output arrives while the command is waiting for input, it
+could relocate point and the mark.
+
+Here's an example of what @emph{not} to do:
+
+@smallexample
+(interactive
+ (list (region-beginning) (region-end)
+ (read-string "Foo: " nil 'my-history)))
+@end smallexample
+
+@noindent
+Here's how to avoid the problem, by examining point and the mark after
+reading the keyboard input:
+
+@smallexample
+(interactive
+ (let ((string (read-string "Foo: " nil 'my-history)))
+ (list (region-beginning) (region-end) string)))
+@end smallexample
+
+@strong{Warning:} the argument values should not include any data
+types that can't be printed and then read. Some facilities save
+@code{command-history} in a file to be read in the subsequent
+sessions; if a command's arguments contain a data type that prints
+using @samp{#<@dots{}>} syntax, those facilities won't work.
+
+There are, however, a few exceptions: it is ok to use a limited set of
+expressions such as @code{(point)}, @code{(mark)},
+@code{(region-beginning)}, and @code{(region-end)}, because Emacs
+recognizes them specially and puts the expression (rather than its
+value) into the command history. To see whether the expression you
+wrote is one of these exceptions, run the command, then examine
+@code{(car command-history)}.
@end itemize
@cindex examining the @code{interactive} form
the argument's value. No I/O.
@item k
-A key sequence (@pxref{Keymap Terminology}). This keeps reading events
+A key sequence (@pxref{Key Sequences}). This keeps reading events
until a command (or undefined command) is found in the current key
maps. The key sequence argument is represented as a string or vector.
The cursor does not move into the echo area. Prompt.
-If the key sequence is a down-event, the following up-event is discarded,
-but can be read via the @code{U} code character.
+If @samp{k} reads a key sequence that ends with a down-event, it also
+reads and discards the following up-event. You can get access to that
+up-event with the @samp{U} code character.
This kind of input is used by commands such as @code{describe-key} and
@code{global-set-key}.
parentheses and brackets) do not do so here. Prompt.
@item U
-A key sequence or @code{nil}. May be used after a @code{k} or @code{K}
-argument to get the up-event that was discarded in case the key
-sequence read for that argument was a down-event. No I/O.
+A key sequence or @code{nil}. Can be used after a @samp{k} or
+@samp{K} argument to get the up-event that was discarded (if any)
+after @samp{k} or @samp{K} read a down-event. If no up-event has been
+discarded, @samp{U} provides @code{nil} as the argument. No I/O.
@item v
A variable declared to be a user option (i.e., satisfying the
@item X
@cindex evaluated expression argument
-A Lisp form is read as with @kbd{x}, but then evaluated so that its
-value becomes the argument for the command. Prompt.
+A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates
+the form so that its value becomes the argument for the command.
+Prompt.
@item z
A coding system name (a symbol). If the user enters null input, the
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
@example
@group
-(execute-extended-command 1)
+(execute-extended-command 3)
---------- Buffer: Minibuffer ----------
-1 M-x forward-word RET
+3 M-x forward-word RET
---------- Buffer: Minibuffer ----------
@result{} t
@end group
@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}).
@end defun
-@tindex clear-this-command-keys
@defun clear-this-command-keys &optional keep-record
This function empties out the table of events for
@code{this-command-keys} to return. Unless @var{keep-record} is
@code{disable-point-adjustment}:
@defvar disable-point-adjustment
-@tindex disable-point-adjustment
If this variable is non-@code{nil} when a command returns to the
command loop, then the command loop does not check for those text
properties, and does not move point out of sequences that have them.
@end defvar
@defvar global-disable-point-adjustment
-@tindex global-disable-point-adjustment
If you set this variable to a non-@code{nil} value, the feature of
moving point out of these sequences is completely turned off.
@end defvar
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
@defun posn-area position
Return the window area recorded in @var{position}. It returns @code{nil}
when the event occurred in the text area of the window; otherwise, it
-is a symbol identifying the area in which the the event occurred.
+is a symbol identifying the area in which the event occurred.
@end defun
@defun posn-point position
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.
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{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.
The argument @var{continue-echo}, if non-@code{nil}, means to echo
after another. It should be @code{nil} if the caller will read just
one key sequence.
-In the example below, the prompt @samp{?} is displayed in the echo area,
-and the user types @kbd{C-x C-f}.
+In the following example, Emacs displays the prompt @samp{?} in the
+echo area, and then the user types @kbd{C-x C-f}.
@example
(read-key-sequence "?")
button and modifier keys. The information about the window part is kept
elsewhere in the event---in the coordinates. But
@code{read-key-sequence} translates this information into imaginary
-``prefix keys'', all of which are symbols: @code{header-line},
+``prefix keys,'' all of which are symbols: @code{header-line},
@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
@code{vertical-line}, and @code{vertical-scroll-bar}. You can define
meanings for mouse clicks in special window parts by defining key
and key sequences read from keyboard macros being executed.
@end defvar
-@defvar num-nonmacro-input-events
-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 Reading One Event
@subsection Reading One Event
@cindex reading a single event
None of the three functions below suppresses quitting.
-@defun read-event &optional prompt inherit-input-method
+@defun read-event &optional prompt inherit-input-method seconds
This function reads and returns the next event of command input, waiting
if necessary until an event is available. Events can come directly from
the user or from a keyboard macro.
moves the cursor temporarily to the echo area, to the end of any message
displayed there. Otherwise @code{read-event} does not move the cursor.
+If @var{seconds} is non-@code{nil}, it should be a number specifying
+the maximum time to wait for input, in seconds. If no input arrives
+within that time, @code{read-event} stops waiting and returns
+@code{nil}. A floating-point value for @var{seconds} means to wait
+for a fractional number of seconds. Some systems support only a whole
+number of seconds; on these systems, @var{seconds} is rounded down.
+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
@end example
@end defun
-@defun read-char &optional prompt inherit-input-method
+@defun read-char &optional prompt inherit-input-method seconds
This function reads and returns a character of command input. If the
user generates an event which is not a character (i.e. a mouse click or
function key event), @code{read-char} signals an error. The arguments
@end example
@end defun
-@defun read-char-exclusive &optional prompt inherit-input-method
+@defun read-char-exclusive &optional prompt inherit-input-method seconds
This function reads and returns a character of command input. If the
user generates an event which is not a character,
@code{read-char-exclusive} ignores it and reads another event, until it
gets a character. The arguments work as in @code{read-event}.
@end defun
+@defvar num-nonmacro-input-events
+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
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
@defvar unread-command-char
This variable holds a character to be read as command input.
-A value of -1 means ``empty''.
+A value of -1 means ``empty.''
This variable is mostly obsolete now that you can use
@code{unread-command-events} instead; it exists only to support programs
Emacs version 18.
@end defvar
-@defmac while-no-input body...
-This construct runs the @var{body} forms and returns the value
-of the last one---but only if no input arrives. If any input
-arrives during the execution of the @var{body} forms, it aborts
-them (working much like a quit), and the @code{while-no-input}
-form returns @code{nil}.
+@defmac while-no-input body@dots{}
+This construct runs the @var{body} forms and returns the value of the
+last one---but only if no input arrives. If any input arrives during
+the execution of the @var{body} forms, it aborts them (working much
+like a quit). The @code{while-no-input} form returns @code{nil} if
+aborted by a real quit, and returns @code{t} if aborted by arrival of
+other input.
If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil},
arrival of input during those parts won't cause an abort until
the end of that part.
+
+If you want to be able to distinguish all possible values computed
+by @var{body} from both kinds of abort conditions, write the code
+like this:
+
+@example
+(while-no-input
+ (list
+ (progn . @var{body})))
+@end example
@end defmac
@defun discard-input
@defun sit-for seconds &optional nodisp
This function performs redisplay (provided there is no pending input
from the user), then waits @var{seconds} seconds, or until input is
-available. The value is @code{t} if @code{sit-for} waited the full
-time with no input arriving (see @code{input-pending-p} in @ref{Event
-Input Misc}). Otherwise, the value is @code{nil}.
+available. The usual purpose of @code{sit-for} is to give the user
+time to read text that you display. The value is @code{t} if
+@code{sit-for} waited the full time with no input arriving
+(@pxref{Event Input Misc}). Otherwise, the value is @code{nil}.
The argument @var{seconds} need not be an integer. If it is a floating
point number, @code{sit-for} waits for a fractional number of seconds.
Some systems support only a whole number of seconds; on these systems,
@var{seconds} is rounded down.
-The expression @code{(sit-for 0)} is a convenient way to request a
-redisplay, without any delay. @xref{Forcing Redisplay}.
+The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)},
+i.e. it requests a redisplay, without any delay, if there is no pending input.
+@xref{Forcing Redisplay}.
If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
redisplay, but it still returns as soon as input is available (or when
the timeout elapses).
-Iconifying or deiconifying a frame makes @code{sit-for} return, because
-that generates an event. @xref{Misc Events}.
-
-The usual purpose of @code{sit-for} is to give the user time to read
-text that you display.
+In batch mode (@pxref{Batch Mode}), @code{sit-for} cannot be
+interrupted, even by input from the standard input descriptor. It is
+thus equivalent to @code{sleep-for}, which is described below.
It is also possible to call @code{sit-for} with three arguments,
as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})},
non-@code{nil}, then @code{quit-flag} has no special effect.
@end defvar
-@defmac with-local-quit forms@dots{}
-This macro executes @var{forms} in sequence, but allows quitting, at
+@defmac with-local-quit body@dots{}
+This macro executes @var{body} forms in sequence, but allows quitting, at
least locally, within @var{body} even if @code{inhibit-quit} was
non-@code{nil} outside this construct. It returns the value of the
-last form in @var{forms}, unless exited by quitting, in which case
+last form in @var{body}, unless exited by quitting, in which case
it returns @code{nil}.
If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit},
-it only executes the @var{forms}, and setting @code{quit-flag} causes
+it only executes the @var{body}, and setting @code{quit-flag} causes
a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so
that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag}
triggers a special kind of local quit. This ends the execution of
-@var{forms} and exits the @code{with-local-quit} form with
+@var{body} and exits the @code{with-local-quit} body with
@code{quit-flag} still non-@code{nil}, so that another (ordinary) quit
will happen as soon as that is allowed. If @code{quit-flag} is
-already non-@code{nil} at the beginning of @var{forms}, the local quit
-happens immediately and they don't execute at all.
+already non-@code{nil} at the beginning of @var{body}, the local quit
+happens immediately and the body doesn't execute at all.
This macro is mainly useful in functions that can be called from
-timers, @code{pre-command-hook}, @code{post-command-hook} and other
-places where @code{inhibit-quit} is normally bound to @code{t}.
+timers, process filters, process sentinels, @code{pre-command-hook},
+@code{post-command-hook}, and other places where @code{inhibit-quit} is
+normally bound to @code{t}.
@end defmac
@deffn Command keyboard-quit
commands.
Normally, commands specify which representation to use for the prefix
-argument, either numeric or raw, in the @code{interactive} declaration.
+argument, either numeric or raw, in the @code{interactive} specification.
(@xref{Using Interactive}.) Alternatively, functions may look at the
value of the prefix argument directly in the variable
@code{current-prefix-arg}, but this is less clean.
change the major mode of the current buffer temporarily to a special
major mode, which should have a command to go back to the previous mode.
(The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
-give the user different text to edit ``recursively'', create and select
+give the user different text to edit ``recursively,'' create and select
a new buffer in a special mode. In this mode, define a command to
complete the processing and go back to the previous buffer. (The
@kbd{m} command in Rmail does this.)
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}.