]> code.delx.au - gnu-emacs/blob - lispref/commands.texi
(Interactive Call): Add called-interactively-p.
[gnu-emacs] / lispref / commands.texi
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/commands
7 @node Command Loop, Keymaps, Minibuffers, Top
8 @chapter Command Loop
9 @cindex editor command loop
10 @cindex command loop
11
12 When you run Emacs, it enters the @dfn{editor command loop} almost
13 immediately. This loop reads key sequences, executes their definitions,
14 and displays the results. In this chapter, we describe how these things
15 are done, and the subroutines that allow Lisp programs to do them.
16
17 @menu
18 * Command Overview:: How the command loop reads commands.
19 * Defining Commands:: Specifying how a function should read arguments.
20 * Interactive Call:: Calling a command, so that it will read arguments.
21 * Command Loop Info:: Variables set by the command loop for you to examine.
22 * Adjusting Point:: Adjustment of point after a command.
23 * Input Events:: What input looks like when you read it.
24 * Reading Input:: How to read input events from the keyboard or mouse.
25 * Special Events:: Events processed immediately and individually.
26 * Waiting:: Waiting for user input or elapsed time.
27 * Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
28 * Prefix Command Arguments:: How the commands to set prefix args work.
29 * Recursive Editing:: Entering a recursive edit,
30 and why you usually shouldn't.
31 * Disabling Commands:: How the command loop handles disabled commands.
32 * Command History:: How the command history is set up, and how accessed.
33 * Keyboard Macros:: How keyboard macros are implemented.
34 @end menu
35
36 @node Command Overview
37 @section Command Loop Overview
38
39 The first thing the command loop must do is read a key sequence, which
40 is a sequence of events that translates into a command. It does this by
41 calling the function @code{read-key-sequence}. Your Lisp code can also
42 call this function (@pxref{Key Sequence Input}). Lisp programs can also
43 do input at a lower level with @code{read-event} (@pxref{Reading One
44 Event}) or discard pending input with @code{discard-input}
45 (@pxref{Event Input Misc}).
46
47 The key sequence is translated into a command through the currently
48 active keymaps. @xref{Key Lookup}, for information on how this is done.
49 The result should be a keyboard macro or an interactively callable
50 function. If the key is @kbd{M-x}, then it reads the name of another
51 command, which it then calls. This is done by the command
52 @code{execute-extended-command} (@pxref{Interactive Call}).
53
54 To execute a command requires first reading the arguments for it.
55 This is done by calling @code{command-execute} (@pxref{Interactive
56 Call}). For commands written in Lisp, the @code{interactive}
57 specification says how to read the arguments. This may use the prefix
58 argument (@pxref{Prefix Command Arguments}) or may read with prompting
59 in the minibuffer (@pxref{Minibuffers}). For example, the command
60 @code{find-file} has an @code{interactive} specification which says to
61 read a file name using the minibuffer. The command's function body does
62 not use the minibuffer; if you call this command from Lisp code as a
63 function, you must supply the file name string as an ordinary Lisp
64 function argument.
65
66 If the command is a string or vector (i.e., a keyboard macro) then
67 @code{execute-kbd-macro} is used to execute it. You can call this
68 function yourself (@pxref{Keyboard Macros}).
69
70 To terminate the execution of a running command, type @kbd{C-g}. This
71 character causes @dfn{quitting} (@pxref{Quitting}).
72
73 @defvar pre-command-hook
74 The editor command loop runs this normal hook before each command. At
75 that time, @code{this-command} contains the command that is about to
76 run, and @code{last-command} describes the previous command.
77 @xref{Hooks}.
78 @end defvar
79
80 @defvar post-command-hook
81 The editor command loop runs this normal hook after each command
82 (including commands terminated prematurely by quitting or by errors),
83 and also when the command loop is first entered. At that time,
84 @code{this-command} describes the command that just ran, and
85 @code{last-command} describes the command before that. @xref{Hooks}.
86 @end defvar
87
88 Quitting is suppressed while running @code{pre-command-hook} and
89 @code{post-command-hook}. If an error happens while executing one of
90 these hooks, it terminates execution of the hook, and clears the hook
91 variable to @code{nil} so as to prevent an infinite loop of errors.
92
93 A request coming into the Emacs server (@pxref{Emacs Server,,,
94 emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard
95 command does.
96
97 @node Defining Commands
98 @section Defining Commands
99 @cindex defining commands
100 @cindex commands, defining
101 @cindex functions, making them interactive
102 @cindex interactive function
103
104 A Lisp function becomes a command when its body contains, at top
105 level, a form that calls the special form @code{interactive}. This
106 form does nothing when actually executed, but its presence serves as a
107 flag to indicate that interactive calling is permitted. Its argument
108 controls the reading of arguments for an interactive call.
109
110 @menu
111 * Using Interactive:: General rules for @code{interactive}.
112 * Interactive Codes:: The standard letter-codes for reading arguments
113 in various ways.
114 * Interactive Examples:: Examples of how to read interactive arguments.
115 @end menu
116
117 @node Using Interactive
118 @subsection Using @code{interactive}
119
120 This section describes how to write the @code{interactive} form that
121 makes a Lisp function an interactively-callable command, and how to
122 examine a command's @code{interactive} form.
123
124 @defspec interactive arg-descriptor
125 @cindex argument descriptors
126 This special form declares that the function in which it appears is a
127 command, and that it may therefore be called interactively (via
128 @kbd{M-x} or by entering a key sequence bound to it). The argument
129 @var{arg-descriptor} declares how to compute the arguments to the
130 command when the command is called interactively.
131
132 A command may be called from Lisp programs like any other function, but
133 then the caller supplies the arguments and @var{arg-descriptor} has no
134 effect.
135
136 The @code{interactive} form has its effect because the command loop
137 (actually, its subroutine @code{call-interactively}) scans through the
138 function definition looking for it, before calling the function. Once
139 the function is called, all its body forms including the
140 @code{interactive} form are executed, but at this time
141 @code{interactive} simply returns @code{nil} without even evaluating its
142 argument.
143 @end defspec
144
145 There are three possibilities for the argument @var{arg-descriptor}:
146
147 @itemize @bullet
148 @item
149 It may be omitted or @code{nil}; then the command is called with no
150 arguments. This leads quickly to an error if the command requires one
151 or more arguments.
152
153 @item
154 It may be a Lisp expression that is not a string; then it should be a
155 form that is evaluated to get a list of arguments to pass to the
156 command.
157 @cindex argument evaluation form
158
159 If this expression reads keyboard input (this includes using the
160 minibuffer), keep in mind that the integer value of point or the mark
161 before reading input may be incorrect after reading input. This is
162 because the current buffer may be receiving subprocess output;
163 if subprocess output arrives while the command is waiting for input,
164 it could relocate point and the mark.
165
166 Here's an example of what @emph{not} to do:
167
168 @smallexample
169 (interactive
170 (list (region-beginning) (region-end)
171 (read-string "Foo: " nil 'my-history)))
172 @end smallexample
173
174 @noindent
175 Here's how to avoid the problem, by examining point and the mark only
176 after reading the keyboard input:
177
178 @smallexample
179 (interactive
180 (let ((string (read-string "Foo: " nil 'my-history)))
181 (list (region-beginning) (region-end) string)))
182 @end smallexample
183
184 @item
185 @cindex argument prompt
186 It may be a string; then its contents should consist of a code character
187 followed by a prompt (which some code characters use and some ignore).
188 The prompt ends either with the end of the string or with a newline.
189 Here is a simple example:
190
191 @smallexample
192 (interactive "bFrobnicate buffer: ")
193 @end smallexample
194
195 @noindent
196 The code letter @samp{b} says to read the name of an existing buffer,
197 with completion. The buffer name is the sole argument passed to the
198 command. The rest of the string is a prompt.
199
200 If there is a newline character in the string, it terminates the prompt.
201 If the string does not end there, then the rest of the string should
202 contain another code character and prompt, specifying another argument.
203 You can specify any number of arguments in this way.
204
205 @c Emacs 19 feature
206 The prompt string can use @samp{%} to include previous argument values
207 (starting with the first argument) in the prompt. This is done using
208 @code{format} (@pxref{Formatting Strings}). For example, here is how
209 you could read the name of an existing buffer followed by a new name to
210 give to that buffer:
211
212 @smallexample
213 @group
214 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
215 @end group
216 @end smallexample
217
218 @cindex @samp{*} in @code{interactive}
219 @cindex read-only buffers in interactive
220 If the first character in the string is @samp{*}, then an error is
221 signaled if the buffer is read-only.
222
223 @cindex @samp{@@} in @code{interactive}
224 @c Emacs 19 feature
225 If the first character in the string is @samp{@@}, and if the key
226 sequence used to invoke the command includes any mouse events, then
227 the window associated with the first of those events is selected
228 before the command is run.
229
230 You can use @samp{*} and @samp{@@} together; the order does not matter.
231 Actual reading of arguments is controlled by the rest of the prompt
232 string (starting with the first character that is not @samp{*} or
233 @samp{@@}).
234 @end itemize
235
236 @cindex examining the @code{interactive} form
237 @defun interactive-form function
238 This function returns the @code{interactive} form of @var{function}.
239 If @var{function} is an interactively callable function
240 (@pxref{Interactive Call}), the value is the command's
241 @code{interactive} form @code{(interactive @var{spec})}, which
242 specifies how to compute its arguments. Otherwise, the value is
243 @code{nil}. If @var{function} is a symbol, its function definition is
244 used.
245 @end defun
246
247 @node Interactive Codes
248 @comment node-name, next, previous, up
249 @subsection Code Characters for @code{interactive}
250 @cindex interactive code description
251 @cindex description for interactive codes
252 @cindex codes, interactive, description of
253 @cindex characters for interactive codes
254
255 The code character descriptions below contain a number of key words,
256 defined here as follows:
257
258 @table @b
259 @item Completion
260 @cindex interactive completion
261 Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name
262 completion because the argument is read using @code{completing-read}
263 (@pxref{Completion}). @kbd{?} displays a list of possible completions.
264
265 @item Existing
266 Require the name of an existing object. An invalid name is not
267 accepted; the commands to exit the minibuffer do not exit if the current
268 input is not valid.
269
270 @item Default
271 @cindex default argument string
272 A default value of some sort is used if the user enters no text in the
273 minibuffer. The default depends on the code character.
274
275 @item No I/O
276 This code letter computes an argument without reading any input.
277 Therefore, it does not use a prompt string, and any prompt string you
278 supply is ignored.
279
280 Even though the code letter doesn't use a prompt string, you must follow
281 it with a newline if it is not the last code character in the string.
282
283 @item Prompt
284 A prompt immediately follows the code character. The prompt ends either
285 with the end of the string or with a newline.
286
287 @item Special
288 This code character is meaningful only at the beginning of the
289 interactive string, and it does not look for a prompt or a newline.
290 It is a single, isolated character.
291 @end table
292
293 @cindex reading interactive arguments
294 Here are the code character descriptions for use with @code{interactive}:
295
296 @table @samp
297 @item *
298 Signal an error if the current buffer is read-only. Special.
299
300 @item @@
301 Select the window mentioned in the first mouse event in the key
302 sequence that invoked this command. Special.
303
304 @item a
305 A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
306 Completion, Prompt.
307
308 @item b
309 The name of an existing buffer. By default, uses the name of the
310 current buffer (@pxref{Buffers}). Existing, Completion, Default,
311 Prompt.
312
313 @item B
314 A buffer name. The buffer need not exist. By default, uses the name of
315 a recently used buffer other than the current buffer. Completion,
316 Default, Prompt.
317
318 @item c
319 A character. The cursor does not move into the echo area. Prompt.
320
321 @item C
322 A command name (i.e., a symbol satisfying @code{commandp}). Existing,
323 Completion, Prompt.
324
325 @item d
326 @cindex position argument
327 The position of point, as an integer (@pxref{Point}). No I/O.
328
329 @item D
330 A directory name. The default is the current default directory of the
331 current buffer, @code{default-directory} (@pxref{File Name Expansion}).
332 Existing, Completion, Default, Prompt.
333
334 @item e
335 The first or next mouse event in the key sequence that invoked the command.
336 More precisely, @samp{e} gets events that are lists, so you can look at
337 the data in the lists. @xref{Input Events}. No I/O.
338
339 You can use @samp{e} more than once in a single command's interactive
340 specification. If the key sequence that invoked the command has
341 @var{n} events that are lists, the @var{n}th @samp{e} provides the
342 @var{n}th such event. Events that are not lists, such as function keys
343 and @acronym{ASCII} characters, do not count where @samp{e} is concerned.
344
345 @item f
346 A file name of an existing file (@pxref{File Names}). The default
347 directory is @code{default-directory}. Existing, Completion, Default,
348 Prompt.
349
350 @item F
351 A file name. The file need not exist. Completion, Default, Prompt.
352
353 @item i
354 An irrelevant argument. This code always supplies @code{nil} as
355 the argument's value. No I/O.
356
357 @item k
358 A key sequence (@pxref{Keymap Terminology}). This keeps reading events
359 until a command (or undefined command) is found in the current key
360 maps. The key sequence argument is represented as a string or vector.
361 The cursor does not move into the echo area. Prompt.
362
363 If the key sequence is a down-event, the following up-event is discarded,
364 but can be read via the @code{U} code character.
365
366 This kind of input is used by commands such as @code{describe-key} and
367 @code{global-set-key}.
368
369 @item K
370 A key sequence, whose definition you intend to change. This works like
371 @samp{k}, except that it suppresses, for the last input event in the key
372 sequence, the conversions that are normally used (when necessary) to
373 convert an undefined key into a defined one.
374
375 @item m
376 @cindex marker argument
377 The position of the mark, as an integer. No I/O.
378
379 @item M
380 Arbitrary text, read in the minibuffer using the current buffer's input
381 method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
382 Emacs Manual}). Prompt.
383
384 @item n
385 A number, read with the minibuffer. If the input is not a number, the
386 user has to try again. @samp{n} never uses the prefix argument.
387 Prompt.
388
389 @item N
390 The numeric prefix argument; but if there is no prefix argument, read
391 a number as with @kbd{n}. The value is always a number. @xref{Prefix
392 Command Arguments}. Prompt.
393
394 @item p
395 @cindex numeric prefix argument usage
396 The numeric prefix argument. (Note that this @samp{p} is lower case.)
397 No I/O.
398
399 @item P
400 @cindex raw prefix argument usage
401 The raw prefix argument. (Note that this @samp{P} is upper case.) No
402 I/O.
403
404 @item r
405 @cindex region argument
406 Point and the mark, as two numeric arguments, smallest first. This is
407 the only code letter that specifies two successive arguments rather than
408 one. No I/O.
409
410 @item s
411 Arbitrary text, read in the minibuffer and returned as a string
412 (@pxref{Text from Minibuffer}). Terminate the input with either
413 @kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of
414 these characters in the input.) Prompt.
415
416 @item S
417 An interned symbol whose name is read in the minibuffer. Any whitespace
418 character terminates the input. (Use @kbd{C-q} to include whitespace in
419 the string.) Other characters that normally terminate a symbol (e.g.,
420 parentheses and brackets) do not do so here. Prompt.
421
422 @item U
423 A key sequence or nil. May be used after a @code{k} or @code{K}
424 argument to get the up-event that was discarded in case the key
425 sequence read for that argument was a down-event. No I/O.
426
427 @item v
428 A variable declared to be a user option (i.e., satisfying the
429 predicate @code{user-variable-p}). This reads the variable using
430 @code{read-variable}. @xref{Definition of read-variable}. Existing,
431 Completion, Prompt.
432
433 @item x
434 A Lisp object, specified with its read syntax, terminated with a
435 @kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from
436 Minibuffer}. Prompt.
437
438 @item X
439 @cindex evaluated expression argument
440 A Lisp form is read as with @kbd{x}, but then evaluated so that its
441 value becomes the argument for the command. Prompt.
442
443 @item z
444 A coding system name (a symbol). If the user enters null input, the
445 argument value is @code{nil}. @xref{Coding Systems}. Completion,
446 Existing, Prompt.
447
448 @item Z
449 A coding system name (a symbol)---but only if this command has a prefix
450 argument. With no prefix argument, @samp{Z} provides @code{nil} as the
451 argument value. Completion, Existing, Prompt.
452 @end table
453
454 @node Interactive Examples
455 @comment node-name, next, previous, up
456 @subsection Examples of Using @code{interactive}
457 @cindex examples of using @code{interactive}
458 @cindex @code{interactive}, examples of using
459
460 Here are some examples of @code{interactive}:
461
462 @example
463 @group
464 (defun foo1 () ; @r{@code{foo1} takes no arguments,}
465 (interactive) ; @r{just moves forward two words.}
466 (forward-word 2))
467 @result{} foo1
468 @end group
469
470 @group
471 (defun foo2 (n) ; @r{@code{foo2} takes one argument,}
472 (interactive "p") ; @r{which is the numeric prefix.}
473 (forward-word (* 2 n)))
474 @result{} foo2
475 @end group
476
477 @group
478 (defun foo3 (n) ; @r{@code{foo3} takes one argument,}
479 (interactive "nCount:") ; @r{which is read with the Minibuffer.}
480 (forward-word (* 2 n)))
481 @result{} foo3
482 @end group
483
484 @group
485 (defun three-b (b1 b2 b3)
486 "Select three existing buffers.
487 Put them into three windows, selecting the last one."
488 @end group
489 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
490 (delete-other-windows)
491 (split-window (selected-window) 8)
492 (switch-to-buffer b1)
493 (other-window 1)
494 (split-window (selected-window) 8)
495 (switch-to-buffer b2)
496 (other-window 1)
497 (switch-to-buffer b3))
498 @result{} three-b
499 @group
500 (three-b "*scratch*" "declarations.texi" "*mail*")
501 @result{} nil
502 @end group
503 @end example
504
505 @node Interactive Call
506 @section Interactive Call
507 @cindex interactive call
508
509 After the command loop has translated a key sequence into a command it
510 invokes that command using the function @code{command-execute}. If the
511 command is a function, @code{command-execute} calls
512 @code{call-interactively}, which reads the arguments and calls the
513 command. You can also call these functions yourself.
514
515 @defun commandp object &optional for-call-interactively
516 Returns @code{t} if @var{object} is suitable for calling interactively;
517 that is, if @var{object} is a command. Otherwise, returns @code{nil}.
518
519 The interactively callable objects include strings and vectors (treated
520 as keyboard macros), lambda expressions that contain a top-level call to
521 @code{interactive}, byte-code function objects made from such lambda
522 expressions, autoload objects that are declared as interactive
523 (non-@code{nil} fourth argument to @code{autoload}), and some of the
524 primitive functions.
525
526 A symbol satisfies @code{commandp} if its function definition
527 satisfies @code{commandp}. Keys and keymaps are not commands.
528 Rather, they are used to look up commands (@pxref{Keymaps}).
529
530 If @var{for-call-interactively} is non-@code{nil}, then
531 @code{commandp} returns @code{t} only for objects that
532 @code{call-interactively} could call---thus, not for keyboard macros.
533
534 See @code{documentation} in @ref{Accessing Documentation}, for a
535 realistic example of using @code{commandp}.
536 @end defun
537
538 @defun call-interactively command &optional record-flag keys
539 This function calls the interactively callable function @var{command},
540 reading arguments according to its interactive calling specifications.
541 It returns whatever @var{command} returns. An error is signaled if
542 @var{command} is not a function or if it cannot be called
543 interactively (i.e., is not a command). Note that keyboard macros
544 (strings and vectors) are not accepted, even though they are
545 considered commands, because they are not functions. If @var{command}
546 is a symbol, then @code{call-interactively} uses its function definition.
547
548 @cindex record command history
549 If @var{record-flag} is non-@code{nil}, then this command and its
550 arguments are unconditionally added to the list @code{command-history}.
551 Otherwise, the command is added only if it uses the minibuffer to read
552 an argument. @xref{Command History}.
553
554 The argument @var{keys}, if given, specifies the sequence of events to
555 supply if the command inquires which events were used to invoke it.
556 If @var{keys} is omitted or @code{nil}, the return value of
557 @code{this-command-keys} is used. @xref{Definition of this-command-keys}.
558 @end defun
559
560 @defun command-execute command &optional record-flag keys special
561 @cindex keyboard macro execution
562 This function executes @var{command}. The argument @var{command} must
563 satisfy the @code{commandp} predicate; i.e., it must be an interactively
564 callable function or a keyboard macro.
565
566 A string or vector as @var{command} is executed with
567 @code{execute-kbd-macro}. A function is passed to
568 @code{call-interactively}, along with the optional @var{record-flag}
569 and @var{keys}.
570
571 A symbol is handled by using its function definition in its place. A
572 symbol with an @code{autoload} definition counts as a command if it was
573 declared to stand for an interactively callable function. Such a
574 definition is handled by loading the specified library and then
575 rechecking the definition of the symbol.
576
577 The argument @var{special}, if given, means to ignore the prefix
578 argument and not clear it. This is used for executing special events
579 (@pxref{Special Events}).
580 @end defun
581
582 @deffn Command execute-extended-command prefix-argument
583 @cindex read command name
584 This function reads a command name from the minibuffer using
585 @code{completing-read} (@pxref{Completion}). Then it uses
586 @code{command-execute} to call the specified command. Whatever that
587 command returns becomes the value of @code{execute-extended-command}.
588
589 @cindex execute with prefix argument
590 If the command asks for a prefix argument, it receives the value
591 @var{prefix-argument}. If @code{execute-extended-command} is called
592 interactively, the current raw prefix argument is used for
593 @var{prefix-argument}, and thus passed on to whatever command is run.
594
595 @c !!! Should this be @kindex?
596 @cindex @kbd{M-x}
597 @code{execute-extended-command} is the normal definition of @kbd{M-x},
598 so it uses the string @w{@samp{M-x }} as a prompt. (It would be better
599 to take the prompt from the events used to invoke
600 @code{execute-extended-command}, but that is painful to implement.) A
601 description of the value of the prefix argument, if any, also becomes
602 part of the prompt.
603
604 @example
605 @group
606 (execute-extended-command 1)
607 ---------- Buffer: Minibuffer ----------
608 1 M-x forward-word RET
609 ---------- Buffer: Minibuffer ----------
610 @result{} t
611 @end group
612 @end example
613 @end deffn
614
615 @defun interactive-p
616 This function returns @code{t} if the containing function (the one
617 whose code includes the call to @code{interactive-p}) was called in
618 direct response to user input. This means that it was called with the
619 function @code{call-interactively}, and that a keyboard macro is
620 not running, and that Emacs is not running in batch mode.
621
622 If the containing function was called by Lisp evaluation (or with
623 @code{apply} or @code{funcall}), then it was not called interactively.
624 @end defun
625
626 The most common use of @code{interactive-p} is for deciding whether
627 to give the user additional visual feedback (such as by printing an
628 informative message). For example:
629
630 @example
631 @group
632 ;; @r{Here's the usual way to use @code{interactive-p}.}
633 (defun foo ()
634 (interactive)
635 (when (interactive-p)
636 (message "foo")))
637 @result{} foo
638 @end group
639
640 @group
641 ;; @r{This function is just to illustrate the behavior.}
642 (defun bar ()
643 (interactive)
644 (setq foobar (list (foo) (interactive-p))))
645 @result{} bar
646 @end group
647
648 @group
649 ;; @r{Type @kbd{M-x foo}.}
650 @print{} foo
651 @end group
652
653 @group
654 ;; @r{Type @kbd{M-x bar}.}
655 ;; @r{This does not display a message.}
656 @end group
657
658 @group
659 foobar
660 @result{} (nil t)
661 @end group
662 @end example
663
664 If you want to test @emph{only} whether the function was called
665 using @code{call-interactively}, add an optional argument
666 @code{print-message} which should be non-@code{nil} in an interactive
667 call, and use the @code{interactive} spec to make sure it is
668 non-@code{nil}. Here's an example:
669
670 @example
671 (defun foo (&optional print-message)
672 (interactive "p")
673 (when print-message
674 (message "foo")))
675 @end example
676
677 @noindent
678 Defined in this way, the function does display the message when called
679 from a keyboard macro. We use @code{"p"} because the numeric prefix
680 argument is never @code{nil}.
681
682 @defun called-interactively-p
683 This function returns @code{t} when the calling function was called
684 using @code{call-interactively}.
685
686 When possible, instead of using this function, you should use the
687 method in the example above; that method makes it possible for a
688 caller to ``pretend'' that the function was called interactively.
689 @end defun
690
691 @node Command Loop Info
692 @comment node-name, next, previous, up
693 @section Information from the Command Loop
694
695 The editor command loop sets several Lisp variables to keep status
696 records for itself and for commands that are run.
697
698 @defvar last-command
699 This variable records the name of the previous command executed by the
700 command loop (the one before the current command). Normally the value
701 is a symbol with a function definition, but this is not guaranteed.
702
703 The value is copied from @code{this-command} when a command returns to
704 the command loop, except when the command has specified a prefix
705 argument for the following command.
706
707 This variable is always local to the current terminal and cannot be
708 buffer-local. @xref{Multiple Displays}.
709 @end defvar
710
711 @defvar real-last-command
712 This variable is set up by Emacs just like @code{last-command},
713 but never altered by Lisp programs.
714 @end defvar
715
716 @defvar this-command
717 @cindex current command
718 This variable records the name of the command now being executed by
719 the editor command loop. Like @code{last-command}, it is normally a symbol
720 with a function definition.
721
722 The command loop sets this variable just before running a command, and
723 copies its value into @code{last-command} when the command finishes
724 (unless the command specified a prefix argument for the following
725 command).
726
727 @cindex kill command repetition
728 Some commands set this variable during their execution, as a flag for
729 whatever command runs next. In particular, the functions for killing text
730 set @code{this-command} to @code{kill-region} so that any kill commands
731 immediately following will know to append the killed text to the
732 previous kill.
733 @end defvar
734
735 If you do not want a particular command to be recognized as the previous
736 command in the case where it got an error, you must code that command to
737 prevent this. One way is to set @code{this-command} to @code{t} at the
738 beginning of the command, and set @code{this-command} back to its proper
739 value at the end, like this:
740
741 @example
742 (defun foo (args@dots{})
743 (interactive @dots{})
744 (let ((old-this-command this-command))
745 (setq this-command t)
746 @r{@dots{}do the work@dots{}}
747 (setq this-command old-this-command)))
748 @end example
749
750 @noindent
751 We do not bind @code{this-command} with @code{let} because that would
752 restore the old value in case of error---a feature of @code{let} which
753 in this case does precisely what we want to avoid.
754
755 @defvar this-original-command
756 This has the same value as @code{this-command} except when command
757 remapping occurs (@pxref{Remapping Commands}). In that case,
758 @code{this-command} gives the command actually run (the result of
759 remapping), and @code{this-original-command} gives the command that
760 was specified to run but remapped into another command.
761 @end defvar
762
763 @defun this-command-keys
764 @anchor{Definition of this-command-keys}
765 This function returns a string or vector containing the key sequence
766 that invoked the present command, plus any previous commands that
767 generated the prefix argument for this command. However, if the
768 command has called @code{read-key-sequence}, it returns the last read
769 key sequence. @xref{Key Sequence Input}. The value is a string if
770 all events in the sequence were characters that fit in a string.
771 @xref{Input Events}.
772
773 @example
774 @group
775 (this-command-keys)
776 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
777 @result{} "^U^X^E"
778 @end group
779 @end example
780 @end defun
781
782 @defun this-command-keys-vector
783 Like @code{this-command-keys}, except that it always returns the events
784 in a vector, so you don't need to deal with the complexities of storing
785 input events in a string (@pxref{Strings of Events}).
786 @end defun
787
788 @tindex clear-this-command-keys
789 @defun clear-this-command-keys &optional keep-record
790 This function empties out the table of events for
791 @code{this-command-keys} to return. Unless @var{keep-record} is
792 non-@code{nil}, it also empties the records that the function
793 @code{recent-keys} (@pxref{Recording Input}) will subsequently return.
794 This is useful after reading a password, to prevent the password from
795 echoing inadvertently as part of the next command in certain cases.
796 @end defun
797
798 @defvar last-nonmenu-event
799 This variable holds the last input event read as part of a key sequence,
800 not counting events resulting from mouse menus.
801
802 One use of this variable is for telling @code{x-popup-menu} where to pop
803 up a menu. It is also used internally by @code{y-or-n-p}
804 (@pxref{Yes-or-No Queries}).
805 @end defvar
806
807 @defvar last-command-event
808 @defvarx last-command-char
809 This variable is set to the last input event that was read by the
810 command loop as part of a command. The principal use of this variable
811 is in @code{self-insert-command}, which uses it to decide which
812 character to insert.
813
814 @example
815 @group
816 last-command-event
817 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
818 @result{} 5
819 @end group
820 @end example
821
822 @noindent
823 The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
824
825 The alias @code{last-command-char} exists for compatibility with
826 Emacs version 18.
827 @end defvar
828
829 @c Emacs 19 feature
830 @defvar last-event-frame
831 This variable records which frame the last input event was directed to.
832 Usually this is the frame that was selected when the event was
833 generated, but if that frame has redirected input focus to another
834 frame, the value is the frame to which the event was redirected.
835 @xref{Input Focus}.
836
837 If the last event came from a keyboard macro, the value is @code{macro}.
838 @end defvar
839
840 @node Adjusting Point
841 @section Adjusting Point After Commands
842
843 It is not easy to display a value of point in the middle of a sequence
844 of text that has the @code{display} or @code{composition} property. So
845 after a command finishes and returns to the command loop, if point is
846 within such a sequence, the command loop normally moves point to the
847 edge of the sequence.
848
849 A command can inhibit this feature by setting the variable
850 @code{disable-point-adjustment}:
851
852 @defvar disable-point-adjustment
853 @tindex disable-point-adjustment
854 If this variable is non-@code{nil} when a command returns to the command
855 loop, then the command loop does not check for text properties such as
856 @code{display} and @code{composition}, and does not move point out of
857 sequences that have these properties.
858
859 The command loop sets this variable to @code{nil} before each command,
860 so if a command sets it, the effect applies only to that command.
861 @end defvar
862
863 @defvar global-disable-point-adjustment
864 @tindex global-disable-point-adjustment
865 If you set this variable to a non-@code{nil} value, the feature of
866 moving point out of these sequences is completely turned off.
867 @end defvar
868
869 @node Input Events
870 @section Input Events
871 @cindex events
872 @cindex input events
873
874 The Emacs command loop reads a sequence of @dfn{input events} that
875 represent keyboard or mouse activity. The events for keyboard activity
876 are characters or symbols; mouse events are always lists. This section
877 describes the representation and meaning of input events in detail.
878
879 @defun eventp object
880 This function returns non-@code{nil} if @var{object} is an input event
881 or event type.
882
883 Note that any symbol might be used as an event or an event type.
884 @code{eventp} cannot distinguish whether a symbol is intended by Lisp
885 code to be used as an event. Instead, it distinguishes whether the
886 symbol has actually been used in an event that has been read as input in
887 the current Emacs session. If a symbol has not yet been so used,
888 @code{eventp} returns @code{nil}.
889 @end defun
890
891 @menu
892 * Keyboard Events:: Ordinary characters--keys with symbols on them.
893 * Function Keys:: Function keys--keys with names, not symbols.
894 * Mouse Events:: Overview of mouse events.
895 * Click Events:: Pushing and releasing a mouse button.
896 * Drag Events:: Moving the mouse before releasing the button.
897 * Button-Down Events:: A button was pushed and not yet released.
898 * Repeat Events:: Double and triple click (or drag, or down).
899 * Motion Events:: Just moving the mouse, not pushing a button.
900 * Focus Events:: Moving the mouse between frames.
901 * Misc Events:: Other events the system can generate.
902 * Event Examples:: Examples of the lists for mouse events.
903 * Classifying Events:: Finding the modifier keys in an event symbol.
904 Event types.
905 * Accessing Events:: Functions to extract info from events.
906 * Strings of Events:: Special considerations for putting
907 keyboard character events in a string.
908 @end menu
909
910 @node Keyboard Events
911 @subsection Keyboard Events
912
913 There are two kinds of input you can get from the keyboard: ordinary
914 keys, and function keys. Ordinary keys correspond to characters; the
915 events they generate are represented in Lisp as characters. The event
916 type of a character event is the character itself (an integer); see
917 @ref{Classifying Events}.
918
919 @cindex modifier bits (of input character)
920 @cindex basic code (of input character)
921 An input character event consists of a @dfn{basic code} between 0 and
922 524287, plus any or all of these @dfn{modifier bits}:
923
924 @table @asis
925 @item meta
926 The
927 @tex
928 @math{2^{27}}
929 @end tex
930 @ifnottex
931 2**27
932 @end ifnottex
933 bit in the character code indicates a character
934 typed with the meta key held down.
935
936 @item control
937 The
938 @tex
939 @math{2^{26}}
940 @end tex
941 @ifnottex
942 2**26
943 @end ifnottex
944 bit in the character code indicates a non-@acronym{ASCII}
945 control character.
946
947 @sc{ascii} control characters such as @kbd{C-a} have special basic
948 codes of their own, so Emacs needs no special bit to indicate them.
949 Thus, the code for @kbd{C-a} is just 1.
950
951 But if you type a control combination not in @acronym{ASCII}, such as
952 @kbd{%} with the control key, the numeric value you get is the code
953 for @kbd{%} plus
954 @tex
955 @math{2^{26}}
956 @end tex
957 @ifnottex
958 2**26
959 @end ifnottex
960 (assuming the terminal supports non-@acronym{ASCII}
961 control characters).
962
963 @item shift
964 The
965 @tex
966 @math{2^{25}}
967 @end tex
968 @ifnottex
969 2**25
970 @end ifnottex
971 bit in the character code indicates an @acronym{ASCII} control
972 character typed with the shift key held down.
973
974 For letters, the basic code itself indicates upper versus lower case;
975 for digits and punctuation, the shift key selects an entirely different
976 character with a different basic code. In order to keep within the
977 @acronym{ASCII} character set whenever possible, Emacs avoids using the
978 @tex
979 @math{2^{25}}
980 @end tex
981 @ifnottex
982 2**25
983 @end ifnottex
984 bit for those characters.
985
986 However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
987 @kbd{C-a}, so Emacs uses the
988 @tex
989 @math{2^{25}}
990 @end tex
991 @ifnottex
992 2**25
993 @end ifnottex
994 bit in @kbd{C-A} and not in
995 @kbd{C-a}.
996
997 @item hyper
998 The
999 @tex
1000 @math{2^{24}}
1001 @end tex
1002 @ifnottex
1003 2**24
1004 @end ifnottex
1005 bit in the character code indicates a character
1006 typed with the hyper key held down.
1007
1008 @item super
1009 The
1010 @tex
1011 @math{2^{23}}
1012 @end tex
1013 @ifnottex
1014 2**23
1015 @end ifnottex
1016 bit in the character code indicates a character
1017 typed with the super key held down.
1018
1019 @item alt
1020 The
1021 @tex
1022 @math{2^{22}}
1023 @end tex
1024 @ifnottex
1025 2**22
1026 @end ifnottex
1027 bit in the character code indicates a character typed with
1028 the alt key held down. (On some terminals, the key labeled @key{ALT}
1029 is actually the meta key.)
1030 @end table
1031
1032 It is best to avoid mentioning specific bit numbers in your program.
1033 To test the modifier bits of a character, use the function
1034 @code{event-modifiers} (@pxref{Classifying Events}). When making key
1035 bindings, you can use the read syntax for characters with modifier bits
1036 (@samp{\C-}, @samp{\M-}, and so on). For making key bindings with
1037 @code{define-key}, you can use lists such as @code{(control hyper ?x)} to
1038 specify the characters (@pxref{Changing Key Bindings}). The function
1039 @code{event-convert-list} converts such a list into an event type
1040 (@pxref{Classifying Events}).
1041
1042 @node Function Keys
1043 @subsection Function Keys
1044
1045 @cindex function keys
1046 Most keyboards also have @dfn{function keys}---keys that have names or
1047 symbols that are not characters. Function keys are represented in Emacs
1048 Lisp as symbols; the symbol's name is the function key's label, in lower
1049 case. For example, pressing a key labeled @key{F1} places the symbol
1050 @code{f1} in the input stream.
1051
1052 The event type of a function key event is the event symbol itself.
1053 @xref{Classifying Events}.
1054
1055 Here are a few special cases in the symbol-naming convention for
1056 function keys:
1057
1058 @table @asis
1059 @item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
1060 These keys correspond to common @acronym{ASCII} control characters that have
1061 special keys on most keyboards.
1062
1063 In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the
1064 terminal can distinguish between them, Emacs conveys the distinction to
1065 Lisp programs by representing the former as the integer 9, and the
1066 latter as the symbol @code{tab}.
1067
1068 Most of the time, it's not useful to distinguish the two. So normally
1069 @code{function-key-map} (@pxref{Translating Input}) is set up to map
1070 @code{tab} into 9. Thus, a key binding for character code 9 (the
1071 character @kbd{C-i}) also applies to @code{tab}. Likewise for the other
1072 symbols in this group. The function @code{read-char} likewise converts
1073 these events into characters.
1074
1075 In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace}
1076 converts into the character code 127 (@key{DEL}), not into code 8
1077 (@key{BS}). This is what most users prefer.
1078
1079 @item @code{left}, @code{up}, @code{right}, @code{down}
1080 Cursor arrow keys
1081 @item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
1082 Keypad keys (to the right of the regular keyboard).
1083 @item @code{kp-0}, @code{kp-1}, @dots{}
1084 Keypad keys with digits.
1085 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
1086 Keypad PF keys.
1087 @item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
1088 Keypad arrow keys. Emacs normally translates these into the
1089 corresponding non-keypad keys @code{home}, @code{left}, @dots{}
1090 @item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
1091 Additional keypad duplicates of keys ordinarily found elsewhere. Emacs
1092 normally translates these into the like-named non-keypad keys.
1093 @end table
1094
1095 You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
1096 @key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to
1097 represent them is with prefixes in the symbol name:
1098
1099 @table @samp
1100 @item A-
1101 The alt modifier.
1102 @item C-
1103 The control modifier.
1104 @item H-
1105 The hyper modifier.
1106 @item M-
1107 The meta modifier.
1108 @item S-
1109 The shift modifier.
1110 @item s-
1111 The super modifier.
1112 @end table
1113
1114 Thus, the symbol for the key @key{F3} with @key{META} held down is
1115 @code{M-f3}. When you use more than one prefix, we recommend you
1116 write them in alphabetical order; but the order does not matter in
1117 arguments to the key-binding lookup and modification functions.
1118
1119 @node Mouse Events
1120 @subsection Mouse Events
1121
1122 Emacs supports four kinds of mouse events: click events, drag events,
1123 button-down events, and motion events. All mouse events are represented
1124 as lists. The @sc{car} of the list is the event type; this says which
1125 mouse button was involved, and which modifier keys were used with it.
1126 The event type can also distinguish double or triple button presses
1127 (@pxref{Repeat Events}). The rest of the list elements give position
1128 and time information.
1129
1130 For key lookup, only the event type matters: two events of the same type
1131 necessarily run the same command. The command can access the full
1132 values of these events using the @samp{e} interactive code.
1133 @xref{Interactive Codes}.
1134
1135 A key sequence that starts with a mouse event is read using the keymaps
1136 of the buffer in the window that the mouse was in, not the current
1137 buffer. This does not imply that clicking in a window selects that
1138 window or its buffer---that is entirely under the control of the command
1139 binding of the key sequence.
1140
1141 @node Click Events
1142 @subsection Click Events
1143 @cindex click event
1144 @cindex mouse click event
1145
1146 When the user presses a mouse button and releases it at the same
1147 location, that generates a @dfn{click} event. All mouse click event
1148 share the same format:
1149
1150 @example
1151 (@var{event-type} @var{position} @var{click-count})
1152 @end example
1153
1154 @table @asis
1155 @item @var{event-type}
1156 This is a symbol that indicates which mouse button was used. It is
1157 one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the
1158 buttons are numbered left to right.
1159
1160 You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-},
1161 @samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift
1162 and super, just as you would with function keys.
1163
1164 This symbol also serves as the event type of the event. Key bindings
1165 describe events by their types; thus, if there is a key binding for
1166 @code{mouse-1}, that binding would apply to all events whose
1167 @var{event-type} is @code{mouse-1}.
1168
1169 @item @var{position}
1170 This is the position where the mouse click occurred. The actual
1171 format of @var{position} depends on what part of a window was clicked
1172 on. The various formats are described below.
1173
1174 @item @var{click-count}
1175 This is the number of rapid repeated presses so far of the same mouse
1176 button. @xref{Repeat Events}.
1177 @end table
1178
1179 For mouse click events in the text area, mode line, header line, or in
1180 the marginal areas, @var{position} has this form:
1181
1182 @example
1183 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
1184 @var{object} @var{text-pos} (@var{col} . @var{row})
1185 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
1186 @end example
1187
1188 @table @asis
1189 @item @var{window}
1190 This is the window in which the click occurred.
1191
1192 @item @var{pos-or-area}
1193 This is the buffer position of the character clicked on in the text
1194 area, or if clicked outside the text area, it is the window area in
1195 which the click occurred. It is one of the symbols @code{mode-line},
1196 @code{header-line}, @code{vertical-line}, @code{left-margin},
1197 @code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
1198
1199 @item @var{x}, @var{y}
1200 These are the pixel-denominated coordinates of the click, relative to
1201 the top left corner of @var{window}, which is @code{(0 . 0)}.
1202 For the mode or header line, @var{y} does not have meaningful data.
1203 For the vertical line, @var{x} does not have meaningful data.
1204
1205 @item @var{timestamp}
1206 This is the time at which the event occurred, in milliseconds.
1207
1208 @item @var{object}
1209 This is the object on which the click occurred. It is either
1210 @code{nil} if there is no string property, or it has the form
1211 (@var{string} . @var{string-pos}) when there is a string-type text
1212 property at the click position.
1213
1214 @item @var{string}
1215 This is the string on which the click occurred, including any
1216 properties.
1217
1218 @item @var{string-pos}
1219 This is the position in the string on which the click occurred,
1220 relevant if properties at the click need to be looked up.
1221
1222 @item @var{text-pos}
1223 For clicks on a marginal area or on a fringe, this is the buffer
1224 position of the first visible character in the corresponding line in
1225 the window. For other events, it is the current buffer position in
1226 the window.
1227
1228 @item @var{col}, @var{row}
1229 These are the actual coordinates of the glyph under the @var{x},
1230 @var{y} position, possibly padded with default character width
1231 glyphs if @var{x} is beyond the last glyph on the line.
1232
1233 @item @var{image}
1234 This is the image object on which the click occurred. It is either
1235 @code{nil} if there is no image at the position clicked on, or it is
1236 an image object as returned by @code{find-image} if click was in an image.
1237
1238 @item @var{dx}, @var{dy}
1239 These are the pixel-denominated coordinates of the click, relative to
1240 the top left corner of @var{object}, which is @code{(0 . 0)}. If
1241 @var{object} is @code{nil}, the coordinates are relative to the top
1242 left corner of the character glyph clicked on.
1243 @end table
1244
1245 For mouse clicks on a scroll-bar, @var{position} has this form:
1246
1247 @example
1248 (@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
1249 @end example
1250
1251 @table @asis
1252 @item @var{window}
1253 This is the window whose scroll-bar was clicked on.
1254
1255 @item @var{area}
1256 This is the scroll bar where the click occurred. It is one of the
1257 symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.
1258
1259 @item @var{portion}
1260 This is the distance of the click from the top or left end of
1261 the scroll bar.
1262
1263 @item @var{whole}
1264 This is the length of the entire scroll bar.
1265
1266 @item @var{timestamp}
1267 This is the time at which the event occurred, in milliseconds.
1268
1269 @item @var{part}
1270 This is the part of the scroll-bar which was clicked on. It is one
1271 of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
1272 @code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
1273 @end table
1274
1275 In one special case, @var{buffer-pos} is a list containing a symbol (one
1276 of the symbols listed above) instead of just the symbol. This happens
1277 after the imaginary prefix keys for the event are inserted into the
1278 input stream. @xref{Key Sequence Input}.
1279
1280 @node Drag Events
1281 @subsection Drag Events
1282 @cindex drag event
1283 @cindex mouse drag event
1284
1285 With Emacs, you can have a drag event without even changing your
1286 clothes. A @dfn{drag event} happens every time the user presses a mouse
1287 button and then moves the mouse to a different character position before
1288 releasing the button. Like all mouse events, drag events are
1289 represented in Lisp as lists. The lists record both the starting mouse
1290 position and the final position, like this:
1291
1292 @example
1293 (@var{event-type}
1294 (@var{window1} @var{buffer-pos1} (@var{x1} . @var{y1}) @var{timestamp1})
1295 (@var{window2} @var{buffer-pos2} (@var{x2} . @var{y2}) @var{timestamp2})
1296 @var{click-count})
1297 @end example
1298
1299 For a drag event, the name of the symbol @var{event-type} contains the
1300 prefix @samp{drag-}. For example, dragging the mouse with button 2 held
1301 down generates a @code{drag-mouse-2} event. The second and third
1302 elements of the event give the starting and ending position of the drag.
1303 Aside from that, the data have the same meanings as in a click event
1304 (@pxref{Click Events}). You can access the second element of any mouse
1305 event in the same way, with no need to distinguish drag events from
1306 others.
1307
1308 The @samp{drag-} prefix follows the modifier key prefixes such as
1309 @samp{C-} and @samp{M-}.
1310
1311 If @code{read-key-sequence} receives a drag event that has no key
1312 binding, and the corresponding click event does have a binding, it
1313 changes the drag event into a click event at the drag's starting
1314 position. This means that you don't have to distinguish between click
1315 and drag events unless you want to.
1316
1317 @node Button-Down Events
1318 @subsection Button-Down Events
1319 @cindex button-down event
1320
1321 Click and drag events happen when the user releases a mouse button.
1322 They cannot happen earlier, because there is no way to distinguish a
1323 click from a drag until the button is released.
1324
1325 If you want to take action as soon as a button is pressed, you need to
1326 handle @dfn{button-down} events.@footnote{Button-down is the
1327 conservative antithesis of drag.} These occur as soon as a button is
1328 pressed. They are represented by lists that look exactly like click
1329 events (@pxref{Click Events}), except that the @var{event-type} symbol
1330 name contains the prefix @samp{down-}. The @samp{down-} prefix follows
1331 modifier key prefixes such as @samp{C-} and @samp{M-}.
1332
1333 The function @code{read-key-sequence} ignores any button-down events
1334 that don't have command bindings; therefore, the Emacs command loop
1335 ignores them too. This means that you need not worry about defining
1336 button-down events unless you want them to do something. The usual
1337 reason to define a button-down event is so that you can track mouse
1338 motion (by reading motion events) until the button is released.
1339 @xref{Motion Events}.
1340
1341 @node Repeat Events
1342 @subsection Repeat Events
1343 @cindex repeat events
1344 @cindex double-click events
1345 @cindex triple-click events
1346 @cindex mouse events, repeated
1347
1348 If you press the same mouse button more than once in quick succession
1349 without moving the mouse, Emacs generates special @dfn{repeat} mouse
1350 events for the second and subsequent presses.
1351
1352 The most common repeat events are @dfn{double-click} events. Emacs
1353 generates a double-click event when you click a button twice; the event
1354 happens when you release the button (as is normal for all click
1355 events).
1356
1357 The event type of a double-click event contains the prefix
1358 @samp{double-}. Thus, a double click on the second mouse button with
1359 @key{meta} held down comes to the Lisp program as
1360 @code{M-double-mouse-2}. If a double-click event has no binding, the
1361 binding of the corresponding ordinary click event is used to execute
1362 it. Thus, you need not pay attention to the double click feature
1363 unless you really want to.
1364
1365 When the user performs a double click, Emacs generates first an ordinary
1366 click event, and then a double-click event. Therefore, you must design
1367 the command binding of the double click event to assume that the
1368 single-click command has already run. It must produce the desired
1369 results of a double click, starting from the results of a single click.
1370
1371 This is convenient, if the meaning of a double click somehow ``builds
1372 on'' the meaning of a single click---which is recommended user interface
1373 design practice for double clicks.
1374
1375 If you click a button, then press it down again and start moving the
1376 mouse with the button held down, then you get a @dfn{double-drag} event
1377 when you ultimately release the button. Its event type contains
1378 @samp{double-drag} instead of just @samp{drag}. If a double-drag event
1379 has no binding, Emacs looks for an alternate binding as if the event
1380 were an ordinary drag.
1381
1382 Before the double-click or double-drag event, Emacs generates a
1383 @dfn{double-down} event when the user presses the button down for the
1384 second time. Its event type contains @samp{double-down} instead of just
1385 @samp{down}. If a double-down event has no binding, Emacs looks for an
1386 alternate binding as if the event were an ordinary button-down event.
1387 If it finds no binding that way either, the double-down event is
1388 ignored.
1389
1390 To summarize, when you click a button and then press it again right
1391 away, Emacs generates a down event and a click event for the first
1392 click, a double-down event when you press the button again, and finally
1393 either a double-click or a double-drag event.
1394
1395 If you click a button twice and then press it again, all in quick
1396 succession, Emacs generates a @dfn{triple-down} event, followed by
1397 either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of
1398 these events contain @samp{triple} instead of @samp{double}. If any
1399 triple event has no binding, Emacs uses the binding that it would use
1400 for the corresponding double event.
1401
1402 If you click a button three or more times and then press it again, the
1403 events for the presses beyond the third are all triple events. Emacs
1404 does not have separate event types for quadruple, quintuple, etc.@:
1405 events. However, you can look at the event list to find out precisely
1406 how many times the button was pressed.
1407
1408 @defun event-click-count event
1409 This function returns the number of consecutive button presses that led
1410 up to @var{event}. If @var{event} is a double-down, double-click or
1411 double-drag event, the value is 2. If @var{event} is a triple event,
1412 the value is 3 or greater. If @var{event} is an ordinary mouse event
1413 (not a repeat event), the value is 1.
1414 @end defun
1415
1416 @defopt double-click-fuzz
1417 To generate repeat events, successive mouse button presses must be at
1418 approximately the same screen position. The value of
1419 @code{double-click-fuzz} specifies the maximum number of pixels the
1420 mouse may be moved (horizontally or vertically) between two successive
1421 clicks to make a double-click.
1422
1423 This variable is also the threshold for motion of the mouse to count
1424 as a drag.
1425 @end defopt
1426
1427 @defopt double-click-time
1428 To generate repeat events, the number of milliseconds between
1429 successive button presses must be less than the value of
1430 @code{double-click-time}. Setting @code{double-click-time} to
1431 @code{nil} disables multi-click detection entirely. Setting it to
1432 @code{t} removes the time limit; Emacs then detects multi-clicks by
1433 position only.
1434 @end defopt
1435
1436 @node Motion Events
1437 @subsection Motion Events
1438 @cindex motion event
1439 @cindex mouse motion events
1440
1441 Emacs sometimes generates @dfn{mouse motion} events to describe motion
1442 of the mouse without any button activity. Mouse motion events are
1443 represented by lists that look like this:
1444
1445 @example
1446 (mouse-movement (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}))
1447 @end example
1448
1449 The second element of the list describes the current position of the
1450 mouse, just as in a click event (@pxref{Click Events}).
1451
1452 The special form @code{track-mouse} enables generation of motion events
1453 within its body. Outside of @code{track-mouse} forms, Emacs does not
1454 generate events for mere motion of the mouse, and these events do not
1455 appear. @xref{Mouse Tracking}.
1456
1457 @node Focus Events
1458 @subsection Focus Events
1459 @cindex focus event
1460
1461 Window systems provide general ways for the user to control which window
1462 gets keyboard input. This choice of window is called the @dfn{focus}.
1463 When the user does something to switch between Emacs frames, that
1464 generates a @dfn{focus event}. The normal definition of a focus event,
1465 in the global keymap, is to select a new frame within Emacs, as the user
1466 would expect. @xref{Input Focus}.
1467
1468 Focus events are represented in Lisp as lists that look like this:
1469
1470 @example
1471 (switch-frame @var{new-frame})
1472 @end example
1473
1474 @noindent
1475 where @var{new-frame} is the frame switched to.
1476
1477 Most X window managers are set up so that just moving the mouse into a
1478 window is enough to set the focus there. Emacs appears to do this,
1479 because it changes the cursor to solid in the new frame. However, there
1480 is no need for the Lisp program to know about the focus change until
1481 some other kind of input arrives. So Emacs generates a focus event only
1482 when the user actually types a keyboard key or presses a mouse button in
1483 the new frame; just moving the mouse between frames does not generate a
1484 focus event.
1485
1486 A focus event in the middle of a key sequence would garble the
1487 sequence. So Emacs never generates a focus event in the middle of a key
1488 sequence. If the user changes focus in the middle of a key
1489 sequence---that is, after a prefix key---then Emacs reorders the events
1490 so that the focus event comes either before or after the multi-event key
1491 sequence, and not within it.
1492
1493 @node Misc Events
1494 @subsection Miscellaneous System Events
1495
1496 A few other event types represent occurrences within the system.
1497
1498 @table @code
1499 @cindex @code{delete-frame} event
1500 @item (delete-frame (@var{frame}))
1501 This kind of event indicates that the user gave the window manager
1502 a command to delete a particular window, which happens to be an Emacs frame.
1503
1504 The standard definition of the @code{delete-frame} event is to delete @var{frame}.
1505
1506 @cindex @code{iconify-frame} event
1507 @item (iconify-frame (@var{frame}))
1508 This kind of event indicates that the user iconified @var{frame} using
1509 the window manager. Its standard definition is @code{ignore}; since the
1510 frame has already been iconified, Emacs has no work to do. The purpose
1511 of this event type is so that you can keep track of such events if you
1512 want to.
1513
1514 @cindex @code{make-frame-visible} event
1515 @item (make-frame-visible (@var{frame}))
1516 This kind of event indicates that the user deiconified @var{frame} using
1517 the window manager. Its standard definition is @code{ignore}; since the
1518 frame has already been made visible, Emacs has no work to do.
1519
1520 @cindex @code{wheel-up} event
1521 @cindex @code{wheel-down} event
1522 @item (wheel-up @var{position})
1523 @item (wheel-down @var{position})
1524 These kinds of event are generated by moving a mouse wheel. Their
1525 usual meaning is a kind of scroll or zoom.
1526
1527 The element @var{position} is a list describing the position of the
1528 event, in the same format as used in a mouse-click event.
1529
1530 This kind of event is generated only on some kinds of systems. On some
1531 systems, @code{mouse-4} and @code{mouse-5} are used instead. For
1532 portable code, use the variables @code{mouse-wheel-up-event} and
1533 @code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine
1534 what event types to expect for the mouse wheel.
1535
1536 @cindex @code{drag-n-drop} event
1537 @item (drag-n-drop @var{position} @var{files})
1538 This kind of event is generated when a group of files is
1539 selected in an application outside of Emacs, and then dragged and
1540 dropped onto an Emacs frame.
1541
1542 The element @var{position} is a list describing the position of the
1543 event, in the same format as used in a mouse-click event, and
1544 @var{files} is the list of file names that were dragged and dropped.
1545 The usual way to handle this event is by visiting these files.
1546
1547 This kind of event is generated, at present, only on some kinds of
1548 systems.
1549
1550 @cindex @code{usr1-signal} event
1551 @cindex @code{usr2-signal} event
1552 @item usr1-signal
1553 @itemx usr2-signal
1554 These events are generated when the Emacs process receives the signals
1555 @code{SIGUSR1} and @code{SIGUSR2}. They contain no additional data
1556 because signals do not carry additional information.
1557 @end table
1558
1559 If one of these events arrives in the middle of a key sequence---that
1560 is, after a prefix key---then Emacs reorders the events so that this
1561 event comes either before or after the multi-event key sequence, not
1562 within it.
1563
1564 @node Event Examples
1565 @subsection Event Examples
1566
1567 If the user presses and releases the left mouse button over the same
1568 location, that generates a sequence of events like this:
1569
1570 @smallexample
1571 (down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
1572 (mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180))
1573 @end smallexample
1574
1575 While holding the control key down, the user might hold down the
1576 second mouse button, and drag the mouse from one line to the next.
1577 That produces two events, as shown here:
1578
1579 @smallexample
1580 (C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
1581 (C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
1582 (#<window 18 on NEWS> 3510 (0 . 28) -729648))
1583 @end smallexample
1584
1585 While holding down the meta and shift keys, the user might press the
1586 second mouse button on the window's mode line, and then drag the mouse
1587 into another window. That produces a pair of events like these:
1588
1589 @smallexample
1590 (M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
1591 (M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
1592 (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
1593 -453816))
1594 @end smallexample
1595
1596 @node Classifying Events
1597 @subsection Classifying Events
1598 @cindex event type
1599
1600 Every event has an @dfn{event type}, which classifies the event for
1601 key binding purposes. For a keyboard event, the event type equals the
1602 event value; thus, the event type for a character is the character, and
1603 the event type for a function key symbol is the symbol itself. For
1604 events that are lists, the event type is the symbol in the @sc{car} of
1605 the list. Thus, the event type is always a symbol or a character.
1606
1607 Two events of the same type are equivalent where key bindings are
1608 concerned; thus, they always run the same command. That does not
1609 necessarily mean they do the same things, however, as some commands look
1610 at the whole event to decide what to do. For example, some commands use
1611 the location of a mouse event to decide where in the buffer to act.
1612
1613 Sometimes broader classifications of events are useful. For example,
1614 you might want to ask whether an event involved the @key{META} key,
1615 regardless of which other key or mouse button was used.
1616
1617 The functions @code{event-modifiers} and @code{event-basic-type} are
1618 provided to get such information conveniently.
1619
1620 @defun event-modifiers event
1621 This function returns a list of the modifiers that @var{event} has. The
1622 modifiers are symbols; they include @code{shift}, @code{control},
1623 @code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition,
1624 the modifiers list of a mouse event symbol always contains one of
1625 @code{click}, @code{drag}, and @code{down}. For double or triple
1626 events, it also contains @code{double} or @code{triple}.
1627
1628 The argument @var{event} may be an entire event object, or just an
1629 event type. If @var{event} is a symbol that has never been used in an
1630 event that has been read as input in the current Emacs session, then
1631 @code{event-modifiers} can return @code{nil}, even when @var{event}
1632 actually has modifiers.
1633
1634 Here are some examples:
1635
1636 @example
1637 (event-modifiers ?a)
1638 @result{} nil
1639 (event-modifiers ?A)
1640 @result{} (shift)
1641 (event-modifiers ?\C-a)
1642 @result{} (control)
1643 (event-modifiers ?\C-%)
1644 @result{} (control)
1645 (event-modifiers ?\C-\S-a)
1646 @result{} (control shift)
1647 (event-modifiers 'f5)
1648 @result{} nil
1649 (event-modifiers 's-f5)
1650 @result{} (super)
1651 (event-modifiers 'M-S-f5)
1652 @result{} (meta shift)
1653 (event-modifiers 'mouse-1)
1654 @result{} (click)
1655 (event-modifiers 'down-mouse-1)
1656 @result{} (down)
1657 @end example
1658
1659 The modifiers list for a click event explicitly contains @code{click},
1660 but the event symbol name itself does not contain @samp{click}.
1661 @end defun
1662
1663 @defun event-basic-type event
1664 This function returns the key or mouse button that @var{event}
1665 describes, with all modifiers removed. The @var{event} argument is as
1666 in @code{event-modifiers}. For example:
1667
1668 @example
1669 (event-basic-type ?a)
1670 @result{} 97
1671 (event-basic-type ?A)
1672 @result{} 97
1673 (event-basic-type ?\C-a)
1674 @result{} 97
1675 (event-basic-type ?\C-\S-a)
1676 @result{} 97
1677 (event-basic-type 'f5)
1678 @result{} f5
1679 (event-basic-type 's-f5)
1680 @result{} f5
1681 (event-basic-type 'M-S-f5)
1682 @result{} f5
1683 (event-basic-type 'down-mouse-1)
1684 @result{} mouse-1
1685 @end example
1686 @end defun
1687
1688 @defun mouse-movement-p object
1689 This function returns non-@code{nil} if @var{object} is a mouse movement
1690 event.
1691 @end defun
1692
1693 @defun event-convert-list list
1694 This function converts a list of modifier names and a basic event type
1695 to an event type which specifies all of them. The basic event type
1696 must be the last element of the list. For example,
1697
1698 @example
1699 (event-convert-list '(control ?a))
1700 @result{} 1
1701 (event-convert-list '(control meta ?a))
1702 @result{} -134217727
1703 (event-convert-list '(control super f1))
1704 @result{} C-s-f1
1705 @end example
1706 @end defun
1707
1708 @node Accessing Events
1709 @subsection Accessing Events
1710 @cindex mouse events, accessing the data
1711 @cindex accessing data of mouse events
1712
1713 This section describes convenient functions for accessing the data in
1714 a mouse button or motion event.
1715
1716 These two functions return the starting or ending position of a
1717 mouse-button event, as a list of this form:
1718
1719 @example
1720 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
1721 @var{object} @var{text-pos} (@var{col} . @var{row})
1722 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
1723 @end example
1724
1725 @defun event-start event
1726 This returns the starting position of @var{event}.
1727
1728 If @var{event} is a click or button-down event, this returns the
1729 location of the event. If @var{event} is a drag event, this returns the
1730 drag's starting position.
1731 @end defun
1732
1733 @defun event-end event
1734 This returns the ending position of @var{event}.
1735
1736 If @var{event} is a drag event, this returns the position where the user
1737 released the mouse button. If @var{event} is a click or button-down
1738 event, the value is actually the starting position, which is the only
1739 position such events have.
1740 @end defun
1741
1742 @cindex mouse position list, accessing
1743 These functions take a position list as described above, and
1744 return various parts of it.
1745
1746 @defun posn-window position
1747 Return the window that @var{position} is in.
1748 @end defun
1749
1750 @defun posn-area position
1751 Return the window area recorded in @var{position}. It returns @code{nil}
1752 when the event occurred in the text area of the window; otherwise, it
1753 is a symbol identifying the area in which the the event occurred.
1754 @end defun
1755
1756 @defun posn-point position
1757 Return the buffer position in @var{position}. When the event occurred
1758 in the text area of the window, in a marginal area, or on a fringe,
1759 this is an integer specifying a buffer position. Otherwise, the value
1760 is undefined.
1761 @end defun
1762
1763 @defun posn-x-y position
1764 Return the pixel-based x and y coordinates in @var{position}, as a
1765 cons cell @code{(@var{x} . @var{y})}. These coordinates are relative
1766 to the window given by @code{posn-window}.
1767
1768 This example shows how to convert these window-relative coordinates
1769 into frame-relative coordinates:
1770
1771 @example
1772 (defun frame-relative-coordinates (position)
1773 "Return frame-relative coordinates from POSITION."
1774 (let* ((x-y (posn-x-y position))
1775 (window (posn-window position))
1776 (edges (window-inside-pixel-edges window)))
1777 (cons (+ (car x-y) (car edges))
1778 (+ (cdr x-y) (cadr edges)))))
1779 @end example
1780 @end defun
1781
1782 @defun posn-col-row position
1783 Return the row and column (in units of the frame's default character
1784 height and width) of @var{position}, as a cons cell @code{(@var{col} .
1785 @var{row})}. These are computed from the @var{x} and @var{y} values
1786 actually found in @var{position}.
1787 @end defun
1788
1789 @defun posn-actual-col-row position
1790 Return the actual row and column in @var{position}, as a cons cell
1791 @code{(@var{col} . @var{row})}. The values are the actual row number
1792 in the window, and the actual character number in that row. It returns
1793 @code{nil} if @var{position} does not include actual positions values.
1794 You can use @code{posn-col-row} to get approximate values.
1795 @end defun
1796
1797 @defun posn-string position
1798 Return the string object in @var{position}, either @code{nil}, or a
1799 cons cell @code{(@var{string} . @var{string-pos})}.
1800 @end defun
1801
1802 @defun posn-image position
1803 Return the image object in @var{position}, either @code{nil}, or an
1804 image @code{(image ...)}.
1805 @end defun
1806
1807 @defun posn-object position
1808 Return the image or string object in @var{position}, either
1809 @code{nil}, an image @code{(image ...)}, or a cons cell
1810 @code{(@var{string} . @var{string-pos})}.
1811 @end defun
1812
1813 @defun posn-object-x-y position
1814 Return the pixel-based x and y coordinates relative to the upper left
1815 corner of the object in @var{position} as a cons cell @code{(@var{dx}
1816 . @var{dy})}. If the @var{position} is a buffer position, return the
1817 relative position in the character at that position.
1818 @end defun
1819
1820 @defun posn-object-width-height position
1821 Return the pixel width and height of the object in @var{position} as a
1822 cons cell @code{(@var{width} . @var{height})}. If the @var{position}
1823 is a buffer position, return the size of the character at that position.
1824 @end defun
1825
1826 @cindex mouse event, timestamp
1827 @cindex timestamp of a mouse event
1828 @defun posn-timestamp position
1829 Return the timestamp in @var{position}. This is the time at which the
1830 event occurred, in milliseconds.
1831 @end defun
1832
1833 These functions compute a position list given particular buffer
1834 position or screen position. You can access the data in this position
1835 list with the functions described above.
1836
1837 @defun posn-at-point &optional pos window
1838 This function returns a position list for position @var{pos} in
1839 @var{window}. @var{pos} defaults to point in @var{window};
1840 @var{window} defaults to the selected window.
1841
1842 @code{posn-at-point} returns @code{nil} if @var{pos} is not visible in
1843 @var{window}.
1844 @end defun
1845
1846 @defun posn-at-x-y x y &optional frame-or-window
1847 This function returns position information corresponding to pixel
1848 coordinates @var{x} and @var{y} in a specified frame or window,
1849 @var{frame-or-window}, which defaults to the selected window.
1850 The coordinates @var{x} and @var{y} are relative to the
1851 frame or window used.
1852 @end defun
1853
1854 These functions are useful for decoding scroll bar events.
1855
1856 @defun scroll-bar-event-ratio event
1857 This function returns the fractional vertical position of a scroll bar
1858 event within the scroll bar. The value is a cons cell
1859 @code{(@var{portion} . @var{whole})} containing two integers whose ratio
1860 is the fractional position.
1861 @end defun
1862
1863 @defun scroll-bar-scale ratio total
1864 This function multiplies (in effect) @var{ratio} by @var{total},
1865 rounding the result to an integer. The argument @var{ratio} is not a
1866 number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
1867 value returned by @code{scroll-bar-event-ratio}.
1868
1869 This function is handy for scaling a position on a scroll bar into a
1870 buffer position. Here's how to do that:
1871
1872 @example
1873 (+ (point-min)
1874 (scroll-bar-scale
1875 (posn-x-y (event-start event))
1876 (- (point-max) (point-min))))
1877 @end example
1878
1879 Recall that scroll bar events have two integers forming a ratio, in place
1880 of a pair of x and y coordinates.
1881 @end defun
1882
1883 @node Strings of Events
1884 @subsection Putting Keyboard Events in Strings
1885 @cindex keyboard events in strings
1886 @cindex strings with keyboard events
1887
1888 In most of the places where strings are used, we conceptualize the
1889 string as containing text characters---the same kind of characters found
1890 in buffers or files. Occasionally Lisp programs use strings that
1891 conceptually contain keyboard characters; for example, they may be key
1892 sequences or keyboard macro definitions. However, storing keyboard
1893 characters in a string is a complex matter, for reasons of historical
1894 compatibility, and it is not always possible.
1895
1896 We recommend that new programs avoid dealing with these complexities
1897 by not storing keyboard events in strings. Here is how to do that:
1898
1899 @itemize @bullet
1900 @item
1901 Use vectors instead of strings for key sequences, when you plan to use
1902 them for anything other than as arguments to @code{lookup-key} and
1903 @code{define-key}. For example, you can use
1904 @code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
1905 @code{this-command-keys-vector} instead of @code{this-command-keys}.
1906
1907 @item
1908 Use vectors to write key sequence constants containing meta characters,
1909 even when passing them directly to @code{define-key}.
1910
1911 @item
1912 When you have to look at the contents of a key sequence that might be a
1913 string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
1914 first, to convert it to a list.
1915 @end itemize
1916
1917 The complexities stem from the modifier bits that keyboard input
1918 characters can include. Aside from the Meta modifier, none of these
1919 modifier bits can be included in a string, and the Meta modifier is
1920 allowed only in special cases.
1921
1922 The earliest GNU Emacs versions represented meta characters as codes
1923 in the range of 128 to 255. At that time, the basic character codes
1924 ranged from 0 to 127, so all keyboard character codes did fit in a
1925 string. Many Lisp programs used @samp{\M-} in string constants to stand
1926 for meta characters, especially in arguments to @code{define-key} and
1927 similar functions, and key sequences and sequences of events were always
1928 represented as strings.
1929
1930 When we added support for larger basic character codes beyond 127, and
1931 additional modifier bits, we had to change the representation of meta
1932 characters. Now the flag that represents the Meta modifier in a
1933 character is
1934 @tex
1935 @math{2^{27}}
1936 @end tex
1937 @ifnottex
1938 2**27
1939 @end ifnottex
1940 and such numbers cannot be included in a string.
1941
1942 To support programs with @samp{\M-} in string constants, there are
1943 special rules for including certain meta characters in a string.
1944 Here are the rules for interpreting a string as a sequence of input
1945 characters:
1946
1947 @itemize @bullet
1948 @item
1949 If the keyboard character value is in the range of 0 to 127, it can go
1950 in the string unchanged.
1951
1952 @item
1953 The meta variants of those characters, with codes in the range of
1954 @tex
1955 @math{2^{27}}
1956 @end tex
1957 @ifnottex
1958 2**27
1959 @end ifnottex
1960 to
1961 @tex
1962 @math{2^{27} + 127},
1963 @end tex
1964 @ifnottex
1965 2**27+127,
1966 @end ifnottex
1967 can also go in the string, but you must change their
1968 numeric values. You must set the
1969 @tex
1970 @math{2^{7}}
1971 @end tex
1972 @ifnottex
1973 2**7
1974 @end ifnottex
1975 bit instead of the
1976 @tex
1977 @math{2^{27}}
1978 @end tex
1979 @ifnottex
1980 2**27
1981 @end ifnottex
1982 bit, resulting in a value between 128 and 255. Only a unibyte string
1983 can include these codes.
1984
1985 @item
1986 Non-@acronym{ASCII} characters above 256 can be included in a multibyte string.
1987
1988 @item
1989 Other keyboard character events cannot fit in a string. This includes
1990 keyboard events in the range of 128 to 255.
1991 @end itemize
1992
1993 Functions such as @code{read-key-sequence} that construct strings of
1994 keyboard input characters follow these rules: they construct vectors
1995 instead of strings, when the events won't fit in a string.
1996
1997 When you use the read syntax @samp{\M-} in a string, it produces a
1998 code in the range of 128 to 255---the same code that you get if you
1999 modify the corresponding keyboard event to put it in the string. Thus,
2000 meta events in strings work consistently regardless of how they get into
2001 the strings.
2002
2003 However, most programs would do well to avoid these issues by
2004 following the recommendations at the beginning of this section.
2005
2006 @node Reading Input
2007 @section Reading Input
2008
2009 The editor command loop reads key sequences using the function
2010 @code{read-key-sequence}, which uses @code{read-event}. These and other
2011 functions for event input are also available for use in Lisp programs.
2012 See also @code{momentary-string-display} in @ref{Temporary Displays},
2013 and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
2014 functions and variables for controlling terminal input modes and
2015 debugging terminal input. @xref{Translating Input}, for features you
2016 can use for translating or modifying input events while reading them.
2017
2018 For higher-level input facilities, see @ref{Minibuffers}.
2019
2020 @menu
2021 * Key Sequence Input:: How to read one key sequence.
2022 * Reading One Event:: How to read just one event.
2023 * Invoking the Input Method:: How reading an event uses the input method.
2024 * Quoted Character Input:: Asking the user to specify a character.
2025 * Event Input Misc:: How to reread or throw away input events.
2026 @end menu
2027
2028 @node Key Sequence Input
2029 @subsection Key Sequence Input
2030 @cindex key sequence input
2031
2032 The command loop reads input a key sequence at a time, by calling
2033 @code{read-key-sequence}. Lisp programs can also call this function;
2034 for example, @code{describe-key} uses it to read the key to describe.
2035
2036 @defun read-key-sequence prompt
2037 @cindex key sequence
2038 This function reads a key sequence and returns it as a string or
2039 vector. It keeps reading events until it has accumulated a complete key
2040 sequence; that is, enough to specify a non-prefix command using the
2041 currently active keymaps. (Remember that a key sequence that starts
2042 with a mouse event is read using the keymaps of the buffer in the
2043 window that the mouse was in, not the current buffer.)
2044
2045 If the events are all characters and all can fit in a string, then
2046 @code{read-key-sequence} returns a string (@pxref{Strings of Events}).
2047 Otherwise, it returns a vector, since a vector can hold all kinds of
2048 events---characters, symbols, and lists. The elements of the string or
2049 vector are the events in the key sequence.
2050
2051 The argument @var{prompt} is either a string to be displayed in the echo
2052 area as a prompt, or @code{nil}, meaning not to display a prompt.
2053
2054 In the example below, the prompt @samp{?} is displayed in the echo area,
2055 and the user types @kbd{C-x C-f}.
2056
2057 @example
2058 (read-key-sequence "?")
2059
2060 @group
2061 ---------- Echo Area ----------
2062 ?@kbd{C-x C-f}
2063 ---------- Echo Area ----------
2064
2065 @result{} "^X^F"
2066 @end group
2067 @end example
2068
2069 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
2070 typed while reading with this function works like any other character,
2071 and does not set @code{quit-flag}. @xref{Quitting}.
2072 @end defun
2073
2074 @defun read-key-sequence-vector prompt
2075 This is like @code{read-key-sequence} except that it always
2076 returns the key sequence as a vector, never as a string.
2077 @xref{Strings of Events}.
2078 @end defun
2079
2080 @cindex upper case key sequence
2081 @cindex downcasing in @code{lookup-key}
2082 If an input character is upper-case (or has the shift modifier) and
2083 has no key binding, but its lower-case equivalent has one, then
2084 @code{read-key-sequence} converts the character to lower case. Note
2085 that @code{lookup-key} does not perform case conversion in this way.
2086
2087 The function @code{read-key-sequence} also transforms some mouse events.
2088 It converts unbound drag events into click events, and discards unbound
2089 button-down events entirely. It also reshuffles focus events and
2090 miscellaneous window events so that they never appear in a key sequence
2091 with any other events.
2092
2093 @cindex @code{header-line} prefix key
2094 @cindex @code{mode-line} prefix key
2095 @cindex @code{vertical-line} prefix key
2096 @cindex @code{horizontal-scroll-bar} prefix key
2097 @cindex @code{vertical-scroll-bar} prefix key
2098 @cindex @code{menu-bar} prefix key
2099 @cindex mouse events, in special parts of frame
2100 When mouse events occur in special parts of a window, such as a mode
2101 line or a scroll bar, the event type shows nothing special---it is the
2102 same symbol that would normally represent that combination of mouse
2103 button and modifier keys. The information about the window part is kept
2104 elsewhere in the event---in the coordinates. But
2105 @code{read-key-sequence} translates this information into imaginary
2106 ``prefix keys'', all of which are symbols: @code{header-line},
2107 @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
2108 @code{vertical-line}, and @code{vertical-scroll-bar}. You can define
2109 meanings for mouse clicks in special window parts by defining key
2110 sequences using these imaginary prefix keys.
2111
2112 For example, if you call @code{read-key-sequence} and then click the
2113 mouse on the window's mode line, you get two events, like this:
2114
2115 @example
2116 (read-key-sequence "Click on the mode line: ")
2117 @result{} [mode-line
2118 (mouse-1
2119 (#<window 6 on NEWS> mode-line
2120 (40 . 63) 5959987))]
2121 @end example
2122
2123 @defvar num-input-keys
2124 @c Emacs 19 feature
2125 This variable's value is the number of key sequences processed so far in
2126 this Emacs session. This includes key sequences read from the terminal
2127 and key sequences read from keyboard macros being executed.
2128 @end defvar
2129
2130 @defvar num-nonmacro-input-events
2131 This variable holds the total number of input events received so far
2132 from the terminal---not counting those generated by keyboard macros.
2133 @end defvar
2134
2135 @node Reading One Event
2136 @subsection Reading One Event
2137 @cindex reading a single event
2138 @cindex event, reading only one
2139
2140 The lowest level functions for command input are those that read a
2141 single event.
2142
2143 None of the three functions below suppresses quitting.
2144
2145 @defun read-event &optional prompt inherit-input-method
2146 This function reads and returns the next event of command input, waiting
2147 if necessary until an event is available. Events can come directly from
2148 the user or from a keyboard macro.
2149
2150 If the optional argument @var{prompt} is non-@code{nil}, it should be a
2151 string to display in the echo area as a prompt. Otherwise,
2152 @code{read-event} does not display any message to indicate it is waiting
2153 for input; instead, it prompts by echoing: it displays descriptions of
2154 the events that led to or were read by the current command. @xref{The
2155 Echo Area}.
2156
2157 If @var{inherit-input-method} is non-@code{nil}, then the current input
2158 method (if any) is employed to make it possible to enter a
2159 non-@acronym{ASCII} character. Otherwise, input method handling is disabled
2160 for reading this event.
2161
2162 If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
2163 moves the cursor temporarily to the echo area, to the end of any message
2164 displayed there. Otherwise @code{read-event} does not move the cursor.
2165
2166 If @code{read-event} gets an event that is defined as a help character,
2167 then in some cases @code{read-event} processes the event directly without
2168 returning. @xref{Help Functions}. Certain other events, called
2169 @dfn{special events}, are also processed directly within
2170 @code{read-event} (@pxref{Special Events}).
2171
2172 Here is what happens if you call @code{read-event} and then press the
2173 right-arrow function key:
2174
2175 @example
2176 @group
2177 (read-event)
2178 @result{} right
2179 @end group
2180 @end example
2181 @end defun
2182
2183 @defun read-char &optional prompt inherit-input-method
2184 This function reads and returns a character of command input. If the
2185 user generates an event which is not a character (i.e. a mouse click or
2186 function key event), @code{read-char} signals an error. The arguments
2187 work as in @code{read-event}.
2188
2189 In the first example, the user types the character @kbd{1} (@acronym{ASCII}
2190 code 49). The second example shows a keyboard macro definition that
2191 calls @code{read-char} from the minibuffer using @code{eval-expression}.
2192 @code{read-char} reads the keyboard macro's very next character, which
2193 is @kbd{1}. Then @code{eval-expression} displays its return value in
2194 the echo area.
2195
2196 @example
2197 @group
2198 (read-char)
2199 @result{} 49
2200 @end group
2201
2202 @group
2203 ;; @r{We assume here you use @kbd{M-:} to evaluate this.}
2204 (symbol-function 'foo)
2205 @result{} "^[:(read-char)^M1"
2206 @end group
2207 @group
2208 (execute-kbd-macro 'foo)
2209 @print{} 49
2210 @result{} nil
2211 @end group
2212 @end example
2213 @end defun
2214
2215 @defun read-char-exclusive &optional prompt inherit-input-method
2216 This function reads and returns a character of command input. If the
2217 user generates an event which is not a character,
2218 @code{read-char-exclusive} ignores it and reads another event, until it
2219 gets a character. The arguments work as in @code{read-event}.
2220 @end defun
2221
2222 @node Invoking the Input Method
2223 @subsection Invoking the Input Method
2224
2225 The event-reading functions invoke the current input method, if any
2226 (@pxref{Input Methods}). If the value of @code{input-method-function}
2227 is non-@code{nil}, it should be a function; when @code{read-event} reads
2228 a printing character (including @key{SPC}) with no modifier bits, it
2229 calls that function, passing the character as an argument.
2230
2231 @defvar input-method-function
2232 If this is non-@code{nil}, its value specifies the current input method
2233 function.
2234
2235 @strong{Warning:} don't bind this variable with @code{let}. It is often
2236 buffer-local, and if you bind it around reading input (which is exactly
2237 when you @emph{would} bind it), switching buffers asynchronously while
2238 Emacs is waiting will cause the value to be restored in the wrong
2239 buffer.
2240 @end defvar
2241
2242 The input method function should return a list of events which should
2243 be used as input. (If the list is @code{nil}, that means there is no
2244 input, so @code{read-event} waits for another event.) These events are
2245 processed before the events in @code{unread-command-events}
2246 (@pxref{Event Input Misc}). Events
2247 returned by the input method function are not passed to the input method
2248 function again, even if they are printing characters with no modifier
2249 bits.
2250
2251 If the input method function calls @code{read-event} or
2252 @code{read-key-sequence}, it should bind @code{input-method-function} to
2253 @code{nil} first, to prevent recursion.
2254
2255 The input method function is not called when reading the second and
2256 subsequent events of a key sequence. Thus, these characters are not
2257 subject to input method processing. The input method function should
2258 test the values of @code{overriding-local-map} and
2259 @code{overriding-terminal-local-map}; if either of these variables is
2260 non-@code{nil}, the input method should put its argument into a list and
2261 return that list with no further processing.
2262
2263 @node Quoted Character Input
2264 @subsection Quoted Character Input
2265 @cindex quoted character input
2266
2267 You can use the function @code{read-quoted-char} to ask the user to
2268 specify a character, and allow the user to specify a control or meta
2269 character conveniently, either literally or as an octal character code.
2270 The command @code{quoted-insert} uses this function.
2271
2272 @defun read-quoted-char &optional prompt
2273 @cindex octal character input
2274 @cindex control characters, reading
2275 @cindex nonprinting characters, reading
2276 This function is like @code{read-char}, except that if the first
2277 character read is an octal digit (0-7), it reads any number of octal
2278 digits (but stopping if a non-octal digit is found), and returns the
2279 character represented by that numeric character code. If the
2280 character that terminates the sequence of octal digits is @key{RET},
2281 it is discarded. Any other terminating character is used as input
2282 after this function returns.
2283
2284 Quitting is suppressed when the first character is read, so that the
2285 user can enter a @kbd{C-g}. @xref{Quitting}.
2286
2287 If @var{prompt} is supplied, it specifies a string for prompting the
2288 user. The prompt string is always displayed in the echo area, followed
2289 by a single @samp{-}.
2290
2291 In the following example, the user types in the octal number 177 (which
2292 is 127 in decimal).
2293
2294 @example
2295 (read-quoted-char "What character")
2296
2297 @group
2298 ---------- Echo Area ----------
2299 What character @kbd{1 7 7}-
2300 ---------- Echo Area ----------
2301
2302 @result{} 127
2303 @end group
2304 @end example
2305 @end defun
2306
2307 @need 2000
2308 @node Event Input Misc
2309 @subsection Miscellaneous Event Input Features
2310
2311 This section describes how to ``peek ahead'' at events without using
2312 them up, how to check for pending input, and how to discard pending
2313 input. See also the function @code{read-passwd} (@pxref{Reading a
2314 Password}).
2315
2316 @defvar unread-command-events
2317 @cindex next input
2318 @cindex peeking at input
2319 This variable holds a list of events waiting to be read as command
2320 input. The events are used in the order they appear in the list, and
2321 removed one by one as they are used.
2322
2323 The variable is needed because in some cases a function reads an event
2324 and then decides not to use it. Storing the event in this variable
2325 causes it to be processed normally, by the command loop or by the
2326 functions to read command input.
2327
2328 @cindex prefix argument unreading
2329 For example, the function that implements numeric prefix arguments reads
2330 any number of digits. When it finds a non-digit event, it must unread
2331 the event so that it can be read normally by the command loop.
2332 Likewise, incremental search uses this feature to unread events with no
2333 special meaning in a search, because these events should exit the search
2334 and then execute normally.
2335
2336 The reliable and easy way to extract events from a key sequence so as to
2337 put them in @code{unread-command-events} is to use
2338 @code{listify-key-sequence} (@pxref{Strings of Events}).
2339
2340 Normally you add events to the front of this list, so that the events
2341 most recently unread will be reread first.
2342 @end defvar
2343
2344 @defun listify-key-sequence key
2345 This function converts the string or vector @var{key} to a list of
2346 individual events, which you can put in @code{unread-command-events}.
2347 @end defun
2348
2349 @defvar unread-command-char
2350 This variable holds a character to be read as command input.
2351 A value of -1 means ``empty''.
2352
2353 This variable is mostly obsolete now that you can use
2354 @code{unread-command-events} instead; it exists only to support programs
2355 written for Emacs versions 18 and earlier.
2356 @end defvar
2357
2358 @defun input-pending-p
2359 @cindex waiting for command key input
2360 This function determines whether any command input is currently
2361 available to be read. It returns immediately, with value @code{t} if
2362 there is available input, @code{nil} otherwise. On rare occasions it
2363 may return @code{t} when no input is available.
2364 @end defun
2365
2366 @defvar last-input-event
2367 @defvarx last-input-char
2368 This variable records the last terminal input event read, whether
2369 as part of a command or explicitly by a Lisp program.
2370
2371 In the example below, the Lisp program reads the character @kbd{1},
2372 @acronym{ASCII} code 49. It becomes the value of @code{last-input-event},
2373 while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
2374 this expression) remains the value of @code{last-command-event}.
2375
2376 @example
2377 @group
2378 (progn (print (read-char))
2379 (print last-command-event)
2380 last-input-event)
2381 @print{} 49
2382 @print{} 5
2383 @result{} 49
2384 @end group
2385 @end example
2386
2387 The alias @code{last-input-char} exists for compatibility with
2388 Emacs version 18.
2389 @end defvar
2390
2391 @defun discard-input
2392 @cindex flush input
2393 @cindex discard input
2394 @cindex terminate keyboard macro
2395 This function discards the contents of the terminal input buffer and
2396 cancels any keyboard macro that might be in the process of definition.
2397 It returns @code{nil}.
2398
2399 In the following example, the user may type a number of characters right
2400 after starting the evaluation of the form. After the @code{sleep-for}
2401 finishes sleeping, @code{discard-input} discards any characters typed
2402 during the sleep.
2403
2404 @example
2405 (progn (sleep-for 2)
2406 (discard-input))
2407 @result{} nil
2408 @end example
2409 @end defun
2410
2411 @node Special Events
2412 @section Special Events
2413
2414 @cindex special events
2415 Special events are handled at a very low level---as soon as they are
2416 read. The @code{read-event} function processes these events itself, and
2417 never returns them. Instead, it keeps waiting for the first event
2418 that is not special and returns that one.
2419
2420 Events that are handled in this way do not echo, they are never grouped
2421 into key sequences, and they never appear in the value of
2422 @code{last-command-event} or @code{(this-command-keys)}. They do not
2423 discard a numeric argument, they cannot be unread with
2424 @code{unread-command-events}, they may not appear in a keyboard macro,
2425 and they are not recorded in a keyboard macro while you are defining
2426 one.
2427
2428 These events do, however, appear in @code{last-input-event} immediately
2429 after they are read, and this is the way for the event's definition to
2430 find the actual event.
2431
2432 The events types @code{iconify-frame}, @code{make-frame-visible} and
2433 @code{delete-frame} are normally handled in this way. The keymap which
2434 defines how to handle special events---and which events are special---is
2435 in the variable @code{special-event-map} (@pxref{Active Keymaps}).
2436
2437 @node Waiting
2438 @section Waiting for Elapsed Time or Input
2439 @cindex pausing
2440 @cindex waiting
2441
2442 The wait functions are designed to wait for a certain amount of time
2443 to pass or until there is input. For example, you may wish to pause in
2444 the middle of a computation to allow the user time to view the display.
2445 @code{sit-for} pauses and updates the screen, and returns immediately if
2446 input comes in, while @code{sleep-for} pauses without updating the
2447 screen.
2448
2449 @defun sit-for seconds &optional nodisp
2450 This function performs redisplay (provided there is no pending input
2451 from the user), then waits @var{seconds} seconds, or until input is
2452 available. The value is @code{t} if @code{sit-for} waited the full
2453 time with no input arriving (see @code{input-pending-p} in @ref{Event
2454 Input Misc}). Otherwise, the value is @code{nil}.
2455
2456 The argument @var{seconds} need not be an integer. If it is a floating
2457 point number, @code{sit-for} waits for a fractional number of seconds.
2458 Some systems support only a whole number of seconds; on these systems,
2459 @var{seconds} is rounded down.
2460
2461 The expression @code{(sit-for 0)} is a convenient way to request a
2462 redisplay, without any delay. @xref{Forcing Redisplay}.
2463
2464 If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
2465 redisplay, but it still returns as soon as input is available (or when
2466 the timeout elapses).
2467
2468 Iconifying or deiconifying a frame makes @code{sit-for} return, because
2469 that generates an event. @xref{Misc Events}.
2470
2471 The usual purpose of @code{sit-for} is to give the user time to read
2472 text that you display.
2473
2474 It is also possible to call @code{sit-for} with three arguments,
2475 as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})},
2476 but that is considered obsolete.
2477 @end defun
2478
2479 @defun sleep-for seconds &optional millisec
2480 This function simply pauses for @var{seconds} seconds without updating
2481 the display. It pays no attention to available input. It returns
2482 @code{nil}.
2483
2484 The argument @var{seconds} need not be an integer. If it is a floating
2485 point number, @code{sleep-for} waits for a fractional number of seconds.
2486 Some systems support only a whole number of seconds; on these systems,
2487 @var{seconds} is rounded down.
2488
2489 The optional argument @var{millisec} specifies an additional waiting
2490 period measured in milliseconds. This adds to the period specified by
2491 @var{seconds}. If the system doesn't support waiting fractions of a
2492 second, you get an error if you specify nonzero @var{millisec}.
2493
2494 Use @code{sleep-for} when you wish to guarantee a delay.
2495 @end defun
2496
2497 @xref{Time of Day}, for functions to get the current time.
2498
2499 @node Quitting
2500 @section Quitting
2501 @cindex @kbd{C-g}
2502 @cindex quitting
2503 @cindex interrupt Lisp functions
2504
2505 Typing @kbd{C-g} while a Lisp function is running causes Emacs to
2506 @dfn{quit} whatever it is doing. This means that control returns to the
2507 innermost active command loop.
2508
2509 Typing @kbd{C-g} while the command loop is waiting for keyboard input
2510 does not cause a quit; it acts as an ordinary input character. In the
2511 simplest case, you cannot tell the difference, because @kbd{C-g}
2512 normally runs the command @code{keyboard-quit}, whose effect is to quit.
2513 However, when @kbd{C-g} follows a prefix key, they combine to form an
2514 undefined key. The effect is to cancel the prefix key as well as any
2515 prefix argument.
2516
2517 In the minibuffer, @kbd{C-g} has a different definition: it aborts out
2518 of the minibuffer. This means, in effect, that it exits the minibuffer
2519 and then quits. (Simply quitting would return to the command loop
2520 @emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit
2521 directly when the command reader is reading input is so that its meaning
2522 can be redefined in the minibuffer in this way. @kbd{C-g} following a
2523 prefix key is not redefined in the minibuffer, and it has its normal
2524 effect of canceling the prefix key and prefix argument. This too
2525 would not be possible if @kbd{C-g} always quit directly.
2526
2527 When @kbd{C-g} does directly quit, it does so by setting the variable
2528 @code{quit-flag} to @code{t}. Emacs checks this variable at appropriate
2529 times and quits if it is not @code{nil}. Setting @code{quit-flag}
2530 non-@code{nil} in any way thus causes a quit.
2531
2532 At the level of C code, quitting cannot happen just anywhere; only at the
2533 special places that check @code{quit-flag}. The reason for this is
2534 that quitting at other places might leave an inconsistency in Emacs's
2535 internal state. Because quitting is delayed until a safe place, quitting
2536 cannot make Emacs crash.
2537
2538 Certain functions such as @code{read-key-sequence} or
2539 @code{read-quoted-char} prevent quitting entirely even though they wait
2540 for input. Instead of quitting, @kbd{C-g} serves as the requested
2541 input. In the case of @code{read-key-sequence}, this serves to bring
2542 about the special behavior of @kbd{C-g} in the command loop. In the
2543 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
2544 to quote a @kbd{C-g}.
2545
2546 @cindex prevent quitting
2547 You can prevent quitting for a portion of a Lisp function by binding
2548 the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
2549 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
2550 usual result of this---a quit---is prevented. Eventually,
2551 @code{inhibit-quit} will become @code{nil} again, such as when its
2552 binding is unwound at the end of a @code{let} form. At that time, if
2553 @code{quit-flag} is still non-@code{nil}, the requested quit happens
2554 immediately. This behavior is ideal when you wish to make sure that
2555 quitting does not happen within a ``critical section'' of the program.
2556
2557 @cindex @code{read-quoted-char} quitting
2558 In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
2559 handled in a special way that does not involve quitting. This is done
2560 by reading the input with @code{inhibit-quit} bound to @code{t}, and
2561 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
2562 becomes @code{nil} again. This excerpt from the definition of
2563 @code{read-quoted-char} shows how this is done; it also shows that
2564 normal quitting is permitted after the first character of input.
2565
2566 @example
2567 (defun read-quoted-char (&optional prompt)
2568 "@dots{}@var{documentation}@dots{}"
2569 (let ((message-log-max nil) done (first t) (code 0) char)
2570 (while (not done)
2571 (let ((inhibit-quit first)
2572 @dots{})
2573 (and prompt (message "%s-" prompt))
2574 (setq char (read-event))
2575 (if inhibit-quit (setq quit-flag nil)))
2576 @r{@dots{}set the variable @code{code}@dots{}})
2577 code))
2578 @end example
2579
2580 @defvar quit-flag
2581 If this variable is non-@code{nil}, then Emacs quits immediately, unless
2582 @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
2583 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
2584 @end defvar
2585
2586 @defvar inhibit-quit
2587 This variable determines whether Emacs should quit when @code{quit-flag}
2588 is set to a value other than @code{nil}. If @code{inhibit-quit} is
2589 non-@code{nil}, then @code{quit-flag} has no special effect.
2590 @end defvar
2591
2592 @defmac with-local-quit forms@dots{}
2593 This macro executes @var{forms} in sequence, but allows quitting, at
2594 least locally, within @var{body} even if @code{inhibit-quit} was
2595 non-@code{nil} outside this construct. It returns the value of the
2596 last form in @var{forms}.
2597
2598 If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit},
2599 it only executes the @var{forms}, and setting @code{quit-flag} causes
2600 a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so
2601 that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag}
2602 triggers a special kind of local quit. This ends the execution of
2603 @var{forms} and exits the @code{with-local-quit} form with
2604 @code{quit-flag} still non-@code{nil}, so that another (ordinary) quit
2605 will happen as soon as that is allowed. If @code{quit-flag} is
2606 already non-@code{nil} at the beginning of @var{forms}, the local quit
2607 happens immediately and they don't execute at all.
2608
2609 This macro is mainly useful in functions that can be called from
2610 timers, @code{pre-command-hook}, @code{post-command-hook} and other
2611 places where @code{inhibit-quit} is normally bound to @code{t}.
2612 @end defmac
2613
2614 @deffn Command keyboard-quit
2615 This function signals the @code{quit} condition with @code{(signal 'quit
2616 nil)}. This is the same thing that quitting does. (See @code{signal}
2617 in @ref{Errors}.)
2618 @end deffn
2619
2620 You can specify a character other than @kbd{C-g} to use for quitting.
2621 See the function @code{set-input-mode} in @ref{Terminal Input}.
2622
2623 @node Prefix Command Arguments
2624 @section Prefix Command Arguments
2625 @cindex prefix argument
2626 @cindex raw prefix argument
2627 @cindex numeric prefix argument
2628
2629 Most Emacs commands can use a @dfn{prefix argument}, a number
2630 specified before the command itself. (Don't confuse prefix arguments
2631 with prefix keys.) The prefix argument is at all times represented by a
2632 value, which may be @code{nil}, meaning there is currently no prefix
2633 argument. Each command may use the prefix argument or ignore it.
2634
2635 There are two representations of the prefix argument: @dfn{raw} and
2636 @dfn{numeric}. The editor command loop uses the raw representation
2637 internally, and so do the Lisp variables that store the information, but
2638 commands can request either representation.
2639
2640 Here are the possible values of a raw prefix argument:
2641
2642 @itemize @bullet
2643 @item
2644 @code{nil}, meaning there is no prefix argument. Its numeric value is
2645 1, but numerous commands make a distinction between @code{nil} and the
2646 integer 1.
2647
2648 @item
2649 An integer, which stands for itself.
2650
2651 @item
2652 A list of one element, which is an integer. This form of prefix
2653 argument results from one or a succession of @kbd{C-u}'s with no
2654 digits. The numeric value is the integer in the list, but some
2655 commands make a distinction between such a list and an integer alone.
2656
2657 @item
2658 The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was
2659 typed, without following digits. The equivalent numeric value is
2660 @minus{}1, but some commands make a distinction between the integer
2661 @minus{}1 and the symbol @code{-}.
2662 @end itemize
2663
2664 We illustrate these possibilities by calling the following function with
2665 various prefixes:
2666
2667 @example
2668 @group
2669 (defun display-prefix (arg)
2670 "Display the value of the raw prefix arg."
2671 (interactive "P")
2672 (message "%s" arg))
2673 @end group
2674 @end example
2675
2676 @noindent
2677 Here are the results of calling @code{display-prefix} with various
2678 raw prefix arguments:
2679
2680 @example
2681 M-x display-prefix @print{} nil
2682
2683 C-u M-x display-prefix @print{} (4)
2684
2685 C-u C-u M-x display-prefix @print{} (16)
2686
2687 C-u 3 M-x display-prefix @print{} 3
2688
2689 M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
2690
2691 C-u - M-x display-prefix @print{} -
2692
2693 M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
2694
2695 C-u - 7 M-x display-prefix @print{} -7
2696
2697 M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
2698 @end example
2699
2700 Emacs uses two variables to store the prefix argument:
2701 @code{prefix-arg} and @code{current-prefix-arg}. Commands such as
2702 @code{universal-argument} that set up prefix arguments for other
2703 commands store them in @code{prefix-arg}. In contrast,
2704 @code{current-prefix-arg} conveys the prefix argument to the current
2705 command, so setting it has no effect on the prefix arguments for future
2706 commands.
2707
2708 Normally, commands specify which representation to use for the prefix
2709 argument, either numeric or raw, in the @code{interactive} declaration.
2710 (@xref{Using Interactive}.) Alternatively, functions may look at the
2711 value of the prefix argument directly in the variable
2712 @code{current-prefix-arg}, but this is less clean.
2713
2714 @defun prefix-numeric-value arg
2715 This function returns the numeric meaning of a valid raw prefix argument
2716 value, @var{arg}. The argument may be a symbol, a number, or a list.
2717 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
2718 value @minus{}1 is returned; if it is a number, that number is returned;
2719 if it is a list, the @sc{car} of that list (which should be a number) is
2720 returned.
2721 @end defun
2722
2723 @defvar current-prefix-arg
2724 This variable holds the raw prefix argument for the @emph{current}
2725 command. Commands may examine it directly, but the usual method for
2726 accessing it is with @code{(interactive "P")}.
2727 @end defvar
2728
2729 @defvar prefix-arg
2730 The value of this variable is the raw prefix argument for the
2731 @emph{next} editing command. Commands such as @code{universal-argument}
2732 that specify prefix arguments for the following command work by setting
2733 this variable.
2734 @end defvar
2735
2736 @defvar last-prefix-arg
2737 The raw prefix argument value used by the previous command.
2738 @end defvar
2739
2740 The following commands exist to set up prefix arguments for the
2741 following command. Do not call them for any other reason.
2742
2743 @deffn Command universal-argument
2744 This command reads input and specifies a prefix argument for the
2745 following command. Don't call this command yourself unless you know
2746 what you are doing.
2747 @end deffn
2748
2749 @deffn Command digit-argument arg
2750 This command adds to the prefix argument for the following command. The
2751 argument @var{arg} is the raw prefix argument as it was before this
2752 command; it is used to compute the updated prefix argument. Don't call
2753 this command yourself unless you know what you are doing.
2754 @end deffn
2755
2756 @deffn Command negative-argument arg
2757 This command adds to the numeric argument for the next command. The
2758 argument @var{arg} is the raw prefix argument as it was before this
2759 command; its value is negated to form the new prefix argument. Don't
2760 call this command yourself unless you know what you are doing.
2761 @end deffn
2762
2763 @node Recursive Editing
2764 @section Recursive Editing
2765 @cindex recursive command loop
2766 @cindex recursive editing level
2767 @cindex command loop, recursive
2768
2769 The Emacs command loop is entered automatically when Emacs starts up.
2770 This top-level invocation of the command loop never exits; it keeps
2771 running as long as Emacs does. Lisp programs can also invoke the
2772 command loop. Since this makes more than one activation of the command
2773 loop, we call it @dfn{recursive editing}. A recursive editing level has
2774 the effect of suspending whatever command invoked it and permitting the
2775 user to do arbitrary editing before resuming that command.
2776
2777 The commands available during recursive editing are the same ones
2778 available in the top-level editing loop and defined in the keymaps.
2779 Only a few special commands exit the recursive editing level; the others
2780 return to the recursive editing level when they finish. (The special
2781 commands for exiting are always available, but they do nothing when
2782 recursive editing is not in progress.)
2783
2784 All command loops, including recursive ones, set up all-purpose error
2785 handlers so that an error in a command run from the command loop will
2786 not exit the loop.
2787
2788 @cindex minibuffer input
2789 Minibuffer input is a special kind of recursive editing. It has a few
2790 special wrinkles, such as enabling display of the minibuffer and the
2791 minibuffer window, but fewer than you might suppose. Certain keys
2792 behave differently in the minibuffer, but that is only because of the
2793 minibuffer's local map; if you switch windows, you get the usual Emacs
2794 commands.
2795
2796 @cindex @code{throw} example
2797 @kindex exit
2798 @cindex exit recursive editing
2799 @cindex aborting
2800 To invoke a recursive editing level, call the function
2801 @code{recursive-edit}. This function contains the command loop; it also
2802 contains a call to @code{catch} with tag @code{exit}, which makes it
2803 possible to exit the recursive editing level by throwing to @code{exit}
2804 (@pxref{Catch and Throw}). If you throw a value other than @code{t},
2805 then @code{recursive-edit} returns normally to the function that called
2806 it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
2807 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
2808 control returns to the command loop one level up. This is called
2809 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
2810
2811 Most applications should not use recursive editing, except as part of
2812 using the minibuffer. Usually it is more convenient for the user if you
2813 change the major mode of the current buffer temporarily to a special
2814 major mode, which should have a command to go back to the previous mode.
2815 (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
2816 give the user different text to edit ``recursively'', create and select
2817 a new buffer in a special mode. In this mode, define a command to
2818 complete the processing and go back to the previous buffer. (The
2819 @kbd{m} command in Rmail does this.)
2820
2821 Recursive edits are useful in debugging. You can insert a call to
2822 @code{debug} into a function definition as a sort of breakpoint, so that
2823 you can look around when the function gets there. @code{debug} invokes
2824 a recursive edit but also provides the other features of the debugger.
2825
2826 Recursive editing levels are also used when you type @kbd{C-r} in
2827 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
2828
2829 @defun recursive-edit
2830 @cindex suspend evaluation
2831 This function invokes the editor command loop. It is called
2832 automatically by the initialization of Emacs, to let the user begin
2833 editing. When called from a Lisp program, it enters a recursive editing
2834 level.
2835
2836 In the following example, the function @code{simple-rec} first
2837 advances point one word, then enters a recursive edit, printing out a
2838 message in the echo area. The user can then do any editing desired, and
2839 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
2840
2841 @example
2842 (defun simple-rec ()
2843 (forward-word 1)
2844 (message "Recursive edit in progress")
2845 (recursive-edit)
2846 (forward-word 1))
2847 @result{} simple-rec
2848 (simple-rec)
2849 @result{} nil
2850 @end example
2851 @end defun
2852
2853 @deffn Command exit-recursive-edit
2854 This function exits from the innermost recursive edit (including
2855 minibuffer input). Its definition is effectively @code{(throw 'exit
2856 nil)}.
2857 @end deffn
2858
2859 @deffn Command abort-recursive-edit
2860 This function aborts the command that requested the innermost recursive
2861 edit (including minibuffer input), by signaling @code{quit}
2862 after exiting the recursive edit. Its definition is effectively
2863 @code{(throw 'exit t)}. @xref{Quitting}.
2864 @end deffn
2865
2866 @deffn Command top-level
2867 This function exits all recursive editing levels; it does not return a
2868 value, as it jumps completely out of any computation directly back to
2869 the main command loop.
2870 @end deffn
2871
2872 @defun recursion-depth
2873 This function returns the current depth of recursive edits. When no
2874 recursive edit is active, it returns 0.
2875 @end defun
2876
2877 @node Disabling Commands
2878 @section Disabling Commands
2879 @cindex disabled command
2880
2881 @dfn{Disabling a command} marks the command as requiring user
2882 confirmation before it can be executed. Disabling is used for commands
2883 which might be confusing to beginning users, to prevent them from using
2884 the commands by accident.
2885
2886 @kindex disabled
2887 The low-level mechanism for disabling a command is to put a
2888 non-@code{nil} @code{disabled} property on the Lisp symbol for the
2889 command. These properties are normally set up by the user's
2890 init file (@pxref{Init File}) with Lisp expressions such as this:
2891
2892 @example
2893 (put 'upcase-region 'disabled t)
2894 @end example
2895
2896 @noindent
2897 For a few commands, these properties are present by default (you can
2898 remove them in your init file if you wish).
2899
2900 If the value of the @code{disabled} property is a string, the message
2901 saying the command is disabled includes that string. For example:
2902
2903 @example
2904 (put 'delete-region 'disabled
2905 "Text deleted this way cannot be yanked back!\n")
2906 @end example
2907
2908 @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on
2909 what happens when a disabled command is invoked interactively.
2910 Disabling a command has no effect on calling it as a function from Lisp
2911 programs.
2912
2913 @deffn Command enable-command command
2914 Allow @var{command} (a symbol) to be executed without special
2915 confirmation from now on, and alter the user's init file (@pxref{Init
2916 File}) so that this will apply to future sessions.
2917 @end deffn
2918
2919 @deffn Command disable-command command
2920 Require special confirmation to execute @var{command} from now on, and
2921 alter the user's init file so that this will apply to future sessions.
2922 @end deffn
2923
2924 @defvar disabled-command-function
2925 The value of this variable should be a function. When the user
2926 invokes a disabled command interactively, this function is called
2927 instead of the disabled command. It can use @code{this-command-keys}
2928 to determine what the user typed to run the command, and thus find the
2929 command itself.
2930
2931 The value may also be @code{nil}. Then all commands work normally,
2932 even disabled ones.
2933
2934 By default, the value is a function that asks the user whether to
2935 proceed.
2936 @end defvar
2937
2938 @node Command History
2939 @section Command History
2940 @cindex command history
2941 @cindex complex command
2942 @cindex history of commands
2943
2944 The command loop keeps a history of the complex commands that have
2945 been executed, to make it convenient to repeat these commands. A
2946 @dfn{complex command} is one for which the interactive argument reading
2947 uses the minibuffer. This includes any @kbd{M-x} command, any
2948 @kbd{M-:} command, and any command whose @code{interactive}
2949 specification reads an argument from the minibuffer. Explicit use of
2950 the minibuffer during the execution of the command itself does not cause
2951 the command to be considered complex.
2952
2953 @defvar command-history
2954 This variable's value is a list of recent complex commands, each
2955 represented as a form to evaluate. It continues to accumulate all
2956 complex commands for the duration of the editing session, but when it
2957 reaches the maximum size (@pxref{Minibuffer History}), the oldest
2958 elements are deleted as new ones are added.
2959
2960 @example
2961 @group
2962 command-history
2963 @result{} ((switch-to-buffer "chistory.texi")
2964 (describe-key "^X^[")
2965 (visit-tags-table "~/emacs/src/")
2966 (find-tag "repeat-complex-command"))
2967 @end group
2968 @end example
2969 @end defvar
2970
2971 This history list is actually a special case of minibuffer history
2972 (@pxref{Minibuffer History}), with one special twist: the elements are
2973 expressions rather than strings.
2974
2975 There are a number of commands devoted to the editing and recall of
2976 previous commands. The commands @code{repeat-complex-command}, and
2977 @code{list-command-history} are described in the user manual
2978 (@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the
2979 minibuffer, the usual minibuffer history commands are available.
2980
2981 @node Keyboard Macros
2982 @section Keyboard Macros
2983 @cindex keyboard macros
2984
2985 A @dfn{keyboard macro} is a canned sequence of input events that can
2986 be considered a command and made the definition of a key. The Lisp
2987 representation of a keyboard macro is a string or vector containing the
2988 events. Don't confuse keyboard macros with Lisp macros
2989 (@pxref{Macros}).
2990
2991 @defun execute-kbd-macro kbdmacro &optional count loopfunc
2992 This function executes @var{kbdmacro} as a sequence of events. If
2993 @var{kbdmacro} is a string or vector, then the events in it are executed
2994 exactly as if they had been input by the user. The sequence is
2995 @emph{not} expected to be a single key sequence; normally a keyboard
2996 macro definition consists of several key sequences concatenated.
2997
2998 If @var{kbdmacro} is a symbol, then its function definition is used in
2999 place of @var{kbdmacro}. If that is another symbol, this process repeats.
3000 Eventually the result should be a string or vector. If the result is
3001 not a symbol, string, or vector, an error is signaled.
3002
3003 The argument @var{count} is a repeat count; @var{kbdmacro} is executed that
3004 many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is
3005 executed once. If it is 0, @var{kbdmacro} is executed over and over until it
3006 encounters an error or a failing search.
3007
3008 If @var{loopfunc} is non-@code{nil}, it is a function that is called,
3009 without arguments, prior to each iteration of the macro. If
3010 @var{loopfunc} returns @code{nil}, then this stops execution of the macro.
3011
3012 @xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
3013 @end defun
3014
3015 @defvar executing-kbd-macro
3016 This variable contains the string or vector that defines the keyboard
3017 macro that is currently executing. It is @code{nil} if no macro is
3018 currently executing. A command can test this variable so as to behave
3019 differently when run from an executing macro. Do not set this variable
3020 yourself.
3021 @end defvar
3022
3023 @defvar defining-kbd-macro
3024 This variable is non-@code{nil} if and only if a keyboard macro is
3025 being defined. A command can test this variable so as to behave
3026 differently while a macro is being defined. The commands
3027 @code{start-kbd-macro} and @code{end-kbd-macro} set this variable---do
3028 not set it yourself.
3029
3030 The variable is always local to the current terminal and cannot be
3031 buffer-local. @xref{Multiple Displays}.
3032 @end defvar
3033
3034 @defvar last-kbd-macro
3035 This variable is the definition of the most recently defined keyboard
3036 macro. Its value is a string or vector, or @code{nil}.
3037
3038 The variable is always local to the current terminal and cannot be
3039 buffer-local. @xref{Multiple Displays}.
3040 @end defvar
3041
3042 @defvar kbd-macro-termination-hook
3043 This normal hook (@pxref{Standard Hooks}) is run when a keyboard
3044 macro terminates, regardless of what caused it to terminate (reaching
3045 the macro end or an error which ended the macro prematurely).
3046 @end defvar
3047
3048 @ignore
3049 arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1
3050 @end ignore