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
@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 @code{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
@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.
The generated event has this form:
@example
- (help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos})
+(help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos})
@end example
@noindent
@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.
+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.
+
+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 example below, the prompt @samp{?} is displayed in the echo area,
and the user types @kbd{C-x C-f}.
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}.