@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, 2001, 2002,
+@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
The editor command loop runs this normal hook before each command. At
that time, @code{this-command} contains the command that is about to
run, and @code{last-command} describes the previous command.
-@xref{Hooks}.
+@xref{Command Loop Info}.
@end defvar
@defvar post-command-hook
The editor command loop runs this normal hook after each command
(including commands terminated prematurely by quitting or by errors),
and also when the command loop is first entered. At that time,
-@code{this-command} describes the command that just ran, and
-@code{last-command} describes the command before that. @xref{Hooks}.
+@code{this-command} refers to the command that just ran, and
+@code{last-command} refers to the command before that.
@end defvar
Quitting is suppressed while running @code{pre-command-hook} and
@node Using Interactive
@subsection Using @code{interactive}
+@cindex arguments, interactive entry
This section describes how to write the @code{interactive} form that
makes a Lisp function an interactively-callable command, and how to
examine a command's @code{interactive} form.
@defspec interactive arg-descriptor
-@cindex argument descriptors
This special form declares that the function in which it appears is a
command, and that it may therefore be called interactively (via
@kbd{M-x} or by entering a key sequence bound to it). The argument
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
followed by a prompt (which some code characters use and some ignore).
The prompt ends either with the end of the string or with a newline.
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}).
+
+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
@item F
A file name. The file need not exist. Completion, Default, Prompt.
+@item G
+A file name. The file need not exist. If the user enters just a
+directory name, then the value is just that directory name, with no
+file name within the directory added. Completion, Default, Prompt.
+
@item i
An irrelevant argument. This code always supplies @code{nil} as
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
@node Adjusting Point
@section Adjusting Point After Commands
-
- It is not easy to display a value of point in the middle of a sequence
-of text that has the @code{display} or @code{composition} property. So
-after a command finishes and returns to the command loop, if point is
-within such a sequence, the command loop normally moves point to the
-edge of the sequence.
+@cindex adjusting point
+@cindex invisible/intangible text, and point
+@cindex @code{display} property, and point display
+@cindex @code{composition} property, and point display
+
+ It is not easy to display a value of point in the middle of a
+sequence of text that has the @code{display}, @code{composition} or
+@code{intangible} property, or is invisible. Therefore, after a
+command finishes and returns to the command loop, if point is within
+such a sequence, the command loop normally moves point to the edge of
+the sequence.
A command can inhibit this feature by setting the variable
@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 text properties such as
-@code{display} and @code{composition}, and does not move point out of
-sequences that have these properties.
+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.
The command loop sets this variable to @code{nil} before each command,
so if a command sets it, the effect applies only to that command.
@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
@node Keyboard Events
@subsection Keyboard Events
+@cindex keyboard events
There are two kinds of input you can get from the keyboard: ordinary
keys, and function keys. Ordinary keys correspond to characters; 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
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{sigusr1} event
+@cindex @code{sigusr2} event
+@cindex user signals
+@item sigusr1
+@itemx sigusr2
+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.
+
+To catch a user signal, bind the corresponding event to an interactive
+command in the @code{special-event-map} (@pxref{Active Keymaps}).
+The command is called with no arguments, and the specific signal event is
+available in @code{last-input-event}. For example:
+
+@smallexample
+(defun sigusr-handler ()
+ (interactive)
+ (message "Caught signal %S" last-input-event))
+
+(define-key special-event-map [sigusr1] 'sigusr-handler)
+@end smallexample
+
+To test the signal handler, you can make Emacs send a signal to itself:
+
+@smallexample
+(signal-process (emacs-pid) 'sigusr1)
+@end smallexample
@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
@node Accessing Events
@subsection Accessing Events
-@cindex mouse events, accessing the data
-@cindex accessing data of mouse events
+@cindex mouse events, data in
This section describes convenient functions for accessing the data in
a mouse button or motion event.
@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
is a buffer position, return the size of the character at that position.
@end defun
-@cindex mouse event, timestamp
@cindex timestamp of a mouse event
@defun posn-timestamp position
Return the timestamp in @var{position}. This is the time at which the
@node Reading Input
@section Reading Input
+@cindex read input
+@cindex keyboard input
The editor command loop reads key sequences using the function
@code{read-key-sequence}, which uses @code{read-event}. These and other
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.
@code{read-key-sequence}. Lisp programs can also call this function;
for example, @code{describe-key} uses it to read the key to describe.
-@defun read-key-sequence prompt
-@cindex key sequence
+@defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
This function reads a key sequence and returns it as a string or
vector. It keeps reading events until it has accumulated a complete key
sequence; that is, enough to specify a non-prefix command using the
events---characters, symbols, and lists. The elements of the string or
vector are the events in the key sequence.
-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.
+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
+this key as a continuation of the previous key.
-In the example below, the prompt @samp{?} is displayed in the echo area,
-and the user types @kbd{C-x C-f}.
+Normally any upper case event is converted to lower case if the
+original event is undefined and the lower case equivalent is defined.
+The argument @var{dont-downcase-last}, if non-@code{nil}, means do not
+convert the last event to lower case. This is appropriate for reading
+a key sequence to be defined.
+
+The argument @var{switch-frame-ok}, if non-@code{nil}, means that this
+function should process a @code{switch-frame} event if the user
+switches frames before typing anything. If the user switches frames
+in the middle of a key sequence, or at the start of the sequence but
+@var{switch-frame-ok} is @code{nil}, then the event will be put off
+until after the current key sequence.
+
+The argument @var{command-loop}, if non-@code{nil}, means that this
+key sequence is being read by something that will read commands one
+after another. It should be @code{nil} if the caller will read just
+one key sequence.
+
+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 "?")
and does not set @code{quit-flag}. @xref{Quitting}.
@end defun
-@defun read-key-sequence-vector prompt
+@defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
This is like @code{read-key-sequence} except that it always
returns the key sequence as a vector, never as a string.
@xref{Strings of Events}.
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
-@cindex flush input
-@cindex discard input
-@cindex terminate keyboard macro
+@cindex flushing input
+@cindex discarding input
+@cindex keyboard macro, terminating
This function discards the contents of the terminal input buffer and
cancels any keyboard macro that might be in the process of definition.
It returns @code{nil}.
after they are read, and this is the way for the event's definition to
find the actual event.
-The events types @code{iconify-frame}, @code{make-frame-visible} and
-@code{delete-frame} are normally handled in this way. The keymap which
+The events types @code{iconify-frame}, @code{make-frame-visible},
+@code{delete-frame}, @code{drag-n-drop}, and user signals like
+@code{sigusr1} are normally handled in this way. The keymap which
defines how to handle special events---and which events are special---is
in the variable @code{special-event-map} (@pxref{Active Keymaps}).
@node Waiting
@section Waiting for Elapsed Time or Input
-@cindex pausing
@cindex waiting
The wait functions are designed to wait for a certain amount of time
@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})},
case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
to quote a @kbd{C-g}.
-@cindex prevent quitting
+@cindex preventing quitting
You can prevent quitting for a portion of a Lisp function by binding
the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
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}.