commands.texi 131 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
Glenn Morris's avatar
Glenn Morris committed
3
@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
@c See the file elisp.texi for copying conditions.
@node Command Loop, Keymaps, Minibuffers, Top
@chapter Command Loop
@cindex editor command loop
@cindex command loop

  When you run Emacs, it enters the @dfn{editor command loop} almost
immediately.  This loop reads key sequences, executes their definitions,
and displays the results.  In this chapter, we describe how these things
are done, and the subroutines that allow Lisp programs to do them.

@menu
* Command Overview::    How the command loop reads commands.
* Defining Commands::   Specifying how a function should read arguments.
* Interactive Call::    Calling a command, so that it will read arguments.
19
* Distinguish Interactive::     Making a command distinguish interactive calls.
Glenn Morris's avatar
Glenn Morris committed
20 21
* Command Loop Info::   Variables set by the command loop for you to examine.
* Adjusting Point::     Adjustment of point after a command.
Glenn Morris's avatar
Glenn Morris committed
22
* Input Events::        What input looks like when you read it.
Glenn Morris's avatar
Glenn Morris committed
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
* 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.
* Recursive Editing::   Entering a recursive edit,
                          and why you usually shouldn't.
* Disabling Commands::  How the command loop handles disabled commands.
* Command History::     How the command history is set up, and how accessed.
* Keyboard Macros::     How keyboard macros are implemented.
@end menu

@node Command Overview
@section Command Loop Overview

38 39 40 41 42 43 44
  The first thing the command loop must do is read a key sequence,
which is a sequence of input events that translates into a command.
It does this by calling the function @code{read-key-sequence}.  Lisp
programs can also call this function (@pxref{Key Sequence Input}).
They can also read input at a lower level with @code{read-key} or
@code{read-event} (@pxref{Reading One Event}), or discard pending
input with @code{discard-input} (@pxref{Event Input Misc}).
Glenn Morris's avatar
Glenn Morris committed
45 46 47 48 49 50 51 52

  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 it then calls.  This is done by the command
@code{execute-extended-command} (@pxref{Interactive Call}).

53 54 55 56 57 58 59 60 61 62 63 64 65
  Prior to executing the command, Emacs runs @code{undo-boundary} to
create an undo boundary.  @xref{Maintaining Undo}.

  To execute a command, Emacs first reads its arguments 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 function body of @code{find-file} does not
use the minibuffer, so if you call @code{find-file} as a function from
Lisp code, you must supply the file name string as an ordinary Lisp
Glenn Morris's avatar
Glenn Morris committed
66 67
function argument.

68 69 70
  If the command is a keyboard macro (i.e.@: a string or vector),
Emacs executes it using @code{execute-kbd-macro} (@pxref{Keyboard
Macros}).
Glenn Morris's avatar
Glenn Morris committed
71 72

@defvar pre-command-hook
73 74 75 76
This normal hook is run by the editor command loop before it executes
each command.  At that time, @code{this-command} contains the command
that is about to run, and @code{last-command} describes the previous
command.  @xref{Command Loop Info}.
Glenn Morris's avatar
Glenn Morris committed
77 78 79
@end defvar

@defvar post-command-hook
80 81 82 83 84 85 86 87 88
This normal hook is run by the editor command loop after it executes
each command (including commands terminated prematurely by quitting or
by errors).  At that time, @code{this-command} refers to the command
that just ran, and @code{last-command} refers to the command before
that.

This hook is also run when Emacs first enters the command loop (at
which point @code{this-command} and @code{last-command} are both
@code{nil}).
Glenn Morris's avatar
Glenn Morris committed
89 90 91 92
@end defvar

  Quitting is suppressed while running @code{pre-command-hook} and
@code{post-command-hook}.  If an error happens while executing one of
93 94 95
these hooks, it does not terminate execution of the hook; instead
the error is silenced and the function in which the error occurred
is removed from the hook.
Glenn Morris's avatar
Glenn Morris committed
96 97 98 99 100 101 102 103 104 105 106 107

  A request coming into the Emacs server (@pxref{Emacs Server,,,
emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard
command does.

@node Defining Commands
@section Defining Commands
@cindex defining commands
@cindex commands, defining
@cindex functions, making them interactive
@cindex interactive function

108 109 110 111 112 113 114 115 116
  The special form @code{interactive} turns a Lisp function into a
command.  The @code{interactive} form must be located at top-level in
the function body (usually as the first form in the body), or in the
@code{interactive-form} property of the function symbol.  When the
@code{interactive} form is located in the function body, it does
nothing when actually executed.  Its presence serves as a flag, which
tells the Emacs command loop that the function can be called
interactively.  The argument of the @code{interactive} form controls
the reading of arguments for an interactive call.
Glenn Morris's avatar
Glenn Morris committed
117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133

@menu
* Using Interactive::     General rules for @code{interactive}.
* Interactive Codes::     The standard letter-codes for reading arguments
                             in various ways.
* Interactive Examples::  Examples of how to read interactive arguments.
@end menu

@node Using Interactive
@subsection Using @code{interactive}
@cindex arguments, interactive entry

  This section describes how to write the @code{interactive} form that
makes a Lisp function an interactively-callable command, and how to
examine a command's @code{interactive} form.

@defspec interactive arg-descriptor
134 135 136 137 138
This special form declares that a function 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
how to compute the arguments to the command when the command is called
interactively.
Glenn Morris's avatar
Glenn Morris committed
139 140 141 142 143

A command may be called from Lisp programs like any other function, but
then the caller supplies the arguments and @var{arg-descriptor} has no
effect.

144
@cindex @code{interactive-form}, function property
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160
The @code{interactive} form must be located at top-level in the
function body, or in the function symbol's @code{interactive-form}
property (@pxref{Symbol Plists}).  It has its effect because the
command loop looks for it before calling the function
(@pxref{Interactive Call}).  Once the function is called, all its body
forms are executed; at this time, if the @code{interactive} form
occurs within the body, the form simply returns @code{nil} without
even evaluating its argument.

By convention, you should put the @code{interactive} form in the
function body, as the first top-level form.  If there is an
@code{interactive} form in both the @code{interactive-form} symbol
property and the function body, the former takes precedence.  The
@code{interactive-form} symbol property can be used to add an
interactive form to an existing function, or change how its arguments
are processed interactively, without redefining the function.
Glenn Morris's avatar
Glenn Morris committed
161 162 163 164 165 166 167 168 169 170 171
@end defspec

There are three possibilities for the argument @var{arg-descriptor}:

@itemize @bullet
@item
It may be omitted or @code{nil}; then the command is called with no
arguments.  This leads quickly to an error if the command requires one
or more arguments.

@item
172
It may be a string; its contents are a sequence of elements separated
173 174
by newlines, one for each argument@footnote{Some elements actually
supply two arguments.}.  Each element consists of a code character
175
(@pxref{Interactive Codes}) optionally followed by a prompt (which
176
some code characters use and some ignore).  Here is an example:
Glenn Morris's avatar
Glenn Morris committed
177 178

@smallexample
179
(interactive "P\nbFrobnicate buffer: ")
Glenn Morris's avatar
Glenn Morris committed
180 181 182
@end smallexample

@noindent
183 184 185 186 187
The code letter @samp{P} sets the command's first argument to the raw
command prefix (@pxref{Prefix Command Arguments}).  @samp{bFrobnicate
buffer: } prompts the user with @samp{Frobnicate buffer: } to enter
the name of an existing buffer, which becomes the second and final
argument.
Glenn Morris's avatar
Glenn Morris committed
188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203

@c Emacs 19 feature
The prompt string can use @samp{%} to include previous argument values
(starting with the first argument) in the prompt.  This is done using
@code{format} (@pxref{Formatting Strings}).  For example, here is how
you could read the name of an existing buffer followed by a new name to
give to that buffer:

@smallexample
@group
(interactive "bBuffer to rename: \nsRename buffer %s to: ")
@end group
@end smallexample

@cindex @samp{*} in @code{interactive}
@cindex read-only buffers in interactive
204
If @samp{*} appears at the beginning of the string, then an error is
Glenn Morris's avatar
Glenn Morris committed
205 206 207 208
signaled if the buffer is read-only.

@cindex @samp{@@} in @code{interactive}
@c Emacs 19 feature
209
If @samp{@@} appears at the beginning of the string, and if the key
Glenn Morris's avatar
Glenn Morris committed
210 211 212 213
sequence used to invoke the command includes any mouse events, then
the window associated with the first of those events is selected
before the command is run.

214 215 216 217 218 219 220 221 222 223 224 225 226 227 228
@cindex @samp{^} in @code{interactive}
@cindex shift-selection, and @code{interactive} spec
If @samp{^} appears at the beginning of the string, and if the command
was invoked through @dfn{shift-translation}, set the mark and activate
the region temporarily, or extend an already active region, before the
command is run.  If the command was invoked without shift-translation,
and the region is temporarily active, deactivate the region before the
command is run.  Shift-translation is controlled on the user level by
@code{shift-select-mode}; see @ref{Shift Selection,,, emacs, The GNU
Emacs Manual}.

You can use @samp{*}, @samp{@@}, and @code{^} together; the order does
not matter.  Actual reading of arguments is controlled by the rest of
the prompt string (starting with the first character that is not
@samp{*}, @samp{@@}, or @samp{^}).
Glenn Morris's avatar
Glenn Morris committed
229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344

@item
It may be a Lisp expression that is not a string; then it should be a
form that is evaluated to get a list of arguments to pass to the
command.  Usually this form will call various functions to read input
from the user, most often through the minibuffer (@pxref{Minibuffers})
or directly from the keyboard (@pxref{Reading Input}).

Providing point or the mark as an argument value is also common, but
if you do this @emph{and} read input (whether using the minibuffer or
not), be sure to get the integer values of point or the mark after
reading.  The current buffer may be receiving subprocess output; if
subprocess output arrives while the command is waiting for input, it
could relocate point and the mark.

Here's an example of what @emph{not} to do:

@smallexample
(interactive
 (list (region-beginning) (region-end)
       (read-string "Foo: " nil 'my-history)))
@end smallexample

@noindent
Here's how to avoid the problem, by examining point and the mark after
reading the keyboard input:

@smallexample
(interactive
 (let ((string (read-string "Foo: " nil 'my-history)))
   (list (region-beginning) (region-end) string)))
@end smallexample

@strong{Warning:} the argument values should not include any data
types that can't be printed and then read.  Some facilities save
@code{command-history} in a file to be read in the subsequent
sessions; if a command's arguments contain a data type that prints
using @samp{#<@dots{}>} syntax, those facilities won't work.

There are, however, a few exceptions: it is ok to use a limited set of
expressions such as @code{(point)}, @code{(mark)},
@code{(region-beginning)}, and @code{(region-end)}, because Emacs
recognizes them specially and puts the expression (rather than its
value) into the command history.  To see whether the expression you
wrote is one of these exceptions, run the command, then examine
@code{(car command-history)}.
@end itemize

@cindex examining the @code{interactive} form
@defun interactive-form function
This function returns the @code{interactive} form of @var{function}.
If @var{function} is an interactively callable function
(@pxref{Interactive Call}), the value is the command's
@code{interactive} form @code{(interactive @var{spec})}, which
specifies how to compute its arguments.  Otherwise, the value is
@code{nil}.  If @var{function} is a symbol, its function definition is
used.
@end defun

@node Interactive Codes
@comment  node-name,  next,  previous,  up
@subsection Code Characters for @code{interactive}
@cindex interactive code description
@cindex description for interactive codes
@cindex codes, interactive, description of
@cindex characters for interactive codes

  The code character descriptions below contain a number of key words,
defined here as follows:

@table @b
@item Completion
@cindex interactive completion
Provide completion.  @key{TAB}, @key{SPC}, and @key{RET} perform name
completion because the argument is read using @code{completing-read}
(@pxref{Completion}).  @kbd{?} displays a list of possible completions.

@item Existing
Require the name of an existing object.  An invalid name is not
accepted; the commands to exit the minibuffer do not exit if the current
input is not valid.

@item Default
@cindex default argument string
A default value of some sort is used if the user enters no text in the
minibuffer.  The default depends on the code character.

@item No I/O
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.

@item Special
This code character is meaningful only at the beginning of the
interactive string, and it does not look for a prompt or a newline.
It is a single, isolated character.
@end table

@cindex reading interactive arguments
  Here are the code character descriptions for use with @code{interactive}:

@table @samp
@item *
Signal an error if the current buffer is read-only.  Special.

@item @@
Select the window mentioned in the first mouse event in the key
sequence that invoked this command.  Special.

345 346 347 348 349 350 351
@item ^
If the command was invoked through shift-translation, set the mark and
activate the region temporarily, or extend an already active region,
before the command is run.  If the command was invoked without
shift-translation, and the region is temporarily active, deactivate
the region before the command is run.  Special.

Glenn Morris's avatar
Glenn Morris committed
352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483
@item a
A function name (i.e., a symbol satisfying @code{fboundp}).  Existing,
Completion, Prompt.

@item b
The name of an existing buffer.  By default, uses the name of the
current buffer (@pxref{Buffers}).  Existing, Completion, Default,
Prompt.

@item B
A buffer name.  The buffer need not exist.  By default, uses the name of
a recently used buffer other than the current buffer.  Completion,
Default, Prompt.

@item c
A character.  The cursor does not move into the echo area.  Prompt.

@item C
A command name (i.e., a symbol satisfying @code{commandp}).  Existing,
Completion, Prompt.

@item d
@cindex position argument
The position of point, as an integer (@pxref{Point}).  No I/O.

@item D
A directory name.  The default is the current default directory of the
current buffer, @code{default-directory} (@pxref{File Name Expansion}).
Existing, Completion, Default, Prompt.

@item e
The first or next mouse event in the key sequence that invoked the command.
More precisely, @samp{e} gets events that are lists, so you can look at
the data in the lists.  @xref{Input Events}.  No I/O.

You can use @samp{e} more than once in a single command's interactive
specification.  If the key sequence that invoked the command has
@var{n} events that are lists, the @var{n}th @samp{e} provides the
@var{n}th such event.  Events that are not lists, such as function keys
and @acronym{ASCII} characters, do not count where @samp{e} is concerned.

@item f
A file name of an existing file (@pxref{File Names}).  The default
directory is @code{default-directory}.  Existing, Completion, Default,
Prompt.

@item F
A file name.  The file need not exist.  Completion, Default, Prompt.

@item G
A file name.  The file need not exist.  If the user enters just a
directory name, then the value is just that directory name, with no
file name within the directory added.  Completion, Default, Prompt.

@item i
An irrelevant argument.  This code always supplies @code{nil} as
the argument's value.  No I/O.

@item k
A key sequence (@pxref{Key Sequences}).  This keeps reading events
until a command (or undefined command) is found in the current key
maps.  The key sequence argument is represented as a string or vector.
The cursor does not move into the echo area.  Prompt.

If @samp{k} reads a key sequence that ends with a down-event, it also
reads and discards the following up-event.  You can get access to that
up-event with the @samp{U} code character.

This kind of input is used by commands such as @code{describe-key} and
@code{global-set-key}.

@item K
A key sequence, whose definition you intend to change.  This works like
@samp{k}, except that it suppresses, for the last input event in the key
sequence, the conversions that are normally used (when necessary) to
convert an undefined key into a defined one.

@item m
@cindex marker argument
The position of the mark, as 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 has to try again.  @samp{n} never uses the prefix argument.
Prompt.

@item N
The numeric prefix argument; but if there is no prefix argument, read
a number as with @kbd{n}.  The value is always a number.  @xref{Prefix
Command Arguments}.  Prompt.

@item p
@cindex numeric prefix argument usage
The numeric prefix argument.  (Note that this @samp{p} is lower case.)
No I/O.

@item P
@cindex raw prefix argument usage
The raw prefix argument.  (Note that this @samp{P} is upper case.)  No
I/O.

@item r
@cindex region argument
Point and the mark, as two numeric arguments, smallest first.  This is
the only code letter that specifies two successive arguments rather than
one.  No I/O.

@item s
Arbitrary text, read in the minibuffer and returned as a string
(@pxref{Text from Minibuffer}).  Terminate the input with either
@kbd{C-j} or @key{RET}.  (@kbd{C-q} may be used to include either of
these characters in the input.)  Prompt.

@item S
An interned symbol whose name is read in the minibuffer.  Any whitespace
character terminates the input.  (Use @kbd{C-q} to include whitespace in
the string.)  Other characters that normally terminate a symbol (e.g.,
parentheses and brackets) do not do so here.  Prompt.

@item U
A key sequence or @code{nil}.  Can be used after a @samp{k} or
@samp{K} argument to get the up-event that was discarded (if any)
after @samp{k} or @samp{K} read a down-event.  If no up-event has been
discarded, @samp{U} provides @code{nil} as the argument.  No I/O.

@item v
A variable declared to be a user option (i.e., satisfying the
484
predicate @code{custom-variable-p}).  This reads the variable using
Glenn Morris's avatar
Glenn Morris committed
485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527
@code{read-variable}.  @xref{Definition of read-variable}.  Existing,
Completion, Prompt.

@item x
A Lisp object, specified with its read syntax, terminated with a
@kbd{C-j} or @key{RET}.  The object is not evaluated.  @xref{Object from
Minibuffer}.  Prompt.

@item X
@cindex evaluated expression argument
A Lisp form's value.  @samp{X} reads as @samp{x} does, then evaluates
the form so that its value becomes the argument for the command.
Prompt.

@item z
A coding system name (a symbol).  If the user enters null input, the
argument value is @code{nil}.  @xref{Coding Systems}.  Completion,
Existing, Prompt.

@item Z
A coding system name (a symbol)---but only if this command has a prefix
argument.  With no prefix argument, @samp{Z} provides @code{nil} as the
argument value.  Completion, Existing, Prompt.
@end table

@node Interactive Examples
@comment  node-name,  next,  previous,  up
@subsection Examples of Using @code{interactive}
@cindex examples of using @code{interactive}
@cindex @code{interactive}, examples of using

  Here are some examples of @code{interactive}:

@example
@group
(defun foo1 ()              ; @r{@code{foo1} takes no arguments,}
    (interactive)           ;   @r{just moves forward two words.}
    (forward-word 2))
     @result{} foo1
@end group

@group
(defun foo2 (n)             ; @r{@code{foo2} takes one argument,}
528 529 530
    (interactive "^p")      ;   @r{which is the numeric prefix.}
                            ; @r{under @code{shift-select-mode},}
                            ;   @r{will activate or extend region.}
Glenn Morris's avatar
Glenn Morris committed
531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566
    (forward-word (* 2 n)))
     @result{} foo2
@end group

@group
(defun foo3 (n)             ; @r{@code{foo3} takes one argument,}
    (interactive "nCount:") ;   @r{which is read with the Minibuffer.}
    (forward-word (* 2 n)))
     @result{} foo3
@end group

@group
(defun three-b (b1 b2 b3)
  "Select three existing buffers.
Put them into three windows, selecting the last one."
@end group
    (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
    (delete-other-windows)
    (split-window (selected-window) 8)
    (switch-to-buffer b1)
    (other-window 1)
    (split-window (selected-window) 8)
    (switch-to-buffer b2)
    (other-window 1)
    (switch-to-buffer b3))
     @result{} three-b
@group
(three-b "*scratch*" "declarations.texi" "*mail*")
     @result{} nil
@end group
@end example

@node Interactive Call
@section Interactive Call
@cindex interactive call

567 568 569
  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
Glenn Morris's avatar
Glenn Morris committed
570 571 572
@code{call-interactively}, which reads the arguments and calls the
command.  You can also call these functions yourself.

573 574 575 576
  Note that the term ``command'', in this context, refers to an
interactively callable function (or function-like object), or a
keyboard macro.  It does not refer to the key sequence used to invoke
a command (@pxref{Keymaps}).
Glenn Morris's avatar
Glenn Morris committed
577

578 579 580 581 582 583 584 585 586 587 588
@defun commandp object &optional for-call-interactively
This function returns @code{t} if @var{object} is a command.
Otherwise, it returns @code{nil}.

Commands include strings and vectors (which are treated as keyboard
macros), lambda expressions that contain a top-level
@code{interactive} form (@pxref{Using Interactive}), byte-code
function objects made from such lambda expressions, autoload objects
that are declared as interactive (non-@code{nil} fourth argument to
@code{autoload}), and some primitive functions.  Also, a symbol is
considered a command if it has a non-@code{nil}
589
@code{interactive-form} property, or if its function definition
590
satisfies @code{commandp}.
Glenn Morris's avatar
Glenn Morris committed
591 592 593 594 595 596 597 598 599 600 601

If @var{for-call-interactively} is non-@code{nil}, then
@code{commandp} returns @code{t} only for objects that
@code{call-interactively} could call---thus, not for keyboard macros.

See @code{documentation} in @ref{Accessing Documentation}, for a
realistic example of using @code{commandp}.
@end defun

@defun call-interactively command &optional record-flag keys
This function calls the interactively callable function @var{command},
602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627
providing arguments according to its interactive calling specifications.
It returns whatever @var{command} returns.

If, for instance, you have a function with the following signature:

@example
(defun foo (begin end)
  (interactive "r")
  ...)
@end example

then saying

@example
(call-interactively 'foo)
@end example

will call @code{foo} with the region (@code{point} and @code{mark}) as
the arguments.

An error is signaled if @var{command} is not a function or if it
cannot be called interactively (i.e., is not a command).  Note that
keyboard macros (strings and vectors) are not accepted, even though
they are considered commands, because they are not functions.  If
@var{command} is a symbol, then @code{call-interactively} uses its
function definition.
Glenn Morris's avatar
Glenn Morris committed
628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649

@cindex record command history
If @var{record-flag} is non-@code{nil}, then this command and its
arguments are unconditionally added to the list @code{command-history}.
Otherwise, the command is added only if it uses the minibuffer to read
an argument.  @xref{Command History}.

The argument @var{keys}, if given, should be a vector which specifies
the sequence of events to supply if the command inquires which events
were used to invoke it.  If @var{keys} is omitted or @code{nil}, the
default is the return value of @code{this-command-keys-vector}.
@xref{Definition of this-command-keys-vector}.
@end defun

@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
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
650 651
@code{call-interactively} (see above), along with the
@var{record-flag} and @var{keys} arguments.
Glenn Morris's avatar
Glenn Morris committed
652

653 654 655 656 657
If @var{command} is a symbol, its function definition is used in its
place.  A symbol with an @code{autoload} definition counts as a
command if it was declared to stand for an interactively callable
function.  Such a definition is handled by loading the specified
library and then rechecking the definition of the symbol.
Glenn Morris's avatar
Glenn Morris committed
658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696

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
@cindex read command name
This function reads a command name from the minibuffer using
@code{completing-read} (@pxref{Completion}).  Then it uses
@code{command-execute} to call the specified command.  Whatever that
command returns becomes the value of @code{execute-extended-command}.

@cindex execute with prefix argument
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?
@cindex @kbd{M-x}
@code{execute-extended-command} is the normal definition of @kbd{M-x},
so it uses the string @w{@samp{M-x }} as a prompt.  (It would be better
to take the prompt from the events used to invoke
@code{execute-extended-command}, but that is painful to implement.)  A
description of the value of the prefix argument, if any, also becomes
part of the prompt.

@example
@group
(execute-extended-command 3)
---------- Buffer: Minibuffer ----------
3 M-x forward-word RET
---------- Buffer: Minibuffer ----------
     @result{} t
@end group
@end example
@end deffn

697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721
@node Distinguish Interactive
@section Distinguish Interactive Calls

  Sometimes a command should display additional visual feedback (such
as an informative message in the echo area) for interactive calls
only.  There are three ways to do this.  The recommended way to test
whether the function was called using @code{call-interactively} is to
give it an optional argument @code{print-message} and use the
@code{interactive} spec to make it non-@code{nil} in interactive
calls.  Here's an example:

@example
(defun foo (&optional print-message)
  (interactive "p")
  (when print-message
    (message "foo")))
@end example

@noindent
We use @code{"p"} because the numeric prefix argument is never
@code{nil}.  Defined in this way, the function does display the
message when called from a keyboard macro.

  The above method with the additional argument is usually best,
because it allows callers to say ``treat this call as interactive.''
722
But you can also do the job by testing @code{called-interactively-p}.
723

Chong Yidong's avatar
Chong Yidong committed
724
@defun called-interactively-p kind
725 726
This function returns @code{t} when the calling function was called
using @code{call-interactively}.
Glenn Morris's avatar
Glenn Morris committed
727

Chong Yidong's avatar
Chong Yidong committed
728 729 730 731 732 733 734 735 736 737 738 739 740 741 742
The argument @var{kind} should be either the symbol @code{interactive}
or the symbol @code{any}.  If it is @code{interactive}, then
@code{called-interactively-p} returns @code{t} only if the call was
made directly by the user---e.g., if the user typed a key sequence
bound to the calling function, but @emph{not} if the user ran a
keyboard macro that called the function (@pxref{Keyboard Macros}).  If
@var{kind} is @code{any}, @code{called-interactively-p} returns
@code{t} for any kind of interactive call, including keyboard macros.

If in doubt, use @code{any}; the only known proper use of
@code{interactive} is if you need to decide whether to display a
helpful message while a function is running.

A function is never considered to be called interactively if it was
called via Lisp evaluation (or with @code{apply} or @code{funcall}).
Glenn Morris's avatar
Glenn Morris committed
743 744
@end defun

Chong Yidong's avatar
Chong Yidong committed
745 746
@noindent
Here is an example of using @code{called-interactively-p}:
Glenn Morris's avatar
Glenn Morris committed
747 748 749 750 751

@example
@group
(defun foo ()
  (interactive)
Chong Yidong's avatar
Chong Yidong committed
752 753 754
  (when (called-interactively-p 'any)
    (message "Interactive!")
    'foo-called-interactively))
Glenn Morris's avatar
Glenn Morris committed
755 756 757
@end group

@group
758
;; @r{Type @kbd{M-x foo}.}
Chong Yidong's avatar
Chong Yidong committed
759
     @print{} Interactive!
Glenn Morris's avatar
Glenn Morris committed
760 761 762
@end group

@group
763
(foo)
Chong Yidong's avatar
Chong Yidong committed
764
     @result{} nil
765 766 767
@end group
@end example

Chong Yidong's avatar
Chong Yidong committed
768 769 770
@noindent
Here is another example that contrasts direct and indirect calls to
@code{called-interactively-p}.
771 772 773 774 775

@example
@group
(defun bar ()
  (interactive)
Chong Yidong's avatar
Chong Yidong committed
776
  (message "%s" (list (foo) (called-interactively-p 'any))))
Glenn Morris's avatar
Glenn Morris committed
777 778 779 780
@end group

@group
;; @r{Type @kbd{M-x bar}.}
Chong Yidong's avatar
Chong Yidong committed
781
     @print{} (nil t)
Glenn Morris's avatar
Glenn Morris committed
782 783 784 785 786 787 788 789
@end group
@end example

@node Command Loop Info
@comment  node-name,  next,  previous,  up
@section Information from the Command Loop

The editor command loop sets several Lisp variables to keep status
790 791 792
records for itself and for commands that are run.  With the exception of
@code{this-command} and @code{last-command} it's generally a bad idea to
change any of these variables in a Lisp program.
Glenn Morris's avatar
Glenn Morris committed
793 794 795 796 797 798 799 800 801 802 803

@defvar last-command
This variable records the name of the previous command executed by the
command loop (the one before the current command).  Normally the value
is a symbol with a function definition, but this is not guaranteed.

The value is copied from @code{this-command} when a command returns to
the command loop, except when the command has specified a prefix
argument for the following command.

This variable is always local to the current terminal and cannot be
804
buffer-local.  @xref{Multiple Terminals}.
Glenn Morris's avatar
Glenn Morris committed
805 806 807 808 809 810 811
@end defvar

@defvar real-last-command
This variable is set up by Emacs just like @code{last-command},
but never altered by Lisp programs.
@end defvar

812 813 814 815 816 817
@defvar last-repeatable-command
This variable stores the most recently executed command that was not
part of an input event.  This is the command @code{repeat} will try to
repeat, @xref{Repeating,,, emacs, The GNU Emacs Manual}.
@end defvar

Glenn Morris's avatar
Glenn Morris committed
818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927
@defvar this-command
@cindex current command
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.

The command loop sets this variable just before running a command, and
copies its value into @code{last-command} when the command finishes
(unless the command specified a prefix argument for the following
command).

@cindex kill command repetition
Some commands set this variable during their execution, as a flag for
whatever command runs next.  In particular, the functions for killing text
set @code{this-command} to @code{kill-region} so that any kill commands
immediately following will know to append the killed text to the
previous kill.
@end defvar

If you do not want a particular command to be recognized as the previous
command in the case where it got an error, you must code that command to
prevent this.  One way is to set @code{this-command} to @code{t} at the
beginning of the command, and set @code{this-command} back to its proper
value at the end, like this:

@example
(defun foo (args@dots{})
  (interactive @dots{})
  (let ((old-this-command this-command))
    (setq this-command t)
    @r{@dots{}do the work@dots{}}
    (setq this-command old-this-command)))
@end example

@noindent
We do not bind @code{this-command} with @code{let} because that would
restore the old value in case of error---a feature of @code{let} which
in this case does precisely what we want to avoid.

@defvar this-original-command
This has the same value as @code{this-command} except when command
remapping occurs (@pxref{Remapping Commands}).  In that case,
@code{this-command} gives the command actually run (the result of
remapping), and @code{this-original-command} gives the command that
was specified to run but remapped into another command.
@end defvar

@defun this-command-keys
This function returns a string or vector containing the key sequence
that invoked the present command, plus any previous commands that
generated the prefix argument for this command.  Any events read by the
command using @code{read-event} without a timeout get tacked on to the end.

However, if the command has called @code{read-key-sequence}, it
returns the last read key sequence.  @xref{Key Sequence Input}.  The
value is a string if all events in the sequence were characters that
fit in a string.  @xref{Input Events}.

@example
@group
(this-command-keys)
;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
     @result{} "^U^X^E"
@end group
@end example
@end defun

@defun this-command-keys-vector
@anchor{Definition of this-command-keys-vector}
Like @code{this-command-keys}, except that it always returns the events
in a vector, so you don't need to deal with the complexities of storing
input events in a string (@pxref{Strings of Events}).
@end defun

@defun clear-this-command-keys &optional keep-record
This function empties out the table of events for
@code{this-command-keys} to return.  Unless @var{keep-record} is
non-@code{nil}, it also empties the records that the function
@code{recent-keys} (@pxref{Recording Input}) will subsequently return.
This is useful after reading a password, to prevent the password from
echoing inadvertently as part of the next command in certain cases.
@end defun

@defvar last-nonmenu-event
This variable holds the last input event read as part of a key sequence,
not counting events resulting from mouse menus.

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
@defvarx last-command-char
This variable is set to the last input event that was read by the
command loop as part of a command.  The principal use of this variable
is in @code{self-insert-command}, which uses it to decide which
character to insert.

@example
@group
last-command-event
;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
     @result{} 5
@end group
@end example

@noindent
The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.

928
The alias @code{last-command-char} is obsolete.
Glenn Morris's avatar
Glenn Morris committed
929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950
@end defvar

@c Emacs 19 feature
@defvar last-event-frame
This variable records which frame the last input event was directed to.
Usually this is the frame that was selected when the event was
generated, but if that frame has redirected input focus to another
frame, the value is the frame to which the event was redirected.
@xref{Input Focus}.

If the last event came from a keyboard macro, the value is @code{macro}.
@end defvar

@node Adjusting Point
@section Adjusting Point After Commands
@cindex adjusting point
@cindex invisible/intangible text, and point
@cindex @code{display} property, and point display
@cindex @code{composition} property, and point display

  It is not easy to display a value of point in the middle of a
sequence of text that has the @code{display}, @code{composition} or
951 952 953
is invisible.  Therefore, after a command finishes and returns to the
command loop, if point is within such a sequence, the command loop
normally moves point to the edge of the sequence.
Glenn Morris's avatar
Glenn Morris committed
954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994

  A command can inhibit this feature by setting the variable
@code{disable-point-adjustment}:

@defvar 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 those text
properties, and does not move point out of sequences that have them.

The command loop sets this variable to @code{nil} before each command,
so if a command sets it, the effect applies only to that command.
@end defvar

@defvar 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
@cindex input events

The Emacs command loop reads a sequence of @dfn{input events} that
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.

@defun eventp object
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
Glenn Morris's avatar
Glenn Morris committed
995 996
* Keyboard Events::             Ordinary characters--keys with symbols on them.
* Function Keys::               Function keys--keys with names, not symbols.
Glenn Morris's avatar
Glenn Morris committed
997
* Mouse Events::                Overview of mouse events.
Glenn Morris's avatar
Glenn Morris committed
998 999 1000
* 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.
Glenn Morris's avatar
Glenn Morris committed
1001
* Repeat Events::               Double and triple click (or drag, or down).
Glenn Morris's avatar
Glenn Morris committed
1002 1003
* Motion Events::               Just moving the mouse, not pushing a button.
* Focus Events::                Moving the mouse between frames.
Glenn Morris's avatar
Glenn Morris committed
1004
* Misc Events::                 Other events the system can generate.
Glenn Morris's avatar
Glenn Morris committed
1005 1006 1007 1008 1009
* Event Examples::              Examples of the lists for mouse events.
* Classifying Events::          Finding the modifier keys in an event symbol.
                                Event types.
* Accessing Mouse::             Functions to extract info from mouse events.
* Accessing Scroll::            Functions to get info from scroll bar events.
Glenn Morris's avatar
Glenn Morris committed
1010
* Strings of Events::           Special considerations for putting
Glenn Morris's avatar
Glenn Morris committed
1011
                                  keyboard character events in a string.
Glenn Morris's avatar
Glenn Morris committed
1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131
@end menu

@node Keyboard Events
@subsection Keyboard Events
@cindex keyboard events

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.  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
524287, plus any or all of these @dfn{modifier bits}:

@table @asis
@item meta
The
@tex
@math{2^{27}}
@end tex
@ifnottex
2**27
@end ifnottex
bit in the character code indicates a character
typed with the meta key held down.

@item control
The
@tex
@math{2^{26}}
@end tex
@ifnottex
2**26
@end ifnottex
bit in the character code indicates a non-@acronym{ASCII}
control character.

@sc{ascii} control characters such as @kbd{C-a} have special basic
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 @acronym{ASCII}, such as
@kbd{%} with the control key, the numeric value you get is the code
for @kbd{%} plus
@tex
@math{2^{26}}
@end tex
@ifnottex
2**26
@end ifnottex
(assuming the terminal supports non-@acronym{ASCII}
control characters).

@item shift
The
@tex
@math{2^{25}}
@end tex
@ifnottex
2**25
@end ifnottex
bit in the character code indicates an @acronym{ASCII} control
character typed with the shift key held down.

For letters, the basic code itself indicates upper versus lower case;
for digits and punctuation, the shift key selects an entirely different
character with a different basic code.  In order to keep within the
@acronym{ASCII} character set whenever possible, Emacs avoids using the
@tex
@math{2^{25}}
@end tex
@ifnottex
2**25
@end ifnottex
bit for those characters.

However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
@kbd{C-a}, so Emacs uses the
@tex
@math{2^{25}}
@end tex
@ifnottex
2**25
@end ifnottex
bit in @kbd{C-A} and not in
@kbd{C-a}.

@item hyper
The
@tex
@math{2^{24}}
@end tex
@ifnottex
2**24
@end ifnottex
bit in the character code indicates a character
typed with the hyper key held down.

@item super
The
@tex
@math{2^{23}}
@end tex
@ifnottex
2**23
@end ifnottex
bit in the character code indicates a character
typed with the super key held down.

@item alt
The
@tex
@math{2^{22}}
@end tex
@ifnottex
2**22
@end ifnottex
1132 1133 1134
bit in the character code indicates a character typed with the alt key
held down.  (The key labeled @key{Alt} on most keyboards is actually
treated as the meta key, not this.)
Glenn Morris's avatar
Glenn Morris committed
1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151
@end table

  It is best to avoid mentioning specific bit numbers in your program.
To test the modifier bits of a character, use the function
@code{event-modifiers} (@pxref{Classifying Events}).  When making key
bindings, you can use the read syntax for characters with modifier bits
(@samp{\C-}, @samp{\M-}, and so on).  For making key bindings with
@code{define-key}, you can use lists such as @code{(control hyper ?x)} to
specify the characters (@pxref{Changing Key Bindings}).  The function
@code{event-convert-list} converts such a list into an event type
(@pxref{Classifying Events}).

@node Function Keys
@subsection Function Keys

@cindex function keys
Most keyboards also have @dfn{function keys}---keys that have names or
1152 1153 1154 1155
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} generates
an input event represented by the symbol @code{f1}.
Glenn Morris's avatar
Glenn Morris committed
1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173

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:

@table @asis
@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
These keys correspond to common @acronym{ASCII} control characters that have
special keys on most keyboards.

In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character.  If the
terminal can distinguish between them, Emacs conveys the distinction to
Lisp programs by representing the former as the integer 9, and the
latter as the symbol @code{tab}.

Most of the time, it's not useful to distinguish the two.  So normally
1174 1175 1176 1177 1178
@code{local-function-key-map} (@pxref{Translation Keymaps}) 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.
Glenn Morris's avatar
Glenn Morris committed
1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287

In @acronym{ASCII}, @key{BS} is really @kbd{C-h}.  But @code{backspace}
converts into the character code 127 (@key{DEL}), not into code 8
(@key{BS}).  This is what most users prefer.

@item @code{left}, @code{up}, @code{right}, @code{down}
Cursor arrow keys
@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
Keypad keys (to the right of the regular keyboard).
@item @code{kp-0}, @code{kp-1}, @dots{}
Keypad keys with digits.
@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
Keypad PF keys.
@item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
Keypad arrow keys.  Emacs normally translates these into the
corresponding non-keypad keys @code{home}, @code{left}, @dots{}
@item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
Additional keypad duplicates of keys ordinarily found elsewhere.  Emacs
normally translates these into the like-named non-keypad keys.
@end table

You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
@key{META}, @key{SHIFT}, and @key{SUPER} with function keys.  The way to
represent them is with prefixes in the symbol name:

@table @samp
@item A-
The alt modifier.
@item C-
The control modifier.
@item H-
The hyper modifier.
@item M-
The meta modifier.
@item S-
The shift modifier.
@item s-
The super modifier.
@end table

Thus, the symbol for the key @key{F3} with @key{META} held down is
@code{M-f3}.  When you use more than one prefix, we recommend you
write them in alphabetical order; but the order does not matter in
arguments to the key-binding lookup and modification functions.

@node Mouse Events
@subsection Mouse Events

Emacs supports four kinds of mouse events: click events, drag events,
button-down events, and motion events.  All mouse events are represented
as lists.  The @sc{car} of the list is the event type; this says which
mouse button was involved, and which modifier keys were used with it.
The event type can also distinguish double or triple button presses
(@pxref{Repeat Events}).  The rest of the list elements give position
and time information.

For key lookup, only the event type matters: two events of the same type
necessarily run the same command.  The command can access the full
values of these events using the @samp{e} interactive code.
@xref{Interactive Codes}.

A key sequence that starts with a mouse event is read using the keymaps
of the buffer in the window that the mouse was in, not the current
buffer.  This does not imply that clicking in a window selects that
window or its buffer---that is entirely under the control of the command
binding of the key sequence.

@node Click Events
@subsection Click Events
@cindex click event
@cindex mouse click event

When the user presses a mouse button and releases it at the same
location, that generates a @dfn{click} event.  All mouse click event
share the same format:

@example
(@var{event-type} @var{position} @var{click-count})
@end example

@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 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
and super, just as you would with function keys.

This symbol also serves as the event type of the event.  Key bindings
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 @var{position}
This is the position where the mouse click occurred.  The actual
format of @var{position} depends on what part of a window was clicked
on.

For mouse click events in the text area, mode line, header line, or in
the marginal areas, @var{position} has this form:

@example
(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
 @var{object} @var{text-pos} (@var{col} . @var{row})
 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
@end example

1288 1289 1290 1291 1292
@noindent
The meanings of these list elements are documented below.
@xref{Accessing Mouse}, for functions that let you easily access these
elements.

Glenn Morris's avatar
Glenn Morris committed
1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303
@table @asis
@item @var{window}
This is the window in which the click occurred.

@item @var{pos-or-area}
This is the buffer position of the character clicked on in the text
area, or if clicked outside the text area, it is the window area in
which the click occurred.  It is one of the symbols @code{mode-line},
@code{header-line}, @code{vertical-line}, @code{left-margin},
@code{right-margin}, @code{left-fringe}, or @code{right-fringe}.

1304 1305 1306 1307
In one special case, @var{pos-or-area} is a list containing a symbol
(one of the symbols listed above) instead of just the symbol.  This
happens after the imaginary prefix keys for the event are registered
by Emacs.  @xref{Key Sequence Input}.
Glenn Morris's avatar
Glenn Morris committed
1308 1309

@item @var{x}, @var{y}
1310 1311 1312 1313 1314 1315 1316 1317 1318
These are the relative pixel coordinates of the click.  For clicks in
the text area of a window, the coordinate origin @code{(0 . 0)} is
taken to be the top left corner of the text area.  @xref{Window
Sizes}.  For clicks in a mode line or header line, the coordinate
origin is the top left corner of the window itself.  For fringes,
margins, and the vertical border, @var{x} does not have meaningful
data.  For fringes and margins, @var{y} is relative to the bottom edge
of the header line.  In all cases, the @var{x} and @var{y} coordinates
increase rightward and downward respectively.
Glenn Morris's avatar
Glenn Morris committed
1319 1320 1321 1322 1323

@item @var{timestamp}
This is the time at which the event occurred, in milliseconds.

@item @var{object}
1324 1325 1326
This is either @code{nil} if there is no string-type text property at
the click position, or a cons cell of the form (@var{string}
. @var{string-pos}) if there is one:
Glenn Morris's avatar
Glenn Morris committed
1327 1328 1329

@table @asis
@item @var{string}
1330
The string which was clicked on, including any properties.
Glenn Morris's avatar
Glenn Morris committed
1331 1332

@item @var{string-pos}
1333
The position in the string where the click occurred.
Glenn Morris's avatar
Glenn Morris committed
1334 1335 1336 1337 1338 1339 1340 1341 1342
@end table

@item @var{text-pos}
For clicks on a marginal area or on a fringe, this is the buffer
position of the first visible character in the corresponding line in
the window.  For other events, it is the current buffer position in
the window.

@item @var{col}, @var{row}
1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353
These are the actual column and row coordinate numbers of the glyph
under the @var{x}, @var{y} position.  If @var{x} lies beyond the last
column of actual text on its line, @var{col} is reported by adding
fictional extra columns that have the default character width.  Row 0
is taken to be the header line if the window has one, or the topmost
row of the text area otherwise.  Column 0 is taken to be the leftmost
column of the text area for clicks on a window text area, or the
leftmost mode line or header line column for clicks there.  For clicks
on fringes or vertical borders, these have no meaningful data.  For
clicks on margins, @var{col} is measured from the left edge of the
margin area and @var{row} is measured from the top of the margin area.
Glenn Morris's avatar
Glenn Morris committed
1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369

@item @var{image}
This is the image object on which the click occurred.  It is either
@code{nil} if there is no image at the position clicked on, or it is
an image object as returned by @code{find-image} if click was in an image.

@item @var{dx}, @var{dy}
These are the pixel coordinates of the click, relative to
the top left corner of @var{object}, which is @code{(0 . 0)}.  If
@var{object} is @code{nil}, the coordinates are relative to the top
left corner of the character glyph clicked on.

@item @var{width}, @var{height}
These are the pixel width and height of @var{object} or, if this is
@code{nil}, those of the character glyph clicked on.
@end table
1370

Glenn Morris's avatar
Glenn Morris committed
1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571
@sp 1
For mouse clicks on a scroll-bar, @var{position} has this form:

@example
(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
@end example

@table @asis
@item @var{window}
This is the window whose scroll-bar was clicked on.

@item @var{area}
This is the scroll bar where the click occurred.  It is one of the
symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.

@item @var{portion}
This is the distance of the click from the top or left end of
the scroll bar.

@item @var{whole}
This is the length of the entire scroll bar.

@item @var{timestamp}
This is the time at which the event occurred, in milliseconds.

@item @var{part}
This is the part of the scroll-bar which was clicked on.  It is one
of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
@code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
@end table

@item @var{click-count}
This is the number of rapid repeated presses so far of the same mouse
button.  @xref{Repeat Events}.
@end table

@node Drag Events
@subsection Drag Events
@cindex drag event
@cindex mouse drag event

With Emacs, you can have a drag event without even changing your
clothes.  A @dfn{drag event} happens every time the user presses a mouse
button and then moves the mouse to a different character position before
releasing the button.  Like all mouse events, drag events are
represented in Lisp as lists.  The lists record both the starting mouse
position and the final position, like this:

@example
(@var{event-type}
 (@var{window1} START-POSITION)
 (@var{window2} END-POSITION))
@end example

For a drag event, the name of the symbol @var{event-type} contains the
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.  They have the same form as @var{position} in a click event
(@pxref{Click Events}) that is not on the scroll bar part of the
window.  You can access the second element of any mouse event in the
same way, with no need to distinguish drag events from others.

The @samp{drag-} prefix follows the modifier key prefixes such as
@samp{C-} and @samp{M-}.

If @code{read-key-sequence} receives a drag event that has no key
binding, and the corresponding click event does have a binding, it
changes the drag event into a click event at the drag's starting
position.  This means that you don't have to distinguish between click
and drag events unless you want to.

@node Button-Down Events
@subsection Button-Down Events
@cindex button-down event

Click and drag events happen when the user releases a mouse button.
They cannot happen earlier, because there is no way to distinguish a
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
pressed.  They are represented by lists that look exactly like click
events (@pxref{Click Events}), except that the @var{event-type} symbol
name contains the prefix @samp{down-}.  The @samp{down-} prefix follows
modifier key prefixes such as @samp{C-} and @samp{M-}.

The function @code{read-key-sequence} 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
@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
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
happens when you release the button (as is normal for all click
events).

The event type of a double-click event contains the prefix
@samp{double-}.  Thus, a double click on the second mouse button with
@key{meta} held down comes to the Lisp program as
@code{M-double-mouse-2}.  If a double-click event has no binding, the
binding of the corresponding ordinary click event is used to execute
it.  Thus, you need not pay attention to the double click feature
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, 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 is convenient, if the meaning of a double click somehow ``builds
on'' the meaning of a single click---which is recommended user interface
design practice for double clicks.

If you click a button, then press it down again and start moving the
mouse with the button held down, then you get a @dfn{double-drag} event
when you ultimately release the button.  Its event type contains
@samp{double-drag} instead of just @samp{drag}.  If a double-drag event
has no binding, Emacs looks for an alternate binding as if the event
were an ordinary drag.

Before the double-click or double-drag event, Emacs generates a
@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.

To summarize, when you click a button and then press it again right
away, Emacs generates a down event and a click event for the first
click, a double-down event when you press the button again, and finally
either a double-click or a double-drag event.

If you click a button twice and then press it again, all in quick
succession, Emacs generates a @dfn{triple-down} event, followed by
either a @dfn{triple-click} or a @dfn{triple-drag}.  The event types of
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 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
up to @var{event}.  If @var{event} is a double-down, double-click or
double-drag event, the value is 2.  If @var{event} is a triple event,
the value is 3 or greater.  If @var{event} is an ordinary mouse event
(not a repeat event), the value is 1.
@end defun

@defopt double-click-fuzz
To generate repeat events, successive mouse button presses must be at
approximately the same screen position.  The value of
@code{double-click-fuzz} specifies the maximum number of pixels the
mouse may be moved (horizontally or vertically) between two successive
clicks to make a double-click.

This variable is also the threshold for motion of the mouse to count
as a drag.
@end defopt

@defopt double-click-time
To generate repeat events, the number of milliseconds between
successive button presses must be less than the value of
@code{double-click-time}.  Setting @code{double-click-time} to
@code{nil} disables multi-click detection entirely.  Setting it to
@code{t} removes the time limit; Emacs then detects multi-clicks by
position only.
@end defopt

@node Motion Events
@subsection Motion Events
@cindex motion event
@cindex mouse motion events

Emacs sometimes generates @dfn{mouse motion} events to describe motion
of the mouse without any button activity.  Mouse motion events are
represented by lists that look like this:

@example
1572
(mouse-movement POSITION)
Glenn Morris's avatar
Glenn Morris committed
1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602
@end example

The second element of the list describes the current position of the
mouse, just as in a click event (@pxref{Click Events}).

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.  @xref{Mouse Tracking}.

@node Focus Events
@subsection Focus Events
@cindex focus event

Window systems provide general ways for the user to control which window
gets keyboard input.  This choice of window is called the @dfn{focus}.
When the user does something to switch between Emacs frames, that
generates a @dfn{focus event}.  The normal definition of a focus event,
in the global keymap, is to select a new frame within Emacs, as the user
would expect.  @xref{Input Focus}.

Focus events are represented in Lisp as lists that look like this:

@example
(switch-frame @var{new-frame})
@end example

@noindent
where @var{new-frame} is the frame switched to.

1603 1604 1605 1606 1607 1608
Some X window managers are set up so that just moving the mouse into a
window is enough to set the focus there.  Usually, there is no need
for a Lisp program to know about the focus change until some other
kind of input arrives.  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
Glenn Morris's avatar
Glenn Morris committed
1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652
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
sequence.  If the user changes focus in the middle of a key
sequence---that is, after a prefix key---then Emacs reorders the events
so that the focus event comes either before or after the multi-event key
sequence, and not within it.

@node Misc Events
@subsection Miscellaneous System Events

A few other event types represent occurrences within the system.

@table @code
@cindex @code{delete-frame} event
@item (delete-frame (@var{frame}))
This kind of event indicates that the user gave the window manager
a command to delete a particular window, which happens to be an Emacs frame.

The standard definition of the @code{delete-frame} event is to delete @var{frame}.

@cindex @code{iconify-frame} event
@item (iconify-frame (@var{frame}))
This kind of event indicates that the user iconified @var{frame} using
the window manager.  Its standard definition is @code{ignore}; since the
frame has already been iconified, Emacs has no work to do.  The purpose
of this event type is so that you can keep track of such events if you
want to.

@cindex @code{make-frame-visible} event
@item (make-frame-visible (@var{frame}))
This kind of event indicates that the user deiconified @var{frame} using
the window manager.  Its standard definition is @code{ignore}; since the
frame has already been made visible, Emacs has no work to do.

@cindex @code{wheel-up} event
@cindex @code{wheel-down} event
@item (wheel-up @var{position})
@item (wheel-down @var{position})
These kinds of event are generated by moving a mouse wheel.  Their
usual meaning is a kind of scroll or zoom.

The element @var{position} is a list describing the position of the
1653 1654
event, in the same format as used in a mouse-click event (@pxref{Click
Events}).
Glenn Morris's avatar
Glenn Morris committed
1655

1656 1657
@vindex mouse-wheel-up-event
@vindex mouse-wheel-down-event
Glenn Morris's avatar
Glenn Morris committed
1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670
This kind of event is generated only on some kinds of systems. On some
systems, @code{mouse-4} and @code{mouse-5} are used instead.  For
portable code, use the variables @code{mouse-wheel-up-event} and
@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine
what event types to expect for the mouse wheel.

@cindex @code{drag-n-drop} event
@item (drag-n-drop @var{position} @var{files})
This kind of event is generated when a group of files is
selected in an application outside of Emacs, and then dragged and
dropped onto an Emacs frame.

The element @var{position} is a list describing the position of the
1671 1672 1673 1674
event, in the same format as used in a mouse-click event (@pxref{Click
Events}), 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.
Glenn Morris's avatar
Glenn Morris committed
1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701

This kind of event is generated, at present, only on some kinds of
systems.

@cindex @code{help-echo} event
@item help-echo
This kind of event is generated when a mouse pointer moves onto a
portion of buffer text which has a @code{help-echo} text property.
The generated event has this form:

@example
(help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos})
@end example

@noindent
The precise meaning of the event parameters and the way these
parameters are used to display the help-echo text are described in
@ref{Text help-echo}.

@cindex @code{sigusr1} event
@cindex @code{sigusr2} event
@cindex user signals
@item sigusr1
@itemx sigusr2
These events are generated when the Emacs process receives
the signals @code{SIGUSR1} and @code{SIGUSR2}.  They contain no
additional data because signals do not carry additional information.
Glenn Morris's avatar
Glenn Morris committed
1702
They can be useful for debugging (@pxref{Error Debugging}).
Glenn Morris's avatar
Glenn Morris committed
1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882

To catch a user signal, bind the corresponding event to an interactive
command in the @code{special-event-map} (@pxref{Active Keymaps}).
The command is called with no arguments, and the specific signal event is
available in @code{last-input-event}.  For example:

@smallexample
(defun sigusr-handler ()
  (interactive)
  (message "Caught signal %S" last-input-event))

(define-key special-event-map [sigusr1] 'sigusr-handler)
@end smallexample

To test the signal handler, you can make Emacs send a signal to itself:

@smallexample
(signal-process (emacs-pid) 'sigusr1)
@end smallexample
@end table

  If one of these events arrives in the middle of a key sequence---that
is, after a prefix key---then Emacs reorders the events so that this
event comes either before or after the multi-event key sequence, not
within it.

@node Event Examples
@subsection Event Examples

If the user presses and releases the left mouse button over the same
location, that generates a sequence of events like this:

@smallexample
(down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
(mouse-1      (#<window 18 on NEWS> 2613 (0 . 38) -864180))
@end smallexample

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:

@smallexample
(C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
(C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
                (#<window 18 on NEWS> 3510 (0 . 28) -729648))
@end smallexample

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 a pair of events like these:

@smallexample
(M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
(M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
                  (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
                   -453816))
@end smallexample

To handle a SIGUSR1 signal, define an interactive function, and
bind it to the @code{signal usr1} event sequence:

@smallexample
(defun usr1-handler ()
  (interactive)
  (message "Got USR1 signal"))
(global-set-key [signal usr1] 'usr1-handler)
@end smallexample

@node Classifying Events
@subsection Classifying Events
@cindex event type

  Every event has an @dfn{event type}, which classifies the event for
key binding purposes.  For a keyboard event, the event type equals the
event value; thus, the event type for a character is the character, and
the event type for a function key symbol is the symbol itself.  For
events that are lists, the event type is the symbol in the @sc{car} of
the list.  Thus, the event type is always a symbol or a character.

  Two events of the same type are equivalent where key bindings are
concerned; thus, they always run the same command.  That does not
necessarily mean they do the same things, however, as some commands look
at the whole event to decide what to do.  For example, some commands use
the location of a mouse event to decide 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,
regardless of which other key or mouse button was used.

  The functions @code{event-modifiers} and @code{event-basic-type} are
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},
@code{meta}, @code{alt}, @code{hyper} and @code{super}.  In addition,
the modifiers list of a mouse event symbol always contains one of
@code{click}, @code{drag}, and @code{down}.  For double or triple
events, it also contains @code{double} or @code{triple}.

The argument @var{event} may be an entire event object, or just an
event type.  If @var{event} is a symbol that has never been used in an
event that has been read as input in the current Emacs session, then
@code{event-modifiers} can return @code{nil}, even when @var{event}
actually has modifiers.

Here are some examples:

@example
(event-modifiers ?a)
     @result{} nil
(event-modifiers ?A)
     @result{} (shift)
(event-modifiers ?\C-a)
     @result{} (control)
(event-modifiers ?\C-%)
     @result{} (control)
(event-modifiers ?\C-\S-a)
     @result{} (control shift)
(event-modifiers 'f5)
     @result{} nil
(event-modifiers 's-f5)
     @result{} (super)
(event-modifiers 'M-S-f5)
     @result{} (meta shift)
(event-modifiers 'mouse-1)
     @result{} (click)
(event-modifiers 'down-mouse-1)
     @result{} (down)
@end example

The modifiers list for a click event explicitly contains @code{click},
but the event symbol name itself does not contain @samp{click}.
@end defun

@defun event-basic-type event
This function returns the key or mouse button that @var{event}
describes, with all modifiers removed.  The @var{event} argument is as
in @code{event-modifiers}.  For example:

@example
(event-basic-type ?a)
     @result{} 97
(event-basic-type ?A)
     @result{} 97
(event-basic-type ?\C-a)
     @result{} 97
(event-basic-type ?\C-\S-a)
     @result{} 97
(event-basic-type 'f5)
     @result{} f5
(event-basic-type 's-f5)
     @result{} f5
(event-basic-type 'M-S-f5)
     @result{} f5
(event-basic-type 'down-mouse-1)
     @result{} mouse-1
@end example
@end defun

@defun mouse-movement-p object
This function returns non-@code{nil} if @var{object} is a mouse movement
event.
@end defun

@defun event-convert-list list
This function converts a list of modifier names and a basic event type
to an event type which specifies all of them.  The basic event type
must be the last element of the list.  For example,

@example
(event-convert-list '(control ?a))
     @result{} 1
(event-convert-list '(control meta ?a))
     @result{} -134217727
(event-convert-list '(control super f1))
     @result{} C-s-f1
@end example
@end defun

1883 1884
@node Accessing Mouse
@subsection Accessing Mouse Events
Glenn Morris's avatar
Glenn Morris committed
1885 1886 1887 1888 1889 1890
@cindex mouse events, data in

  This section describes convenient functions for accessing the data in
a mouse button or motion event.

  These two functions return the starting or ending position of a
1891
mouse-button event, as a list of this form (@pxref{Click Events}):
Glenn Morris's avatar
Glenn Morris committed
1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941

@example
(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
 @var{object} @var{text-pos} (@var{col} . @var{row})
 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
@end example

@defun event-start event
This returns the starting position of @var{event}.

If @var{event} is a click or button-down event, this returns the
location of the event.  If @var{event} is a drag event, this returns the
drag's starting position.
@end defun

@defun event-end event
This returns the ending position of @var{event}.

If @var{event} is a drag event, this returns the position where the user
released the mouse button.  If @var{event} is a click or button-down
event, the value is actually the starting position, which is the only
position such events have.
@end defun

@cindex mouse position list, accessing
  These functions take a position list as described above, and
return various parts of it.

@defun posn-window position
Return the window that @var{position} is in.
@end defun

@defun posn-area position
Return the window area recorded in @var{position}.  It returns @code{nil}
when the event occurred in the text area of the window; otherwise, it
is a symbol identifying the area in which the event occurred.
@end defun

@defun posn-point position
Return the buffer position in @var{position}.  When the event occurred
in the text area of the window, in a marginal area, or on a fringe,
this is an integer specifying a buffer position.  Otherwise, the value
is undefined.
@end defun

@defun posn-x-y position
Return the pixel-based x and y coordinates in @var{position}, as a
cons cell @code{(@var{x} . @var{y})}.  These coordinates are relative
to the window given by @code{posn-window}.

1942 1943
This example shows how to convert the window-relative coordinates in
the text area of a window into frame-relative coordinates:
Glenn Morris's avatar
Glenn Morris committed
1944 1945 1946

@example
(defun frame-relative-coordinates (position)
1947 1948
  "Return frame-relative coordinates from POSITION.
POSITION is assumed to lie in a window text area."
Glenn Morris's avatar
Glenn Morris committed
1949 1950 1951 1952 1953 1954 1955 1956 1957
  (let* ((x-y (posn-x-y position))
         (window (posn-window position))
         (edges (window-inside-pixel-edges window)))
    (cons (+ (car x-y) (car edges))
          (+ (cdr x-y) (cadr edges)))))
@end example
@end defun

@defun posn-col-row position
1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968
This function returns a cons cell @code{(@var{col} .  @var{row})},
containing the estimated column and row corresponding to buffer
position @var{position}.  The return value is given in units of the
frame's default character width and height, as computed from the
@var{x} and @var{y} values corresponding to @var{position}.  (So, if
the actual characters have non-default sizes, the actual row and
column may differ from these computed values.)

Note that @var{row} is counted from the top of the text area.  If the
window possesses a header line (@pxref{Header Lines}), it is
@emph{not} counted as the first line.
Glenn Morris's avatar
Glenn Morris committed
1969 1970 1971 1972
@end defun

@defun posn-actual-col-row position
Return the actual row and column in @var{position}, as a cons cell
1973 1974 1975 1976
@code{(@var{col} . @var{row})}.  The values are the actual row and
column numbers in the window.  @xref{Click Events}, for details.  It
returns @code{nil} if @var{position} does not include actual positions
values.
Glenn Morris's avatar
Glenn Morris committed
1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023