@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
* 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.
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
supply if the command inquires which events were used to invoke it.
@end defun
-@defun command-execute command &optional record-flag keys
+@defun command-execute command &optional record-flag keys special
@cindex keyboard macro execution
This function executes @var{command}. The argument @var{command} must
satisfy the @code{commandp} predicate; i.e., it must be an interactively
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
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 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}).
+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
+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
@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.
@xref{Input Focus}.
@end defvar
+@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.
+
+ 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
@section Input Events
@cindex events
@item meta
The
@tex
-$2^{27}$
+@math{2^{27}}
@end tex
-@ifinfo
+@ifnottex
2**27
-@end ifinfo
+@end ifnottex
bit in the character code indicates a character
typed with the meta key held down.
@item control
The
@tex
-$2^{26}$
+@math{2^{26}}
@end tex
-@ifinfo
+@ifnottex
2**26
-@end ifinfo
-bit in the character code indicates a non-@sc{ASCII}
+@end ifnottex
+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
@tex
-$2^{26}$
+@math{2^{26}}
@end tex
-@ifinfo
+@ifnottex
2**26
-@end ifinfo
-(assuming the terminal supports non-@sc{ASCII}
+@end ifnottex
+(assuming the terminal supports non-@sc{ascii}
control characters).
@item shift
The
@tex
-$2^{25}$
+@math{2^{25}}
@end tex
-@ifinfo
+@ifnottex
2**25
-@end ifinfo
-bit in the character code indicates an @sc{ASCII} control
+@end ifnottex
+bit in the character code indicates an @sc{ascii} control
character typed with the shift key held down.
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
+@sc{ascii} character set whenever possible, Emacs avoids using the
@tex
-$2^{25}$
+@math{2^{25}}
@end tex
-@ifinfo
+@ifnottex
2**25
-@end ifinfo
+@end ifnottex
bit for those characters.
-However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
+However, @sc{ascii} provides no way to distinguish @kbd{C-A} from
@kbd{C-a}, so Emacs uses the
@tex
-$2^{25}$
+@math{2^{25}}
@end tex
-@ifinfo
+@ifnottex
2**25
-@end ifinfo
+@end ifnottex
bit in @kbd{C-A} and not in
@kbd{C-a}.
@item hyper
The
@tex
-$2^{24}$
+@math{2^{24}}
@end tex
-@ifinfo
+@ifnottex
2**24
-@end ifinfo
+@end ifnottex
bit in the character code indicates a character
typed with the hyper key held down.
@item super
The
@tex
-$2^{23}$
+@math{2^{23}}
@end tex
-@ifinfo
+@ifnottex
2**23
-@end ifinfo
+@end ifnottex
bit in the character code indicates a character
typed with the super key held down.
@item alt
The
@tex
-$2^{22}$
+@math{2^{22}}
@end tex
-@ifinfo
+@ifnottex
2**22
-@end ifinfo
+@end ifnottex
bit in the character code indicates a character typed with
the alt key held down. (On some terminals, the key labeled @key{ALT}
is actually the meta key.)
@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.
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
@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 generates special @dfn{repeat} mouse
(not a repeat event), the value is 1.
@end defun
-@defvar double-click-time
+@defvar double-click-fuzz
To generate repeat events, successive mouse button presses must be at
-the same screen position, and the number of milliseconds between
+approximately the same screen position. The value of
+@code{double-click-fuzz} specifies the maximum number of pixels the
+mouse may be moved between two successive clicks to make a
+double-click.
+@end defvar
+
+@defvar double-click-time
+To generate repeat events, the number of milliseconds between
successive button presses must be less than the value of
@code{double-click-time}. Setting @code{double-click-time} to
@code{nil} disables multi-click detection entirely. Setting it to
@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
a mouse button or motion event.
position such events have.
@end defun
+@cindex mouse position list, accessing
These five functions take a position list as described above, and
return various parts of it.
@var{x} and @var{y} values actually found in @var{position}.
@end defun
+@cindex mouse event, timestamp
+@cindex timestamp of a mouse event
@defun posn-timestamp position
Return the timestamp in @var{position}.
@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
characters. Now the flag that represents the Meta modifier in a
character is
@tex
-$2^{27}$
+@math{2^{27}}
@end tex
-@ifinfo
+@ifnottex
2**27
-@end ifinfo
+@end ifnottex
and such numbers cannot be included in a string.
To support programs with @samp{\M-} in string constants, there are
@item
The meta variants of those characters, with codes in the range of
@tex
-$2^{27}$
+@math{2^{27}}
@end tex
-@ifinfo
+@ifnottex
2**27
-@end ifinfo
+@end ifnottex
to
@tex
-$2^{27} + 127$,
+@math{2^{27} + 127},
@end tex
-@ifinfo
+@ifnottex
2**27+127,
-@end ifinfo
+@end ifnottex
can also go in the string, but you must change their
numeric values. You must set the
@tex
-$2^{7}$
+@math{2^{7}}
@end tex
-@ifinfo
+@ifnottex
2**7
-@end ifinfo
+@end ifnottex
bit instead of the
@tex
-$2^{27}$
+@math{2^{27}}
@end tex
-@ifinfo
+@ifnottex
2**27
-@end ifinfo
+@end ifnottex
bit, resulting in a value between 128 and 255. Only a unibyte string
can include these codes.
@item
-Non-@sc{ASCII} characters above 256 can be included in a multibyte string.
+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
@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
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 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{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.
+``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, you get two events, like this:
@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
+@cindex reading a single event
+@cindex event, reading only one
The lowest level functions for command input are those that read a
single event.
-@defun read-event &optional prompt suppress-input-method
+@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.
-If @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 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{suppress-input-method} is non-@code{nil}, then the current input
-method is disabled for reading this event. If you want to read an event
-without input-method processing, always do it this way; don't try binding
-@code{input-method-function} (see below).
+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
@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
- @code{read-event} also invokes the current input method, if any. 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 event as an argument.
+@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
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
+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.
@code{nil} first, to prevent recursion.
The input method function is not called when reading the second and
-subsequent event of a key sequence. Thus, these characters are not
-subject to input method processing. It is usually a good idea for the
-input method processing to 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.
+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
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}.
@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
this variable.
@end defvar
-@tindex last-prefix-arg
@defvar last-prefix-arg
The raw prefix argument value used by the previous command.
@end defvar
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