@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/commands.info
@node Command Loop, Keymaps, Minibuffers, Top
@chapter Command Loop
@cindex editor command loop
@cindex command loop

  When you run XEmacs, it enters the @dfn{editor command loop} almost
immediately.  This loop reads events, executes their definitions,
and displays the results.  In this chapter, we describe how these things
are done, and the subroutines that allow Lisp programs to do them.  

@menu
* Command Overview::    How the command loop reads commands.
* Defining Commands::   Specifying how a function should read arguments.
* Interactive Call::    Calling a command, so that it will read arguments.
* Command Loop Info::   Variables set by the command loop for you to examine.
* Events::		What input looks like when you read it.
* Reading Input::       How to read input events from the keyboard or mouse.
* Waiting::             Waiting for user input or elapsed time.
* Quitting::            How @kbd{C-g} works.  How to catch or defer quitting.
* Prefix Command Arguments::    How the commands to set prefix args work.
* Recursive Editing::   Entering a recursive edit,
                          and why you usually shouldn't.
* Disabling Commands::  How the command loop handles disabled commands.
* Command History::     How the command history is set up, and how accessed.
* Keyboard Macros::     How keyboard macros are implemented.
@end menu

@node Command Overview
@section Command Loop Overview

  The command loop in XEmacs is a standard event loop, reading events
one at a time with @code{next-event} and handling them with
@code{dispatch-event}.  An event is typically a single user action, such
as a keypress, mouse movement, or menu selection; but they can also be
notifications from the window system, informing XEmacs that (for
example) part of its window was just uncovered and needs to be redrawn.
@xref{Events}.  Pending events are held in a first-in, first-out list
called the @dfn{event queue}: events are read from the head of the list,
and newly arriving events are added to the tail.  In this way, events
are always processed in the order in which they arrive.

  @code{dispatch-event} does most of the work of handling user actions.
The first thing it must do is put the events together into a key
sequence, which is a sequence of events that translates into a command.
It does this by consulting the active keymaps, which specify what the
valid key sequences are and how to translate them into commands.
@xref{Key Lookup}, for information on how this is done.  The result of
the translation should be a keyboard macro or an interactively callable
function.  If the key is @kbd{M-x}, then it reads the name of another
command, which it then calls.  This is done by the command
@code{execute-extended-command} (@pxref{Interactive Call}).

  To execute a command requires first reading the arguments for it.
This is done by calling @code{command-execute} (@pxref{Interactive
Call}).  For commands written in Lisp, the @code{interactive}
specification says how to read the arguments.  This may use the prefix
argument (@pxref{Prefix Command Arguments}) or may read with prompting
in the minibuffer (@pxref{Minibuffers}).  For example, the command
@code{find-file} has an @code{interactive} specification which says to
read a file name using the minibuffer.  The command's function body does
not use the minibuffer; if you call this command from Lisp code as a
function, you must supply the file name string as an ordinary Lisp
function argument.

  If the command is a string or vector (i.e., a keyboard macro) then
@code{execute-kbd-macro} is used to execute it.  You can call this
function yourself (@pxref{Keyboard Macros}).

  To terminate the execution of a running command, type @kbd{C-g}.  This
character causes @dfn{quitting} (@pxref{Quitting}).

@defvar pre-command-hook
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}.
@end defvar

@defvar post-command-hook
The editor command loop runs this normal hook after each command.  (In
FSF Emacs, it is also run when the command loop is entered, or
reentered after an error or quit.)  At that time,
@code{this-command} describes the command that just ran, and
@code{last-command} describes the command before that.  @xref{Hooks}.
@end defvar

  Quitting is suppressed while running @code{pre-command-hook} and
@code{post-command-hook}.  If an error happens while executing one of
these hooks, it terminates execution of the hook, but that is all it
does.

@node Defining Commands
@section Defining Commands
@cindex defining commands
@cindex commands, defining
@cindex functions, making them interactive
@cindex interactive function

  A Lisp function becomes a command when its body contains, at top
level, a form that calls the special form @code{interactive}.  This
form does nothing when actually executed, but its presence serves as a
flag to indicate that interactive calling is permitted.  Its argument
controls the reading of arguments for an interactive call.

@menu
* Using Interactive::     General rules for @code{interactive}.
* Interactive Codes::     The standard letter-codes for reading arguments
                             in various ways.
* Interactive Examples::  Examples of how to read interactive arguments.
@end menu

@node Using Interactive
@subsection Using @code{interactive}

  This section describes how to write the @code{interactive} form that
makes a Lisp function an interactively-callable command.

@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
@var{arg-descriptor} declares how to compute the arguments to the
command when the command is called interactively.

A command may be called from Lisp programs like any other function, but
then the caller supplies the arguments and @var{arg-descriptor} has no
effect.

The @code{interactive} form has its effect because the command loop
(actually, its subroutine @code{call-interactively}) scans through the
function definition looking for it, before calling the function.  Once
the function is called, all its body forms including the
@code{interactive} form are executed, but at this time
@code{interactive} simply returns @code{nil} without even evaluating its
argument.
@end defspec

There are three possibilities for the argument @var{arg-descriptor}:

@itemize @bullet
@item
It may be omitted or @code{nil}; then the command is called with no
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
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.
Here is a simple example:

@smallexample
(interactive "bFrobnicate buffer: ")
@end smallexample

@noindent
The code letter @samp{b} says to read the name of an existing buffer,
with completion.  The buffer name is the sole argument passed to the
command.  The rest of the string is a prompt.

If there is a newline character in the string, it terminates the prompt.
If the string does not end there, then the rest of the string should
contain another code character and prompt, specifying another argument.
You can specify any number of arguments in this way.

@c Emacs 19 feature
The prompt string can use @samp{%} to include previous argument values
(starting with the first argument) in the prompt.  This is done using
@code{format} (@pxref{Formatting Strings}).  For example, here is how
you could read the name of an existing buffer followed by a new name to
give to that buffer:

@smallexample
@group
(interactive "bBuffer to rename: \nsRename buffer %s to: ")
@end group
@end smallexample

@cindex @samp{*} in interactive
@cindex read-only buffers in interactive
If the first character in the string is @samp{*}, then an error is
signaled if the buffer is read-only.

@cindex @samp{@@} in interactive
@c Emacs 19 feature
If the first character in the string is @samp{@@}, and if the key
sequence used to invoke the command includes any mouse events, then
the window associated with the first of those events is selected
before the command is run.

@cindex @samp{_} in interactive
@c XEmacs feature
If the first character in the string is @samp{_}, then this command will
not cause the region to be deactivated when it completes; that is,
@code{zmacs-region-stays} will be set to @code{t} when the command exits
successfully.

You can use @samp{*}, @samp{@@}, and @samp{_} together; the order does
not matter.  Actual reading of arguments is controlled by the rest of
the prompt string (starting with the first character that is not
@samp{*}, @samp{@@}, or @samp{_}).
@end itemize

@node Interactive Codes
@subsection Code Characters for @code{interactive}
@cindex interactive code description
@cindex description for interactive codes
@cindex codes, interactive, description of
@cindex characters for interactive codes

  The code character descriptions below contain a number of key words,
defined here as follows:

@table @b
@item Completion
@cindex interactive completion
Provide completion.  @key{TAB}, @key{SPC}, and @key{RET} perform name
completion because the argument is read using @code{completing-read}
(@pxref{Completion}).  @kbd{?} displays a list of possible completions.

@item Existing
Require the name of an existing object.  An invalid name is not
accepted; the commands to exit the minibuffer do not exit if the current
input is not valid.

@item Default
@cindex default argument string
A default value of some sort is used if the user enters no text in the
minibuffer.  The default depends on the code character.

@item No I/O
This code letter computes an argument without reading any input.
Therefore, it does not use a prompt string, and any prompt string you
supply is ignored.

Even though the code letter doesn't use a prompt string, you must follow
it with a newline if it is not the last code character in the string.

@item Prompt
A prompt immediately follows the code character.  The prompt ends either
with the end of the string or with a newline.

@item Special
This code character is meaningful only at the beginning of the
interactive string, and it does not look for a prompt or a newline.
It is a single, isolated character.
@end table

@cindex reading interactive arguments
  Here are the code character descriptions for use with @code{interactive}:

@table @samp
@item *
Signal an error if the current buffer is read-only.  Special.

@item @@
Select the window mentioned in the first mouse event in the key
sequence that invoked this command.  Special.

@item _
Do not cause the region to be deactivated when this command completes.
Special.

@item a
A function name (i.e., a symbol satisfying @code{fboundp}).  Existing,
Completion, Prompt.

@item b
The name of an existing buffer.  By default, uses the name of the
current buffer (@pxref{Buffers}).  Existing, Completion, Default,
Prompt.

@item B
A buffer name.  The buffer need not exist.  By default, uses the name of
a recently used buffer other than the current buffer.  Completion,
Default, Prompt.

@item c
A character.  The cursor does not move into the echo area.  Prompt.

@item C
A command name (i.e., a symbol satisfying @code{commandp}).  Existing,
Completion, Prompt.

@item d
@cindex position argument
The position of point, as an integer (@pxref{Point}).  No I/O.

@item D
A directory name.  The default is the current default directory of the
current buffer, @code{default-directory} (@pxref{System Environment}).
Existing, Completion, Default, Prompt.

@item e
The last mouse-button or misc-user event in the key sequence that
invoked the command.  No I/O.

You can use @samp{e} more than once in a single command's interactive
specification.  If the key sequence that invoked the command has @var{n}
mouse-button or misc-user events, the @var{n}th @samp{e} provides the
@var{n}th such event.

@item f
A file name of an existing file (@pxref{File Names}).  The default
directory is @code{default-directory}.  Existing, Completion, Default,
Prompt.

@item F
A file name.  The file need not exist.  Completion, Default, Prompt.

@item k
A key sequence (@pxref{Keymap Terminology}).  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 vector of events.
The cursor does not move into the echo area.  Prompt.

This kind of input is used by commands such as @code{describe-key} and
@code{global-set-key}.

@item K
A key sequence, whose definition you intend to change.  This works like
@samp{k}, except that it suppresses, for the last input event in the key
sequence, the conversions that are normally used (when necessary) to
convert an undefined key into a defined one.

@item m
@cindex marker argument
The position of the mark, as an integer.  No I/O.

@item n
A number read with the minibuffer.  If the input is not a number, the
user is asked to try again.  The prefix argument, if any, is not used.
Prompt.

@item N
@cindex raw prefix argument usage
The raw prefix argument.  If the prefix argument is @code{nil}, then
read a number as with @kbd{n}.  Requires a number.  @xref{Prefix Command
Arguments}.  Prompt.

@item p
@cindex numeric prefix argument usage
The numeric prefix argument.  (Note that this @samp{p} is lower case.)
No I/O.

@item P
The raw prefix argument.  (Note that this @samp{P} is upper case.)  No
I/O.

@item r
@cindex region argument
Point and the mark, as two numeric arguments, smallest first.  This is
the only code letter that specifies two successive arguments rather than
one.  No I/O.

@item s
Arbitrary text, read in the minibuffer and returned as a string
(@pxref{Text from Minibuffer}).  Terminate the input with either
@key{LFD} or @key{RET}.  (@kbd{C-q} may be used to include either of
these characters in the input.)  Prompt.

@item S
An interned symbol whose name is read in the minibuffer.  Any whitespace
character terminates the input.  (Use @kbd{C-q} to include whitespace in
the string.)  Other characters that normally terminate a symbol (e.g.,
parentheses and brackets) do not do so here.  Prompt.

@item v
A variable declared to be a user option (i.e., satisfying the predicate
@code{user-variable-p}).  @xref{High-Level Completion}.  Existing,
Completion, Prompt.

@item x
A Lisp object, specified with its read syntax, terminated with a
@key{LFD} or @key{RET}.  The object is not evaluated.  @xref{Object from
Minibuffer}.  Prompt.

@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.
@end table

@node Interactive Examples
@subsection Examples of Using @code{interactive}
@cindex examples of using @code{interactive}
@cindex @code{interactive}, examples of using 

  Here are some examples of @code{interactive}:

@example
@group
(defun foo1 ()              ; @r{@code{foo1} takes no arguments,}
    (interactive)           ;   @r{just moves forward two words.}
    (forward-word 2))
     @result{} foo1
@end group

@group
(defun foo2 (n)             ; @r{@code{foo2} takes one argument,}
    (interactive "p")       ;   @r{which is the numeric prefix.}
    (forward-word (* 2 n)))
     @result{} foo2
@end group

@group
(defun foo3 (n)             ; @r{@code{foo3} takes one argument,}
    (interactive "nCount:") ;   @r{which is read with the Minibuffer.}
    (forward-word (* 2 n)))
     @result{} foo3
@end group

@group
(defun three-b (b1 b2 b3)
  "Select three existing buffers.
Put them into three windows, selecting the last one."
@end group
    (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
    (delete-other-windows)
    (split-window (selected-window) 8)
    (switch-to-buffer b1)
    (other-window 1)
    (split-window (selected-window) 8)
    (switch-to-buffer b2)
    (other-window 1)
    (switch-to-buffer b3))
     @result{} three-b
@group
(three-b "*scratch*" "declarations.texi" "*mail*")
     @result{} nil
@end group
@end example

@node Interactive Call
@section Interactive Call
@cindex interactive call

  After the command loop has translated a key sequence into a
definition, it invokes that definition using the function
@code{command-execute}.  If the definition is a function that is a
command, @code{command-execute} calls @code{call-interactively}, which
reads the arguments and calls the command.  You can also call these
functions yourself.

@defun commandp object
Returns @code{t} if @var{object} is suitable for calling interactively;
that is, if @var{object} is a command.  Otherwise, returns @code{nil}.  

The interactively callable objects include strings and vectors (treated
as keyboard macros), lambda expressions that contain a top-level call to
@code{interactive}, compiled-function objects made from such lambda
expressions, autoload objects that are declared as interactive
(non-@code{nil} fourth argument to @code{autoload}), and some of the
primitive functions.

A symbol is @code{commandp} if its function definition is
@code{commandp}.

Keys and keymaps are not commands.  Rather, they are used to look up
commands (@pxref{Keymaps}).

See @code{documentation} in @ref{Accessing Documentation}, for a
realistic example of using @code{commandp}.
@end defun

@defun call-interactively command &optional record-flag
This function calls the interactively callable function @var{command},
reading arguments according to its interactive calling specifications.
An error is signaled if @var{command} is not a function or if it cannot
be called interactively (i.e., is not a command).  Note that keyboard
macros (strings and vectors) are not accepted, even though they are
considered commands, because they are not functions.

@c XEmacs feature?
If @var{record-flag} is the symbol @code{lambda}, the interactive
calling arguments for @code{command} are read and returned as a list,
but the function is not called on them.

@cindex record command history
If @var{record-flag} is @code{t}, then this command and its arguments
are unconditionally added to the list @code{command-history}.
Otherwise, the command is added only if it uses the minibuffer to read
an argument.  @xref{Command History}.
@end defun

@defun command-execute command &optional record-flag
@cindex keyboard macro execution
This function executes @var{command} as an editing command.  The
argument @var{command} must satisfy the @code{commandp} predicate; i.e.,
it must be an interactively callable function or a keyboard macro.

A string or vector as @var{command} is executed with
@code{execute-kbd-macro}.  A function is passed to
@code{call-interactively}, along with the optional @var{record-flag}.

A symbol is handled by using its function definition in its place.  A
symbol with an @code{autoload} definition counts as a command if it was
declared to stand for an interactively callable function.  Such a
definition is handled by loading the specified library and then
rechecking the definition of the symbol.
@end defun

@deffn Command execute-extended-command prefix-argument
@cindex read command name
This function reads a command name from the minibuffer using
@code{completing-read} (@pxref{Completion}).  Then it uses
@code{command-execute} to call the specified command.  Whatever that
command returns becomes the value of @code{execute-extended-command}.

@cindex execute with prefix argument
If the command asks for a prefix argument, it receives the value
@var{prefix-argument}.  If @code{execute-extended-command} is called
interactively, the current raw prefix argument is used for
@var{prefix-argument}, and thus passed on to whatever command is run.

@c !!! Should this be @kindex?
@cindex @kbd{M-x}
@code{execute-extended-command} is the normal definition of @kbd{M-x},
so it uses the string @w{@samp{M-x }} as a prompt.  (It would be better
to take the prompt from the events used to invoke
@code{execute-extended-command}, but that is painful to implement.)  A
description of the value of the prefix argument, if any, also becomes
part of the prompt.

@example
@group
(execute-extended-command 1)
---------- Buffer: Minibuffer ----------
1 M-x forward-word RET
---------- Buffer: Minibuffer ----------
     @result{} t
@end group
@end example
@end deffn

@defun interactive-p
This function returns @code{t} if the containing function (the one that
called @code{interactive-p}) was called interactively, with the function
@code{call-interactively}.  (It makes no difference whether
@code{call-interactively} was called from Lisp or directly from the
editor command loop.)  If the containing function was called by Lisp
evaluation (or with @code{apply} or @code{funcall}), then it was not
called interactively.

The most common use of @code{interactive-p} is for deciding whether to
print an informative message.  As a special exception,
@code{interactive-p} returns @code{nil} whenever a keyboard macro is
being run.  This is to suppress the informative messages and speed
execution of the macro.

For example:

@example
@group
(defun foo ()
  (interactive)
  (and (interactive-p)
       (message "foo")))
     @result{} foo
@end group

@group
(defun bar ()
  (interactive)
  (setq foobar (list (foo) (interactive-p))))
     @result{} bar
@end group

@group
;; @r{Type @kbd{M-x foo}.}
     @print{} foo
@end group

@group
;; @r{Type @kbd{M-x bar}.}
;; @r{This does not print anything.}
@end group

@group
foobar
     @result{} (nil t)
@end group
@end example
@end defun

@node Command Loop Info
@section Information from the Command Loop

The editor command loop sets several Lisp variables to keep status
records for itself and for commands that are run.  

@defvar last-command
This variable records the name of the previous command executed by the
command loop (the one before the current command).  Normally the value
is a symbol with a function definition, but this is not guaranteed.

The value is copied from @code{this-command} when a command returns to
the command loop, except when the command specifies a prefix argument
for the following command.
@end defvar

@defvar this-command
@cindex current command
This variable records the name of the command now being executed by
the editor command loop.  Like @code{last-command}, it is normally a symbol
with a function definition.

The command loop sets this variable just before running a command, and
copies its value into @code{last-command} when the command finishes
(unless the command specifies a prefix argument for the following
command).

@cindex kill command repetition
Some commands set this variable during their execution, as a flag for
whatever command runs next.  In particular, the functions for killing text
set @code{this-command} to @code{kill-region} so that any kill commands
immediately following will know to append the killed text to the
previous kill.
@end defvar

If you do not want a particular command to be recognized as the previous
command in the case where it got an error, you must code that command to
prevent this.  One way is to set @code{this-command} to @code{t} at the
beginning of the command, and set @code{this-command} back to its proper
value at the end, like this:

@example
(defun foo (args@dots{})
  (interactive @dots{})
  (let ((old-this-command this-command))
    (setq this-command t)
    @r{@dots{}do the work@dots{}}
    (setq this-command old-this-command)))
@end example

@defun this-command-keys
This function returns a vector containing the key and mouse events that
invoked the present command, plus any previous commands that generated
the prefix argument for this command. (Note: this is not the same as in
FSF Emacs, which can return a string.)  @xref{Events}.

This function copies the vector and the events; it is safe to keep and
modify them.

@example
@group
(this-command-keys)
;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
     @result{} [#<keypress-event control-U> #<keypress-event control-X> #<keypress-event control-E>]
@end group
@end example
@end defun

@ignore Not in XEmacs
@defvar last-nonmenu-event
This variable holds the last input event read as part of a key
sequence, not counting events resulting from mouse menus.

One use of this variable is to figure out a good default location to
pop up another menu.
@end defvar
@end ignore

@defvar last-command-event
This variable is set to the last input event that was read by the
command loop as part of a command.  The principal use of this variable
is in @code{self-insert-command}, which uses it to decide which
character to insert.

This variable is off limits: you may not set its value or modify the
event that is its value, as it is destructively modified by
@code{read-key-sequence}.  If you want to keep a pointer to this value,
you must use @code{copy-event}.

Note that this variable is an alias for @code{last-command-char} in
FSF Emacs.

@example
@group
last-command-event
;; @r{Now type @kbd{C-u C-x C-e}.}
     @result{} #<keypress-event control-E>
@end group
@end example
@end defvar

@defvar last-command-char

If the value of @code{last-command-event} is a keyboard event, then this
is the nearest character equivalent to it (or @code{nil} if there is no
character equivalent).  @code{last-command-char} is the character that
@code{self-insert-command} will insert in the buffer.  Remember that
there is @emph{not} a one-to-one mapping between keyboard events and
XEmacs characters: many keyboard events have no corresponding character,
and when the Mule feature is available, most characters can not be input
on standard keyboards, except possibly with help from an input method.
So writing code that examines this variable to determine what key has
been typed is bad practice, unless you are certain that it will be one
of a small set of characters.

This variable exists for compatibility with Emacs version 18.

@example
@group
last-command-char
;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
     @result{} ?\^E
@end group
@end example

@end defvar

@defvar current-mouse-event
This variable holds the mouse-button event which invoked this command,
or @code{nil}.  This is what @code{(interactive "e")} returns.
@end defvar

@defvar echo-keystrokes
This variable determines how much time should elapse before command
characters echo.  Its value must be an integer, which specifies the
number of seconds to wait before echoing.  If the user types a prefix
key (say @kbd{C-x}) and then delays this many seconds before continuing,
the key @kbd{C-x} is echoed in the echo area.  Any subsequent characters
in the same command will be echoed as well.

If the value is zero, then command input is not echoed.
@end defvar

@node Events
@section Events
@cindex events
@cindex input events

The XEmacs command loop reads a sequence of @dfn{events} that
represent keyboard or mouse activity.  Unlike in Emacs 18 and in FSF
Emacs, events are a primitive Lisp type that must be manipulated
using their own accessor and settor primitives.  This section describes
the representation and meaning of input events in detail.

A key sequence that starts with a mouse event is read using the keymaps
of the buffer in the window that the mouse was in, not the current
buffer.  This does not imply that clicking in a window selects that
window or its buffer---that is entirely under the control of the command
binding of the key sequence.

For information about how exactly the XEmacs command loop works,
@xref{Reading Input}.

@defun eventp object
This function returns non-@code{nil} if @var{event} is an input event.
@end defun

@menu
* Event Types::			Events come in different types.
* Event Contents::		What the contents of each event type are.
* Event Predicates::		Querying whether an event is of a
				  particular type.
* Accessing Mouse Event Positions::
				Determining where a mouse event occurred,
				  and over what.
* Accessing Other Event Info::  Accessing non-positional event info.
* Working With Events::		Creating, copying, and destroying events.
* Converting Events::		Converting between events, keys, and
				  characters.
@end menu

@node Event Types
@subsection Event Types

Events represent keyboard or mouse activity or status changes of various
sorts, such as process input being available or a timeout being triggered.
The different event types are as follows:

@table @asis
@item key-press event
  A key was pressed.  Note that modifier keys such as ``control'', ``shift'',
and ``alt'' do not generate events; instead, they are tracked internally
by XEmacs, and non-modifier key presses generate events that specify both
the key pressed and the modifiers that were held down at the time.

@item button-press event
@itemx button-release event
  A button was pressed or released.  Along with the button that was pressed
or released, button events specify the modifier keys that were held down
at the time and the position of the pointer at the time.

@item motion event
  The pointer was moved.  Along with the position of the pointer, these events
also specify the modifier keys that were held down at the time.

@item misc-user event
  A menu item was selected, or the scrollbar was used.

@item process event
  Input is available on a process.

@item timeout event
  A timeout has triggered.

@item magic event
  Some window-system-specific action (such as a frame being resized or
a portion of a frame needing to be redrawn) has occurred.  The contents
of this event are not accessible at the E-Lisp level, but
@code{dispatch-event} knows what to do with an event of this type.
  
@item eval event
  This is a special kind of event specifying that a particular function
needs to be called when this event is dispatched.  An event of this type
is sometimes placed in the event queue when a magic event is processed.
This kind of event should generally just be passed off to
@code{dispatch-event}.  @xref{Dispatching an Event}.
@end table

@node Event Contents
@subsection Contents of the Different Types of Events

  Every event, no matter what type it is, contains a timestamp (which is
typically an offset in milliseconds from when the X server was started)
indicating when the event occurred.  In addition, many events contain
a @dfn{channel}, which specifies which frame the event occurred on,
and/or a value indicating which modifier keys (shift, control, etc.)
were held down at the time of the event.

The contents of each event are as follows:

@table @asis
@item key-press event
@table @asis
@item channel
@item timestamp
@item key
  Which key was pressed.  This is an integer (in the printing @sc{ASCII}
range: >32 and <127) or a symbol such as @code{left} or @code{right}.
Note that many physical keys are actually treated as two separate keys,
depending on whether the shift key is pressed; for example, the ``a''
key is treated as either ``a'' or ``A'' depending on the state of the
shift key, and the ``1'' key is similarly treated as either ``1'' or
``!'' on most keyboards.  In such cases, the shift key does not show up
in the modifier list.  For other keys, such as @code{backspace}, the
shift key shows up as a regular modifier.
@item modifiers
  Which modifier keys were pressed.  As mentioned above, the shift key
is not treated as a modifier for many keys and will not show up in this list
in such cases.
@end table

@item button-press event
@itemx button-release event
@table @asis
@item channel
@item timestamp
@item button
  What button went down or up.  Buttons are numbered starting at 1.
@item modifiers
  Which modifier keys were pressed.  The special business mentioned above
for the shift key does @emph{not} apply to mouse events.
@item x
@itemx y
  The position of the pointer (in pixels) at the time of the event.
@end table

@item pointer-motion event
@table @asis
@item channel
@item timestamp
@item x
@itemx y
  The position of the pointer (in pixels) after it moved.
@item modifiers
  Which modifier keys were pressed.  The special business mentioned above
for the shift key does @emph{not} apply to mouse events.
@end table

@item misc-user event
@table @asis
@item timestamp
@item function
  The E-Lisp function to call for this event.  This is normally either
@code{eval} or @code{call-interactively}.
@item object
  The object to pass to the function.  This is normally the callback that
was specified in the menu description.
@end table

@item process_event
@table @asis
@item timestamp
@item process
  The Emacs ``process'' object in question.
@end table

@item timeout event
@table @asis
@item timestamp
@item function
  The E-Lisp function to call for this timeout.  It is called with one
argument, the event.
@item object
  Some Lisp object associated with this timeout, to make it easier to tell
them apart.  The function and object for this event were specified when
the timeout was set.
@end table

@item magic event
@table @asis
@item timestamp
@end table
(The rest of the information in this event is not user-accessible.)

@item eval event
@table @asis
@item timestamp
@item function
  An E-Lisp function to call when this event is dispatched.
@item object
  The object to pass to the function.  The function and object are set
when the event is created.
@end table
@end table

@defun event-type event
Return the type of @var{event}.

This will be a symbol; one of

@table @code
@item key-press
A key was pressed.
@item button-press
A mouse button was pressed.
@item button-release
A mouse button was released.
@item motion
The mouse moved.
@item misc-user
Some other user action happened; typically, this is
a menu selection or scrollbar action.
@item process
Input is available from a subprocess.
@item timeout
A timeout has expired.
@item eval
This causes a specified action to occur when dispatched.
@item magic
Some window-system-specific event has occurred.
@end table
@end defun

@node Event Predicates
@subsection Event Predicates

The following predicates return whether an object is an event of a
particular type.

@defun key-press-event-p object
This is true if @var{object} is a key-press event.
@end defun

@defun button-event-p object object
This is true if @var{object} is a mouse button-press or button-release
event.
@end defun

@defun button-press-event-p object
This is true if @var{object} is a mouse button-press event.
@end defun

@defun button-release-event-p object
This is true if @var{object} is a mouse button-release event.
@end defun

@defun motion-event-p object
This is true if @var{object} is a mouse motion event.
@end defun

@defun mouse-event-p object
This is true if @var{object} is a mouse button-press, button-release
or motion event.
@end defun

@defun eval-event-p object
This is true if @var{object} is an eval event.
@end defun

@defun misc-user-event-p object
This is true if @var{object} is a misc-user event.
@end defun

@defun process-event-p object
This is true if @var{object} is a process event.
@end defun

@defun timeout-event-p object
This is true if @var{object} is a timeout event.
@end defun

@defun event-live-p object
This is true if @var{object} is any event that has not been deallocated.
@end defun

@node Accessing Mouse Event Positions
@subsection Accessing the Position of a Mouse Event

Unlike other events, mouse events (i.e. motion, button-press, and
button-release events) occur in a particular location on the screen.
Many primitives are provided for determining exactly where the event
occurred and what is under that location.

@menu
* Frame-Level Event Position Info::
* Window-Level Event Position Info::
* Event Text Position Info::
* Event Glyph Position Info::
* Event Toolbar Position Info::
* Other Event Position Info::
@end menu

@node Frame-Level Event Position Info
@subsubsection Frame-Level Event Position Info

The following functions return frame-level information about where
a mouse event occurred.

@defun event-frame event
This function returns the ``channel'' or frame that the given mouse
motion, button press, or button release event occurred in.  This will be
@code{nil} for non-mouse events.
@end defun

@defun event-x-pixel event
This function returns the X position in pixels of the given mouse event.
The value returned is relative to the frame the event occurred in.
This will signal an error if the event is not a mouse event.
@end defun

@defun event-y-pixel event
This function returns the Y position in pixels of the given mouse event.
The value returned is relative to the frame the event occurred in.
This will signal an error if the event is not a mouse event.
@end defun

@node Window-Level Event Position Info
@subsubsection Window-Level Event Position Info

The following functions return window-level information about where
a mouse event occurred.

@defun event-window event
Given a mouse motion, button press, or button release event, compute and
return the window on which that event occurred.  This may be @code{nil}
if the event occurred in the border or over a toolbar.  The modeline is
considered to be within the window it describes.
@end defun

@defun event-buffer event
Given a mouse motion, button press, or button release event, compute and
return the buffer of the window on which that event occurred.  This may
be @code{nil} if the event occurred in the border or over a toolbar.
The modeline is considered to be within the window it describes.  This is
equivalent to calling @code{event-window} and then calling
@code{window-buffer} on the result if it is a window.
@end defun

@defun event-window-x-pixel event
This function returns the X position in pixels of the given mouse event.
The value returned is relative to the window the event occurred in.
This will signal an error if the event is not a mouse-motion, button-press,
or button-release event.
@end defun

@defun event-window-y-pixel event
This function returns the Y position in pixels of the given mouse event.
The value returned is relative to the window the event occurred in.
This will signal an error if the event is not a mouse-motion, button-press,
or button-release event.
@end defun

@node Event Text Position Info
@subsubsection Event Text Position Info

The following functions return information about the text (including the
modeline) that a mouse event occurred over or near.

@defun event-over-text-area-p event
Given a mouse-motion, button-press, or button-release event, this
function returns @code{t} if the event is over the text area of a
window.  Otherwise, @code{nil} is returned.  The modeline is not
considered to be part of the text area.
@end defun

@defun event-over-modeline-p event
Given a mouse-motion, button-press, or button-release event, this
function returns @code{t} if the event is over the modeline of a window.
Otherwise, @code{nil} is returned.
@end defun

@defun event-x event
This function returns the X position of the given mouse-motion,
button-press, or button-release event in characters.  This is relative
to the window the event occurred over.
@end defun

@defun event-y event
This function returns the Y position of the given mouse-motion,
button-press, or button-release event in characters.  This is relative
to the window the event occurred over.
@end defun

@defun event-point event
This function returns the character position of the given mouse-motion,
button-press, or button-release event.  If the event did not occur over
a window, or did not occur over text, then this returns @code{nil}.
Otherwise, it returns an index into the buffer visible in the event's
window.
@end defun

@defun event-closest-point event
This function returns the character position of the given mouse-motion,
button-press, or button-release event.  If the event did not occur over
a window or over text, it returns the closest point to the location of
the event.  If the Y pixel position overlaps a window and the X pixel
position is to the left of that window, the closest point is the
beginning of the line containing the Y position.  If the Y pixel
position overlaps a window and the X pixel position is to the right of
that window, the closest point is the end of the line containing the Y
position.  If the Y pixel position is above a window, 0 is returned.  If
it is below a window, the value of @code{(window-end)} is returned.
@end defun

@node Event Glyph Position Info
@subsubsection Event Glyph Position Info

The following functions return information about the glyph (if any) that
a mouse event occurred over.

@defun event-over-glyph-p event
Given a mouse-motion, button-press, or button-release event, this
function returns @code{t} if the event is over a glyph.  Otherwise,
@code{nil} is returned.
@end defun

@defun event-glyph-extent event
If the given mouse-motion, button-press, or button-release event happened
on top of a glyph, this returns its extent; else @code{nil} is returned.
@end defun

@defun event-glyph-x-pixel event
Given a mouse-motion, button-press, or button-release event over a
glyph, this function returns the X position of the pointer relative to
the upper left of the glyph.  If the event is not over a glyph, it returns
@code{nil}.
@end defun

@defun event-glyph-y-pixel event
Given a mouse-motion, button-press, or button-release event over a
glyph, this function returns the Y position of the pointer relative to
the upper left of the glyph.  If the event is not over a glyph, it returns
@code{nil}.
@end defun

@node Event Toolbar Position Info
@subsubsection Event Toolbar Position Info

@defun event-over-toolbar-p event
Given a mouse-motion, button-press, or button-release event, this
function returns @code{t} if the event is over a toolbar.  Otherwise,
@code{nil} is returned.
@end defun

@defun event-toolbar-button event
If the given mouse-motion, button-press, or button-release event
happened on top of a toolbar button, this function returns the button.
Otherwise, @code{nil} is returned.
@end defun

@node Other Event Position Info
@subsubsection Other Event Position Info

@defun event-over-border-p event
Given a mouse-motion, button-press, or button-release event, this
function returns @code{t} if the event is over an internal toolbar.
Otherwise, @code{nil} is returned.
@end defun

@node Accessing Other Event Info
@subsection Accessing the Other Contents of Events

The following functions allow access to the contents of events other than
the position info described in the previous section.

@defun event-timestamp event
This function returns the timestamp of the given event object.
@end defun

@defun event-device event
This function returns the device that the given event occurred on.
@end defun

@defun event-key event
This function returns the Keysym of the given key-press event.
This will be the @sc{ASCII} code of a printing character, or a symbol.
@end defun

@defun event-button event
This function returns the button-number of the given button-press or
button-release event.
@end defun

@defun event-modifiers event
This function returns a list of symbols, the names of the modifier keys
which were down when the given mouse or keyboard event was produced.
@end defun

@defun event-modifier-bits event
This function returns a number representing the modifier keys which were down
when the given mouse or keyboard event was produced.
@end defun

@defun event-function event
This function returns the callback function of the given timeout, misc-user,
or eval event.
@end defun

@defun event-object event
This function returns the callback function argument of the given timeout,
misc-user, or eval event.
@end defun

@defun event-process event
This function returns the process of the given process event.
@end defun

@node Working With Events
@subsection Working With Events

XEmacs provides primitives for creating, copying, and destroying event
objects.  Many functions that return events take an event object as an
argument and fill in the fields of this event; or they make accept
either an event object or @code{nil}, creating the event object first in
the latter case.

@defun allocate-event
This function returns an empty event structure.  WARNING: The event
object returned may be a reused one; see the function
@code{deallocate-event}.
@end defun

@defun copy-event event1 &optional event2
This function makes a copy of the given event object.  If a second
argument is given, the first event is copied into the second and the
second is returned.  If the second argument is not supplied (or is
@code{nil}) then a new event will be made as with @code{allocate-event}.
@end defun

@defun deallocate-event event
This function allows the given event structure to be reused.  You
@strong{MUST NOT} use this event object after calling this function with
it.  You will lose.  It is not necessary to call this function, as event
objects are garbage-collected like all other objects; however, it may be
more efficient to explicitly deallocate events when you are sure that
that is safe.
@end defun

@node Converting Events
@subsection Converting Events

XEmacs provides some auxiliary functions for converting between events
and other ways of representing keys.  These are useful when working with
@sc{ASCII} strings and with keymaps.

@defun character-to-event ch &optional event device
This function converts a numeric @sc{ASCII} value to an event structure,
replete with modifier bits.  @var{ch} is the character to convert, and
@var{event} is the event object to fill in.  This function contains
knowledge about what the codes ``mean'' -- for example, the number 9 is
converted to the character @key{Tab}, not the distinct character
@key{Control-I}.

Note that @var{ch} does not have to be a numeric value, but can be a
symbol such as @code{clear} or a list such as @code{(control
backspace)}.

If @code{event} is not @code{nil}, it is modified; otherwise, a
new event object is created.  In both cases, the event is returned.

Optional third arg @var{device} is the device to store in the event;
this also affects whether the high bit is interpreted as a meta key.  A
value of @code{nil} means use the selected device but always treat the
high bit as meta.

Beware that @code{character-to-event} and @code{event-to-character} are
not strictly inverse functions, since events contain much more
information than the @sc{ASCII} character set can encode.
@end defun

@defun event-to-character event &optional allow-extra-modifiers allow-meta allow-non-ascii
This function returns the closest @sc{ASCII} approximation to
@var{event}.  If the event isn't a keypress, this returns @code{nil}.

If @var{allow-extra-modifiers} is non-@code{nil}, then this is lenient
in its translation; it will ignore modifier keys other than
@key{control} and @key{meta}, and will ignore the @key{shift} modifier
on those characters which have no shifted @sc{ASCII} equivalent
(@key{Control-Shift-A} for example, will be mapped to the same
@sc{ASCII} code as @key{Control-A}).

If @var{allow-meta} is non-@code{nil}, then the @key{Meta} modifier will
be represented by turning on the high bit of the byte returned;
otherwise, @code{nil} will be returned for events containing the
@key{Meta} modifier.

If @var{allow-non-ascii} is non-@code{nil}, then characters which are
present in the prevailing character set (@pxref{Keymaps, variable
@code{character-set-property}}) will be returned as their code in that
character set, instead of the return value being restricted to
@sc{ASCII}.

Note that specifying both @var{allow-meta} and @var{allow-non-ascii} is
ambiguous, as both use the high bit; @key{M-x} and @key{oslash} will be
indistinguishable.
@end defun

@defun events-to-keys events &optional no-mice
Given a vector of event objects, this function returns a vector of key
descriptors, or a string (if they all fit in the @sc{ASCII} range).
Optional arg @var{no-mice} means that button events are not allowed.
@end defun

@node Reading Input
@section Reading Input

  The editor command loop reads keyboard input using the function
@code{next-event} and constructs key sequences out of the events using
@code{dispatch-event}.  Lisp programs can also use the function
@code{read-key-sequence}, which reads input a key sequence at a time.
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.

  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.
* Dispatching an Event::        What to do with an event once it has been read.
* Quoted Character Input::	Asking the user to specify a character.
* Peeking and Discarding::    	How to reread or throw away input events.
@end menu

@node Key Sequence Input
@subsection Key Sequence Input
@cindex key sequence input

Lisp programs can read input a key sequence at a time by calling
@code{read-key-sequence}; for example, @code{describe-key} uses it to
read the key to describe.

@defun read-key-sequence prompt
@cindex key sequence
This function reads a sequence of keystrokes or mouse clicks and returns
it as a vector of events.  It keeps reading events until it has
accumulated a full key sequence; that is, enough to specify a non-prefix
command using the currently active keymaps.

The vector and the event objects it contains are freshly created, and
will not be side-effected by subsequent calls to this function.

The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
typed while reading with this function works like any other character,
and does not set @code{quit-flag}.  @xref{Quitting}.

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.

@c XEmacs feature
If the user selects a menu item while we are prompting for a key
sequence, the returned value will be a vector of a single menu-selection
event (a misc-user event).  An error will be signalled if you pass this
value to @code{lookup-key} or a related function.

In the example below, the prompt @samp{?} is displayed in the echo area,
and the user types @kbd{C-x C-f}.

@example
(read-key-sequence "?")

@group
---------- Echo Area ----------
?@kbd{C-x C-f}
---------- Echo Area ----------

     @result{} [#<keypress-event control-X> #<keypress-event control-F>]
@end group
@end example
@end defun

@ignore  @c Not in XEmacs
@defvar num-input-keys
@c Emacs 19 feature
This variable's value is the number of key sequences processed so far in
this XEmacs session.  This includes key sequences read from the terminal
and key sequences read from keyboard macros being executed.
@end defvar
@end ignore

@cindex upper case key sequence
@cindex downcasing in @code{lookup-key}
If an input character is an upper-case letter and has no key binding,
but its lower-case equivalent has one, then @code{read-key-sequence}
converts the character to lower case.  Note that @code{lookup-key} does
not perform case conversion in this way.

@node Reading One Event
@subsection Reading One Event

  The lowest level functions for command input are those which read a
single event.  These functions often make a distinction between
@dfn{command events}, which are user actions (keystrokes and mouse
actions), and other events, which serve as communication between
XEmacs and the window system.

@defun next-event &optional event prompt
This function reads and returns the next available event from the window
system or terminal driver, waiting if necessary until an event is
available.  Pass this object to @code{dispatch-event} to handle it. If
an event object is supplied, it is filled in and returned; otherwise a
new event object will be created.

Events can come directly from the user, from a keyboard macro, or from
@code{unread-command-events}.

In most cases, the function @code{next-command-event} is more
appropriate.
@end defun

@defun next-command-event &optional event
This function returns the next available ``user'' event from the window
system or terminal driver.  Pass this object to @code{dispatch-event} to
handle it.  If an event object is supplied, it is filled in and
returned, otherwise a new event object will be created.

The event returned will be a keyboard, mouse press, or mouse release
event.  If there are non-command events available (mouse motion,
sub-process output, etc) then these will be executed (with
@code{dispatch-event}) and discarded.  This function is provided as a
convenience; it is equivalent to the Lisp code

@lisp
@group
	(while (progn
		 (next-event event)
	         (not (or (key-press-event-p event)
	                  (button-press-event-p event)
	                  (button-release-event-p event)
	                  (menu-event-p event))))
	   (dispatch-event event))
@end group
@end lisp

Here is what happens if you call @code{next-command-event} and then
press the right-arrow function key:

@example
@group
(next-command-event)
     @result{} #<keypress-event right>
@end group
@end example
@end defun

@defun read-char
This function reads and returns a character of command input.  If a
mouse click is detected, an error is signalled.  The character typed is
returned as an @sc{ASCII} value.  This function is retained for
compatibility with Emacs 18, and is most likely the wrong thing for you
to be using: consider using @code{next-command-event} instead.
@end defun

@defun enqueue-eval-event function object
This function adds an eval event to the back of the queue.  The
eval event will be the next event read after all pending events.
@end defun

@node Dispatching an Event
@subsection Dispatching an Event
@cindex dispatching an event

@defun dispatch-event event
Given an event object returned by @code{next-event}, this function
executes it.  This is the basic function that makes XEmacs respond to
user input; it also deals with notifications from the window system
(such as Expose events).
@end defun

@node Quoted Character Input
@subsection Quoted Character Input
@cindex quoted character input

  You can use the function @code{read-quoted-char} to ask the user to
specify a character, and allow the user to specify a control or meta
character conveniently, either literally or as an octal character code.
The command @code{quoted-insert} uses this function.

@defun read-quoted-char &optional prompt
@cindex octal character input
@cindex control characters, reading
@cindex nonprinting characters, reading
This function is like @code{read-char}, except that if the first
character read is an octal digit (0-7), it reads up to two more octal digits
(but stopping if a non-octal digit is found) and returns the
character represented by those digits in octal.

Quitting is suppressed when the first character is read, so that the
user can enter a @kbd{C-g}.  @xref{Quitting}.

If @var{prompt} is supplied, it specifies a string for prompting the
user.  The prompt string is always displayed in the echo area, followed
by a single @samp{-}.

In the following example, the user types in the octal number 177 (which
is 127 in decimal).

@example
(read-quoted-char "What character")

@group
---------- Echo Area ----------
What character-@kbd{177}
---------- Echo Area ----------

     @result{} 127
@end group
@end example
@end defun

@need 2000
@node Peeking and Discarding
@subsection Miscellaneous Event Input Features

This section describes how to ``peek ahead'' at events without using
them up, how to check for pending input, and how to discard pending
input.

See also the variables @code{last-command-event} and @code{last-command-char}
(@ref{Command Loop Info}).

@defvar unread-command-events
@cindex next input
@cindex peeking at input
This variable holds a list of events waiting to be read as command
input.  The events are used in the order they appear in the list, and
removed one by one as they are used.

The variable is needed because in some cases a function reads a event
and then decides not to use it.  Storing the event in this variable
causes it to be processed normally, by the command loop or by the
functions to read command input.

@cindex prefix argument unreading
For example, the function that implements numeric prefix arguments reads
any number of digits.  When it finds a non-digit event, it must unread
the event so that it can be read normally by the command loop.
Likewise, incremental search uses this feature to unread events with no 
special meaning in a search, because these events should exit the search
and then execute normally.

@ignore FSF Emacs stuff
The reliable and easy way to extract events from a key sequence so as to
put them in @code{unread-command-events} is to use
@code{listify-key-sequence} (@pxref{Strings of Events}).
@end ignore
@end defvar

@defvar unread-command-event
This variable holds a single event to be read as command input.

This variable is mostly obsolete now that you can use
@code{unread-command-events} instead; it exists only to support programs
written for versions of XEmacs prior to 19.12.
@end defvar

@defun input-pending-p
@cindex waiting for command key input
This function determines whether any command input is currently
available to be read.  It returns immediately, with value @code{t} if
there is available input, @code{nil} otherwise.  On rare occasions it
may return @code{t} when no input is available.
@end defun

@defvar last-input-event
This variable is set to the last keyboard or mouse button event received.

This variable is off limits: you may not set its value or modify the
event that is its value, as it is destructively modified by
@code{read-key-sequence}.  If you want to keep a pointer to this value,
you must use @code{copy-event}.

Note that this variable is an alias for @code{last-input-char} in
FSF Emacs.

In the example below, a character is read (the character @kbd{1}).  It
becomes the value of @code{last-input-event}, while @kbd{C-e} (from the
@kbd{C-x C-e} command used to evaluate this expression) remains the
value of @code{last-command-event}.

@example
@group
(progn (print (next-command-event))
       (print last-command-event)
       last-input-event)
     @print{} #<keypress-event 1>
     @print{} #<keypress-event control-E>
     @result{} #<keypress-event 1>

@end group
@end example
@end defvar

@defvar last-input-char
If the value of @code{last-input-event} is a keyboard event, then this
is the nearest @sc{ASCII} equivalent to it.  Remember that there is
@emph{not} a 1:1 mapping between keyboard events and @sc{ASCII}
characters: the set of keyboard events is much larger, so writing code
that examines this variable to determine what key has been typed is bad
practice, unless you are certain that it will be one of a small set of
characters.

This function exists for compatibility with Emacs version 18.
@end defvar

@defun discard-input
@cindex flush input
@cindex discard input
@cindex terminate keyboard macro
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}.

In the following example, the user may type a number of characters right
after starting the evaluation of the form.  After the @code{sleep-for}
finishes sleeping, @code{discard-input} discards any characters typed 
during the sleep.

@example
(progn (sleep-for 2)
       (discard-input))
     @result{} nil
@end example
@end defun

@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
to pass or until there is input.  For example, you may wish to pause in
the middle of a computation to allow the user time to view the display.
@code{sit-for} pauses and updates the screen, and returns immediately if
input comes in, while @code{sleep-for} pauses without updating the
screen.

Note that in FSF Emacs, the commands @code{sit-for} and @code{sleep-for}
take two arguments to specify the time (one integer and one float
value), instead of a single argument that can be either an integer or a
float.

@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 result is @code{t} if @code{sit-for} waited the full
time with no input arriving (see @code{input-pending-p} in @ref{Peeking
and Discarding}).  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.
@ignore FSF Emacs stuff
Some systems support only a whole number of seconds; on these systems,
@var{seconds} is rounded down.

The optional argument @var{millisec} specifies an additional waiting
period measured in milliseconds.  This adds to the period specified by
@var{seconds}.  If the system doesn't support waiting fractions of a
second, you get an error if you specify nonzero @var{millisec}.
@end ignore

@cindex forcing redisplay
Redisplay is normally preempted if input arrives, and does not happen at
all if input is available before it starts. (You can force screen
updating in such a case by using @code{force-redisplay}.  @xref{Refresh
Screen}.) If there is no input pending, you can force an update with no
delay by using @code{(sit-for 0)}.

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).

@ignore
Iconifying or deiconifying a frame makes @code{sit-for} return, because
that generates an event.  @xref{Misc Events}.
@end ignore

The usual purpose of @code{sit-for} is to give the user time to read
text that you display.
@end defun

@defun sleep-for seconds
This function simply pauses for @var{seconds} seconds without updating
the display.  This function pays no attention to available input.  It
returns @code{nil}.

The argument @var{seconds} need not be an integer.  If it is a floating
point number, @code{sleep-for} waits for a fractional number of seconds.
@ignore FSF Emacs stuff
Some systems support only a whole number of seconds; on these systems,
@var{seconds} is rounded down.

The optional argument @var{millisec} specifies an additional waiting
period measured in milliseconds.  This adds to the period specified by
@var{seconds}.  If the system doesn't support waiting fractions of a
second, you get an error if you specify nonzero @var{millisec}.
@end ignore

Use @code{sleep-for} when you wish to guarantee a delay.
@end defun

  @xref{Time of Day}, for functions to get the current time.

@node Quitting
@section Quitting
@cindex @kbd{C-g}
@cindex quitting

  Typing @kbd{C-g} while a Lisp function is running causes XEmacs to
@dfn{quit} whatever it is doing.  This means that control returns to the
innermost active command loop.

  Typing @kbd{C-g} while the command loop is waiting for keyboard input
does not cause a quit; it acts as an ordinary input character.  In the
simplest case, you cannot tell the difference, because @kbd{C-g}
normally runs the command @code{keyboard-quit}, whose effect is to quit.
However, when @kbd{C-g} follows a prefix key, the result is an undefined
key.  The effect is to cancel the prefix key as well as any prefix
argument.

  In the minibuffer, @kbd{C-g} has a different definition: it aborts out
of the minibuffer.  This means, in effect, that it exits the minibuffer
and then quits.  (Simply quitting would return to the command loop
@emph{within} the minibuffer.)  The reason why @kbd{C-g} does not quit
directly when the command reader is reading input is so that its meaning
can be redefined in the minibuffer in this way.  @kbd{C-g} following a
prefix key is not redefined in the minibuffer, and it has its normal
effect of canceling the prefix key and prefix argument.  This too
would not be possible if @kbd{C-g} always quit directly.

  When @kbd{C-g} does directly quit, it does so by setting the variable
@code{quit-flag} to @code{t}.  XEmacs checks this variable at appropriate
times and quits if it is not @code{nil}.  Setting @code{quit-flag}
non-@code{nil} in any way thus causes a quit.

  At the level of C code, quitting cannot happen just anywhere; only at the
special places that check @code{quit-flag}.  The reason for this is
that quitting at other places might leave an inconsistency in XEmacs's
internal state.  Because quitting is delayed until a safe place, quitting 
cannot make XEmacs crash.

  Certain functions such as @code{read-key-sequence} or
@code{read-quoted-char} prevent quitting entirely even though they wait
for input.  Instead of quitting, @kbd{C-g} serves as the requested
input.  In the case of @code{read-key-sequence}, this serves to bring
about the special behavior of @kbd{C-g} in the command loop.  In the
case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
to quote a @kbd{C-g}.  

  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
usual result of this---a quit---is prevented.  Eventually,
@code{inhibit-quit} will become @code{nil} again, such as when its
binding is unwound at the end of a @code{let} form.  At that time, if
@code{quit-flag} is still non-@code{nil}, the requested quit happens
immediately.  This behavior is ideal when you wish to make sure that
quitting does not happen within a ``critical section'' of the program.

@cindex @code{read-quoted-char} quitting
  In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
handled in a special way that does not involve quitting.  This is done
by reading the input with @code{inhibit-quit} bound to @code{t}, and
setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
becomes @code{nil} again.  This excerpt from the definition of
@code{read-quoted-char} shows how this is done; it also shows that
normal quitting is permitted after the first character of input.

@example
(defun read-quoted-char (&optional prompt)
  "@dots{}@var{documentation}@dots{}"
  (let ((count 0) (code 0) char)
    (while (< count 3)
      (let ((inhibit-quit (zerop count))
            (help-form nil))
        (and prompt (message "%s-" prompt))
        (setq char (read-char))
        (if inhibit-quit (setq quit-flag nil)))
      @dots{})
    (logand 255 code)))
@end example

@defvar quit-flag
If this variable is non-@code{nil}, then XEmacs quits immediately, unless
@code{inhibit-quit} is non-@code{nil}.  Typing @kbd{C-g} ordinarily sets
@code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
@end defvar

@defvar inhibit-quit
This variable determines whether XEmacs should quit when @code{quit-flag}
is set to a value other than @code{nil}.  If @code{inhibit-quit} is
non-@code{nil}, then @code{quit-flag} has no special effect.
@end defvar

@deffn Command keyboard-quit
This function signals the @code{quit} condition with @code{(signal 'quit
nil)}.  This is the same thing that quitting does.  (See @code{signal}
in @ref{Errors}.)
@end deffn

  You can specify a character other than @kbd{C-g} to use for quitting.
See the function @code{set-input-mode} in @ref{Terminal Input}.
 
@node Prefix Command Arguments
@section Prefix Command Arguments
@cindex prefix argument
@cindex raw prefix argument
@cindex numeric prefix argument

  Most XEmacs commands can use a @dfn{prefix argument}, a number
specified before the command itself.  (Don't confuse prefix arguments
with prefix keys.)  The prefix argument is at all times represented by a
value, which may be @code{nil}, meaning there is currently no prefix
argument.  Each command may use the prefix argument or ignore it.

  There are two representations of the prefix argument: @dfn{raw} and
@dfn{numeric}.  The editor command loop uses the raw representation
internally, and so do the Lisp variables that store the information, but
commands can request either representation.

  Here are the possible values of a raw prefix argument:

@itemize @bullet
@item
@code{nil}, meaning there is no prefix argument.  Its numeric value is
1, but numerous commands make a distinction between @code{nil} and the
integer 1.

@item
An integer, which stands for itself.

@item
A list of one element, which is an integer.  This form of prefix
argument results from one or a succession of @kbd{C-u}'s with no
digits.  The numeric value is the integer in the list, but some
commands make a distinction between such a list and an integer alone.

@item
The symbol @code{-}.  This indicates that @kbd{M--} or @kbd{C-u -} was
typed, without following digits.  The equivalent numeric value is
@minus{}1, but some commands make a distinction between the integer
@minus{}1 and the symbol @code{-}.
@end itemize

We illustrate these possibilities by calling the following function with
various prefixes:

@example
@group
(defun display-prefix (arg)
  "Display the value of the raw prefix arg."
  (interactive "P")
  (message "%s" arg))
@end group
@end example

@noindent
Here are the results of calling @code{display-prefix} with various
raw prefix arguments:

@example
        M-x display-prefix  @print{} nil

C-u     M-x display-prefix  @print{} (4)

C-u C-u M-x display-prefix  @print{} (16)

C-u 3   M-x display-prefix  @print{} 3

M-3     M-x display-prefix  @print{} 3      ; @r{(Same as @code{C-u 3}.)}

C-3     M-x display-prefix  @print{} 3      ; @r{(Same as @code{C-u 3}.)}

C-u -   M-x display-prefix  @print{} -      

M--     M-x display-prefix  @print{} -      ; @r{(Same as @code{C-u -}.)}

C--     M-x display-prefix  @print{} -      ; @r{(Same as @code{C-u -}.)}

C-u - 7 M-x display-prefix  @print{} -7     

M-- 7   M-x display-prefix  @print{} -7     ; @r{(Same as @code{C-u -7}.)}

C-- 7   M-x display-prefix  @print{} -7     ; @r{(Same as @code{C-u -7}.)}
@end example

  XEmacs uses two variables to store the prefix argument:
@code{prefix-arg} and @code{current-prefix-arg}.  Commands such as
@code{universal-argument} that set up prefix arguments for other
commands store them in @code{prefix-arg}.  In contrast,
@code{current-prefix-arg} conveys the prefix argument to the current
command, so setting it has no effect on the prefix arguments for future
commands.

  Normally, commands specify which representation to use for the prefix
argument, either numeric or raw, in the @code{interactive} declaration.
(@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.

@defun prefix-numeric-value arg
This function returns the numeric meaning of a valid raw prefix argument
value, @var{arg}.  The argument may be a symbol, a number, or a list.
If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
value @minus{}1 is returned; if it is a number, that number is returned;
if it is a list, the @sc{car} of that list (which should be a number) is
returned.
@end defun

@defvar current-prefix-arg
This variable holds the raw prefix argument for the @emph{current}
command.  Commands may examine it directly, but the usual way to access
it is with @code{(interactive "P")}.
@end defvar

@defvar prefix-arg
The value of this variable is the raw prefix argument for the
@emph{next} editing command.  Commands that specify prefix arguments for
the following command work by setting this variable.
@end defvar

  Do not call the functions @code{universal-argument},
@code{digit-argument}, or @code{negative-argument} unless you intend to
let the user enter the prefix argument for the @emph{next} command.

@deffn Command universal-argument
This command reads input and specifies a prefix argument for the
following command.  Don't call this command yourself unless you know
what you are doing.
@end deffn

@deffn Command digit-argument arg
This command adds to the prefix argument for the following command.  The
argument @var{arg} is the raw prefix argument as it was before this
command; it is used to compute the updated prefix argument.  Don't call
this command yourself unless you know what you are doing.
@end deffn

@deffn Command negative-argument arg
This command adds to the numeric argument for the next command.  The
argument @var{arg} is the raw prefix argument as it was before this
command; its value is negated to form the new prefix argument.  Don't
call this command yourself unless you know what you are doing.
@end deffn

@node Recursive Editing
@section Recursive Editing
@cindex recursive command loop
@cindex recursive editing level
@cindex command loop, recursive

  The XEmacs command loop is entered automatically when XEmacs starts up.
This top-level invocation of the command loop never exits; it keeps
running as long as XEmacs does.  Lisp programs can also invoke the
command loop.  Since this makes more than one activation of the command
loop, we call it @dfn{recursive editing}.  A recursive editing level has
the effect of suspending whatever command invoked it and permitting the
user to do arbitrary editing before resuming that command.

  The commands available during recursive editing are the same ones
available in the top-level editing loop and defined in the keymaps.
Only a few special commands exit the recursive editing level; the others
return to the recursive editing level when they finish.  (The special
commands for exiting are always available, but they do nothing when
recursive editing is not in progress.)

  All command loops, including recursive ones, set up all-purpose error
handlers so that an error in a command run from the command loop will
not exit the loop.

@cindex minibuffer input
  Minibuffer input is a special kind of recursive editing.  It has a few
special wrinkles, such as enabling display of the minibuffer and the
minibuffer window, but fewer than you might suppose.  Certain keys
behave differently in the minibuffer, but that is only because of the
minibuffer's local map; if you switch windows, you get the usual XEmacs
commands.

@cindex @code{throw} example
@kindex exit
@cindex exit recursive editing
@cindex aborting
  To invoke a recursive editing level, call the function
@code{recursive-edit}.  This function contains the command loop; it also
contains a call to @code{catch} with tag @code{exit}, which makes it
possible to exit the recursive editing level by throwing to @code{exit}
(@pxref{Catch and Throw}).  If you throw a value other than @code{t},
then @code{recursive-edit} returns normally to the function that called
it.  The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
control returns to the command loop one level up.  This is called
@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).

  Most applications should not use recursive editing, except as part of
using the minibuffer.  Usually it is more convenient for the user if you
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
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.)

  Recursive edits are useful in debugging.  You can insert a call to
@code{debug} into a function definition as a sort of breakpoint, so that
you can look around when the function gets there.  @code{debug} invokes
a recursive edit but also provides the other features of the debugger.

  Recursive editing levels are also used when you type @kbd{C-r} in
@code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).

@defun recursive-edit
@cindex suspend evaluation
This function invokes the editor command loop.  It is called
automatically by the initialization of XEmacs, to let the user begin
editing.  When called from a Lisp program, it enters a recursive editing
level.

  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}.

@example
(defun simple-rec ()
  (forward-word 1)
  (message "Recursive edit in progress")
  (recursive-edit)
  (forward-word 1))
     @result{} simple-rec
(simple-rec)
     @result{} nil
@end example
@end defun

@deffn Command exit-recursive-edit
This function exits from the innermost recursive edit (including
minibuffer input).  Its definition is effectively @code{(throw 'exit
nil)}.  
@end deffn

@deffn Command abort-recursive-edit
This function aborts the command that requested the innermost recursive
edit (including minibuffer input), by signaling @code{quit} 
after exiting the recursive edit.  Its definition is effectively
@code{(throw 'exit t)}.  @xref{Quitting}.
@end deffn

@deffn Command top-level
This function exits all recursive editing levels; it does not return a
value, as it jumps completely out of any computation directly back to
the main command loop.
@end deffn

@defun recursion-depth
This function returns the current depth of recursive edits.  When no
recursive edit is active, it returns 0.
@end defun

@node Disabling Commands
@section Disabling Commands
@cindex disabled command

  @dfn{Disabling a command} marks the command as requiring user
confirmation before it can be executed.  Disabling is used for commands
which might be confusing to beginning users, to prevent them from using
the commands by accident.

@kindex disabled
  The low-level mechanism for disabling a command is to put a
non-@code{nil} @code{disabled} property on the Lisp symbol for the
command.  These properties are normally set up by the user's
@file{.emacs} file with Lisp expressions such as this:

@example
(put 'upcase-region 'disabled t)
@end example

@noindent
For a few commands, these properties are present by default and may be
removed by the @file{.emacs} file.

  If the value of the @code{disabled} property is a string, the message
saying the command is disabled includes that string.  For example:

@example
(put 'delete-region 'disabled
     "Text deleted this way cannot be yanked back!\n")
@end example

  @xref{Disabling,,, emacs, The XEmacs Reference Manual}, for the details on
what happens when a disabled command is invoked interactively.
Disabling a command has no effect on calling it as a function from Lisp
programs.

@deffn Command enable-command command
Allow @var{command} to be executed without special confirmation from now
on, and (if the user confirms) alter the user's @file{.emacs} file so
that this will apply to future sessions.
@end deffn

@deffn Command disable-command command
Require special confirmation to execute @var{command} from now on, and
(if the user confirms) alter the user's @file{.emacs} file so that this
will apply to future sessions.
@end deffn

@defvar disabled-command-hook
This normal hook is run instead of a disabled command, when the user
invokes the disabled command interactively.  The hook functions can use
@code{this-command-keys} to determine what the user typed to run the
command, and thus find the command itself.  @xref{Hooks}.

By default, @code{disabled-command-hook} contains a function that asks
the user whether to proceed.
@end defvar

@node Command History
@section Command History
@cindex command history
@cindex complex command
@cindex history of commands

  The command loop keeps a history of the complex commands that have
been executed, to make it convenient to repeat these commands.  A
@dfn{complex command} is one for which the interactive argument reading
uses the minibuffer.  This includes any @kbd{M-x} command, any
@kbd{M-:} command, and any command whose @code{interactive}
specification reads an argument from the minibuffer.  Explicit use of
the minibuffer during the execution of the command itself does not cause
the command to be considered complex.

@defvar command-history
This variable's value is a list of recent complex commands, each
represented as a form to evaluate.  It continues to accumulate all
complex commands for the duration of the editing session, but all but
the first (most recent) thirty elements are deleted when a garbage
collection takes place (@pxref{Garbage Collection}).

@example
@group
command-history
@result{} ((switch-to-buffer "chistory.texi")
    (describe-key "^X^[")
    (visit-tags-table "~/emacs/src/")
    (find-tag "repeat-complex-command"))
@end group
@end example
@end defvar

  This history list is actually a special case of minibuffer history
(@pxref{Minibuffer History}), with one special twist: the elements are
expressions rather than strings.

  There are a number of commands devoted to the editing and recall of
previous commands.  The commands @code{repeat-complex-command}, and
@code{list-command-history} are described in the user manual
(@pxref{Repetition,,, emacs, The XEmacs Reference Manual}).  Within the
minibuffer, the history commands used are the same ones available in any
minibuffer.

@node Keyboard Macros
@section Keyboard Macros
@cindex keyboard macros

  A @dfn{keyboard macro} is a canned sequence of input events that can
be considered a command and made the definition of a key.  The Lisp
representation of a keyboard macro is a string or vector containing the
events.  Don't confuse keyboard macros with Lisp macros
(@pxref{Macros}).

@defun execute-kbd-macro macro &optional count
This function executes @var{macro} as a sequence of events.  If
@var{macro} is a string or vector, then the events in it are executed
exactly as if they had been input by the user.  The sequence is
@emph{not} expected to be a single key sequence; normally a keyboard
macro definition consists of several key sequences concatenated.

If @var{macro} is a symbol, then its function definition is used in
place of @var{macro}.  If that is another symbol, this process repeats.
Eventually the result should be a string or vector.  If the result is
not a symbol, string, or vector, an error is signaled.

The argument @var{count} is a repeat count; @var{macro} is executed that
many times.  If @var{count} is omitted or @code{nil}, @var{macro} is
executed once.  If it is 0, @var{macro} is executed over and over until it
encounters an error or a failing search.  
@end defun

@defvar executing-macro
This variable contains the string or vector that defines the keyboard
macro that is currently executing.  It is @code{nil} if no macro is
currently executing.  A command can test this variable to behave
differently when run from an executing macro.  Do not set this variable
yourself.
@end defvar

@defvar defining-kbd-macro
This variable indicates whether a keyboard macro is being defined.  A
command can test this variable to behave differently while a macro is
being defined.  The commands @code{start-kbd-macro} and
@code{end-kbd-macro} set this variable---do not set it yourself.
@end defvar

@defvar last-kbd-macro
This variable is the definition of the most recently defined keyboard
macro.  Its value is a string or vector, or @code{nil}.
@end defvar

@c Broke paragraph to prevent overfull hbox. --rjc 15mar92
  The commands are described in the user's manual (@pxref{Keyboard
Macros,,, emacs, The XEmacs Reference Manual}).