Commit f142f62a authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

*** empty log message ***

parent 4d4cd289
@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 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
......@@ -39,42 +39,46 @@ calling the function @code{read-key-sequence}. Your Lisp code can also
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.
@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.
@end defvar
@node Defining Commands
......@@ -108,12 +112,12 @@ makes a Lisp function an interactively-callable command.
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
......@@ -172,7 +176,7 @@ existing buffer followed by a new name to give to that buffer:
@end smallexample
@cindex @samp{*} in interactive
@kindex buffer-read-only
@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.
......@@ -222,6 +226,9 @@ This code letter computes an argument without reading any input.
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.
......@@ -266,7 +273,7 @@ Completion, 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
......@@ -280,13 +287,10 @@ 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
@var{n} events that are lists, the @var{n}th @samp{e} provides the
@var{n}th such 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.
@item f
A file name of an existing file (@pxref{File Names}). The default
directory is @code{default-directory}. Existing, Completion, Default,
......@@ -306,7 +310,7 @@ This kind of input is used by commands such as @code{describe-key} and
@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 n
A number read with the minibuffer. If the input is not a number, the
......@@ -315,8 +319,8 @@ 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 raw prefix argument. If the prefix argument is @code{nil}, then
read a number as with @kbd{n}. Requires a number. Prompt.
@item p
@cindex numeric prefix argument usage
......@@ -429,9 +433,10 @@ 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}, compiled 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}.
......@@ -461,7 +466,7 @@ an argument. @xref{Command History}.
@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.
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
......@@ -482,9 +487,9 @@ This function reads a command name from the minibuffer using
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?
......@@ -512,11 +517,11 @@ 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.
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.
The usual application 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
......@@ -569,9 +574,9 @@ 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 specifies a prefix argument
for the following command.
@end defvar
@defvar this-command
......@@ -580,17 +585,17 @@ This variable records the name of the command now being executed by
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 specifies 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 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.
@end defvar
If you do not want a particular command to be recognized as the previous
......@@ -625,7 +630,7 @@ if all those events were characters. @xref{Input Events}.
@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.
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.
......@@ -640,7 +645,7 @@ character to insert.
@example
@group
last-command-char
last-command-event
;; @r{Now type @kbd{C-u C-x C-e}.}
@result{} 5
@end group
......@@ -666,9 +671,9 @@ frame, the value is the frame to which the event was redirected.
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.
key (such as @kbd{C-x}) and then delays this many seconds before
continuing, the prefix key is echoed in the echo area. Any subsequent
characters in the same command will be echoed as well.
If the value is zero, then command input is not echoed.
@end defvar
......@@ -683,16 +688,6 @@ represent keyboard or mouse activity. The events for keyboard activity
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.
@end defun
......@@ -700,6 +695,7 @@ This function returns non-@code{nil} if @var{event} is an input event.
@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.
......@@ -720,7 +716,9 @@ This function returns non-@code{nil} if @var{event} is an input event.
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.
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}.
@cindex modifier bits (of input character)
@cindex basic code (of input character)
......@@ -756,7 +754,7 @@ 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
@kbd{C-a}, so Emacs uses the 2**21 bit in @kbd{C-A} and not in
@kbd{C-a}.
@item hyper
......@@ -785,13 +783,12 @@ function @code{event-modifiers} (@pxref{Classifying Events}).
@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.
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
function keys:
......@@ -801,15 +798,16 @@ function keys:
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. 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 @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}.
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} 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}
converts into the character code 127 (@key{DEL}), not into code 8
......@@ -845,9 +843,31 @@ The super modifier.
@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).
@kbd{M-@key{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
......@@ -860,18 +880,17 @@ this form:
@example
(@var{event-type}
(@var{window} @var{buffer-pos}
(@var{x} . @var{y}) @var{timestamp})
(@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp})
@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
......@@ -882,30 +901,29 @@ describe events by their types; thus, if there is a key binding for
@code{mouse-1}, that binding would apply to all events whose
@var{event-type} is @code{mouse-1}.
@item window
@item @var{window}
This is the window in which the click occurred.
@item x
@itemx y
@item @var{x}, @var{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 buffer-pos
@item @var{buffer-pos}
This is the buffer position of the character clicked on.
@item timestamp
@item @var{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.)
@item click-count
@item @var{click-count}
This is the number of rapid repeated presses so far of the same mouse
button. @xref{Repeat Events}.
@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.
The meanings of @var{buffer-pos}, @var{x} and @var{y} are somewhat
different when the event location is in a special part of the screen,
such as the mode line or a 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
......@@ -917,8 +935,8 @@ 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.
@var{y} does not have meaningful data. For the vertical line, @var{x}
does not have meaningful data.
@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
......@@ -939,10 +957,8 @@ position and the final position, like this:
@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
......@@ -972,10 +988,10 @@ click from a drag until the button is released.
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
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
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,
......@@ -983,10 +999,7 @@ 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
@xref{Motion Events}.
@end ifinfo
until the button is released. @xref{Motion Events}.
@node Repeat Events
@subsection Repeat Events
......@@ -995,8 +1008,8 @@ until the button is released.
@cindex triple-click events
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
......@@ -1004,7 +1017,7 @@ happens when you release the button (as is normal for all click
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
......@@ -1012,14 +1025,14 @@ 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
......@@ -1029,11 +1042,12 @@ has no binding, Emacs looks for an alternate binding as if the event
were an ordinary click.
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
......@@ -1046,11 +1060,11 @@ these events contain @samp{triple} instead of @samp{double}. If any
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
......@@ -1061,9 +1075,9 @@ the value is 3 or greater. If @var{event} is an ordinary mouse event
@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
To generate repeat events, successive mouse button presses must be at
the same screen position, and 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
......@@ -1081,8 +1095,7 @@ represented by lists that look like this:
@example
(mouse-movement
(@var{window} @var{buffer-pos}
(@var{x} . @var{y}) @var{timestamp}))
(@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
......@@ -1099,8 +1112,8 @@ 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.
Typically, @var{body} should return when it sees the click event, and
discard that event.
@end defspec
@node Focus Events
......@@ -1123,14 +1136,14 @@ Focus events are represented in Lisp as lists that look like this:
@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 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
......@@ -1150,7 +1163,7 @@ location, that generates a sequence of events like this:
(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:
......@@ -1160,9 +1173,9 @@ 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))
......@@ -1186,7 +1199,7 @@ list. Thus, the event type is always a symbol or a character.
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,
......@@ -1196,11 +1209,16 @@ regardless of which other key or mouse button was used.
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}.