root/trunk/lispref/commands.texi

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
@c   2003, 2004, 2005, 2006, 2007, 2008  Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
@chapter Command Loop
@cindex editor command loop
@cindex command loop

  When you run Emacs, it enters the @dfn{editor command loop} almost
immediately.  This loop reads key sequences, 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.
* Distinguish Interactive::     Making a command distinguish interactive calls.
* Command Loop Info::   Variables set by the command loop for you to examine.
* Adjusting Point::     Adjustment of point after a command.
* Input Events::        What input looks like when you read it.
* Reading Input::       How to read input events from the keyboard or mouse.
* Special Events::      Events processed immediately and individually.
* 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 first thing the command loop must do is read a key sequence, which
is a sequence of events that translates into a command.  It does this by
calling the function @code{read-key-sequence}.  Your Lisp code can also
call this function (@pxref{Key Sequence Input}).  Lisp programs can also
do input at a lower level with @code{read-event} (@pxref{Reading One
Event}) or discard pending input with @code{discard-input}
(@pxref{Event Input Misc}).

  The key sequence is translated into a command through the currently
active keymaps.  @xref{Key Lookup}, for information on how this is done.
The result 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{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} 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
@code{post-command-hook}.  If an error happens while executing one of
these hooks, it terminates execution of the hook, and clears the hook
variable to @code{nil} so as to prevent an infinite loop of errors.

  A request coming into the Emacs server (@pxref{Emacs Server,,,
emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard
command 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}
@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
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 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 @code{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 @code{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.

You can use @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{*} 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
@defun interactive-form function
This function returns the @code{interactive} form of @var{function}.
If @var{function} is an interactively callable function
(@pxref{Interactive Call}), the value is the command's
@code{interactive} form @code{(interactive @var{spec})}, which
specifies how to compute its arguments.  Otherwise, the value is
@code{nil}.  If @var{function} is a symbol, its function definition is
used.
@end defun

@node Interactive Codes
@comment  node-name,  next,  previous,  up
@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 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{File Name Expansion}).
Existing, Completion, Default, Prompt.

@item e
The first or next mouse event in the key sequence that invoked the command.
More precisely, @samp{e} gets events that are lists, so you can look at
the data in the lists.  @xref{Input Events}.  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} events that are lists, the @var{n}th @samp{e} provides the
@var{n}th such event.  Events that are not lists, such as function keys
and @acronym{ASCII} characters, do not count where @samp{e} is concerned.

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

@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 M
Arbitrary text, read in the minibuffer using the current buffer's input
method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
Emacs Manual}).  Prompt.

@item n
A number, read with the minibuffer.  If the input is not a number, the
user has to try again.  @samp{n} never uses the prefix argument.
Prompt.

@item N
The numeric prefix argument; but if there is no prefix argument, read
a number as with @kbd{n}.  The value is always 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
@cindex raw prefix argument usage
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
@kbd{C-j} 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 U
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
predicate @code{user-variable-p}).  This reads the variable using
@code{read-variable}.  @xref{Definition of read-variable}.  Existing,
Completion, Prompt.

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

@item X
@cindex evaluated expression argument
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
argument value is @code{nil}.  @xref{Coding Systems}.  Completion,
Existing, Prompt.

@item Z
A coding system name (a symbol)---but only if this command has a prefix
argument.  With no prefix argument, @samp{Z} provides @code{nil} as the
argument value.  Completion, Existing, Prompt.
@end table

@node Interactive Examples
@comment  node-name,  next,  previous,  up
@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 command it
invokes that command using the function @code{command-execute}.  If the
command is a function, @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 &optional for-call-interactively
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}, byte-code 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 satisfies @code{commandp} if its function definition
satisfies @code{commandp}.  Keys and keymaps are not commands.
Rather, they are used to look up commands (@pxref{Keymaps}).

If @var{for-call-interactively} is non-@code{nil}, then
@code{commandp} returns @code{t} only for objects that
@code{call-interactively} could call---thus, not for keyboard macros.

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

@defun call-interactively command &optional record-flag keys
This function calls the interactively callable function @var{command},
reading arguments according to its interactive calling specifications.
It returns whatever @var{command} returns.  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.  If @var{command}
is a symbol, then @code{call-interactively} uses its function definition.

@cindex record command history
If @var{record-flag} is non-@code{nil}, 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}.

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
@cindex keyboard macro execution
This function executes @var{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}
and @var{keys}.

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.

The argument @var{special}, if given, means to ignore the prefix
argument and not clear it.  This is used for executing special events
(@pxref{Special Events}).
@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 3)
---------- Buffer: Minibuffer ----------
3 M-x forward-word RET
---------- Buffer: Minibuffer ----------
     @result{} t
@end group
@end example
@end deffn

@node Distinguish Interactive
@section Distinguish Interactive Calls

  Sometimes a command should display additional visual feedback (such
as an informative message in the echo area) for interactive calls
only.  There are three ways to do this.  The recommended way to test
whether the function was called using @code{call-interactively} is to
give it an optional argument @code{print-message} and use the
@code{interactive} spec to make it non-@code{nil} in interactive
calls.  Here's an example:

@example
(defun foo (&optional print-message)
  (interactive "p")
  (when print-message
    (message "foo")))
@end example

@noindent
We use @code{"p"} because the numeric prefix argument is never
@code{nil}.  Defined in this way, the function does display the
message when called from a keyboard macro.

  The above method with the additional argument is usually best,
because it allows callers to say ``treat this call as interactive.''
But you can also do the job in a simpler way by testing
@code{called-interactively-p}.

@defun called-interactively-p
This function returns @code{t} when the calling function was called
using @code{call-interactively}.

If the containing function was called by Lisp evaluation (or with
@code{apply} or @code{funcall}), then it was not called interactively.
@end defun

   Here's an example of using @code{called-interactively-p}:

@example
@group
(defun foo ()
  (interactive)
  (when (called-interactively-p)
    (message "foo"))
  'haha)
     @result{} foo
@end group

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

@group
(foo)
     @result{} haha
@end group
@end example

  Here is another example that contrasts direct and indirect
calls to @code{called-interactively-p}.

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

@group
;; @r{Type @kbd{M-x bar}.}
;; @r{This does not display a message.}
@end group

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

  If you want to treat commands run in keyboard macros just like calls
from Lisp programs, test @code{interactive-p} instead of
@code{called-interactively-p}.

@defun interactive-p
This function returns @code{t} if the containing function (the one
whose code includes the call to @code{interactive-p}) was called in
direct response to user input.  This means that it was called with the
function @code{call-interactively}, and that a keyboard macro is
not running, and that Emacs is not running in batch mode.
@end defun

@node Command Loop Info
@comment  node-name,  next,  previous,  up
@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.  With the exception of
@code{this-command} and @code{last-command} it's generally a bad idea to
change any of these variables in a Lisp program.

@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 has specified a prefix
argument for the following command.

This variable is always local to the current terminal and cannot be
buffer-local.  @xref{Multiple Displays}.
@end defvar

@defvar real-last-command
This variable is set up by Emacs just like @code{last-command},
but never altered by Lisp programs.
@end defvar

@defvar last-repeatable-command
This variable stores the most recently executed command that was not
part of an input event.  This is the command @code{repeat} will try to
repeat, @xref{Repeating,,, emacs, The GNU Emacs Manual}.
@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 specified 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

@noindent
We do not bind @code{this-command} with @code{let} because that would
restore the old value in case of error---a feature of @code{let} which
in this case does precisely what we want to avoid.

@defvar this-original-command
This has the same value as @code{this-command} except when command
remapping occurs (@pxref{Remapping Commands}).  In that case,
@code{this-command} gives the command actually run (the result of
remapping), and @code{this-original-command} gives the command that
was specified to run but remapped into another command.
@end defvar

@defun 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.  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
(this-command-keys)
;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
     @result{} "^U^X^E"
@end group
@end example
@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

@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
non-@code{nil}, it also empties the records that the function
@code{recent-keys} (@pxref{Recording Input}) will subsequently return.
This is useful after reading a password, to prevent the password from
echoing inadvertently as part of the next command in certain cases.
@end defun

@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 for telling @code{x-popup-menu} where to pop
up a menu.  It is also used internally by @code{y-or-n-p}
(@pxref{Yes-or-No Queries}).
@end defvar

@defvar last-command-event
@defvarx last-command-char
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.

@example
@group
last-command-event
;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
     @result{} 5
@end group
@end example

@noindent
The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.

The alias @code{last-command-char} exists for compatibility with
Emacs version 18.
@end defvar

@c Emacs 19 feature
@defvar last-event-frame
This variable records which frame the last input event was directed to.
Usually this is the frame that was selected when the event was
generated, but if that frame has redirected input focus to another
frame, the value is the frame to which the event was redirected.
@xref{Input Focus}.

If the last event came from a keyboard macro, the value is @code{macro}.
@end defvar

@node Adjusting Point
@section Adjusting Point After Commands
@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
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
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 Input Events
@section Input Events
@cindex events
@cindex input events

The Emacs command loop reads a sequence of @dfn{input events} that
represent keyboard or mouse activity.  The events for keyboard activity
are characters or symbols; mouse events are always lists.  This section
describes the representation and meaning of input events in detail.

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

Note that any symbol might be used as an event or an event type.
@code{eventp} cannot distinguish whether a symbol is intended by Lisp
code to be used as an event.  Instead, it distinguishes whether the
symbol has actually been used in an event that has been read as input in
the current Emacs session.  If a symbol has not yet been so used,
@code{eventp} returns @code{nil}.
@end defun

@menu
* Keyboard Events::             Ordinary characters--keys with symbols on them.
* Function Keys::               Function keys--keys with names, not symbols.
* Mouse Events::                Overview of mouse events.
* Click Events::                Pushing and releasing a mouse button.
* Drag Events::                 Moving the mouse before releasing the button.
* Button-Down Events::          A button was pushed and not yet released.
* Repeat Events::               Double and triple click (or drag, or down).
* Motion Events::               Just moving the mouse, not pushing a button.
* Focus Events::                Moving the mouse between frames.
* Misc Events::                 Other events the system can generate.
* Event Examples::              Examples of the lists for mouse events.
* Classifying Events::          Finding the modifier keys in an event symbol.
                                Event types.
* Accessing Mouse::             Functions to extract info from mouse events.
* Accessing Scroll::            Functions to get info from scroll bar events.
* Strings of Events::           Special considerations for putting
                                  keyboard character events in a string.
@end menu

@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
events they generate are represented in Lisp as characters.  The event
type of a character event is the character itself (an integer); see
@ref{Classifying Events}.

@cindex modifier bits (of input character)
@cindex basic code (of input character)
An input character event consists of a @dfn{basic code} between 0 and
524287, plus any or all of these @dfn{modifier bits}:

@table @asis
@item meta
The
@tex
@math{2^{27}}
@end tex
@ifnottex
2**27
@end ifnottex
bit in the character code indicates a character
typed with the meta key held down.

@item control
The
@tex
@math{2^{26}}
@end tex
@ifnottex
2**26
@end ifnottex
bit in the character code indicates a non-@acronym{ASCII}
control character.

@sc{ascii} control characters such as @kbd{C-a} have special basic
codes of their own, so Emacs needs no special bit to indicate them.
Thus, the code for @kbd{C-a} is just 1.

But if you type a control combination not in @acronym{ASCII}, such as
@kbd{%} with the control key, the numeric value you get is the code
for @kbd{%} plus
@tex
@math{2^{26}}
@end tex
@ifnottex
2**26
@end ifnottex
(assuming the terminal supports non-@acronym{ASCII}
control characters).

@item shift
The
@tex
@math{2^{25}}
@end tex
@ifnottex
2**25
@end ifnottex
bit in the character code indicates an @acronym{ASCII} control
character typed with the shift key held down.

For letters, the basic code itself indicates upper versus lower case;
for digits and punctuation, the shift key selects an entirely different
character with a different basic code.  In order to keep within the
@acronym{ASCII} character set whenever possible, Emacs avoids using the
@tex
@math{2^{25}}
@end tex
@ifnottex
2**25
@end ifnottex
bit for those characters.

However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
@kbd{C-a}, so Emacs uses the
@tex
@math{2^{25}}
@end tex
@ifnottex
2**25
@end ifnottex
bit in @kbd{C-A} and not in
@kbd{C-a}.

@item hyper
The
@tex
@math{2^{24}}
@end tex
@ifnottex
2**24
@end ifnottex
bit in the character code indicates a character
typed with the hyper key held down.

@item super
The
@tex
@math{2^{23}}
@end tex
@ifnottex
2**23
@end ifnottex
bit in the character code indicates a character
typed with the super key held down.

@item alt
The
@tex
@math{2^{22}}
@end tex
@ifnottex
2**22
@end ifnottex
bit in the character code indicates a character typed with
the alt key held down.  (On some terminals, the key labeled @key{ALT}
is actually the meta key.)
@end table

  It is best to avoid mentioning specific bit numbers in your program.
To test the modifier bits of a character, use the function
@code{event-modifiers} (@pxref{Classifying Events}).  When making key
bindings, you can use the read syntax for characters with modifier bits
(@samp{\C-}, @samp{\M-}, and so on).  For making key bindings with
@code{define-key}, you can use lists such as @code{(control hyper ?x)} to
specify the characters (@pxref{Changing Key Bindings}).  The function
@code{event-convert-list} converts such a list into an event type
(@pxref{Classifying Events}).

@node Function Keys
@subsection Function Keys

@cindex function keys
Most keyboards also have @dfn{function keys}---keys that have names or
symbols that are not characters.  Function keys are represented in Emacs
Lisp as symbols; the symbol's name is the function key's label, in lower
case.  For example, pressing a key labeled @key{F1} places the symbol
@code{f1} in the input stream.

The event type of a function key event is the event symbol itself.
@xref{Classifying Events}.

Here are a few special cases in the symbol-naming convention for
function keys:

@table @asis
@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
These keys correspond to common @acronym{ASCII} control characters that have
special keys on most keyboards.

In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character.  If the
terminal can distinguish between them, Emacs conveys the distinction to
Lisp programs by representing the former as the integer 9, and the
latter as the symbol @code{tab}.

Most of the time, it's not useful to distinguish the two.  So normally
@code{function-key-map} (@pxref{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
these events into characters.

In @acronym{ASCII}, @key{BS} is really @kbd{C-h}.  But @code{backspace}
converts into the character code 127 (@key{DEL}), not into code 8
(@key{BS}).  This is what most users prefer.

@item @code{left}, @code{up}, @code{right}, @code{down}
Cursor arrow keys
@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
Keypad keys (to the right of the regular keyboard).
@item @code{kp-0}, @code{kp-1}, @dots{}
Keypad keys with digits.
@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
Keypad PF keys.
@item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
Keypad arrow keys.  Emacs normally translates these into the
corresponding non-keypad keys @code{home}, @code{left}, @dots{}
@item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
Additional keypad duplicates of keys ordinarily found elsewhere.  Emacs
normally translates these into the like-named non-keypad keys.
@end table

You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
@key{META}, @key{SHIFT}, and @key{SUPER} with function keys.  The way to
represent them is with prefixes in the symbol name:

@table @samp
@item A-
The alt modifier.
@item C-
The control modifier.
@item H-
The hyper modifier.
@item M-
The meta modifier.
@item S-
The shift modifier.
@item s-
The super modifier.
@end table

Thus, the symbol for the key @key{F3} with @key{META} held down is
@code{M-f3}.  When you use more than one prefix, we recommend you
write them in alphabetical order; but the order does not matter in
arguments to the key-binding lookup and modification functions.

@node Mouse Events
@subsection Mouse Events

Emacs supports four kinds of mouse events: click events, drag events,
button-down events, and motion events.  All mouse events are represented
as lists.  The @sc{car} of the list is the event type; this says which
mouse button was involved, and which modifier keys were used with it.
The event type can also distinguish double or triple button presses
(@pxref{Repeat Events}).  The rest of the list elements give position
and time information.

For key lookup, only the event type matters: two events of the same type
necessarily run the same command.  The command can access the full
values of these events using the @samp{e} interactive code.
@xref{Interactive Codes}.

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.

@node Click Events
@subsection Click Events
@cindex click event
@cindex mouse click event

When the user presses a mouse button and releases it at the same
location, that generates a @dfn{click} event.  All mouse click event
share the same format:

@example
(@var{event-type} @var{position} @var{click-count})
@end example

@table @asis
@item @var{event-type}
This is a symbol that indicates which mouse button was used.  It is
one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the
buttons are numbered left to right.

You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-},
@samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift
and super, just as you would with function keys.

This symbol also serves as the event type of the event.  Key bindings
describe events by their types; thus, if there is a key binding for
@code{mouse-1}, that binding would apply to all events whose
@var{event-type} is @code{mouse-1}.

@item @var{position}
This is the position where the mouse click occurred.  The actual
format of @var{position} depends on what part of a window was clicked
on.  The various formats are described below.

@item @var{click-count}
This is the number of rapid repeated presses so far of the same mouse
button.  @xref{Repeat Events}.
@end table

For mouse click events in the text area, mode line, header line, or in
the marginal areas, @var{position} has this form: