@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
The editor command loop runs this normal hook before each command. At
that time, @code{this-command} contains the command that is about to
run, and @code{last-command} describes the previous command.
-@xref{Hooks}.
+@xref{Command Loop Info}.
@end defvar
@defvar post-command-hook
The editor command loop runs this normal hook after each command
(including commands terminated prematurely by quitting or by errors),
and also when the command loop is first entered. At that time,
-@code{this-command} describes the command that just ran, and
-@code{last-command} describes the command before that. @xref{Hooks}.
+@code{this-command} refers to the command that just ran, and
+@code{last-command} refers to the command before that.
@end defvar
Quitting is suppressed while running @code{pre-command-hook} and
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
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}).
+@cindex argument evaluation form
+
+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
@end itemize
@cindex examining the @code{interactive} form
@item F
A file name. The file need not exist. Completion, Default, Prompt.
+@item G
+A file name. The file need not exist. If the user enters just a
+directory name, then the value is just that directory name, with no
+file name within the directory added. Completion, Default, Prompt.
+
@item i
An irrelevant argument. This code always supplies @code{nil} as
the argument's value. No I/O.
maps. The key sequence argument is represented as a string or vector.
The cursor does not move into the echo area. Prompt.
-If the key sequence is a down-event, the following up-event is discarded,
-but can be read via the @code{U} code character.
+If @samp{k} reads a key sequence that ends with a down-event, it also
+reads and discards the following up-event. You can get access to that
+up-event with the @samp{U} code character.
This kind of input is used by commands such as @code{describe-key} and
@code{global-set-key}.
parentheses and brackets) do not do so here. Prompt.
@item U
-A key sequence or nil. May be used after a @code{k} or @code{K}
-argument to get the up-event that was discarded in case the key
-sequence read for that argument was a down-event. No I/O.
+A key sequence or @code{nil}. Can be used after a @samp{k} or
+@samp{K} argument to get the up-event that was discarded (if any)
+after @samp{k} or @samp{K} read a down-event. If no up-event has been
+discarded, @samp{U} provides @code{nil} as the argument. No I/O.
@item v
A variable declared to be a user option (i.e., satisfying the
@item X
@cindex evaluated expression argument
-A Lisp form is read as with @kbd{x}, but then evaluated so that its
-value becomes the argument for the command. Prompt.
+A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates
+the form so that its value becomes the argument for the command.
+Prompt.
@item z
A coding system name (a symbol). If the user enters null input, the
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.
+not running, and that Emacs is not running in batch mode.
If the containing function was called by Lisp evaluation (or with
@code{apply} or @code{funcall}), then it was not called interactively.
from a keyboard macro. We use @code{"p"} because the numeric prefix
argument is never @code{nil}.
+@defun called-interactively-p
+This function returns @code{t} when the calling function was called
+using @code{call-interactively}.
+
+When possible, instead of using this function, you should use the
+method in the example above; that method makes it possible for a
+caller to ``pretend'' that the function was called interactively.
+@end defun
+
@node Command Loop Info
@comment node-name, next, previous, up
@section Information from the Command Loop
@node Adjusting Point
@section Adjusting Point After Commands
- It is not easy to display a value of point in the middle of a sequence
-of text that has the @code{display} or @code{composition} property. So
-after a command finishes and returns to the command loop, if point is
-within such a sequence, the command loop normally moves point to the
-edge of the sequence.
+ It is not easy to display a value of point in the middle of a
+sequence of text that has the @code{display}, @code{composition} or
+@code{intangible} property, or is invisible. Therefore, after a
+command finishes and returns to the command loop, if point is within
+such a sequence, the command loop normally moves point to the edge of
+the sequence.
A command can inhibit this feature by setting the variable
@code{disable-point-adjustment}:
@defvar disable-point-adjustment
@tindex disable-point-adjustment
-If this variable is non-@code{nil} when a command returns to the command
-loop, then the command loop does not check for text properties such as
-@code{display} and @code{composition}, and does not move point out of
-sequences that have these properties.
+If this variable is non-@code{nil} when a command returns to the
+command loop, then the command loop does not check for those text
+properties, and does not move point out of sequences that have them.
The command loop sets this variable to @code{nil} before each command,
so if a command sets it, the effect applies only to that command.
This kind of event is generated, at present, only on some kinds of
systems.
+@cindex @code{help-echo} event
+@item help-echo
+This kind of event is generated when a mouse pointer moves onto a
+portion of buffer text which has a @code{help-echo} text property.
+The generated event has this form:
+
+@example
+(help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos})
+@end example
+
+@noindent
+The precise meaning of the event parameters and the way these
+parameters are used to display the help-echo text are described in
+@ref{Text help-echo}.
+
@cindex @code{usr1-signal} event
@cindex @code{usr2-signal} event
@item usr1-signal
@defun posn-area position
Return the window area recorded in @var{position}. It returns @code{nil}
when the event occurred in the text area of the window; otherwise, it
-is a symbol identifying the area in which the the event occurred.
+is a symbol identifying the area in which the event occurred.
@end defun
@defun posn-point position
@var{window}.
@end defun
-@defun posn-at-x-y x y &optional frame-or-window
+@defun posn-at-x-y x y &optional frame-or-window whole
This function returns position information corresponding to pixel
coordinates @var{x} and @var{y} in a specified frame or window,
@var{frame-or-window}, which defaults to the selected window.
The coordinates @var{x} and @var{y} are relative to the
frame or window used.
+If @var{whole} is @code{nil}, the coordinates are relative
+to the window text area, otherwise they are relative to
+the entire window area including scroll bars, margins and fringes.
@end defun
These functions are useful for decoding scroll bar events.
@code{read-key-sequence}. Lisp programs can also call this function;
for example, @code{describe-key} uses it to read the key to describe.
-@defun read-key-sequence prompt
+@defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
@cindex key sequence
This function reads a key sequence and returns it as a string or
vector. It keeps reading events until it has accumulated a complete key
events---characters, symbols, and lists. The elements of the string or
vector are the events in the key sequence.
-The argument @var{prompt} is either a string to be displayed in the echo
-area as a prompt, or @code{nil}, meaning not to display a prompt.
+Reading a key sequence includes translating the events in various
+ways. @xref{Translating Input}.
+
+The argument @var{prompt} is either a string to be displayed in the
+echo area as a prompt, or @code{nil}, meaning not to display a prompt.
+The argument @var{continue-echo}, if non-@code{nil}, means to echo
+this key as a continuation of the previous key.
+
+Normally any upper case event is converted to lower case if the
+original event is undefined and the lower case equivalent is defined.
+The argument @var{dont-downcase-last}, if non-@code{nil}, means do not
+convert the last event to lower case. This is appropriate for reading
+a key sequence to be defined.
-In the example below, the prompt @samp{?} is displayed in the echo area,
-and the user types @kbd{C-x C-f}.
+The argument @var{switch-frame-ok}, if non-@code{nil}, means that this
+function should process a @code{switch-frame} event if the user
+switches frames before typing anything. If the user switches frames
+in the middle of a key sequence, or at the start of the sequence but
+@var{switch-frame-ok} is @code{nil}, then the event will be put off
+until after the current key sequence.
+
+The argument @var{command-loop}, if non-@code{nil}, means that this
+key sequence is being read by something that will read commands one
+after another. It should be @code{nil} if the caller will read just
+one key sequence.
+
+In the following example, Emacs displays the prompt @samp{?} in the
+echo area, and then the user types @kbd{C-x C-f}.
@example
(read-key-sequence "?")
and does not set @code{quit-flag}. @xref{Quitting}.
@end defun
-@defun read-key-sequence-vector prompt
+@defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
This is like @code{read-key-sequence} except that it always
returns the key sequence as a vector, never as a string.
@xref{Strings of Events}.
and key sequences read from keyboard macros being executed.
@end defvar
-@defvar num-nonmacro-input-events
-This variable holds the total number of input events received so far
-from the terminal---not counting those generated by keyboard macros.
-@end defvar
-
@node Reading One Event
@subsection Reading One Event
@cindex reading a single event
gets a character. The arguments work as in @code{read-event}.
@end defun
+@defvar num-nonmacro-input-events
+This variable holds the total number of input events received so far
+from the terminal---not counting those generated by keyboard macros.
+@end defvar
+
@node Invoking the Input Method
@subsection Invoking the Input Method
Emacs version 18.
@end defvar
+@defmac while-no-input body@dots{}
+This construct runs the @var{body} forms and returns the value of the
+last one---but only if no input arrives. If any input arrives during
+the execution of the @var{body} forms, it aborts them (working much
+like a quit). The @code{while-no-input} form returns @code{nil} if
+aborted by a real quit, and returns @code{t} if aborted by arrival of
+other input.
+
+If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil},
+arrival of input during those parts won't cause an abort until
+the end of that part.
+
+If you want to be able to distingish all possible values computed
+by @var{body} from both kinds of abort conditions, write the code
+like this:
+
+@example
+(while-no-input
+ (list
+ (progn . @var{body})))
+@end example
+@end defmac
+
@defun discard-input
@cindex flush input
@cindex discard input
non-@code{nil}, then @code{quit-flag} has no special effect.
@end defvar
-@defmac with-local-quit forms@dots{}
-This macro executes @var{forms} in sequence, but allows quitting, at
+@defmac with-local-quit body@dots{}
+This macro executes @var{body} forms in sequence, but allows quitting, at
least locally, within @var{body} even if @code{inhibit-quit} was
non-@code{nil} outside this construct. It returns the value of the
-last form in @var{forms}.
+last form in @var{body}, unless exited by quitting, in which case
+it returns @code{nil}.
If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit},
-it only executes the @var{forms}, and setting @code{quit-flag} causes
+it only executes the @var{body}, and setting @code{quit-flag} causes
a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so
that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag}
triggers a special kind of local quit. This ends the execution of
-@var{forms} and exits the @code{with-local-quit} form with
+@var{body} and exits the @code{with-local-quit} body with
@code{quit-flag} still non-@code{nil}, so that another (ordinary) quit
will happen as soon as that is allowed. If @code{quit-flag} is
-already non-@code{nil} at the beginning of @var{forms}, the local quit
-happens immediately and they don't execute at all.
+already non-@code{nil} at the beginning of @var{body}, the local quit
+happens immediately and the body doesn't execute at all.
This macro is mainly useful in functions that can be called from
-timers, @code{pre-command-hook}, @code{post-command-hook} and other
-places where @code{inhibit-quit} is normally bound to @code{t}.
+timers, process filters, process sentinels, @code{pre-command-hook},
+@code{post-command-hook}, and other places where @code{inhibit-quit} is
+normally bound to @code{t}.
@end defmac
@deffn Command keyboard-quit
commands.
Normally, commands specify which representation to use for the prefix
-argument, either numeric or raw, in the @code{interactive} declaration.
+argument, either numeric or raw, in the @code{interactive} specification.
(@xref{Using Interactive}.) Alternatively, functions may look at the
value of the prefix argument directly in the variable
@code{current-prefix-arg}, but this is less clean.
@defvar defining-kbd-macro
This variable is non-@code{nil} if and only if a keyboard macro is
being defined. A command can test this variable so as 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.
+differently while a macro is being defined. The value is
+@code{append} while appending to the definition of an existing macro.
+The commands @code{start-kbd-macro}, @code{kmacro-start-macro} and
+@code{end-kbd-macro} set this variable---do not set it yourself.
The variable is always local to the current terminal and cannot be
buffer-local. @xref{Multiple Displays}.