@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
* Command Loop Info:: Variables set by the command loop for you to examine.
* 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.
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, but that is all it
-does.
+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.
@node Defining Commands
@section Defining Commands
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 @sc{ASCII} characters, do not count where @samp{e} is concerned.
+and @sc{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
@cindex marker argument
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.
@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
@item x
A Lisp object, specified with its read syntax, terminated with a
-@key{LFD} or @key{RET}. The object is not evaluated. @xref{Object from
+@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
@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
Returns @code{t} if @var{object} is suitable for calling interactively;
(non-@code{nil} fourth argument to @code{autoload}), and some of the
primitive functions.
-A symbol is @code{commandp} if its function definition is
+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
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} is not a function or if it cannot
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.
@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 keyboard macro.
+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
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{keys}, if given, specifies the sequence of events to
+supply if the command inquires which events were used to invoke it.
+
+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
directly from the editor command loop.) 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
+ The most common use 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:
+ For example:
@example
@group
(defun foo ()
(interactive)
- (and (interactive-p)
- (message "foo")))
+ (when (interactive-p)
+ (message "foo")))
@result{} foo
@end group
@result{} (nil t)
@end group
@end example
-@end defun
+
+ The other way to do this sort of job is to make the command take an
+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 how:
+
+@example
+(defun foo (&optional print-message)
+ (interactive "p")
+ (when print-message
+ (message "foo")))
+@end example
+
+ The numeric prefix argument, provided by @samp{p}, is never @code{nil}.
@node Command Loop Info
@comment node-name, next, previous, up
is a symbol with a function definition, but this is not guaranteed.
The value is copied from @code{this-command} when a command returns to
-the command loop, except when the command specifies a prefix argument
-for the following command.
+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
+@tindex real-last-command
+@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
@cindex current command
This variable records the name of the command now being executed by
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 specifies a prefix argument for the following
+(unless the command specified a prefix argument for the following
command).
@cindex kill command repetition
(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.
+
@defun this-command-keys
This function returns a string or vector containing the key sequence
that invoked the present command, plus any previous commands that
@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 do never 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
+This function empties out the table of events for
+@code{this-command-keys} to return. This is useful after reading a
+password, to prevent the password from echoing inadvertently as part of
+the next command in certain cases.
+@end defun
+
@defvar last-nonmenu-event
-This variable holds the last input event read as part of a key
-sequence, not counting 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
@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 @sc{ascii} code for @kbd{C-e}.
The alias @code{last-command-char} exists for compatibility with
Emacs version 18.
describes the representation and meaning of input events in detail.
@defun eventp object
-This function returns non-@code{nil} if @var{object} 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
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. The event
-type of a character event is the character itself (an integer);
-see @ref{Classifying 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
-@iftex
-$2^{27}$
-@end iftex
+@tex
+@math{2^{27}}
+@end tex
@ifinfo
2**27
@end ifinfo
@item control
The
-@iftex
-$2^{26}$
-@end iftex
+@tex
+@math{2^{26}}
+@end tex
@ifinfo
2**26
@end ifinfo
-bit in the character code indicates a non-@sc{ASCII}
+bit in the character code indicates a non-@sc{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 @sc{ascii}, such as
@kbd{%} with the control key, the numeric value you get is the code
for @kbd{%} plus
-@iftex
-$2^{26}$
-@end iftex
+@tex
+@math{2^{26}}
+@end tex
@ifinfo
2**26
@end ifinfo
-(assuming the terminal supports non-@sc{ASCII}
+(assuming the terminal supports non-@sc{ascii}
control characters).
@item shift
The
-@iftex
-$2^{25}$
-@end iftex
+@tex
+@math{2^{25}}
+@end tex
@ifinfo
2**25
@end ifinfo
-bit in the character code indicates an @sc{ASCII} control
+bit in the character code indicates an @sc{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
-@iftex
-$2^{25}$
-@end iftex
+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
+@sc{ascii} character set whenever possible, Emacs avoids using the
+@tex
+@math{2^{25}}
+@end tex
@ifinfo
2**25
@end ifinfo
bit for those characters.
-However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
+However, @sc{ascii} provides no way to distinguish @kbd{C-A} from
@kbd{C-a}, so Emacs uses the
-@iftex
-$2^{25}$
-@end iftex
+@tex
+@math{2^{25}}
+@end tex
@ifinfo
2**25
@end ifinfo
@item hyper
The
-@iftex
-$2^{24}$
-@end iftex
+@tex
+@math{2^{24}}
+@end tex
@ifinfo
2**24
@end ifinfo
@item super
The
-@iftex
-$2^{23}$
-@end iftex
+@tex
+@math{2^{23}}
+@end tex
@ifinfo
2**23
@end ifinfo
@item alt
The
-@iftex
-$2^{22}$
-@end iftex
+@tex
+@math{2^{22}}
+@end tex
@ifinfo
2**22
@end ifinfo
@cindex function keys
Most keyboards also have @dfn{function keys}---keys that 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, in lower
+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.
@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 @sc{ascii} control characters that have
special keys on most keyboards.
-In @sc{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the
+In @sc{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}.
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 @sc{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{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
Keypad PF 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 non-keypad keys @code{home}, @code{left}, @dots{}
+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.
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{y} does not have meaningful data. For the vertical line, @var{x}
-does not have meaningful data.
+the symbol @code{mode-line}, @code{header-line}, or
+@code{vertical-line}. For the mode line, @var{y} does not have
+meaningful data. For the vertical line, @var{x} does not have
+meaningful data.
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
@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-}.
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 therefore the Emacs command
-loop as well, 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. @xref{Motion Events}.
+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}.
@node Repeat Events
@subsection Repeat 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.
-Typically, @var{body} should return when it sees the click event, and
-discard that event.
-@end defspec
+appear. @xref{Mouse Tracking}.
@node Focus Events
@subsection Focus Events
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{mouse-wheel} event
+@item (mouse-wheel @var{position} @var{delta})
+This kind of event is generated by moving a wheel on a mouse (such as
+the MS Intellimouse). Its effect is typically a kind of scroll or zoom.
+
+The element @var{delta} describes the amount and direction of the wheel
+rotation. Its absolute value is the number of increments by which the
+wheel was rotated. A negative @var{delta} indicates that the wheel was
+rotated backwards, towards the user, and a positive @var{delta}
+indicates that the wheel was rotated forward, away from the user.
+
+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.
+
+@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.
@end table
If one of these events arrives in the middle of a key sequence---that
a mouse button or motion event.
These two functions return the starting or ending position of a
-mouse-button event. The position is a list of this form:
+mouse-button event, as a list of this form:
@example
(@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp})
position such events have.
@end defun
- These five functions take a position as described above, and return
-various parts of it.
+ These five 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.
Return the timestamp in @var{position}.
@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
(- (point-max) (point-min))))
@end example
-Recall that scroll bar events have two integers forming ratio in place
+Recall that scroll bar events have two integers forming a ratio, in place
of a pair of x and y coordinates.
@end defun
string as containing text characters---the same kind of characters found
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
-@iftex
-$2^{27}$
-@end iftex
+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
+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
+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
@ifinfo
2**27
@end ifinfo
-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.
+and such numbers cannot be included in a string.
- We provide backward compatibility to run those programs using special
-rules for how to put a keyboard character event in a string. Here are
-the rules:
+ 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
@item
The meta variants of those characters, with codes in the range of
-@iftex
-$2^{27}$
-@end iftex
+@tex
+@math{2^{27}}
+@end tex
@ifinfo
2**27
@end ifinfo
to
-@iftex
-$2^{27} + 127$,
-@end iftex
+@tex
+@math{2^{27} + 127},
+@end tex
@ifinfo
2**27+127,
@end ifinfo
can also go in the string, but you must change their
numeric values. You must set the
-@iftex
-$2^{7}$
-@end iftex
+@tex
+@math{2^{7}}
+@end tex
@ifinfo
2**7
@end ifinfo
bit instead of the
-@iftex
-$2^{27}$
-@end iftex
+@tex
+@math{2^{27}}
+@end tex
@ifinfo
2**27
@end ifinfo
-bit,
-resulting in a value between 128 and 255.
+bit, resulting in a value between 128 and 255. Only a unibyte string
+can include these codes.
+
+@item
+Non-@sc{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
-of keyboard input characters follow these rules. They construct vectors
+ 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
meta events in strings work consistently regardless of how they get into
the strings.
- 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.
-
- New programs can avoid dealing with these special compatibility rules
-by using vectors instead of strings for key sequences when there is any
-possibility that they might contain meta characters, and by using
-@code{listify-key-sequence} to access a string of events.
-
-@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.
-@end defun
+ 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
+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.
@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.
* Event Input Misc:: How to reread or throw away input events.
@end menu
@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.
events---characters, symbols, and lists. The elements of the string or
vector are the events in the key sequence.
-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}.
-
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}
When mouse events occur in special parts of a window, such as a mode
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
+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{mode-line},
+``prefix keys'', all of which are symbols: @code{mode-line},
@code{vertical-line}, @code{horizontal-scroll-bar} 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.
+@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, you get two events, like this:
(40 . 63) 5959987))]
@end example
+@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
+@tindex 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
The lowest level functions for command input are those that read a
single event.
-@defun read-event
+@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}
-prompts by echoing: 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-@sc{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.
+If @code{read-event} gets an event that is defined as a help character, 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:
@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 the character @kbd{1} (@sc{ASCII}
+In the first example, the user types the character @kbd{1} (@sc{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
@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{Note:} 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}. 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
@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 in octal.
+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.
Quitting is suppressed when the first character is read, so that the
user can enter a @kbd{C-g}. @xref{Quitting}.
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.
+input. See also the function @code{read-passwd} (@pxref{Reading a
+Password}).
@defvar unread-command-events
@cindex next input
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 needed because in some cases a function reads a event
+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.
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''.
@end defun
@defvar last-input-event
+@defvarx last-input-char
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, the Lisp program reads the character @kbd{1},
-@sc{ASCII} code 49. It becomes the value of @code{last-input-event},
+@sc{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}.
@end group
@end example
-@vindex last-input-char
The alias @code{last-input-char} exists for compatibility with
Emacs version 18.
@end defvar
@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.
+
+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
@var{seconds}. If the system doesn't support waiting fractions of a
second, you get an error if you specify nonzero @var{millisec}.
-@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
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
@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
@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.
+@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
- Do not call @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.
+@tindex last-prefix-arg
+@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
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, the message
saying the command is disabled includes that string. For example:
@deffn Command enable-command command
Allow @var{command} to be executed without special confirmation from now
-on, and (if the user confirms) alter the user's @file{.emacs} file so
-that this will apply to future sessions.
+on, and (if the user confirms) 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, and
-(if the user confirms) alter the user's @file{.emacs} file so that this
+(if the user confirms) alter the user's init file so that this
will apply to future sessions.
@end deffn
@defvar disabled-command-hook
-This normal hook is run instead of a disabled command, when the user
-invokes the disabled command interactively. The hook functions can use
+When the user invokes a disabled command interactively, this normal hook
+is run instead of the disabled command. 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. @xref{Hooks}.
@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 (specified by the variable
+@code{history-length}), 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
events. 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
+@defun execute-kbd-macro kbdmacro &optional count
+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
+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.
+
+@xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
@end defun
@defvar executing-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. A command can test this variable to behave
+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. A
-command can test this variable to behave differently while a macro is
-being defined. The commands @code{start-kbd-macro} and
+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