@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
-@c Free Software Foundation, Inc.
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
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.
+are done, and the subroutines that allow Lisp programs to do them.
@menu
* Command Overview:: How the command loop reads commands.
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
@comment node-name, next, previous, up
@subsection Examples of Using @code{interactive}
@cindex examples of using @code{interactive}
-@cindex @code{interactive}, examples of using
+@cindex @code{interactive}, examples of using
Here are some examples of @code{interactive}:
@code{call-interactively}, which reads the arguments and calls the
command. You can also call these functions yourself.
-@defun commandp object
+@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}.
+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
(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}.
+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}).
-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}.
(message "foo")))
@end example
+@noindent
+Defined in this way, the function does display the message when
+called from a keyboard macro.
+
The numeric prefix argument, provided by @samp{p}, is never @code{nil}.
@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.
+records for itself and for commands that are run.
@defvar last-command
This variable records the name of the previous command executed by the
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
@example
(@var{event-type}
- (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp})
+ (@var{window} @var{buffer-pos} (@var{x} . @var{y})
+ @var{timestamp})
+ @var{click-count})
+@end example
+
+or, for clicks on strings in the mode line, header line or marginal
+areas:
+
+@example
+(@var{event-type}
+ (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp} (@var{string} . @var{string-pos})
@var{click-count})
@end example
@item @var{timestamp}
This is the time at which the event occurred, in milliseconds. (Since
this value wraps around the entire range of Emacs Lisp integers in about
-five hours, it is useful only for relating the times of nearby events.)
+five hours, it is useful only for relating the times of nearby
+events.)
+
+@item @var{string}
+This is the string on which the click occurred, including any
+properties.
+
+@item @var{string-pos}
+This is the position in the string on which the click occurred,
+relevant if properties at the click need to be looked up.
@item @var{click-count}
This is the number of rapid repeated presses so far of the same mouse
the top or left end of the scroll bar, and @var{whole} is the length of
the entire scroll bar.
-If the position is on a mode line or the vertical line separating
-@var{window} from its neighbor to the right, then @var{buffer-pos} is
-the symbol @code{mode-line}, @code{header-line}, or
-@code{vertical-line}. For the mode line, @var{y} does not have
+If the position is on a mode line, the vertical line separating
+@var{window} from its neighbor to the right, or in a marginal area,
+then @var{buffer-pos} is the symbol @code{mode-line},
+@code{header-line}, @code{vertical-line}, @code{left-margin}, or
+@code{right-margin}. For the mode line, @var{y} does not have
meaningful data. For the vertical line, @var{x} does not have
meaningful data.
@key{meta} held down comes to the Lisp program as
@code{M-double-mouse-2}. If a double-click event has no binding, the
binding of the corresponding ordinary click event is used to execute
-it. Thus, you need not pay attention to the double click feature
+it. Thus, you need not pay attention to the double click feature
unless you really want to.
When the user performs a double click, Emacs generates first an ordinary
If this is non-@code{nil}, its value specifies the current input method
function.
-@strong{Note:} Don't bind this variable with @code{let}. It is often
+@strong{Warning:} don't bind this variable with @code{let}. It is often
buffer-local, and if you bind it around reading input (which is exactly
when you @emph{would} bind it), switching buffers asynchronously while
Emacs is waiting will cause the value to be restored in the wrong
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
+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.
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
+finishes sleeping, @code{discard-input} discards any characters typed
during the sleep.
@example
input comes in, while @code{sleep-for} pauses without updating the
screen.
-@defun sit-for seconds &optional millisec nodisp
+@defun sit-for seconds &optional nodisp
This function performs redisplay (provided there is no pending input
from the user), then waits @var{seconds} seconds, or until input is
available. The value is @code{t} if @code{sit-for} waited the full
-time with no input arriving (see @code{input-pending-p} in @ref{Event
+time with no input arriving (see @code{input-pending-p} in @ref{Event
Input Misc}). Otherwise, the value is @code{nil}.
The argument @var{seconds} need not be an integer. If it is a floating
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}.
-
The expression @code{(sit-for 0)} is a convenient way to request a
redisplay, without any delay. @xref{Forcing Redisplay}.
The usual purpose of @code{sit-for} is to give the user time to read
text that you display.
+
+It is also possible to call @code{sit-for} with three arguments,
+as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})},
+but that is considered obsolete.
@end defun
@defun sleep-for seconds &optional millisec
@section Quitting
@cindex @kbd{C-g}
@cindex quitting
+@cindex interrupt Lisp functions
Typing @kbd{C-g} while a Lisp function is running causes Emacs to
@dfn{quit} whatever it is doing. This means that control returns to the
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 Emacs's
-internal state. Because quitting is delayed until a safe place, quitting
+internal state. Because quitting is delayed until a safe place, quitting
cannot make Emacs crash.
Certain functions such as @code{read-key-sequence} or
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}.
+to quote a @kbd{C-g}.
+@cindex prevent quitting
You can prevent quitting for a portion of a Lisp function by binding
the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
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
M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
-C-u - M-x display-prefix @print{} -
+C-u - M-x display-prefix @print{} -
M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
-C-u - 7 M-x display-prefix @print{} -7
+C-u - 7 M-x display-prefix @print{} -7
M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
@end example
@deffn Command exit-recursive-edit
This function exits from the innermost recursive edit (including
minibuffer input). Its definition is effectively @code{(throw 'exit
-nil)}.
+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}
+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
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 when it
-reaches the maximum size (specified by the variable
-@code{history-length}), the oldest elements are deleted as new ones are
-added.
+reaches the maximum size (@pxref{Minibuffer History}), the oldest
+elements are deleted as new ones are added.
@example
@group
The argument @var{count} is a repeat count; @var{kbdmacro} is executed that
many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is
executed once. If it is 0, @var{kbdmacro} is executed over and over until it
-encounters an error or a failing search.
+encounters an error or a failing search.
@xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
@end defun
macro terminates, regardless of what caused it to terminate (reaching
the macro end or an error which ended the macro prematurely).
@end defvar
+
+@ignore
+ arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1
+@end ignore