@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
+@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.
* Defining Commands:: Specifying how a function should read arguments.
* Interactive Call:: Calling a command, so that it will read arguments.
* 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.
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{Peeking and Discarding}).
+(@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 is used instead. This is done by the command
+command, which it then calls. This is done by the command
@code{execute-extended-command} (@pxref{Interactive Call}).
- Once the command is chosen, it must be executed, which includes
-reading arguments to be given to 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.
+ 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}).
- If a command runs away, typing @kbd{C-g} terminates its execution
-immediately. This is called @dfn{quitting} (@pxref{Quitting}).
+ 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.
+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}.
@end defvar
@defvar post-command-hook
-The editor command loop runs this normal hook after each command,
-and also when the command loop is entered, or reentered after
-an error or quit.
+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}.
@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 interactive function
A Lisp function becomes a command when its body contains, at top
-level, a form which calls the special form @code{interactive}. This
+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.
@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 command's @code{interactive} form.
@defspec interactive arg-descriptor
@cindex argument descriptors
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 the way the arguments to the command are
-to be computed when the command is called interactively.
+@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 arguments are supplied by the caller and @var{arg-descriptor}
-has no effect.
+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
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
@c Emacs 19 feature
The prompt string can use @samp{%} to include previous argument values
-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:
+(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
@end group
@end smallexample
-@cindex @samp{*} in interactive
-@kindex buffer-read-only
+@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 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}
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.
sequence that invoked this command. Special.
@item a
-A function name (i.e., a symbol which is @code{fboundp}). Existing,
+A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
Completion, Prompt.
@item b
@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,
-Prompt.
+Default, Prompt.
@item c
A character. The cursor does not move into the echo area. Prompt.
@item d
@cindex position argument
-The position of point as a number (@pxref{Point}). No I/O.
+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{System Environment}).
+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 which are lists, so you can look at
+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 which invoked the command has
-@var{n} events with parameters, the @var{n}th @samp{e} provides the
-@var{n}th list event. Events which are not lists, such as function keys
-and @sc{ASCII} characters, do not count where @samp{e} is concerned.
-
-Even though @samp{e} does not use a prompt string, you must follow
-it with a newline if it is not the last code character.
+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
@item F
A file name. The file need not exist. 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{Keymap Terminology}). 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 the key sequence is a down-event, the following up-event is discarded,
+but can be read via the @code{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 a number. No I/O.
+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 is asked to try again. The prefix argument, if any, is not used.
+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
-@cindex raw prefix argument usage
-The raw prefix argument. If the prefix argument is @code{nil}, then a
-number is read as with @kbd{n}. Requires a number. Prompt.
+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.@refill
+No I/O.
@item P
-The raw prefix argument. (Note that this @samp{P} is upper case.)
-@xref{Prefix Command Arguments}. No I/O.@refill
+@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
@item s
Arbitrary text, read in the minibuffer and returned as a string
(@pxref{Text from Minibuffer}). Terminate the input with either
-@key{LFD} or @key{RET}. (@kbd{C-q} may be used to include either of
+@kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of
these characters in the input.) Prompt.
@item S
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 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.
+
@item v
-A variable declared to be a user option (i.e., satisfying the predicate
-@code{user-variable-p}). @xref{High-Level Completion}. Existing,
+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 in printed representation, terminated with a
-@key{LFD} or @key{RET}. The object is not evaluated. @xref{Object from
+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 is read as with @kbd{x}, but then evaluated 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
+@cindex @code{interactive}, examples of using
Here are some examples of @code{interactive}:
@section Interactive Call
@cindex interactive call
- After the command loop has translated a key sequence into a
-definition, it invokes that definition using the function
-@code{command-execute}. If the definition is a function that is a
-command, @code{command-execute} calls @code{call-interactively}, which
-reads the arguments and calls the command. You can also call these
-functions yourself.
+ 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
+@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
-@code{interactive}, byte-code function objects, autoload objects that
-are declared as interactive (non-@code{nil} fourth argument to
-@code{autoload}), and some of the primitive functions.
+@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 is @code{commandp} if its function definition is
-@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}.
@end defun
-@defun call-interactively command &optional record-flag
+@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.
-An error is signaled if @var{command} cannot be called interactively
-(i.e., it is not a command). Note that keyboard macros (strings and
-vectors) are not accepted, even though they are considered commands.
+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, 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 return value of
+@code{this-command-keys} is used. @xref{Definition of this-command-keys}.
@end defun
-@defun command-execute command &optional record-flag
+@defun command-execute command &optional record-flag keys special
@cindex keyboard macro execution
-This function executes @var{command} as an editing command. The
-argument @var{command} must satisfy the @code{commandp} predicate; i.e.,
-it must be an interactively callable function or a string.
+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}.
+@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
command returns becomes the value of @code{execute-extended-command}.
@cindex execute with prefix argument
-If the command asks for a prefix argument, the value
-@var{prefix-argument} is supplied. If @code{execute-extended-command}
-is called interactively, the current raw prefix argument is used for
+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?
@group
(execute-extended-command 1)
---------- Buffer: Minibuffer ----------
-M-x forward-word RET
+1 M-x forward-word RET
---------- Buffer: Minibuffer ----------
@result{} t
@end group
@end deffn
@defun interactive-p
-This function returns @code{t} if the containing function (the one that
-called @code{interactive-p}) was called interactively, with the function
-@code{call-interactively}. (It makes no difference whether
-@code{call-interactively} was called from Lisp or directly from the
-editor command loop.) Note that if the containing function was called
-by Lisp evaluation (or with @code{apply} or @code{funcall}), then it was
-not called interactively.
-
-The usual application of @code{interactive-p} is for deciding whether to
-print an informative message. As a special exception,
-@code{interactive-p} returns @code{nil} whenever a keyboard macro is
-being run. This is to suppress the informative messages and speed
-execution of the macro.
-
-For example:
+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.
+
+If the containing function was called by Lisp evaluation (or with
+@code{apply} or @code{funcall}), then it was not called interactively.
+@end defun
+
+ The most common use of @code{interactive-p} is for deciding whether
+to give the user additional visual feedback (such as by printing an
+informative message). For example:
@example
@group
+;; @r{Here's the usual way to use @code{interactive-p}.}
(defun foo ()
(interactive)
- (and (interactive-p)
- (message "foo")))
+ (when (interactive-p)
+ (message "foo")))
@result{} foo
@end group
@group
+;; @r{This function is just to illustrate the behavior.}
(defun bar ()
(interactive)
(setq foobar (list (foo) (interactive-p))))
@group
;; @r{Type @kbd{M-x bar}.}
-;; @r{This does not print anything.}
+;; @r{This does not display a message.}
@end group
@group
@result{} (nil t)
@end group
@end example
+
+ If you want to test @emph{only} whether the function was called
+using @code{call-interactively}, add an optional argument
+@code{print-message} which should be non-@code{nil} in an interactive
+call, and use the @code{interactive} spec to make sure it is
+non-@code{nil}. Here's an example:
+
+@example
+(defun foo (&optional print-message)
+ (interactive "p")
+ (when print-message
+ (message "foo")))
+@end example
+
+@noindent
+Defined in this way, the function does display the message when called
+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
@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
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 set by copying the value of @code{this-command} when a
-command returns to the command loop, except when the command specifies a
-prefix argument for the following command.
+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 this-command
the editor command loop. Like @code{last-command}, it is normally a symbol
with a function definition.
-This variable is set by the command loop just before the command is run,
-and its value is copied into @code{last-command} when the command
-finishes (unless the command specifies a prefix argument for the
-following command).
+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 change the value of this variable during their execution,
-simply as a flag for whatever command runs next. In particular, the
-functions that kill 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.
+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
(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
+@anchor{Definition of 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. The value is a string
-if all those events were characters. @xref{Input Events}.
+generated the prefix argument for this command. 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 type @kbd{C-u C-x C-e}.}
+;; @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
+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
+
+@tindex clear-this-command-keys
+@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, aside from events resulting from mouse menus.
+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 to figure out a good default location to
-pop up another menu.
+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
@example
@group
-last-command-char
-;; @r{Now type @kbd{C-u C-x C-e}.}
+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 @sc{ASCII} code for @kbd{C-e}.
+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.
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
-@defvar echo-keystrokes
-This variable determines how much time should elapse before command
-characters echo. Its value must be an integer, which specifies the
-number of seconds to wait before echoing. If the user types a prefix
-key (say @kbd{C-x}) and then delays this many seconds before continuing,
-the key @kbd{C-x} is echoed in the echo area. Any subsequent characters
-in the same command will be echoed as well.
+@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.
-If the value is zero, then command input is not echoed.
+ 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.
+
+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
+@tindex 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
are characters or symbols; mouse events are always lists. This section
describes the representation and meaning of input events in detail.
-A command invoked using events that are lists can get 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.
-
@defun eventp object
-This function returns non-@code{nil} if @var{event} is an input event.
+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.
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. In Emacs
-versions 18 and earlier, characters were the only events.
+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
-255, plus any or all of these @dfn{modifier bits}:
+524287, plus any or all of these @dfn{modifier bits}:
@table @asis
@item meta
-The 2**23 bit in the character code indicates a character
+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 2**22 bit in the character code indicates a non-@sc{ASCII}
+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
+@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 @sc{ASCII}, such as
+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 2**22 (assuming the terminal supports non-@sc{ASCII}
+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 2**21 bit in the character code indicates an @sc{ASCII} control
+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 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 @sc{ASCII} character set whenever possible, Emacs avoids using
-the 2**21 bit for those characters.
-
-However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
-@kbd{C-A}, so Emacs uses the 2**21 bit in @kbd{C-A} and not in
+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 2**20 bit in the character code indicates a character
+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 2**19 bit in the character code indicates a character
+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 2**18 bit in the character code indicates a character typed with
+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
- In the future, Emacs may support a larger range of basic codes. We
-may also move the modifier bits to larger bit numbers. Therefore, you
-should avoid mentioning specific bit numbers in your program.
-Instead, the way to test the modifier bits of a character is with the
-function @code{event-modifiers} (@pxref{Classifying Events}).
+ 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 which have names or
-symbols that are not characters. Function keys are represented in Lisp
-as symbols; the symbol's name is the function key's label. For example,
-pressing a key labeled @key{F1} places the symbol @code{f1} in the input
-stream.
+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.
-For all keyboard events, the event type (which classifies the event for
-key lookup purposes) is identical to the event---it is the character or
-the symbol. @xref{Classifying Events}.
+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
+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 @sc{ASCII} control characters that have
+These keys correspond to common @acronym{ASCII} control characters that have
special keys on most keyboards.
-In @sc{ASCII}, @kbd{C-i} and @key{TAB} are the same character. Emacs
-lets you distinguish them if you wish, by returning the former as the
-integer 9, and the latter as the symbol @code{tab}.
+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} is set up to map @code{tab} into 9. Thus, a
-key binding for character code 9 also applies to @code{tab}. Likewise
-for the other symbols in this group. The function @code{read-char}
-also converts these events into characters.
+@code{function-key-map} (@pxref{Translating Input}) 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 @sc{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace}
+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{left}, @code{up}, @code{right}, @code{down}
-Cursor arrow 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{CTRL}, @key{META}, @key{HYPER},
-@key{SUPER}, @key{ALT} and @key{SHIFT} with function keys. The way
-to represent them is with prefixes in the symbol name:
+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-
@end table
Thus, the symbol for the key @key{F3} with @key{META} held down is
-@kbd{M-@key{F3}}. When you use more than one prefix, we recommend you
-write them in alphabetical order (though the order does not matter in
-arguments to the key-binding lookup and modification functions).
+@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 mouse click event
When the user presses a mouse button and releases it at the same
-location, that generates a @dfn{click} event. Mouse click events have
-this form:
+location, that generates a @dfn{click} event. All mouse click event
+share the same format:
@example
-(@var{event-type}
- (@var{window} @var{buffer-pos}
- (@var{x} . @var{y}) @var{timestamp})
- @var{click-count})
+(@var{event-type} @var{position} @var{click-count})
@end example
-Here is what the elements normally mean:
-
-@table @var
-@item event-type
+@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 numbered left to right.
+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
@code{mouse-1}, that binding would apply to all events whose
@var{event-type} is @code{mouse-1}.
-@item window
-This is the window in which the click occurred.
+@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 x
-@itemx y
-These are the pixel-based coordinates of the click, relative to the top
-left corner of @var{window}, which is @code{(0 . 0)}.
+@item @var{click-count}
+This is the number of rapid repeated presses so far of the same mouse
+button. @xref{Repeat Events}.
+@end table
-@item buffer-pos
-This is the buffer position of the character clicked on.
+For mouse click events in the text area, mode line, header line, or in
+the marginal areas, @var{position} has this form:
-@item 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.)
+@example
+(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
+ @var{object} @var{text-pos} (@var{col} . @var{row})
+ @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
+@end example
-@item click-count
-This is the number of rapid repeated presses so far of the same mouse
-button. @xref{Repeat Events}.
+@table @asis
+@item @var{window}
+This is the window in which the click occurred.
+
+@item @var{pos-or-area}
+This is the buffer position of the character clicked on in the text
+area, or if clicked outside the text area, it is the window area in
+which the click occurred. It is one of the symbols @code{mode-line},
+@code{header-line}, @code{vertical-line}, @code{left-margin},
+@code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
+
+@item @var{x}, @var{y}
+These are the pixel-denominated coordinates of the click, relative to
+the top left corner of @var{window}, which is @code{(0 . 0)}.
+For the mode or header line, @var{y} does not have meaningful data.
+For the vertical line, @var{x} does not have meaningful data.
+
+@item @var{timestamp}
+This is the time at which the event occurred, in milliseconds.
+
+@item @var{object}
+This is the object on which the click occurred. It is either
+@code{nil} if there is no string property, or it has the form
+(@var{string} . @var{string-pos}) when there is a string-type text
+property at the click position.
+
+@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{text-pos}
+For clicks on a marginal area or on a fringe, this is the buffer
+position of the first visible character in the corresponding line in
+the window. For other events, it is the current buffer position in
+the window.
+
+@item @var{col}, @var{row}
+These are the actual coordinates of the glyph under the @var{x},
+@var{y} position, possibly padded with default character width
+glyphs if @var{x} is beyond the last glyph on the line.
+
+@item @var{image}
+This is the image object on which the click occurred. It is either
+@code{nil} if there is no image at the position clicked on, or it is
+an image object as returned by @code{find-image} if click was in an image.
+
+@item @var{dx}, @var{dy}
+These are the pixel-denominated coordinates of the click, relative to
+the top left corner of @var{object}, which is @code{(0 . 0)}. If
+@var{object} is @code{nil}, the coordinates are relative to the top
+left corner of the character glyph clicked on.
@end table
-The meanings of @var{buffer-pos}, @var{row} and @var{column} are
-somewhat different when the event location is in a special part of the
-screen, such as the mode line or a scroll bar.
+For mouse clicks on a scroll-bar, @var{position} has this form:
+
+@example
+(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
+@end example
+
+@table @asis
+@item @var{window}
+This is the window whose scroll-bar was clicked on.
+
+@item @var{area}
+This is the scroll bar where the click occurred. It is one of the
+symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.
+
+@item @var{portion}
+This is the distance of the click from the top or left end of
+the scroll bar.
-If the location is in a scroll bar, then @var{buffer-pos} is the symbol
-@code{vertical-scroll-bar} or @code{horizontal-scroll-bar}, and the pair
-@code{(@var{x} . @var{y})} is replaced with a pair @code{(@var{portion}
-. @var{whole})}, where @var{portion} is the distance of the click from
-the top or left end of the scroll bar, and @var{whole} is the length of
-the entire scroll bar.
+@item @var{whole}
+This 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} or @code{vertical-line}. For the mode line,
-@var{row} does not have meaningful data. For the vertical line,
-@var{column} does not have meaningful data.
+@item @var{timestamp}
+This is the time at which the event occurred, in milliseconds.
-@var{buffer-pos} may be a list containing a symbol (one of the symbols
-listed above) instead of just the symbol. This is what happens after
-the imaginary prefix keys for these events are inserted into the input
-stream. @xref{Key Sequence Input}.
+@item @var{part}
+This is the part of the scroll-bar which was clicked on. It is one
+of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
+@code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
+@end table
+
+In one special case, @var{buffer-pos} is a list containing a symbol (one
+of the symbols listed above) instead of just the symbol. This happens
+after the imaginary prefix keys for the event are inserted into the
+input stream. @xref{Key Sequence Input}.
@node Drag Events
@subsection Drag Events
@example
(@var{event-type}
- (@var{window1} @var{buffer-pos1}
- (@var{x1} . @var{y1}) @var{timestamp1})
- (@var{window2} @var{buffer-pos2}
- (@var{x2} . @var{y2}) @var{timestamp2})
+ (@var{window1} @var{buffer-pos1} (@var{x1} . @var{y1}) @var{timestamp1})
+ (@var{window2} @var{buffer-pos2} (@var{x2} . @var{y2}) @var{timestamp2})
@var{click-count})
@end example
For a drag event, the name of the symbol @var{event-type} contains the
-prefix @samp{drag-}. The second and third elements of the event give
-the starting and ending position of the drag. Aside from that, the data
-have the same meanings as in a click event (@pxref{Click Events}). You
-can access the second element of any mouse event in the same way, with
-no need to distinguish drag events from others.
+prefix @samp{drag-}. For example, dragging the mouse with button 2 held
+down generates a @code{drag-mouse-2} event. The second and third
+elements of the event give the starting and ending position of the drag.
+Aside from that, the data have the same meanings as in a click event
+(@pxref{Click Events}). You can access the second element of any mouse
+event in the same way, with no need to distinguish drag events from
+others.
The @samp{drag-} prefix follows the modifier key prefixes such as
@samp{C-} and @samp{M-}.
-If @code{read-key-sequence} receives a drag event which has no key
+If @code{read-key-sequence} receives a drag event that has no key
binding, and the corresponding click event does have a binding, it
changes the drag event into a click event at the drag's starting
position. This means that you don't have to distinguish between click
If you want to take action as soon as a button is pressed, you need to
handle @dfn{button-down} events.@footnote{Button-down is the
-conservative antithesis of drag.}. These occur as soon as a button is
-pressed. They are represented by lists which look exactly like click
-events (@pxref{Click Events}), except that the name of @var{event-type}
-contains the prefix @samp{down-}. The @samp{down-} prefix follows the
+conservative antithesis of drag.} These occur as soon as a button is
+pressed. They are represented by lists that look exactly like click
+events (@pxref{Click Events}), except that the @var{event-type} symbol
+name contains the prefix @samp{down-}. The @samp{down-} prefix follows
modifier key prefixes such as @samp{C-} and @samp{M-}.
-The function @code{read-key-sequence}, and the Emacs command loop,
-ignore any button-down events that don't have command bindings. This
-means that you need not worry about defining button-down events unless
-you want them to do something. The usual reason to define a button-down
-event is so that you can track mouse motion (by reading motion events)
-until the button is released.
-@ifinfo
+The function @code{read-key-sequence} ignores any button-down events
+that don't have command bindings; therefore, the Emacs command loop
+ignores them too. This means that you need not worry about defining
+button-down events unless you want them to do something. The usual
+reason to define a button-down event is so that you can track mouse
+motion (by reading motion events) until the button is released.
@xref{Motion Events}.
-@end ifinfo
@node Repeat Events
@subsection Repeat Events
@cindex repeat events
@cindex double-click events
@cindex triple-click events
+@cindex mouse events, repeated
If you press the same mouse button more than once in quick succession
-without moving the mouse, Emacs uses special @dfn{repeat} mouse events
-for the second and subsequent presses.
+without moving the mouse, Emacs generates special @dfn{repeat} mouse
+events for the second and subsequent presses.
The most common repeat events are @dfn{double-click} events. Emacs
generates a double-click event when you click a button twice; the event
events).
The event type of a double-click event contains the prefix
-@code{double}. Thus, a double click on the second mouse button with
+@samp{double-}. Thus, a double click on the second mouse button with
@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
-click event, and then a double-click event. Therefore, the command
-binding of the double click event must be written to assume that the
+click event, and then a double-click event. Therefore, you must design
+the command binding of the double click event to assume that the
single-click command has already run. It must produce the desired
results of a double click, starting from the results of a single click.
-This means that it is most convenient to give double clicks a meaning
-that somehow ``builds on'' the meaning of a single click. This is what
-user interface experts recommend that double clicks should do.
+This is convenient, if the meaning of a double click somehow ``builds
+on'' the meaning of a single click---which is recommended user interface
+design practice for double clicks.
If you click a button, then press it down again and start moving the
mouse with the button held down, then you get a @dfn{double-drag} event
when you ultimately release the button. Its event type contains
@samp{double-drag} instead of just @samp{drag}. If a double-drag event
has no binding, Emacs looks for an alternate binding as if the event
-were an ordinary click.
+were an ordinary drag.
Before the double-click or double-drag event, Emacs generates a
-@dfn{double-down} event when the button is pressed down for the second
-time. Its event type contains @samp{double-down} instead of just
+@dfn{double-down} event when the user presses the button down for the
+second time. Its event type contains @samp{double-down} instead of just
@samp{down}. If a double-down event has no binding, Emacs looks for an
alternate binding as if the event were an ordinary button-down event.
-If it finds no binding that way either, the double-down event is ignored.
+If it finds no binding that way either, the double-down event is
+ignored.
To summarize, when you click a button and then press it again right
-away, Emacs generates a double-down event, followed by either a
-double-click or a double-drag.
+away, Emacs generates a down event and a click event for the first
+click, a double-down event when you press the button again, and finally
+either a double-click or a double-drag event.
If you click a button twice and then press it again, all in quick
succession, Emacs generates a @dfn{triple-down} event, followed by
triple event has no binding, Emacs uses the binding that it would use
for the corresponding double event.
-If you click a button three or more times and then press it again,
-the events for the presses beyond the third are all triple events.
-Emacs does not have quadruple, quintuple, etc. events as separate
-event types. However, you can look at the event list to find out
-precisely how many times the button was pressed.
+If you click a button three or more times and then press it again, the
+events for the presses beyond the third are all triple events. Emacs
+does not have separate event types for quadruple, quintuple, etc.@:
+events. However, you can look at the event list to find out precisely
+how many times the button was pressed.
@defun event-click-count event
This function returns the number of consecutive button presses that led
(not a repeat event), the value is 1.
@end defun
-@defvar double-click-time
-To count as double- and triple-clicks, mouse clicks must be at the same
-location as the first click, and the number of milliseconds between the
-first release and the second must be less than the value of
+@defopt double-click-fuzz
+To generate repeat events, successive mouse button presses must be at
+approximately the same screen position. The value of
+@code{double-click-fuzz} specifies the maximum number of pixels the
+mouse may be moved (horizontally or vertically) between two successive
+clicks to make a double-click.
+
+This variable is also the threshold for motion of the mouse to count
+as a drag.
+@end defopt
+
+@defopt 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
@code{t} removes the time limit; Emacs then detects multi-clicks by
position only.
-@end defvar
+@end defopt
@node Motion Events
@subsection Motion Events
represented by lists that look like this:
@example
-(mouse-movement
- (@var{window} @var{buffer-pos}
- (@var{x} . @var{y}) @var{timestamp}))
+(mouse-movement (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}))
@end example
The second element of the list describes the current position of the
The special form @code{track-mouse} enables generation of motion events
within its body. Outside of @code{track-mouse} forms, Emacs does not
generate events for mere motion of the mouse, and these events do not
-appear.
-
-@defspec track-mouse body@dots{}
-This special form executes @var{body}, with generation of mouse motion
-events enabled. Typically @var{body} would use @code{read-event}
-to read the motion events and modify the display accordingly.
-
-When the user releases the button, that generates a click event.
-Normally @var{body} should return when it sees the click event, and
-discard the event.
-@end defspec
+appear. @xref{Mouse Tracking}.
@node Focus Events
@subsection Focus Events
@noindent
where @var{new-frame} is the frame switched to.
-In X windows, most window managers are set up so that just moving the
-mouse into a window is enough to set the focus there. Emacs appears to
-do this, because it changes the cursor to solid in the new frame.
-However, there is no need for the Lisp program to know about the focus
-change until some other kind of input arrives. So Emacs generates the
-focus event only when the user actually types a keyboard key or presses
-a mouse button in the new frame; just moving the mouse between frames
-does not generate a focus event.
+Most X window managers are set up so that just moving the mouse into a
+window is enough to set the focus there. Emacs appears to do this,
+because it changes the cursor to solid in the new frame. However, there
+is no need for the Lisp program to know about the focus change until
+some other kind of input arrives. So Emacs generates a focus event only
+when the user actually types a keyboard key or presses a mouse button in
+the new frame; just moving the mouse between frames does not generate a
+focus event.
A focus event in the middle of a key sequence would garble the
sequence. So Emacs never generates a focus event in the middle of a key
so that the focus event comes either before or after the multi-event key
sequence, and not within it.
+@node Misc Events
+@subsection Miscellaneous System Events
+
+A few other event types represent occurrences within the system.
+
+@table @code
+@cindex @code{delete-frame} event
+@item (delete-frame (@var{frame}))
+This kind of event indicates that the user gave the window manager
+a command to delete a particular window, which happens to be an Emacs frame.
+
+The standard definition of the @code{delete-frame} event is to delete @var{frame}.
+
+@cindex @code{iconify-frame} event
+@item (iconify-frame (@var{frame}))
+This kind of event indicates that the user iconified @var{frame} using
+the window manager. Its standard definition is @code{ignore}; since the
+frame has already been iconified, Emacs has no work to do. The purpose
+of this event type is so that you can keep track of such events if you
+want to.
+
+@cindex @code{make-frame-visible} event
+@item (make-frame-visible (@var{frame}))
+This kind of event indicates that the user deiconified @var{frame} using
+the window manager. Its standard definition is @code{ignore}; since the
+frame has already been made visible, Emacs has no work to do.
+
+@cindex @code{wheel-up} event
+@cindex @code{wheel-down} event
+@item (wheel-up @var{position})
+@item (wheel-down @var{position})
+These kinds of event are generated by moving a mouse wheel. Their
+usual meaning is a kind of scroll or zoom.
+
+The element @var{position} is a list describing the position of the
+event, in the same format as used in a mouse-click event.
+
+This kind of event is generated only on some kinds of systems. On some
+systems, @code{mouse-4} and @code{mouse-5} are used instead. For
+portable code, use the variables @code{mouse-wheel-up-event} and
+@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine
+what event types to expect for the mouse wheel.
+
+@cindex @code{drag-n-drop} event
+@item (drag-n-drop @var{position} @var{files})
+This kind of event is generated when a group of files is
+selected in an application outside of Emacs, and then dragged and
+dropped onto an Emacs frame.
+
+The element @var{position} is a list describing the position of the
+event, in the same format as used in a mouse-click event, and
+@var{files} is the list of file names that were dragged and dropped.
+The usual way to handle this event is by visiting these files.
+
+This kind of event is generated, at present, only on some kinds of
+systems.
+
+@cindex @code{usr1-signal} event
+@cindex @code{usr2-signal} event
+@item usr1-signal
+@itemx usr2-signal
+These events are generated when the Emacs process receives the signals
+@code{SIGUSR1} and @code{SIGUSR2}. They contain no additional data
+because signals do not carry additional information.
+@end table
+
+ If one of these events arrives in the middle of a key sequence---that
+is, after a prefix key---then Emacs reorders the events so that this
+event comes either before or after the multi-event key sequence, not
+within it.
+
@node Event Examples
@subsection Event Examples
(mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180))
@end smallexample
-Or, while holding the control key down, the user might hold down the
+While holding the control key down, the user might hold down the
second mouse button, and drag the mouse from one line to the next.
That produces two events, as shown here:
(#<window 18 on NEWS> 3510 (0 . 28) -729648))
@end smallexample
-Or, while holding down the meta and shift keys, the user might press the
+While holding down the meta and shift keys, the user might press the
second mouse button on the window's mode line, and then drag the mouse
-into another window. That produces the following pair of events:
+into another window. That produces a pair of events like these:
@smallexample
(M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
@subsection Classifying Events
@cindex event type
- Every event has an @dfn{event type} which classifies the event for key
-binding purposes. For a keyboard event, the event type equals the event
-value; thus, the event type for a character is the character, and the
-event type for a function key symbol is the symbol itself. For events
-which are lists, the event type is the symbol in the @sc{car} of the
-list. Thus, the event type is always a symbol or a character.
+ Every event has an @dfn{event type}, which classifies the event for
+key binding purposes. For a keyboard event, the event type equals the
+event value; thus, the event type for a character is the character, and
+the event type for a function key symbol is the symbol itself. For
+events that are lists, the event type is the symbol in the @sc{car} of
+the list. Thus, the event type is always a symbol or a character.
Two events of the same type are equivalent where key bindings are
concerned; thus, they always run the same command. That does not
necessarily mean they do the same things, however, as some commands look
at the whole event to decide what to do. For example, some commands use
-the location of a mouse event to decide what text to act on.
+the location of a mouse event to decide where in the buffer to act.
Sometimes broader classifications of events are useful. For example,
you might want to ask whether an event involved the @key{META} key,
provided to get such information conveniently.
@defun event-modifiers event
-This function returns a list of the modifiers that @var{event} has.
-The modifiers are symbols; they include @code{shift}, @code{control},
+This function returns a list of the modifiers that @var{event} has. The
+modifiers are symbols; they include @code{shift}, @code{control},
@code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition,
-the property of a mouse event symbol always has one of @code{click},
-@code{drag}, and @code{down} among the modifiers. For example:
+the modifiers list of a mouse event symbol always contains one of
+@code{click}, @code{drag}, and @code{down}. For double or triple
+events, it also contains @code{double} or @code{triple}.
+
+The argument @var{event} may be an entire event object, or just an
+event type. If @var{event} is a symbol that has never been used in an
+event that has been read as input in the current Emacs session, then
+@code{event-modifiers} can return @code{nil}, even when @var{event}
+actually has modifiers.
+
+Here are some examples:
@example
(event-modifiers ?a)
@result{} nil
+(event-modifiers ?A)
+ @result{} (shift)
(event-modifiers ?\C-a)
@result{} (control)
(event-modifiers ?\C-%)
@defun event-basic-type event
This function returns the key or mouse button that @var{event}
-describes, with all modifiers removed. For example:
+describes, with all modifiers removed. The @var{event} argument is as
+in @code{event-modifiers}. For example:
@example
(event-basic-type ?a)
event.
@end defun
+@defun event-convert-list list
+This function converts a list of modifier names and a basic event type
+to an event type which specifies all of them. The basic event type
+must be the last element of the list. For example,
+
+@example
+(event-convert-list '(control ?a))
+ @result{} 1
+(event-convert-list '(control meta ?a))
+ @result{} -134217727
+(event-convert-list '(control super f1))
+ @result{} C-s-f1
+@end example
+@end defun
+
@node Accessing Events
@subsection Accessing Events
+@cindex mouse events, accessing the data
+@cindex accessing data of mouse events
This section describes convenient functions for accessing the data in
-an event which is a list.
+a mouse button or motion event.
- The following functions return the starting or ending position of a
-mouse-button event. The position is a list of this form:
+ These two functions return the starting or ending position of a
+mouse-button event, as a list of this form:
-@smallexample
-(@var{window} @var{buffer-position} (@var{col} . @var{row}) @var{timestamp})
-@end smallexample
+@example
+(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
+ @var{object} @var{text-pos} (@var{col} . @var{row})
+ @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
+@end example
@defun event-start event
This returns the starting position of @var{event}.
position such events have.
@end defun
- These four functions take a position-list as described above, and
+@cindex mouse position list, accessing
+ These functions take a position list as described above, and
return various parts of it.
@defun posn-window position
Return the window that @var{position} is in.
@end defun
+@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.
+@end defun
+
@defun posn-point position
-Return the buffer location in @var{position}.
+Return the buffer position in @var{position}. When the event occurred
+in the text area of the window, in a marginal area, or on a fringe,
+this is an integer specifying a buffer position. Otherwise, the value
+is undefined.
@end defun
@defun posn-x-y position
-Return the pixel-based x and y coordinates column in @var{position}, as
-a cons cell @code{(@var{x} . @var{y})}.
+Return the pixel-based x and y coordinates in @var{position}, as a
+cons cell @code{(@var{x} . @var{y})}. These coordinates are relative
+to the window given by @code{posn-window}.
+
+This example shows how to convert these window-relative coordinates
+into frame-relative coordinates:
+
+@example
+(defun frame-relative-coordinates (position)
+ "Return frame-relative coordinates from POSITION."
+ (let* ((x-y (posn-x-y position))
+ (window (posn-window position))
+ (edges (window-inside-pixel-edges window)))
+ (cons (+ (car x-y) (car edges))
+ (+ (cdr x-y) (cadr edges)))))
+@end example
@end defun
@defun posn-col-row position
-Return the row and column (in units of characters) in @var{position}, as
-a cons cell @code{(@var{col} . @var{row})}. These are computed from the
-@var{x} and @var{y} values actually found in @var{position}.
+Return the row and column (in units of the frame's default character
+height and width) of @var{position}, as a cons cell @code{(@var{col} .
+@var{row})}. These are computed from the @var{x} and @var{y} values
+actually found in @var{position}.
+@end defun
+
+@defun posn-actual-col-row position
+Return the actual row and column in @var{position}, as a cons cell
+@code{(@var{col} . @var{row})}. The values are the actual row number
+in the window, and the actual character number in that row. It returns
+@code{nil} if @var{position} does not include actual positions values.
+You can use @code{posn-col-row} to get approximate values.
+@end defun
+
+@defun posn-string position
+Return the string object in @var{position}, either @code{nil}, or a
+cons cell @code{(@var{string} . @var{string-pos})}.
+@end defun
+
+@defun posn-image position
+Return the image object in @var{position}, either @code{nil}, or an
+image @code{(image ...)}.
+@end defun
+
+@defun posn-object position
+Return the image or string object in @var{position}, either
+@code{nil}, an image @code{(image ...)}, or a cons cell
+@code{(@var{string} . @var{string-pos})}.
@end defun
+@defun posn-object-x-y position
+Return the pixel-based x and y coordinates relative to the upper left
+corner of the object in @var{position} as a cons cell @code{(@var{dx}
+. @var{dy})}. If the @var{position} is a buffer position, return the
+relative position in the character at that position.
+@end defun
+
+@defun posn-object-width-height position
+Return the pixel width and height of the object in @var{position} as a
+cons cell @code{(@var{width} . @var{height})}. If the @var{position}
+is a buffer position, return the size of the character at that position.
+@end defun
+
+@cindex mouse event, timestamp
+@cindex timestamp of a mouse event
@defun posn-timestamp position
-Return the timestamp of @var{position}.
+Return the timestamp in @var{position}. This is the time at which the
+event occurred, in milliseconds.
+@end defun
+
+ These functions compute a position list given particular buffer
+position or screen position. You can access the data in this position
+list with the functions described above.
+
+@defun posn-at-point &optional pos window
+This function returns a position list for position @var{pos} in
+@var{window}. @var{pos} defaults to point in @var{window};
+@var{window} defaults to the selected window.
+
+@code{posn-at-point} returns @code{nil} if @var{pos} is not visible in
+@var{window}.
+@end defun
+
+@defun posn-at-x-y x y &optional frame-or-window
+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.
+@end defun
+
+ These functions are useful for decoding scroll bar events.
+
+@defun scroll-bar-event-ratio event
+This function returns the fractional vertical position of a scroll bar
+event within the scroll bar. The value is a cons cell
+@code{(@var{portion} . @var{whole})} containing two integers whose ratio
+is the fractional position.
@end defun
@defun scroll-bar-scale ratio total
-This function multiples (in effect) @var{ratio} by @var{total},
-rounding the result to an integer. @var{ratio} is not a number,
-but rather a pair @code{(@var{num} . @var{denom})}.
+This function multiplies (in effect) @var{ratio} by @var{total},
+rounding the result to an integer. The argument @var{ratio} is not a
+number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
+value returned by @code{scroll-bar-event-ratio}.
-This is handy for scaling a position on a scroll bar into a buffer
-position. Here's how to do that:
+This function is handy for scaling a position on a scroll bar into a
+buffer position. Here's how to do that:
@example
(+ (point-min)
(scroll-bar-scale
- (posn-col-row (event-start event))
+ (posn-x-y (event-start event))
(- (point-max) (point-min))))
@end example
+
+Recall that scroll bar events have two integers forming a ratio, in place
+of a pair of x and y coordinates.
@end defun
@node Strings of Events
@subsection Putting Keyboard Events in Strings
+@cindex keyboard events in strings
+@cindex strings with keyboard events
In most of the places where strings are used, we conceptualize the
string as containing text characters---the same kind of characters found
-in buffers or files. Occasionally Lisp programs use strings which
+in buffers or files. Occasionally Lisp programs use strings that
conceptually contain keyboard characters; for example, they may be key
-sequences or keyboard macro definitions. There are special rules for
-how to put keyboard characters into a string, because they are not
-limited to the range of 0 to 255 as text characters are.
-
- A keyboard character typed using the @key{META} key is called a
-@dfn{meta character}. The numeric code for such an event includes the
-2**23 bit; it does not even come close to fitting in a string. However,
-earlier Emacs versions used a different representation for these
-characters, which gave them codes in the range of 128 to 255. That did
-fit in a string, and many Lisp programs contain string constants that
-use @samp{\M-} to express meta characters, especially as the argument to
-@code{define-key} and similar functions.
-
- We provide backward compatibility to run those programs with special
-rules for how to put a keyboard character event in a string. Here are
-the rules:
+sequences or keyboard macro definitions. However, storing keyboard
+characters in a string is a complex matter, for reasons of historical
+compatibility, and it is not always possible.
+
+ We recommend that new programs avoid dealing with these complexities
+by not storing keyboard events in strings. Here is how to do that:
@itemize @bullet
@item
-If the keyboard event value is in the range of 0 to 127, it can go in the
-string unchanged.
+Use vectors instead of strings for key sequences, when you plan to use
+them for anything other than as arguments to @code{lookup-key} and
+@code{define-key}. For example, you can use
+@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
+@code{this-command-keys-vector} instead of @code{this-command-keys}.
@item
-The meta variants of those events, with codes in the range of 2**23 to
-2**23+127, can also go in the string, but you must change their numeric
-values. You must set the 2**7 bit instead of the 2**23 bit, resulting
-in a value between 128 and 255.
+Use vectors to write key sequence constants containing meta characters,
+even when passing them directly to @code{define-key}.
+
+@item
+When you have to look at the contents of a key sequence that might be a
+string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
+first, to convert it to a list.
+@end itemize
+
+ The complexities stem from the modifier bits that keyboard input
+characters can include. Aside from the Meta modifier, none of these
+modifier bits can be included in a string, and the Meta modifier is
+allowed only in special cases.
+
+ The earliest GNU Emacs versions represented meta characters as codes
+in the range of 128 to 255. At that time, the basic character codes
+ranged from 0 to 127, so all keyboard character codes did fit in a
+string. Many Lisp programs used @samp{\M-} in string constants to stand
+for meta characters, especially in arguments to @code{define-key} and
+similar functions, and key sequences and sequences of events were always
+represented as strings.
+
+ When we added support for larger basic character codes beyond 127, and
+additional modifier bits, we had to change the representation of meta
+characters. Now the flag that represents the Meta modifier in a
+character is
+@tex
+@math{2^{27}}
+@end tex
+@ifnottex
+2**27
+@end ifnottex
+and such numbers cannot be included in a string.
+
+ To support programs with @samp{\M-} in string constants, there are
+special rules for including certain meta characters in a string.
+Here are the rules for interpreting a string as a sequence of input
+characters:
+
+@itemize @bullet
+@item
+If the keyboard character value is in the range of 0 to 127, it can go
+in the string unchanged.
+
+@item
+The meta variants of those characters, with codes in the range of
+@tex
+@math{2^{27}}
+@end tex
+@ifnottex
+2**27
+@end ifnottex
+to
+@tex
+@math{2^{27} + 127},
+@end tex
+@ifnottex
+2**27+127,
+@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
+@ifnottex
+2**7
+@end ifnottex
+bit instead of the
+@tex
+@math{2^{27}}
+@end tex
+@ifnottex
+2**27
+@end ifnottex
+bit, resulting in a value between 128 and 255. Only a unibyte string
+can include these codes.
+
+@item
+Non-@acronym{ASCII} characters above 256 can be included in a multibyte string.
@item
Other keyboard character events cannot fit in a string. This includes
keyboard events in the range of 128 to 255.
@end itemize
- Functions such as @code{read-key-sequence} that can construct strings
-containing events follow these rules.
+ Functions such as @code{read-key-sequence} that construct strings of
+keyboard input characters follow these rules: they construct vectors
+instead of strings, when the events won't fit in a string.
When you use the read syntax @samp{\M-} in a string, it produces a
code in the range of 128 to 255---the same code that you get if you
meta events in strings work consistently regardless of how they get into
the strings.
- New programs can avoid dealing with these rules by using vectors
-instead of strings for key sequences when there is any possibility that
-these issues might arise.
-
- The reason we changed the representation of meta characters as
-keyboard events is to make room for basic character codes beyond 127,
-and support meta variants of such larger character codes.
+ However, most programs would do well to avoid these issues by
+following the recommendations at the beginning of this section.
@node Reading Input
@section Reading Input
- The editor command loop reads keyboard input using the function
+ The editor command loop reads key sequences using the function
@code{read-key-sequence}, which uses @code{read-event}. These and other
-functions for keyboard input are also available for use in Lisp
-programs. See also @code{momentary-string-display} in @ref{Temporary
-Displays}, and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input},
-for functions and variables for controlling terminal input modes and
-debugging terminal input.
+functions for event input are also available for use in Lisp programs.
+See also @code{momentary-string-display} in @ref{Temporary Displays},
+and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
+functions and variables for controlling terminal input modes and
+debugging terminal input. @xref{Translating Input}, for features you
+can use for translating or modifying input events while reading them.
For higher-level input facilities, see @ref{Minibuffers}.
@menu
* Key Sequence Input:: How to read one key sequence.
* Reading One Event:: How to read just one event.
+* Invoking the Input Method:: How reading an event uses the input method.
* Quoted Character Input:: Asking the user to specify a character.
-* Peeking and Discarding:: How to reread or throw away input events.
+* Event Input Misc:: How to reread or throw away input events.
@end menu
@node Key Sequence Input
@defun read-key-sequence prompt
@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 full key
+vector. It keeps reading events until it has accumulated a complete key
sequence; that is, enough to specify a non-prefix command using the
-currently active keymaps.
+currently active keymaps. (Remember that 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.)
If the events are all characters and all can fit in a string, then
@code{read-key-sequence} returns a string (@pxref{Strings of Events}).
events---characters, symbols, and lists. The elements of the string or
vector are the events in the key sequence.
-Quitting is suppressed inside @code{read-key-sequence}. In other words,
-a @kbd{C-g} typed while reading with this function is treated like any
-other character, and does not set @code{quit-flag}. @xref{Quitting}.
-
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.
@result{} "^X^F"
@end group
@end example
+
+The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
+typed while reading with this function works like any other character,
+and does not set @code{quit-flag}. @xref{Quitting}.
@end defun
-@defvar num-input-keys
-@c Emacs 19 feature
-This variable's value is the number of key sequences processed so far in
-this Emacs session. This includes key sequences read from the terminal
-and key sequences read from keyboard macros being executed.
-@end defvar
+@defun read-key-sequence-vector prompt
+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}.
+@end defun
@cindex upper case key sequence
@cindex downcasing in @code{lookup-key}
-If an input character is an upper case letter and has no key binding,
-but the lower case equivalent has one, then @code{read-key-sequence}
-converts the character to lower case. Note that @code{lookup-key} does
-not perform case conversion in this way.
+If an input character is upper-case (or has the shift modifier) and
+has no key binding, but its lower-case equivalent has one, then
+@code{read-key-sequence} converts the character to lower case. Note
+that @code{lookup-key} does not perform case conversion in this way.
The function @code{read-key-sequence} also transforms some mouse events.
It converts unbound drag events into click events, and discards unbound
-button-down events entirely. It also reshuffles focus events so that they
-never appear in a key sequence with any other events.
-
+button-down events entirely. It also reshuffles focus events and
+miscellaneous window events so that they never appear in a key sequence
+with any other events.
+
+@cindex @code{header-line} prefix key
+@cindex @code{mode-line} prefix key
+@cindex @code{vertical-line} prefix key
+@cindex @code{horizontal-scroll-bar} prefix key
+@cindex @code{vertical-scroll-bar} prefix key
+@cindex @code{menu-bar} prefix key
+@cindex mouse events, in special parts of frame
When mouse events occur in special parts of a window, such as a mode
-line or a scroll bar, the event itself shows nothing special---only the
-symbol that would normally represent that mouse button and modifier
-keys. The information about the screen region 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{mode-line}, @code{vertical-line}, @code{horizontal-scroll-bar} and
-@code{vertical-scroll-bar}.
+line or a scroll bar, the event type shows nothing special---it is the
+same symbol that would normally represent that combination of mouse
+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{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
+sequences using these imaginary prefix keys.
For example, if you call @code{read-key-sequence} and then click the
-mouse on the window's mode line, this is what happens:
+mouse on the window's mode line, you get two events, like this:
-@smallexample
+@example
(read-key-sequence "Click on the mode line: ")
@result{} [mode-line
- (mouse-1
- (#<window 6 on NEWS> mode-line
- (40 . 63) 5959987))]
-@end smallexample
+ (mouse-1
+ (#<window 6 on NEWS> mode-line
+ (40 . 63) 5959987))]
+@end example
-You can define meanings for mouse clicks in special window regions by
-defining key sequences using these imaginary prefix keys.
+@defvar num-input-keys
+@c Emacs 19 feature
+This variable's value is the number of key sequences processed so far in
+this Emacs session. This includes key sequences read from the terminal
+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
+@cindex event, reading only one
- The lowest level functions for command input are those which read a
+ The lowest level functions for command input are those that read a
single event.
-@defun read-event
+None of the three functions below suppresses quitting.
+
+@defun read-event &optional prompt inherit-input-method
This function reads and returns the next event of command input, waiting
if necessary until an event is available. Events can come directly from
the user or from a keyboard macro.
-The function @code{read-event} does not display any message to indicate
-it is waiting for input; use @code{message} first, if you wish to
-display one. If you have not displayed a message, @code{read-event}
-does @dfn{prompting}: it displays descriptions of the events that led to
-or were read by the current command. @xref{The Echo Area}.
+If the optional argument @var{prompt} is non-@code{nil}, it should be a
+string to display in the echo area as a prompt. Otherwise,
+@code{read-event} does not display any message to indicate it is waiting
+for input; instead, it prompts by echoing: it displays descriptions of
+the events that led to or were read by the current command. @xref{The
+Echo Area}.
+
+If @var{inherit-input-method} is non-@code{nil}, then the current input
+method (if any) is employed to make it possible to enter a
+non-@acronym{ASCII} character. Otherwise, input method handling is disabled
+for reading this event.
If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
moves the cursor temporarily to the echo area, to the end of any message
displayed there. Otherwise @code{read-event} does not move the cursor.
-@end defun
+
+If @code{read-event} gets an event that is defined as a help character,
+then in some cases @code{read-event} processes the event directly without
+returning. @xref{Help Functions}. Certain other events, called
+@dfn{special events}, are also processed directly within
+@code{read-event} (@pxref{Special Events}).
Here is what happens if you call @code{read-event} and then press the
right-arrow function key:
@result{} right
@end group
@end example
+@end defun
-@defun read-char
-This function reads and returns a character of command input. It
-discards any events that are not characters until it gets a character.
+@defun read-char &optional prompt inherit-input-method
+This function reads and returns a character of command input. If the
+user generates an event which is not a character (i.e. a mouse click or
+function key event), @code{read-char} signals an error. The arguments
+work as in @code{read-event}.
-In the first example, the user types @kbd{1} (which is @sc{ASCII} code
-49). The second example shows a keyboard macro definition that calls
-@code{read-char} from the minibuffer. @code{read-char} reads the
-keyboard macro's very next character, which is @kbd{1}. The value of
-this function is displayed in the echo area by the command
-@code{eval-expression}.
+In the first example, the user types the character @kbd{1} (@acronym{ASCII}
+code 49). The second example shows a keyboard macro definition that
+calls @code{read-char} from the minibuffer using @code{eval-expression}.
+@code{read-char} reads the keyboard macro's very next character, which
+is @kbd{1}. Then @code{eval-expression} displays its return value in
+the echo area.
@example
@group
@end group
@group
+;; @r{We assume here you use @kbd{M-:} to evaluate this.}
(symbol-function 'foo)
- @result{} "^[^[(read-char)^M1"
+ @result{} "^[:(read-char)^M1"
@end group
@group
-(execute-kbd-macro foo)
+(execute-kbd-macro 'foo)
@print{} 49
@result{} nil
@end group
@end example
@end defun
+@defun read-char-exclusive &optional prompt inherit-input-method
+This function reads and returns a character of command input. If the
+user generates an event which is not a character,
+@code{read-char-exclusive} ignores it and reads another event, until it
+gets a character. The arguments work as in @code{read-event}.
+@end defun
+
+@node Invoking the Input Method
+@subsection Invoking the Input Method
+
+ The event-reading functions invoke the current input method, if any
+(@pxref{Input Methods}). If the value of @code{input-method-function}
+is non-@code{nil}, it should be a function; when @code{read-event} reads
+a printing character (including @key{SPC}) with no modifier bits, it
+calls that function, passing the character as an argument.
+
+@defvar input-method-function
+If this is non-@code{nil}, its value specifies the current input method
+function.
+
+@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
+buffer.
+@end defvar
+
+ The input method function should return a list of events which should
+be used as input. (If the list is @code{nil}, that means there is no
+input, so @code{read-event} waits for another event.) These events are
+processed before the events in @code{unread-command-events}
+(@pxref{Event Input Misc}). Events
+returned by the input method function are not passed to the input method
+function again, even if they are printing characters with no modifier
+bits.
+
+ If the input method function calls @code{read-event} or
+@code{read-key-sequence}, it should bind @code{input-method-function} to
+@code{nil} first, to prevent recursion.
+
+ The input method function is not called when reading the second and
+subsequent events of a key sequence. Thus, these characters are not
+subject to input method processing. The input method function should
+test the values of @code{overriding-local-map} and
+@code{overriding-terminal-local-map}; if either of these variables is
+non-@code{nil}, the input method should put its argument into a list and
+return that list with no further processing.
+
@node Quoted Character Input
@subsection Quoted Character Input
@cindex quoted character input
- You can use the function @code{read-quoted-char} when you want the user
-to specify a character, and allow the user to specify a control or meta
-character conveniently with quoting or as an octal character code. The
-command @code{quoted-insert} calls this function.
+ You can use the function @code{read-quoted-char} to ask the user to
+specify a character, and allow the user to specify a control or meta
+character conveniently, either literally or as an octal character code.
+The command @code{quoted-insert} uses this function.
@defun read-quoted-char &optional prompt
@cindex octal character input
@cindex control characters, reading
@cindex nonprinting characters, reading
This function is like @code{read-char}, except that if the first
-character read is an octal digit (0-7), it reads up to two more octal digits
-(but stopping if a non-octal digit is found) and returns the
-character represented by those digits as an octal number.
+character read is an octal digit (0-7), it reads any number of octal
+digits (but stopping if a non-octal digit is found), and returns the
+character represented by that numeric character code. If the
+character that terminates the sequence of octal digits is @key{RET},
+it is discarded. Any other terminating character is used as input
+after this function returns.
Quitting is suppressed when the first character is read, so that the
user can enter a @kbd{C-g}. @xref{Quitting}.
If @var{prompt} is supplied, it specifies a string for prompting the
-user. The prompt string is always printed in the echo area and followed
+user. The prompt string is always displayed in the echo area, followed
by a single @samp{-}.
In the following example, the user types in the octal number 177 (which
@group
---------- Echo Area ----------
-What character-@kbd{177}
+What character @kbd{1 7 7}-
---------- Echo Area ----------
@result{} 127
@end example
@end defun
-@need 3000
+@need 2000
+@node Event Input Misc
+@subsection Miscellaneous Event Input Features
-@node Peeking and Discarding
-@subsection Peeking and Discarding
+This section describes how to ``peek ahead'' at events without using
+them up, how to check for pending input, and how to discard pending
+input. See also the function @code{read-passwd} (@pxref{Reading a
+Password}).
@defvar unread-command-events
@cindex next input
@cindex peeking at input
This variable holds a list of events waiting to be read as command
-input. The events are used in the order they appear in the list.
+input. The events are used in the order they appear in the list, and
+removed one by one as they are used.
-The variable is used because in some cases a function reads a event and
-then decides not to use it. Storing the event in this variable causes
-it to be processed normally by the command loop or when the functions to
-read command input are called.
+The variable is needed because in some cases a function reads an event
+and then decides not to use it. Storing the event in this variable
+causes it to be processed normally, by the command loop or by the
+functions to read command input.
@cindex prefix argument unreading
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 it does
-not recognize.
+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.
+
+The reliable and easy way to extract events from a key sequence so as to
+put them in @code{unread-command-events} is to use
+@code{listify-key-sequence} (@pxref{Strings of Events}).
+
+Normally you add events to the front of this list, so that the events
+most recently unread will be reread first.
@end defvar
+@defun listify-key-sequence key
+This function converts the string or vector @var{key} to a list of
+individual events, which you can put in @code{unread-command-events}.
+@end defun
+
@defvar unread-command-char
This variable holds a character to be read as command input.
A value of -1 means ``empty''.
-This variable is pretty much obsolete now that you can use
+This variable is mostly obsolete now that you can use
@code{unread-command-events} instead; it exists only to support programs
written for Emacs versions 18 and earlier.
@end defvar
-@defun listify-key-sequence key
-This function converts the string or vector @var{key} to a list of
-events which you can put in @code{unread-command-events}. Converting a
-vector is simple, but converting a string is tricky because of the
-special representation used for meta characters in a string
-(@pxref{Strings of Events}).
-@end defun
-
@defun input-pending-p
@cindex waiting for command key input
This function determines whether any command input is currently
available to be read. It returns immediately, with value @code{t} if
-there is input, @code{nil} otherwise. On rare occasions it may return
-@code{t} when no input is available.
+there is available input, @code{nil} otherwise. On rare occasions it
+may return @code{t} when no input is available.
@end defun
@defvar last-input-event
@defvarx last-input-char
- This variable records the last terminal input event read, whether
+This variable records the last terminal input event read, whether
as part of a command or explicitly by a Lisp program.
- In the example below, a character is read (the character @kbd{1},
-@sc{ASCII} code 49). It becomes the value of @code{last-input-char},
-while @kbd{C-e} (from the @kbd{C-x C-e} command used to evaluate this
-expression) remains the value of @code{last-command-char}.
+In the example below, the Lisp program reads the character @kbd{1},
+@acronym{ASCII} code 49. It becomes the value of @code{last-input-event},
+while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
+this expression) remains the value of @code{last-command-event}.
@example
@group
(progn (print (read-char))
- (print last-command-char)
- last-input-char)
+ (print last-command-event)
+ last-input-event)
@print{} 49
@print{} 5
@result{} 49
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, any characters that have been typed are discarded.
+finishes sleeping, @code{discard-input} discards any characters typed
+during the sleep.
@example
(progn (sleep-for 2)
- (discard-input))
+ (discard-input))
@result{} nil
@end example
@end defun
+@node Special Events
+@section Special Events
+
+@cindex special events
+Special events are handled at a very low level---as soon as they are
+read. The @code{read-event} function processes these events itself, and
+never returns them. Instead, it keeps waiting for the first event
+that is not special and returns that one.
+
+Events that are handled in this way do not echo, they are never grouped
+into key sequences, and they never appear in the value of
+@code{last-command-event} or @code{(this-command-keys)}. They do not
+discard a numeric argument, they cannot be unread with
+@code{unread-command-events}, they may not appear in a keyboard macro,
+and they are not recorded in a keyboard macro while you are defining
+one.
+
+These events do, however, appear in @code{last-input-event} immediately
+after they are read, and this is the way for the event's definition to
+find the actual event.
+
+The events types @code{iconify-frame}, @code{make-frame-visible} and
+@code{delete-frame} are normally handled in this way. The keymap which
+defines how to handle special events---and which events are special---is
+in the variable @code{special-event-map} (@pxref{Active Keymaps}).
+
@node Waiting
@section Waiting for Elapsed Time or Input
@cindex pausing
@cindex waiting
- The waiting commands are designed to make Emacs wait for a certain
-amount of time to pass or until there is input. For example, you may
-wish to pause in the middle of a computation to allow the user time to
-view the display. @code{sit-for} pauses and updates the screen, and
-returns immediately if input comes in, while @code{sleep-for} pauses
-without updating the screen.
+ The wait functions are designed to wait for a certain amount of time
+to pass or until there is input. For example, you may wish to pause in
+the middle of a computation to allow the user time to view the display.
+@code{sit-for} pauses and updates the screen, and returns immediately if
+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 result is @code{t} if @code{sit-for} waited the full
-time with no input arriving (see @code{input-pending-p} in @ref{Peeking
-and Discarding}). Otherwise, the value is @code{nil}.
+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
+Input Misc}). Otherwise, the value is @code{nil}.
-@c Emacs 19 feature ??? maybe not working yet
-The optional argument @var{millisec} specifies an additional waiting
-period measured in milliseconds. This adds to the period specified by
-@var{seconds}. Not all operating systems support waiting periods other
-than multiples of a second; on those that do not, you get an error if
-you specify nonzero @var{millisec}.
+The argument @var{seconds} need not be an integer. If it is a floating
+point number, @code{sit-for} waits for a fractional number of seconds.
+Some systems support only a whole number of seconds; on these systems,
+@var{seconds} is rounded down.
-@cindex forcing redisplay
-Redisplay is always preempted if input arrives, and does not happen at
-all if input is available before it starts. Thus, there is no way to
-force screen updating if there is pending input; however, if there is no
-input pending, you can force an update with no delay by using
-@code{(sit-for 0)}.
+The expression @code{(sit-for 0)} is a convenient way to request a
+redisplay, without any delay. @xref{Forcing Redisplay}.
If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
redisplay, but it still returns as soon as input is available (or when
the timeout elapses).
+Iconifying or deiconifying a frame makes @code{sit-for} return, because
+that generates an event. @xref{Misc Events}.
+
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
the display. It pays no attention to available input. It returns
@code{nil}.
-@c Emacs 19 feature ??? maybe not working yet
+The argument @var{seconds} need not be an integer. If it is a floating
+point number, @code{sleep-for} waits for a fractional number of seconds.
+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}. Not all operating systems support waiting periods other
-than multiples of a second; on those that do not, you get an error if
-you specify nonzero @var{millisec}.
+@var{seconds}. If the system doesn't support waiting fractions of a
+second, you get an error if you specify nonzero @var{millisec}.
Use @code{sleep-for} when you wish to guarantee a delay.
@end defun
@section Quitting
@cindex @kbd{C-g}
@cindex quitting
+@cindex interrupt Lisp functions
- Typing @kbd{C-g} while the command loop has run a Lisp function causes
-Emacs to @dfn{quit} whatever it is doing. This means that control
-returns to the innermost active command loop.
+ 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
+innermost active command loop.
Typing @kbd{C-g} while the command loop is waiting for keyboard input
does not cause a quit; it acts as an ordinary input character. In the
simplest case, you cannot tell the difference, because @kbd{C-g}
normally runs the command @code{keyboard-quit}, whose effect is to quit.
-However, when @kbd{C-g} follows a prefix key, the result is an undefined
-key. The effect is to cancel the prefix key as well as any prefix
-argument.
+However, when @kbd{C-g} follows a prefix key, they combine to form an
+undefined key. The effect is to cancel the prefix key as well as any
+prefix argument.
In the minibuffer, @kbd{C-g} has a different definition: it aborts out
of the minibuffer. This means, in effect, that it exits the minibuffer
can be redefined in the minibuffer in this way. @kbd{C-g} following a
prefix key is not redefined in the minibuffer, and it has its normal
effect of canceling the prefix key and prefix argument. This too
-would not be possible if @kbd{C-g} quit directly.
+would not be possible if @kbd{C-g} always quit directly.
- @kbd{C-g} causes a quit by setting the variable @code{quit-flag} to a
-non-@code{nil} value. Emacs checks this variable at appropriate times
-and quits if it is not @code{nil}. Setting @code{quit-flag}
+ When @kbd{C-g} does directly quit, it does so by setting the variable
+@code{quit-flag} to @code{t}. Emacs checks this variable at appropriate
+times and quits if it is not @code{nil}. Setting @code{quit-flag}
non-@code{nil} in any way thus causes a quit.
- At the level of C code, quits cannot happen just anywhere; only at the
-special places which check @code{quit-flag}. The reason for this is
+ 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
@code{inhibit-quit} will become @code{nil} again, such as when its
binding is unwound at the end of a @code{let} form. At that time, if
@code{quit-flag} is still non-@code{nil}, the requested quit happens
-immediately. This behavior is ideal for a ``critical section'', where
-you wish to make sure that quitting does not happen within that part of
-the program.
+immediately. This behavior is ideal when you wish to make sure that
+quitting does not happen within a ``critical section'' of the program.
@cindex @code{read-quoted-char} quitting
In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
-handled in a special way which does not involve quitting. This is done
-by reading the input with @code{inhibit-quit} bound to @code{t} and
+handled in a special way that does not involve quitting. This is done
+by reading the input with @code{inhibit-quit} bound to @code{t}, and
setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
becomes @code{nil} again. This excerpt from the definition of
@code{read-quoted-char} shows how this is done; it also shows that
@example
(defun read-quoted-char (&optional prompt)
"@dots{}@var{documentation}@dots{}"
- (let ((count 0) (code 0) char)
- (while (< count 3)
- (let ((inhibit-quit (zerop count))
- (help-form nil))
- (and prompt (message "%s-" prompt))
- (setq char (read-char))
- (if inhibit-quit (setq quit-flag nil)))
- @dots{})
- (logand 255 code)))
+ (let ((message-log-max nil) done (first t) (code 0) char)
+ (while (not done)
+ (let ((inhibit-quit first)
+ @dots{})
+ (and prompt (message "%s-" prompt))
+ (setq char (read-event))
+ (if inhibit-quit (setq quit-flag nil)))
+ @r{@dots{}set the variable @code{code}@dots{}})
+ code))
@end example
@defvar quit-flag
-If this variable is non-@code{nil}, then Emacs quits immediately,
-unless @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} sets
+If this variable is non-@code{nil}, then Emacs quits immediately, unless
+@code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
@code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
@end defvar
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
+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}.
+
+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
+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
+@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.
+
+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}.
+@end defmac
+
@deffn Command keyboard-quit
This function signals the @code{quit} condition with @code{(signal 'quit
nil)}. This is the same thing that quitting does. (See @code{signal}
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
Most Emacs commands can use a @dfn{prefix argument}, a number
specified before the command itself. (Don't confuse prefix arguments
-with prefix keys.) The prefix argument is represented by a value that
-is always available (though it may be @code{nil}, meaning there is no
-prefix argument). Each command may use the prefix argument or ignore
-it.
+with prefix keys.) The prefix argument is at all times represented by a
+value, which may be @code{nil}, meaning there is currently no prefix
+argument. Each command may use the prefix argument or ignore it.
There are two representations of the prefix argument: @dfn{raw} and
@dfn{numeric}. The editor command loop uses the raw representation
@minus{}1 and the symbol @code{-}.
@end itemize
-The various possibilities may be illustrated by calling the following
-function with various prefixes:
+We illustrate these possibilities by calling the following function with
+various prefixes:
@example
@group
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 -}.)}
+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}.)}
+M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
@end example
Emacs uses two variables to store the prefix argument:
Normally, commands specify which representation to use for the prefix
argument, either numeric or raw, in the @code{interactive} declaration.
-(@xref{Interactive Call}.) Alternatively, functions may look at the
+(@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.
- Do not call the functions @code{universal-argument},
-@code{digit-argument}, or @code{negative-argument} unless you intend to
-let the user enter the prefix argument for the @emph{next} command.
+@defun prefix-numeric-value arg
+This function returns the numeric meaning of a valid raw prefix argument
+value, @var{arg}. The argument may be a symbol, a number, or a list.
+If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
+value @minus{}1 is returned; if it is a number, that number is returned;
+if it is a list, the @sc{car} of that list (which should be a number) is
+returned.
+@end defun
+
+@defvar current-prefix-arg
+This variable holds the raw prefix argument for the @emph{current}
+command. Commands may examine it directly, but the usual method for
+accessing it is with @code{(interactive "P")}.
+@end defvar
+
+@defvar prefix-arg
+The value of this variable is the raw prefix argument for the
+@emph{next} editing command. Commands such as @code{universal-argument}
+that specify prefix arguments for the following command work by setting
+this variable.
+@end defvar
+
+@defvar last-prefix-arg
+The raw prefix argument value used by the previous command.
+@end defvar
+
+ The following commands exist to set up prefix arguments for the
+following command. Do not call them for any other reason.
@deffn Command universal-argument
This command reads input and specifies a prefix argument for the
call this command yourself unless you know what you are doing.
@end deffn
-@defun prefix-numeric-value arg
-This function returns the numeric meaning of a valid raw prefix argument
-value, @var{arg}. The argument may be a symbol, a number, or a list.
-If it is @code{nil}, the value 1 is returned; if it is any other symbol,
-the value @minus{}1 is returned. If it is a number, that number is
-returned; if it is a list, the @sc{car} of that list (which should be a
-number) is returned.
-@end defun
-
-@defvar current-prefix-arg
-This variable is the value of the raw prefix argument for the
-@emph{current} command. Commands may examine it directly, but the usual
-way to access it is with @code{(interactive "P")}.
-@end defvar
-
-@defvar prefix-arg
-The value of this variable is the raw prefix argument for the
-@emph{next} editing command. Commands that specify prefix arguments for
-the following command work by setting this variable.
-@end defvar
-
@node Recursive Editing
@section Recursive Editing
@cindex recursive command loop
@cindex recursive editing level
@cindex command loop, recursive
- The Emacs command loop is entered automatically when Emacs starts up.
-This top-level invocation of the command loop is never exited until the
-Emacs is killed. Lisp programs can also invoke the command loop. Since
-this makes more than one activation of the command loop, we call it
-@dfn{recursive editing}. A recursive editing level has the effect of
-suspending whatever command invoked it and permitting the user to do
-arbitrary editing before resuming that command.
+ The Emacs command loop is entered automatically when Emacs starts up.
+This top-level invocation of the command loop never exits; it keeps
+running as long as Emacs does. Lisp programs can also invoke the
+command loop. Since this makes more than one activation of the command
+loop, we call it @dfn{recursive editing}. A recursive editing level has
+the effect of suspending whatever command invoked it and permitting the
+user to do arbitrary editing before resuming that command.
The commands available during recursive editing are the same ones
available in the top-level editing loop and defined in the keymaps.
Only a few special commands exit the recursive editing level; the others
-return to the recursive editing level when finished. (The special
-commands for exiting are always available, but do nothing when recursive
-editing is not in progress.)
+return to the recursive editing level when they finish. (The special
+commands for exiting are always available, but they do nothing when
+recursive editing is not in progress.)
All command loops, including recursive ones, set up all-purpose error
handlers so that an error in a command run from the command loop will
Most applications should not use recursive editing, except as part of
using the minibuffer. Usually it is more convenient for the user if you
change the major mode of the current buffer temporarily to a special
-major mode, which has a command to go back to the previous mode. (This
-technique is used by the @kbd{w} command in Rmail.) Or, if you wish to
+major mode, which should have a command to go back to the previous mode.
+(The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
give the user different text to edit ``recursively'', create and select
a new buffer in a special mode. In this mode, define a command to
complete the processing and go back to the previous buffer. (The
@example
(defun simple-rec ()
(forward-word 1)
- (message "Recursive edit in progress.")
+ (message "Recursive edit in progress")
(recursive-edit)
(forward-word 1))
@result{} simple-rec
@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
The low-level mechanism for disabling a command is to put a
non-@code{nil} @code{disabled} property on the Lisp symbol for the
command. These properties are normally set up by the user's
-@file{.emacs} file with Lisp expressions such as this:
+init file (@pxref{Init File}) with Lisp expressions such as this:
@example
(put 'upcase-region 'disabled t)
@end example
@noindent
-For a few commands, these properties are present by default and may be
-removed by the @file{.emacs} file.
+For a few commands, these properties are present by default (you can
+remove them in your init file if you wish).
- If the value of the @code{disabled} property is a string, that string
-is included in the message printed when the command is used:
+ If the value of the @code{disabled} property is a string, the message
+saying the command is disabled includes that string. For example:
@example
(put 'delete-region 'disabled
programs.
@deffn Command enable-command command
-Allow @var{command} to be executed without special confirmation from now
-on. The user's @file{.emacs} file is optionally altered so that this
-will apply to future sessions.
+Allow @var{command} (a symbol) to be executed without special
+confirmation from now on, and alter the user's init file (@pxref{Init
+File}) so that this will apply to future sessions.
@end deffn
@deffn Command disable-command command
-Require special confirmation to execute @var{command} from now on. The
-user's @file{.emacs} file is optionally altered so that this will apply
-to future sessions.
+Require special confirmation to execute @var{command} from now on, and
+alter the user's init file so that this will apply to future sessions.
@end deffn
-@defvar disabled-command-hook
-This variable is a normal hook that is run instead of a disabled command,
-when the user runs the disabled command interactively. The hook functions
-can use @code{this-command-keys} to determine what the user typed to run
-the command, and thus find the command itself.
+@defvar disabled-command-function
+The value of this variable should be a function. When the user
+invokes a disabled command interactively, this function is called
+instead of the disabled command. It can use @code{this-command-keys}
+to determine what the user typed to run the command, and thus find the
+command itself.
+
+The value may also be @code{nil}. Then all commands work normally,
+even disabled ones.
-By default, @code{disabled-command-hook} contains a function that asks
-the user whether to proceed.
+By default, the value is a function that asks the user whether to
+proceed.
@end defvar
@node Command History
been executed, to make it convenient to repeat these commands. A
@dfn{complex command} is one for which the interactive argument reading
uses the minibuffer. This includes any @kbd{M-x} command, any
-@kbd{M-ESC} command, and any command whose @code{interactive}
+@kbd{M-:} command, and any command whose @code{interactive}
specification reads an argument from the minibuffer. Explicit use of
the minibuffer during the execution of the command itself does not cause
the command to be considered complex.
@defvar command-history
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 all but
-the first (most recent) thirty elements are deleted when a garbage
-collection takes place (@pxref{Garbage Collection}).
+complex commands for the duration of the editing session, but when it
+reaches the maximum size (@pxref{Minibuffer History}), the oldest
+elements are deleted as new ones are added.
@example
@group
previous commands. The commands @code{repeat-complex-command}, and
@code{list-command-history} are described in the user manual
(@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the
-minibuffer, the history commands used are the same ones available in any
-minibuffer.
+minibuffer, the usual minibuffer history commands are available.
@node Keyboard Macros
@section Keyboard Macros
@cindex keyboard macros
A @dfn{keyboard macro} is a canned sequence of input events that can
-be considered a command and made the definition of a key. Don't confuse
-keyboard macros with Lisp macros (@pxref{Macros}).
-
-@defun execute-kbd-macro macro &optional count
-This function executes @var{macro} as a sequence of events. If
-@var{macro} is a string or vector, then the events in it are executed
+be considered a command and made the definition of a key. The Lisp
+representation of a keyboard macro is a string or vector containing the
+events. Don't confuse keyboard macros with Lisp macros
+(@pxref{Macros}).
+
+@defun execute-kbd-macro kbdmacro &optional count loopfunc
+This function executes @var{kbdmacro} as a sequence of events. If
+@var{kbdmacro} is a string or vector, then the events in it are executed
exactly as if they had been input by the user. The sequence is
@emph{not} expected to be a single key sequence; normally a keyboard
macro definition consists of several key sequences concatenated.
-If @var{macro} is a symbol, then its function definition is used in
-place of @var{macro}. If that is another symbol, this process repeats.
+If @var{kbdmacro} is a symbol, then its function definition is used in
+place of @var{kbdmacro}. If that is another symbol, this process repeats.
Eventually the result should be a string or vector. If the result is
not a symbol, string, or vector, an error is signaled.
-The argument @var{count} is a repeat count; @var{macro} is executed that
-many times. If @var{count} is omitted or @code{nil}, @var{macro} is
-executed once. If it is 0, @var{macro} is executed over and over until it
-encounters an error or a failing search.
-@end defun
+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.
-@defvar last-kbd-macro
-This variable is the definition of the most recently defined keyboard
-macro. Its value is a string or vector, or @code{nil}.
-@end defvar
+If @var{loopfunc} is non-@code{nil}, it is a function that is called,
+without arguments, prior to each iteration of the macro. If
+@var{loopfunc} returns @code{nil}, then this stops execution of the macro.
-@defvar executing-macro
+@xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
+@end defun
+
+@defvar executing-kbd-macro
This variable contains the string or vector that defines the keyboard
macro that is currently executing. It is @code{nil} if no macro is
-currently executing.
+currently executing. A command can test this variable so as to behave
+differently when run from an executing macro. Do not set this variable
+yourself.
@end defvar
@defvar defining-kbd-macro
-This variable indicates whether a keyboard macro is being defined. It
-is set to @code{t} by @code{start-kbd-macro}, and @code{nil} by
-@code{end-kbd-macro}. You can use this variable to make a command
-behave differently when run from a keyboard macro (perhaps indirectly by
-calling @code{interactive-p}). However, do not set this variable
-yourself.
+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.
+
+The variable is always local to the current terminal and cannot be
+buffer-local. @xref{Multiple Displays}.
@end defvar
-@ignore @c It's hard to make this format ok.
- The user-level commands for defining, running and editing keyboard
-macros include @code{call-last-kbd-macro}, @code{insert-kbd-macro},
-@code{start-kbd-macro}, @code{end-kbd-macro}, @code{kbd-macro-query},
-and @code{name-last-kbd-macro}.
-@end ignore
+@defvar last-kbd-macro
+This variable is the definition of the most recently defined keyboard
+macro. Its value is a string or vector, or @code{nil}.
-@c Broke paragraph to prevent overfull hbox. --rjc 15mar92
- The commands are described in the user's manual (@pxref{Keyboard
-Macros,,, emacs, The GNU Emacs Manual}).
+The variable is always local to the current terminal and cannot be
+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