@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
@subsection Using @code{interactive}
This section describes how to write the @code{interactive} form that
-makes a Lisp function an interactively-callable command.
+makes a Lisp function an interactively-callable command, and how to
+examine a commands's @code{interactive} form.
@defspec interactive arg-descriptor
@cindex argument descriptors
@end group
@end smallexample
-@cindex @samp{*} in interactive
+@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 interactive
+@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
@samp{@@}).
@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 a command (@pxref{Interactive Call}), the value is a
+list of the form @code{(interactive @var{spec})}, where @var{spec} is
+the descriptor specification used by the command's @code{interactive}
+form to compute the function's arguments (@pxref{Using Interactive}).
+If @var{function} is not a command, @code{interactive-form} returns
+@code{nil}.
+@end defun
+
@node Interactive Codes
@comment node-name, next, previous, up
@subsection Code Characters for @code{interactive}
@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
@tindex clear-this-command-keys
@defun clear-this-command-keys
This function empties out the table of events for
-@code{this-command-keys} to return. This is useful after reading a
-password, to prevent the password from echoing inadvertently as part of
-the next command in certain cases.
+@code{this-command-keys} to return, and 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
@tex
@math{2^{27}}
@end tex
-@ifinfo
+@ifnottex
2**27
-@end ifinfo
+@end ifnottex
bit in the character code indicates a character
typed with the meta key held down.
@tex
@math{2^{26}}
@end tex
-@ifinfo
+@ifnottex
2**26
-@end ifinfo
+@end ifnottex
bit in the character code indicates a non-@sc{ascii}
control character.
@tex
@math{2^{26}}
@end tex
-@ifinfo
+@ifnottex
2**26
-@end ifinfo
+@end ifnottex
(assuming the terminal supports non-@sc{ascii}
control characters).
@tex
@math{2^{25}}
@end tex
-@ifinfo
+@ifnottex
2**25
-@end ifinfo
+@end ifnottex
bit in the character code indicates an @sc{ascii} control
character typed with the shift key held down.
@tex
@math{2^{25}}
@end tex
-@ifinfo
+@ifnottex
2**25
-@end ifinfo
+@end ifnottex
bit for those characters.
However, @sc{ascii} provides no way to distinguish @kbd{C-A} from
@tex
@math{2^{25}}
@end tex
-@ifinfo
+@ifnottex
2**25
-@end ifinfo
+@end ifnottex
bit in @kbd{C-A} and not in
@kbd{C-a}.
@tex
@math{2^{24}}
@end tex
-@ifinfo
+@ifnottex
2**24
-@end ifinfo
+@end ifnottex
bit in the character code indicates a character
typed with the hyper key held down.
@tex
@math{2^{23}}
@end tex
-@ifinfo
+@ifnottex
2**23
-@end ifinfo
+@end ifnottex
bit in the character code indicates a character
typed with the super key held down.
@tex
@math{2^{22}}
@end tex
-@ifinfo
+@ifnottex
2**22
-@end ifinfo
+@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.)
@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
(not a repeat event), the value is 1.
@end defun
-@defvar double-click-time
+@defvar double-click-fuzz
To generate repeat events, successive mouse button presses must be at
-the same screen position, and the number of milliseconds between
+approximately the same screen position. The value of
+@code{double-click-fuzz} specifies the maximum number of pixels the
+mouse may be moved between two successive clicks to make a
+double-click.
+@end defvar
+
+@defvar double-click-time
+To generate repeat events, the number of milliseconds between
successive button presses must be less than the value of
@code{double-click-time}. Setting @code{double-click-time} to
@code{nil} disables multi-click detection entirely. Setting it to
@tex
@math{2^{27}}
@end tex
-@ifinfo
+@ifnottex
2**27
-@end ifinfo
+@end ifnottex
and such numbers cannot be included in a string.
To support programs with @samp{\M-} in string constants, there are
@tex
@math{2^{27}}
@end tex
-@ifinfo
+@ifnottex
2**27
-@end ifinfo
+@end ifnottex
to
@tex
@math{2^{27} + 127},
@end tex
-@ifinfo
+@ifnottex
2**27+127,
-@end ifinfo
+@end ifnottex
can also go in the string, but you must change their
numeric values. You must set the
@tex
@math{2^{7}}
@end tex
-@ifinfo
+@ifnottex
2**7
-@end ifinfo
+@end ifnottex
bit instead of the
@tex
@math{2^{27}}
@end tex
-@ifinfo
+@ifnottex
2**27
-@end ifinfo
+@end ifnottex
bit, resulting in a value between 128 and 255. Only a unibyte string
can include these codes.
button and modifier keys. The information about the window part is kept
elsewhere in the event---in the coordinates. But
@code{read-key-sequence} translates this information into imaginary
-``prefix keys'', all of which are symbols: @code{heder-line},
+``prefix keys'', all of which are symbols: @code{header-line},
@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
@code{vertical-line}, and @code{vertical-scroll-bar}. You can define
meanings for mouse clicks in special window parts by defining key
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
buffer-local. @xref{Multiple Displays}.
@end defvar
+@defvar kbd-macro-termination-hook
+This normal hook (@pxref{Standard Hooks}) is run when a keyboard
+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
HCoop / bpt / emacs.git / blobdiff