2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
7 @cindex editor command loop
10 When you run Emacs, it enters the @dfn{editor command loop} almost
11 immediately. This loop reads key sequences, executes their definitions,
12 and displays the results. In this chapter, we describe how these things
13 are done, and the subroutines that allow Lisp programs to do them.
16 * Command Overview:: How the command loop reads commands.
17 * Defining Commands:: Specifying how a function should read arguments.
18 * Interactive Call:: Calling a command, so that it will read arguments.
19 * Distinguish Interactive:: Making a command distinguish interactive calls.
20 * Command Loop Info:: Variables set by the command loop for you to examine.
21 * Adjusting Point:: Adjustment of point after a command.
22 * Input Events:: What input looks like when you read it.
23 * Reading Input:: How to read input events from the keyboard or mouse.
24 * Special Events:: Events processed immediately and individually.
25 * Waiting:: Waiting for user input or elapsed time.
26 * Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
27 * Prefix Command Arguments:: How the commands to set prefix args work.
28 * Recursive Editing:: Entering a recursive edit,
29 and why you usually shouldn't.
30 * Disabling Commands:: How the command loop handles disabled commands.
31 * Command History:: How the command history is set up, and how accessed.
32 * Keyboard Macros:: How keyboard macros are implemented.
35 @node Command Overview
36 @section Command Loop Overview
38 The first thing the command loop must do is read a key sequence,
39 which is a sequence of input events that translates into a command.
40 It does this by calling the function @code{read-key-sequence}. Lisp
41 programs can also call this function (@pxref{Key Sequence Input}).
42 They can also read input at a lower level with @code{read-key} or
43 @code{read-event} (@pxref{Reading One Event}), or discard pending
44 input with @code{discard-input} (@pxref{Event Input Misc}).
46 The key sequence is translated into a command through the currently
47 active keymaps. @xref{Key Lookup}, for information on how this is done.
48 The result should be a keyboard macro or an interactively callable
49 function. If the key is @kbd{M-x}, then it reads the name of another
50 command, which it then calls. This is done by the command
51 @code{execute-extended-command} (@pxref{Interactive Call}).
53 Prior to executing the command, Emacs runs @code{undo-boundary} to
54 create an undo boundary. @xref{Maintaining Undo}.
56 To execute a command, Emacs first reads its arguments by calling
57 @code{command-execute} (@pxref{Interactive Call}). For commands
58 written in Lisp, the @code{interactive} specification says how to read
59 the arguments. This may use the prefix argument (@pxref{Prefix
60 Command Arguments}) or may read with prompting in the minibuffer
61 (@pxref{Minibuffers}). For example, the command @code{find-file} has
62 an @code{interactive} specification which says to read a file name
63 using the minibuffer. The function body of @code{find-file} does not
64 use the minibuffer, so if you call @code{find-file} as a function from
65 Lisp code, you must supply the file name string as an ordinary Lisp
68 If the command is a keyboard macro (i.e.@: a string or vector),
69 Emacs executes it using @code{execute-kbd-macro} (@pxref{Keyboard
72 @defvar pre-command-hook
73 This normal hook is run by the editor command loop before it executes
74 each command. At that time, @code{this-command} contains the command
75 that is about to run, and @code{last-command} describes the previous
76 command. @xref{Command Loop Info}.
79 @defvar post-command-hook
80 This normal hook is run by the editor command loop after it executes
81 each command (including commands terminated prematurely by quitting or
82 by errors). At that time, @code{this-command} refers to the command
83 that just ran, and @code{last-command} refers to the command before
86 This hook is also run when Emacs first enters the command loop (at
87 which point @code{this-command} and @code{last-command} are both
91 Quitting is suppressed while running @code{pre-command-hook} and
92 @code{post-command-hook}. If an error happens while executing one of
93 these hooks, it does not terminate execution of the hook; instead
94 the error is silenced and the function in which the error occurred
95 is removed from the hook.
97 A request coming into the Emacs server (@pxref{Emacs Server,,,
98 emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard
101 @node Defining Commands
102 @section Defining Commands
103 @cindex defining commands
104 @cindex commands, defining
105 @cindex functions, making them interactive
106 @cindex interactive function
108 The special form @code{interactive} turns a Lisp function into a
109 command. The @code{interactive} form must be located at top-level in
110 the function body (usually as the first form in the body), or in the
111 @code{interactive-form} property of the function symbol. When the
112 @code{interactive} form is located in the function body, it does
113 nothing when actually executed. Its presence serves as a flag, which
114 tells the Emacs command loop that the function can be called
115 interactively. The argument of the @code{interactive} form controls
116 the reading of arguments for an interactive call.
119 * Using Interactive:: General rules for @code{interactive}.
120 * Interactive Codes:: The standard letter-codes for reading arguments
122 * Interactive Examples:: Examples of how to read interactive arguments.
125 @node Using Interactive
126 @subsection Using @code{interactive}
127 @cindex arguments, interactive entry
129 This section describes how to write the @code{interactive} form that
130 makes a Lisp function an interactively-callable command, and how to
131 examine a command's @code{interactive} form.
133 @defspec interactive arg-descriptor
134 This special form declares that a function is a command, and that it
135 may therefore be called interactively (via @kbd{M-x} or by entering a
136 key sequence bound to it). The argument @var{arg-descriptor} declares
137 how to compute the arguments to the command when the command is called
140 A command may be called from Lisp programs like any other function, but
141 then the caller supplies the arguments and @var{arg-descriptor} has no
144 @cindex @code{interactive-form}, function property
145 The @code{interactive} form must be located at top-level in the
146 function body, or in the function symbol's @code{interactive-form}
147 property (@pxref{Symbol Plists}). It has its effect because the
148 command loop looks for it before calling the function
149 (@pxref{Interactive Call}). Once the function is called, all its body
150 forms are executed; at this time, if the @code{interactive} form
151 occurs within the body, the form simply returns @code{nil} without
152 even evaluating its argument.
154 By convention, you should put the @code{interactive} form in the
155 function body, as the first top-level form. If there is an
156 @code{interactive} form in both the @code{interactive-form} symbol
157 property and the function body, the former takes precedence. The
158 @code{interactive-form} symbol property can be used to add an
159 interactive form to an existing function, or change how its arguments
160 are processed interactively, without redefining the function.
163 There are three possibilities for the argument @var{arg-descriptor}:
167 It may be omitted or @code{nil}; then the command is called with no
168 arguments. This leads quickly to an error if the command requires one
172 It may be a string; its contents are a sequence of elements separated
173 by newlines, one for each argument@footnote{Some elements actually
174 supply two arguments.}. Each element consists of a code character
175 (@pxref{Interactive Codes}) optionally followed by a prompt (which
176 some code characters use and some ignore). Here is an example:
179 (interactive "P\nbFrobnicate buffer: ")
183 The code letter @samp{P} sets the command's first argument to the raw
184 command prefix (@pxref{Prefix Command Arguments}). @samp{bFrobnicate
185 buffer: } prompts the user with @samp{Frobnicate buffer: } to enter
186 the name of an existing buffer, which becomes the second and final
190 The prompt string can use @samp{%} to include previous argument values
191 (starting with the first argument) in the prompt. This is done using
192 @code{format} (@pxref{Formatting Strings}). For example, here is how
193 you could read the name of an existing buffer followed by a new name to
198 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
202 @cindex @samp{*} in @code{interactive}
203 @cindex read-only buffers in interactive
204 If @samp{*} appears at the beginning of the string, then an error is
205 signaled if the buffer is read-only.
207 @cindex @samp{@@} in @code{interactive}
209 If @samp{@@} appears at the beginning of the string, and if the key
210 sequence used to invoke the command includes any mouse events, then
211 the window associated with the first of those events is selected
212 before the command is run.
214 @cindex @samp{^} in @code{interactive}
215 @cindex shift-selection, and @code{interactive} spec
216 If @samp{^} appears at the beginning of the string, and if the command
217 was invoked through @dfn{shift-translation}, set the mark and activate
218 the region temporarily, or extend an already active region, before the
219 command is run. If the command was invoked without shift-translation,
220 and the region is temporarily active, deactivate the region before the
221 command is run. Shift-translation is controlled on the user level by
222 @code{shift-select-mode}; see @ref{Shift Selection,,, emacs, The GNU
225 You can use @samp{*}, @samp{@@}, and @code{^} together; the order does
226 not matter. Actual reading of arguments is controlled by the rest of
227 the prompt string (starting with the first character that is not
228 @samp{*}, @samp{@@}, or @samp{^}).
231 It may be a Lisp expression that is not a string; then it should be a
232 form that is evaluated to get a list of arguments to pass to the
233 command. Usually this form will call various functions to read input
234 from the user, most often through the minibuffer (@pxref{Minibuffers})
235 or directly from the keyboard (@pxref{Reading Input}).
237 Providing point or the mark as an argument value is also common, but
238 if you do this @emph{and} read input (whether using the minibuffer or
239 not), be sure to get the integer values of point or the mark after
240 reading. The current buffer may be receiving subprocess output; if
241 subprocess output arrives while the command is waiting for input, it
242 could relocate point and the mark.
244 Here's an example of what @emph{not} to do:
248 (list (region-beginning) (region-end)
249 (read-string "Foo: " nil 'my-history)))
253 Here's how to avoid the problem, by examining point and the mark after
254 reading the keyboard input:
258 (let ((string (read-string "Foo: " nil 'my-history)))
259 (list (region-beginning) (region-end) string)))
262 @strong{Warning:} the argument values should not include any data
263 types that can't be printed and then read. Some facilities save
264 @code{command-history} in a file to be read in the subsequent
265 sessions; if a command's arguments contain a data type that prints
266 using @samp{#<@dots{}>} syntax, those facilities won't work.
268 There are, however, a few exceptions: it is ok to use a limited set of
269 expressions such as @code{(point)}, @code{(mark)},
270 @code{(region-beginning)}, and @code{(region-end)}, because Emacs
271 recognizes them specially and puts the expression (rather than its
272 value) into the command history. To see whether the expression you
273 wrote is one of these exceptions, run the command, then examine
274 @code{(car command-history)}.
277 @cindex examining the @code{interactive} form
278 @defun interactive-form function
279 This function returns the @code{interactive} form of @var{function}.
280 If @var{function} is an interactively callable function
281 (@pxref{Interactive Call}), the value is the command's
282 @code{interactive} form @code{(interactive @var{spec})}, which
283 specifies how to compute its arguments. Otherwise, the value is
284 @code{nil}. If @var{function} is a symbol, its function definition is
288 @node Interactive Codes
289 @subsection Code Characters for @code{interactive}
290 @cindex interactive code description
291 @cindex description for interactive codes
292 @cindex codes, interactive, description of
293 @cindex characters for interactive codes
295 The code character descriptions below contain a number of key words,
296 defined here as follows:
300 @cindex interactive completion
301 Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name
302 completion because the argument is read using @code{completing-read}
303 (@pxref{Completion}). @kbd{?} displays a list of possible completions.
306 Require the name of an existing object. An invalid name is not
307 accepted; the commands to exit the minibuffer do not exit if the current
311 @cindex default argument string
312 A default value of some sort is used if the user enters no text in the
313 minibuffer. The default depends on the code character.
316 This code letter computes an argument without reading any input.
317 Therefore, it does not use a prompt string, and any prompt string you
320 Even though the code letter doesn't use a prompt string, you must follow
321 it with a newline if it is not the last code character in the string.
324 A prompt immediately follows the code character. The prompt ends either
325 with the end of the string or with a newline.
328 This code character is meaningful only at the beginning of the
329 interactive string, and it does not look for a prompt or a newline.
330 It is a single, isolated character.
333 @cindex reading interactive arguments
334 Here are the code character descriptions for use with @code{interactive}:
338 Signal an error if the current buffer is read-only. Special.
341 Select the window mentioned in the first mouse event in the key
342 sequence that invoked this command. Special.
345 If the command was invoked through shift-translation, set the mark and
346 activate the region temporarily, or extend an already active region,
347 before the command is run. If the command was invoked without
348 shift-translation, and the region is temporarily active, deactivate
349 the region before the command is run. Special.
352 A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
356 The name of an existing buffer. By default, uses the name of the
357 current buffer (@pxref{Buffers}). Existing, Completion, Default,
361 A buffer name. The buffer need not exist. By default, uses the name of
362 a recently used buffer other than the current buffer. Completion,
366 A character. The cursor does not move into the echo area. Prompt.
369 A command name (i.e., a symbol satisfying @code{commandp}). Existing,
373 @cindex position argument
374 The position of point, as an integer (@pxref{Point}). No I/O.
377 A directory name. The default is the current default directory of the
378 current buffer, @code{default-directory} (@pxref{File Name Expansion}).
379 Existing, Completion, Default, Prompt.
382 The first or next non-keyboard event in the key sequence that invoked
383 the command. More precisely, @samp{e} gets events that are lists, so
384 you can look at the data in the lists. @xref{Input Events}. No I/O.
386 You use @samp{e} for mouse events and for special system events
387 (@pxref{Misc Events}). The event list that the command receives
388 depends on the event. @xref{Input Events}, which describes the forms
389 of the list for each event in the corresponding subsections.
391 You can use @samp{e} more than once in a single command's interactive
392 specification. If the key sequence that invoked the command has
393 @var{n} events that are lists, the @var{n}th @samp{e} provides the
394 @var{n}th such event. Events that are not lists, such as function keys
395 and @acronym{ASCII} characters, do not count where @samp{e} is concerned.
398 A file name of an existing file (@pxref{File Names}). The default
399 directory is @code{default-directory}. Existing, Completion, Default,
403 A file name. The file need not exist. Completion, Default, Prompt.
406 A file name. The file need not exist. If the user enters just a
407 directory name, then the value is just that directory name, with no
408 file name within the directory added. Completion, Default, Prompt.
411 An irrelevant argument. This code always supplies @code{nil} as
412 the argument's value. No I/O.
415 A key sequence (@pxref{Key Sequences}). This keeps reading events
416 until a command (or undefined command) is found in the current key
417 maps. The key sequence argument is represented as a string or vector.
418 The cursor does not move into the echo area. Prompt.
420 If @samp{k} reads a key sequence that ends with a down-event, it also
421 reads and discards the following up-event. You can get access to that
422 up-event with the @samp{U} code character.
424 This kind of input is used by commands such as @code{describe-key} and
425 @code{global-set-key}.
428 A key sequence, whose definition you intend to change. This works like
429 @samp{k}, except that it suppresses, for the last input event in the key
430 sequence, the conversions that are normally used (when necessary) to
431 convert an undefined key into a defined one.
434 @cindex marker argument
435 The position of the mark, as an integer. No I/O.
438 Arbitrary text, read in the minibuffer using the current buffer's input
439 method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
440 Emacs Manual}). Prompt.
443 A number, read with the minibuffer. If the input is not a number, the
444 user has to try again. @samp{n} never uses the prefix argument.
448 The numeric prefix argument; but if there is no prefix argument, read
449 a number as with @kbd{n}. The value is always a number. @xref{Prefix
450 Command Arguments}. Prompt.
453 @cindex numeric prefix argument usage
454 The numeric prefix argument. (Note that this @samp{p} is lower case.)
458 @cindex raw prefix argument usage
459 The raw prefix argument. (Note that this @samp{P} is upper case.) No
463 @cindex region argument
464 Point and the mark, as two numeric arguments, smallest first. This is
465 the only code letter that specifies two successive arguments rather than
469 Arbitrary text, read in the minibuffer and returned as a string
470 (@pxref{Text from Minibuffer}). Terminate the input with either
471 @kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of
472 these characters in the input.) Prompt.
475 An interned symbol whose name is read in the minibuffer. Any whitespace
476 character terminates the input. (Use @kbd{C-q} to include whitespace in
477 the string.) Other characters that normally terminate a symbol (e.g.,
478 parentheses and brackets) do not do so here. Prompt.
481 A key sequence or @code{nil}. Can be used after a @samp{k} or
482 @samp{K} argument to get the up-event that was discarded (if any)
483 after @samp{k} or @samp{K} read a down-event. If no up-event has been
484 discarded, @samp{U} provides @code{nil} as the argument. No I/O.
487 A variable declared to be a user option (i.e., satisfying the
488 predicate @code{custom-variable-p}). This reads the variable using
489 @code{read-variable}. @xref{Definition of read-variable}. Existing,
493 A Lisp object, specified with its read syntax, terminated with a
494 @kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from
498 @cindex evaluated expression argument
499 A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates
500 the form so that its value becomes the argument for the command.
504 A coding system name (a symbol). If the user enters null input, the
505 argument value is @code{nil}. @xref{Coding Systems}. Completion,
509 A coding system name (a symbol)---but only if this command has a prefix
510 argument. With no prefix argument, @samp{Z} provides @code{nil} as the
511 argument value. Completion, Existing, Prompt.
514 @node Interactive Examples
515 @subsection Examples of Using @code{interactive}
516 @cindex examples of using @code{interactive}
517 @cindex @code{interactive}, examples of using
519 Here are some examples of @code{interactive}:
523 (defun foo1 () ; @r{@code{foo1} takes no arguments,}
524 (interactive) ; @r{just moves forward two words.}
530 (defun foo2 (n) ; @r{@code{foo2} takes one argument,}
531 (interactive "^p") ; @r{which is the numeric prefix.}
532 ; @r{under @code{shift-select-mode},}
533 ; @r{will activate or extend region.}
534 (forward-word (* 2 n)))
539 (defun foo3 (n) ; @r{@code{foo3} takes one argument,}
540 (interactive "nCount:") ; @r{which is read with the Minibuffer.}
541 (forward-word (* 2 n)))
546 (defun three-b (b1 b2 b3)
547 "Select three existing buffers.
548 Put them into three windows, selecting the last one."
550 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
551 (delete-other-windows)
552 (split-window (selected-window) 8)
553 (switch-to-buffer b1)
555 (split-window (selected-window) 8)
556 (switch-to-buffer b2)
558 (switch-to-buffer b3))
561 (three-b "*scratch*" "declarations.texi" "*mail*")
566 @node Interactive Call
567 @section Interactive Call
568 @cindex interactive call
570 After the command loop has translated a key sequence into a command,
571 it invokes that command using the function @code{command-execute}. If
572 the command is a function, @code{command-execute} calls
573 @code{call-interactively}, which reads the arguments and calls the
574 command. You can also call these functions yourself.
576 Note that the term ``command'', in this context, refers to an
577 interactively callable function (or function-like object), or a
578 keyboard macro. It does not refer to the key sequence used to invoke
579 a command (@pxref{Keymaps}).
581 @defun commandp object &optional for-call-interactively
582 This function returns @code{t} if @var{object} is a command.
583 Otherwise, it returns @code{nil}.
585 Commands include strings and vectors (which are treated as keyboard
586 macros), lambda expressions that contain a top-level
587 @code{interactive} form (@pxref{Using Interactive}), byte-code
588 function objects made from such lambda expressions, autoload objects
589 that are declared as interactive (non-@code{nil} fourth argument to
590 @code{autoload}), and some primitive functions. Also, a symbol is
591 considered a command if it has a non-@code{nil}
592 @code{interactive-form} property, or if its function definition
593 satisfies @code{commandp}.
595 If @var{for-call-interactively} is non-@code{nil}, then
596 @code{commandp} returns @code{t} only for objects that
597 @code{call-interactively} could call---thus, not for keyboard macros.
599 See @code{documentation} in @ref{Accessing Documentation}, for a
600 realistic example of using @code{commandp}.
603 @defun call-interactively command &optional record-flag keys
604 This function calls the interactively callable function @var{command},
605 providing arguments according to its interactive calling specifications.
606 It returns whatever @var{command} returns.
608 If, for instance, you have a function with the following signature:
611 (defun foo (begin end)
619 (call-interactively 'foo)
622 will call @code{foo} with the region (@code{point} and @code{mark}) as
625 An error is signaled if @var{command} is not a function or if it
626 cannot be called interactively (i.e., is not a command). Note that
627 keyboard macros (strings and vectors) are not accepted, even though
628 they are considered commands, because they are not functions. If
629 @var{command} is a symbol, then @code{call-interactively} uses its
632 @cindex record command history
633 If @var{record-flag} is non-@code{nil}, then this command and its
634 arguments are unconditionally added to the list @code{command-history}.
635 Otherwise, the command is added only if it uses the minibuffer to read
636 an argument. @xref{Command History}.
638 The argument @var{keys}, if given, should be a vector which specifies
639 the sequence of events to supply if the command inquires which events
640 were used to invoke it. If @var{keys} is omitted or @code{nil}, the
641 default is the return value of @code{this-command-keys-vector}.
642 @xref{Definition of this-command-keys-vector}.
645 @defun command-execute command &optional record-flag keys special
646 @cindex keyboard macro execution
647 This function executes @var{command}. The argument @var{command} must
648 satisfy the @code{commandp} predicate; i.e., it must be an interactively
649 callable function or a keyboard macro.
651 A string or vector as @var{command} is executed with
652 @code{execute-kbd-macro}. A function is passed to
653 @code{call-interactively} (see above), along with the
654 @var{record-flag} and @var{keys} arguments.
656 If @var{command} is a symbol, its function definition is used in its
657 place. A symbol with an @code{autoload} definition counts as a
658 command if it was declared to stand for an interactively callable
659 function. Such a definition is handled by loading the specified
660 library and then rechecking the definition of the symbol.
662 The argument @var{special}, if given, means to ignore the prefix
663 argument and not clear it. This is used for executing special events
664 (@pxref{Special Events}).
667 @deffn Command execute-extended-command prefix-argument
668 @cindex read command name
669 This function reads a command name from the minibuffer using
670 @code{completing-read} (@pxref{Completion}). Then it uses
671 @code{command-execute} to call the specified command. Whatever that
672 command returns becomes the value of @code{execute-extended-command}.
674 @cindex execute with prefix argument
675 If the command asks for a prefix argument, it receives the value
676 @var{prefix-argument}. If @code{execute-extended-command} is called
677 interactively, the current raw prefix argument is used for
678 @var{prefix-argument}, and thus passed on to whatever command is run.
680 @c !!! Should this be @kindex?
682 @code{execute-extended-command} is the normal definition of @kbd{M-x},
683 so it uses the string @w{@samp{M-x }} as a prompt. (It would be better
684 to take the prompt from the events used to invoke
685 @code{execute-extended-command}, but that is painful to implement.) A
686 description of the value of the prefix argument, if any, also becomes
691 (execute-extended-command 3)
692 ---------- Buffer: Minibuffer ----------
693 3 M-x forward-word RET
694 ---------- Buffer: Minibuffer ----------
700 @node Distinguish Interactive
701 @section Distinguish Interactive Calls
703 Sometimes a command should display additional visual feedback (such
704 as an informative message in the echo area) for interactive calls
705 only. There are three ways to do this. The recommended way to test
706 whether the function was called using @code{call-interactively} is to
707 give it an optional argument @code{print-message} and use the
708 @code{interactive} spec to make it non-@code{nil} in interactive
709 calls. Here's an example:
712 (defun foo (&optional print-message)
719 We use @code{"p"} because the numeric prefix argument is never
720 @code{nil}. Defined in this way, the function does display the
721 message when called from a keyboard macro.
723 The above method with the additional argument is usually best,
724 because it allows callers to say ``treat this call as interactive''.
725 But you can also do the job by testing @code{called-interactively-p}.
727 @defun called-interactively-p kind
728 This function returns @code{t} when the calling function was called
729 using @code{call-interactively}.
731 The argument @var{kind} should be either the symbol @code{interactive}
732 or the symbol @code{any}. If it is @code{interactive}, then
733 @code{called-interactively-p} returns @code{t} only if the call was
734 made directly by the user---e.g., if the user typed a key sequence
735 bound to the calling function, but @emph{not} if the user ran a
736 keyboard macro that called the function (@pxref{Keyboard Macros}). If
737 @var{kind} is @code{any}, @code{called-interactively-p} returns
738 @code{t} for any kind of interactive call, including keyboard macros.
740 If in doubt, use @code{any}; the only known proper use of
741 @code{interactive} is if you need to decide whether to display a
742 helpful message while a function is running.
744 A function is never considered to be called interactively if it was
745 called via Lisp evaluation (or with @code{apply} or @code{funcall}).
749 Here is an example of using @code{called-interactively-p}:
755 (when (called-interactively-p 'any)
756 (message "Interactive!")
757 'foo-called-interactively))
761 ;; @r{Type @kbd{M-x foo}.}
762 @print{} Interactive!
772 Here is another example that contrasts direct and indirect calls to
773 @code{called-interactively-p}.
779 (message "%s" (list (foo) (called-interactively-p 'any))))
783 ;; @r{Type @kbd{M-x bar}.}
788 @node Command Loop Info
789 @section Information from the Command Loop
791 The editor command loop sets several Lisp variables to keep status
792 records for itself and for commands that are run. With the exception of
793 @code{this-command} and @code{last-command} it's generally a bad idea to
794 change any of these variables in a Lisp program.
797 This variable records the name of the previous command executed by the
798 command loop (the one before the current command). Normally the value
799 is a symbol with a function definition, but this is not guaranteed.
801 The value is copied from @code{this-command} when a command returns to
802 the command loop, except when the command has specified a prefix
803 argument for the following command.
805 This variable is always local to the current terminal and cannot be
806 buffer-local. @xref{Multiple Terminals}.
809 @defvar real-last-command
810 This variable is set up by Emacs just like @code{last-command},
811 but never altered by Lisp programs.
814 @defvar last-repeatable-command
815 This variable stores the most recently executed command that was not
816 part of an input event. This is the command @code{repeat} will try to
817 repeat, @xref{Repeating,,, emacs, The GNU Emacs Manual}.
821 @cindex current command
822 This variable records the name of the command now being executed by
823 the editor command loop. Like @code{last-command}, it is normally a symbol
824 with a function definition.
826 The command loop sets this variable just before running a command, and
827 copies its value into @code{last-command} when the command finishes
828 (unless the command specified a prefix argument for the following
831 @cindex kill command repetition
832 Some commands set this variable during their execution, as a flag for
833 whatever command runs next. In particular, the functions for killing text
834 set @code{this-command} to @code{kill-region} so that any kill commands
835 immediately following will know to append the killed text to the
839 If you do not want a particular command to be recognized as the previous
840 command in the case where it got an error, you must code that command to
841 prevent this. One way is to set @code{this-command} to @code{t} at the
842 beginning of the command, and set @code{this-command} back to its proper
843 value at the end, like this:
846 (defun foo (args@dots{})
847 (interactive @dots{})
848 (let ((old-this-command this-command))
849 (setq this-command t)
850 @r{@dots{}do the work@dots{}}
851 (setq this-command old-this-command)))
855 We do not bind @code{this-command} with @code{let} because that would
856 restore the old value in case of error---a feature of @code{let} which
857 in this case does precisely what we want to avoid.
859 @defvar this-original-command
860 This has the same value as @code{this-command} except when command
861 remapping occurs (@pxref{Remapping Commands}). In that case,
862 @code{this-command} gives the command actually run (the result of
863 remapping), and @code{this-original-command} gives the command that
864 was specified to run but remapped into another command.
867 @defun this-command-keys
868 This function returns a string or vector containing the key sequence
869 that invoked the present command, plus any previous commands that
870 generated the prefix argument for this command. Any events read by the
871 command using @code{read-event} without a timeout get tacked on to the end.
873 However, if the command has called @code{read-key-sequence}, it
874 returns the last read key sequence. @xref{Key Sequence Input}. The
875 value is a string if all events in the sequence were characters that
876 fit in a string. @xref{Input Events}.
881 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
887 @defun this-command-keys-vector
888 @anchor{Definition of this-command-keys-vector}
889 Like @code{this-command-keys}, except that it always returns the events
890 in a vector, so you don't need to deal with the complexities of storing
891 input events in a string (@pxref{Strings of Events}).
894 @defun clear-this-command-keys &optional keep-record
895 This function empties out the table of events for
896 @code{this-command-keys} to return. Unless @var{keep-record} is
897 non-@code{nil}, it also empties the records that the function
898 @code{recent-keys} (@pxref{Recording Input}) will subsequently return.
899 This is useful after reading a password, to prevent the password from
900 echoing inadvertently as part of the next command in certain cases.
903 @defvar last-nonmenu-event
904 This variable holds the last input event read as part of a key sequence,
905 not counting events resulting from mouse menus.
907 One use of this variable is for telling @code{x-popup-menu} where to pop
908 up a menu. It is also used internally by @code{y-or-n-p}
909 (@pxref{Yes-or-No Queries}).
912 @defvar last-command-event
913 @defvarx last-command-char
914 This variable is set to the last input event that was read by the
915 command loop as part of a command. The principal use of this variable
916 is in @code{self-insert-command}, which uses it to decide which
922 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
928 The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
930 The alias @code{last-command-char} is obsolete.
934 @defvar last-event-frame
935 This variable records which frame the last input event was directed to.
936 Usually this is the frame that was selected when the event was
937 generated, but if that frame has redirected input focus to another
938 frame, the value is the frame to which the event was redirected.
941 If the last event came from a keyboard macro, the value is @code{macro}.
944 @node Adjusting Point
945 @section Adjusting Point After Commands
946 @cindex adjusting point
947 @cindex invisible/intangible text, and point
948 @cindex @code{display} property, and point display
949 @cindex @code{composition} property, and point display
951 It is not easy to display a value of point in the middle of a
952 sequence of text that has the @code{display}, @code{composition} or
953 is invisible. Therefore, after a command finishes and returns to the
954 command loop, if point is within such a sequence, the command loop
955 normally moves point to the edge of the sequence.
957 A command can inhibit this feature by setting the variable
958 @code{disable-point-adjustment}:
960 @defvar disable-point-adjustment
961 If this variable is non-@code{nil} when a command returns to the
962 command loop, then the command loop does not check for those text
963 properties, and does not move point out of sequences that have them.
965 The command loop sets this variable to @code{nil} before each command,
966 so if a command sets it, the effect applies only to that command.
969 @defvar global-disable-point-adjustment
970 If you set this variable to a non-@code{nil} value, the feature of
971 moving point out of these sequences is completely turned off.
975 @section Input Events
979 The Emacs command loop reads a sequence of @dfn{input events} that
980 represent keyboard or mouse activity, or system events sent to Emacs.
981 The events for keyboard activity are characters or symbols; other
982 events are always lists. This section describes the representation
983 and meaning of input events in detail.
986 This function returns non-@code{nil} if @var{object} is an input event
989 Note that any symbol might be used as an event or an event type.
990 @code{eventp} cannot distinguish whether a symbol is intended by Lisp
991 code to be used as an event. Instead, it distinguishes whether the
992 symbol has actually been used in an event that has been read as input in
993 the current Emacs session. If a symbol has not yet been so used,
994 @code{eventp} returns @code{nil}.
998 * Keyboard Events:: Ordinary characters--keys with symbols on them.
999 * Function Keys:: Function keys--keys with names, not symbols.
1000 * Mouse Events:: Overview of mouse events.
1001 * Click Events:: Pushing and releasing a mouse button.
1002 * Drag Events:: Moving the mouse before releasing the button.
1003 * Button-Down Events:: A button was pushed and not yet released.
1004 * Repeat Events:: Double and triple click (or drag, or down).
1005 * Motion Events:: Just moving the mouse, not pushing a button.
1006 * Focus Events:: Moving the mouse between frames.
1007 * Misc Events:: Other events the system can generate.
1008 * Event Examples:: Examples of the lists for mouse events.
1009 * Classifying Events:: Finding the modifier keys in an event symbol.
1011 * Accessing Mouse:: Functions to extract info from mouse events.
1012 * Accessing Scroll:: Functions to get info from scroll bar events.
1013 * Strings of Events:: Special considerations for putting
1014 keyboard character events in a string.
1017 @node Keyboard Events
1018 @subsection Keyboard Events
1019 @cindex keyboard events
1021 There are two kinds of input you can get from the keyboard: ordinary
1022 keys, and function keys. Ordinary keys correspond to characters; the
1023 events they generate are represented in Lisp as characters. The event
1024 type of a character event is the character itself (an integer); see
1025 @ref{Classifying Events}.
1027 @cindex modifier bits (of input character)
1028 @cindex basic code (of input character)
1029 An input character event consists of a @dfn{basic code} between 0 and
1030 524287, plus any or all of these @dfn{modifier bits}:
1041 bit in the character code indicates a character
1042 typed with the meta key held down.
1052 bit in the character code indicates a non-@acronym{ASCII}
1055 @sc{ascii} control characters such as @kbd{C-a} have special basic
1056 codes of their own, so Emacs needs no special bit to indicate them.
1057 Thus, the code for @kbd{C-a} is just 1.
1059 But if you type a control combination not in @acronym{ASCII}, such as
1060 @kbd{%} with the control key, the numeric value you get is the code
1068 (assuming the terminal supports non-@acronym{ASCII}
1069 control characters).
1079 bit in the character code indicates an @acronym{ASCII} control
1080 character typed with the shift key held down.
1082 For letters, the basic code itself indicates upper versus lower case;
1083 for digits and punctuation, the shift key selects an entirely different
1084 character with a different basic code. In order to keep within the
1085 @acronym{ASCII} character set whenever possible, Emacs avoids using the
1092 bit for those characters.
1094 However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
1095 @kbd{C-a}, so Emacs uses the
1102 bit in @kbd{C-A} and not in
1113 bit in the character code indicates a character
1114 typed with the hyper key held down.
1124 bit in the character code indicates a character
1125 typed with the super key held down.
1135 bit in the character code indicates a character typed with the alt key
1136 held down. (The key labeled @key{Alt} on most keyboards is actually
1137 treated as the meta key, not this.)
1140 It is best to avoid mentioning specific bit numbers in your program.
1141 To test the modifier bits of a character, use the function
1142 @code{event-modifiers} (@pxref{Classifying Events}). When making key
1143 bindings, you can use the read syntax for characters with modifier bits
1144 (@samp{\C-}, @samp{\M-}, and so on). For making key bindings with
1145 @code{define-key}, you can use lists such as @code{(control hyper ?x)} to
1146 specify the characters (@pxref{Changing Key Bindings}). The function
1147 @code{event-convert-list} converts such a list into an event type
1148 (@pxref{Classifying Events}).
1151 @subsection Function Keys
1153 @cindex function keys
1154 Most keyboards also have @dfn{function keys}---keys that have names or
1155 symbols that are not characters. Function keys are represented in
1156 Emacs Lisp as symbols; the symbol's name is the function key's label,
1157 in lower case. For example, pressing a key labeled @key{F1} generates
1158 an input event represented by the symbol @code{f1}.
1160 The event type of a function key event is the event symbol itself.
1161 @xref{Classifying Events}.
1163 Here are a few special cases in the symbol-naming convention for
1167 @item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
1168 These keys correspond to common @acronym{ASCII} control characters that have
1169 special keys on most keyboards.
1171 In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the
1172 terminal can distinguish between them, Emacs conveys the distinction to
1173 Lisp programs by representing the former as the integer 9, and the
1174 latter as the symbol @code{tab}.
1176 Most of the time, it's not useful to distinguish the two. So normally
1177 @code{local-function-key-map} (@pxref{Translation Keymaps}) is set up
1178 to map @code{tab} into 9. Thus, a key binding for character code 9
1179 (the character @kbd{C-i}) also applies to @code{tab}. Likewise for
1180 the other symbols in this group. The function @code{read-char}
1181 likewise converts these events into characters.
1183 In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace}
1184 converts into the character code 127 (@key{DEL}), not into code 8
1185 (@key{BS}). This is what most users prefer.
1187 @item @code{left}, @code{up}, @code{right}, @code{down}
1189 @item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
1190 Keypad keys (to the right of the regular keyboard).
1191 @item @code{kp-0}, @code{kp-1}, @dots{}
1192 Keypad keys with digits.
1193 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
1195 @item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
1196 Keypad arrow keys. Emacs normally translates these into the
1197 corresponding non-keypad keys @code{home}, @code{left}, @dots{}
1198 @item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
1199 Additional keypad duplicates of keys ordinarily found elsewhere. Emacs
1200 normally translates these into the like-named non-keypad keys.
1203 You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
1204 @key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to
1205 represent them is with prefixes in the symbol name:
1211 The control modifier.
1222 Thus, the symbol for the key @key{F3} with @key{META} held down is
1223 @code{M-f3}. When you use more than one prefix, we recommend you
1224 write them in alphabetical order; but the order does not matter in
1225 arguments to the key-binding lookup and modification functions.
1228 @subsection Mouse Events
1230 Emacs supports four kinds of mouse events: click events, drag events,
1231 button-down events, and motion events. All mouse events are represented
1232 as lists. The @sc{car} of the list is the event type; this says which
1233 mouse button was involved, and which modifier keys were used with it.
1234 The event type can also distinguish double or triple button presses
1235 (@pxref{Repeat Events}). The rest of the list elements give position
1236 and time information.
1238 For key lookup, only the event type matters: two events of the same type
1239 necessarily run the same command. The command can access the full
1240 values of these events using the @samp{e} interactive code.
1241 @xref{Interactive Codes}.
1243 A key sequence that starts with a mouse event is read using the keymaps
1244 of the buffer in the window that the mouse was in, not the current
1245 buffer. This does not imply that clicking in a window selects that
1246 window or its buffer---that is entirely under the control of the command
1247 binding of the key sequence.
1250 @subsection Click Events
1252 @cindex mouse click event
1254 When the user presses a mouse button and releases it at the same
1255 location, that generates a @dfn{click} event. All mouse click event
1256 share the same format:
1259 (@var{event-type} @var{position} @var{click-count})
1263 @item @var{event-type}
1264 This is a symbol that indicates which mouse button was used. It is
1265 one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the
1266 buttons are numbered left to right.
1268 You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-},
1269 @samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift
1270 and super, just as you would with function keys.
1272 This symbol also serves as the event type of the event. Key bindings
1273 describe events by their types; thus, if there is a key binding for
1274 @code{mouse-1}, that binding would apply to all events whose
1275 @var{event-type} is @code{mouse-1}.
1277 @item @var{position}
1278 This is the position where the mouse click occurred. The actual
1279 format of @var{position} depends on what part of a window was clicked
1282 For mouse click events in the text area, mode line, header line, or in
1283 the marginal areas, @var{position} has this form:
1286 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
1287 @var{object} @var{text-pos} (@var{col} . @var{row})
1288 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
1292 The meanings of these list elements are documented below.
1293 @xref{Accessing Mouse}, for functions that let you easily access these
1298 This is the window in which the click occurred.
1300 @item @var{pos-or-area}
1301 This is the buffer position of the character clicked on in the text
1302 area, or if clicked outside the text area, it is the window area in
1303 which the click occurred. It is one of the symbols @code{mode-line},
1304 @code{header-line}, @code{vertical-line}, @code{left-margin},
1305 @code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
1307 In one special case, @var{pos-or-area} is a list containing a symbol
1308 (one of the symbols listed above) instead of just the symbol. This
1309 happens after the imaginary prefix keys for the event are registered
1310 by Emacs. @xref{Key Sequence Input}.
1312 @item @var{x}, @var{y}
1313 These are the relative pixel coordinates of the click. For clicks in
1314 the text area of a window, the coordinate origin @code{(0 . 0)} is
1315 taken to be the top left corner of the text area. @xref{Window
1316 Sizes}. For clicks in a mode line or header line, the coordinate
1317 origin is the top left corner of the window itself. For fringes,
1318 margins, and the vertical border, @var{x} does not have meaningful
1319 data. For fringes and margins, @var{y} is relative to the bottom edge
1320 of the header line. In all cases, the @var{x} and @var{y} coordinates
1321 increase rightward and downward respectively.
1323 @item @var{timestamp}
1324 This is the time at which the event occurred, in milliseconds.
1327 This is either @code{nil} if there is no string-type text property at
1328 the click position, or a cons cell of the form (@var{string}
1329 . @var{string-pos}) if there is one:
1333 The string which was clicked on, including any properties.
1335 @item @var{string-pos}
1336 The position in the string where the click occurred.
1339 @item @var{text-pos}
1340 For clicks on a marginal area or on a fringe, this is the buffer
1341 position of the first visible character in the corresponding line in
1342 the window. For other events, it is the current buffer position in
1345 @item @var{col}, @var{row}
1346 These are the actual column and row coordinate numbers of the glyph
1347 under the @var{x}, @var{y} position. If @var{x} lies beyond the last
1348 column of actual text on its line, @var{col} is reported by adding
1349 fictional extra columns that have the default character width. Row 0
1350 is taken to be the header line if the window has one, or the topmost
1351 row of the text area otherwise. Column 0 is taken to be the leftmost
1352 column of the text area for clicks on a window text area, or the
1353 leftmost mode line or header line column for clicks there. For clicks
1354 on fringes or vertical borders, these have no meaningful data. For
1355 clicks on margins, @var{col} is measured from the left edge of the
1356 margin area and @var{row} is measured from the top of the margin area.
1359 This is the image object on which the click occurred. It is either
1360 @code{nil} if there is no image at the position clicked on, or it is
1361 an image object as returned by @code{find-image} if click was in an image.
1363 @item @var{dx}, @var{dy}
1364 These are the pixel coordinates of the click, relative to
1365 the top left corner of @var{object}, which is @code{(0 . 0)}. If
1366 @var{object} is @code{nil}, the coordinates are relative to the top
1367 left corner of the character glyph clicked on.
1369 @item @var{width}, @var{height}
1370 These are the pixel width and height of @var{object} or, if this is
1371 @code{nil}, those of the character glyph clicked on.
1375 For mouse clicks on a scroll-bar, @var{position} has this form:
1378 (@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
1383 This is the window whose scroll-bar was clicked on.
1386 This is the scroll bar where the click occurred. It is one of the
1387 symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.
1390 This is the distance of the click from the top or left end of
1394 This is the length of the entire scroll bar.
1396 @item @var{timestamp}
1397 This is the time at which the event occurred, in milliseconds.
1400 This is the part of the scroll-bar which was clicked on. It is one
1401 of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
1402 @code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
1405 @item @var{click-count}
1406 This is the number of rapid repeated presses so far of the same mouse
1407 button. @xref{Repeat Events}.
1411 @subsection Drag Events
1413 @cindex mouse drag event
1415 With Emacs, you can have a drag event without even changing your
1416 clothes. A @dfn{drag event} happens every time the user presses a mouse
1417 button and then moves the mouse to a different character position before
1418 releasing the button. Like all mouse events, drag events are
1419 represented in Lisp as lists. The lists record both the starting mouse
1420 position and the final position, like this:
1424 (@var{window1} START-POSITION)
1425 (@var{window2} END-POSITION))
1428 For a drag event, the name of the symbol @var{event-type} contains the
1429 prefix @samp{drag-}. For example, dragging the mouse with button 2
1430 held down generates a @code{drag-mouse-2} event. The second and third
1431 elements of the event give the starting and ending position of the
1432 drag. They have the same form as @var{position} in a click event
1433 (@pxref{Click Events}) that is not on the scroll bar part of the
1434 window. You can access the second element of any mouse event in the
1435 same way, with no need to distinguish drag events from others.
1437 The @samp{drag-} prefix follows the modifier key prefixes such as
1438 @samp{C-} and @samp{M-}.
1440 If @code{read-key-sequence} receives a drag event that has no key
1441 binding, and the corresponding click event does have a binding, it
1442 changes the drag event into a click event at the drag's starting
1443 position. This means that you don't have to distinguish between click
1444 and drag events unless you want to.
1446 @node Button-Down Events
1447 @subsection Button-Down Events
1448 @cindex button-down event
1450 Click and drag events happen when the user releases a mouse button.
1451 They cannot happen earlier, because there is no way to distinguish a
1452 click from a drag until the button is released.
1454 If you want to take action as soon as a button is pressed, you need to
1455 handle @dfn{button-down} events.@footnote{Button-down is the
1456 conservative antithesis of drag.} These occur as soon as a button is
1457 pressed. They are represented by lists that look exactly like click
1458 events (@pxref{Click Events}), except that the @var{event-type} symbol
1459 name contains the prefix @samp{down-}. The @samp{down-} prefix follows
1460 modifier key prefixes such as @samp{C-} and @samp{M-}.
1462 The function @code{read-key-sequence} ignores any button-down events
1463 that don't have command bindings; therefore, the Emacs command loop
1464 ignores them too. This means that you need not worry about defining
1465 button-down events unless you want them to do something. The usual
1466 reason to define a button-down event is so that you can track mouse
1467 motion (by reading motion events) until the button is released.
1468 @xref{Motion Events}.
1471 @subsection Repeat Events
1472 @cindex repeat events
1473 @cindex double-click events
1474 @cindex triple-click events
1475 @cindex mouse events, repeated
1477 If you press the same mouse button more than once in quick succession
1478 without moving the mouse, Emacs generates special @dfn{repeat} mouse
1479 events for the second and subsequent presses.
1481 The most common repeat events are @dfn{double-click} events. Emacs
1482 generates a double-click event when you click a button twice; the event
1483 happens when you release the button (as is normal for all click
1486 The event type of a double-click event contains the prefix
1487 @samp{double-}. Thus, a double click on the second mouse button with
1488 @key{meta} held down comes to the Lisp program as
1489 @code{M-double-mouse-2}. If a double-click event has no binding, the
1490 binding of the corresponding ordinary click event is used to execute
1491 it. Thus, you need not pay attention to the double click feature
1492 unless you really want to.
1494 When the user performs a double click, Emacs generates first an ordinary
1495 click event, and then a double-click event. Therefore, you must design
1496 the command binding of the double click event to assume that the
1497 single-click command has already run. It must produce the desired
1498 results of a double click, starting from the results of a single click.
1500 This is convenient, if the meaning of a double click somehow ``builds
1501 on'' the meaning of a single click---which is recommended user interface
1502 design practice for double clicks.
1504 If you click a button, then press it down again and start moving the
1505 mouse with the button held down, then you get a @dfn{double-drag} event
1506 when you ultimately release the button. Its event type contains
1507 @samp{double-drag} instead of just @samp{drag}. If a double-drag event
1508 has no binding, Emacs looks for an alternate binding as if the event
1509 were an ordinary drag.
1511 Before the double-click or double-drag event, Emacs generates a
1512 @dfn{double-down} event when the user presses the button down for the
1513 second time. Its event type contains @samp{double-down} instead of just
1514 @samp{down}. If a double-down event has no binding, Emacs looks for an
1515 alternate binding as if the event were an ordinary button-down event.
1516 If it finds no binding that way either, the double-down event is
1519 To summarize, when you click a button and then press it again right
1520 away, Emacs generates a down event and a click event for the first
1521 click, a double-down event when you press the button again, and finally
1522 either a double-click or a double-drag event.
1524 If you click a button twice and then press it again, all in quick
1525 succession, Emacs generates a @dfn{triple-down} event, followed by
1526 either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of
1527 these events contain @samp{triple} instead of @samp{double}. If any
1528 triple event has no binding, Emacs uses the binding that it would use
1529 for the corresponding double event.
1531 If you click a button three or more times and then press it again, the
1532 events for the presses beyond the third are all triple events. Emacs
1533 does not have separate event types for quadruple, quintuple, etc.@:
1534 events. However, you can look at the event list to find out precisely
1535 how many times the button was pressed.
1537 @defun event-click-count event
1538 This function returns the number of consecutive button presses that led
1539 up to @var{event}. If @var{event} is a double-down, double-click or
1540 double-drag event, the value is 2. If @var{event} is a triple event,
1541 the value is 3 or greater. If @var{event} is an ordinary mouse event
1542 (not a repeat event), the value is 1.
1545 @defopt double-click-fuzz
1546 To generate repeat events, successive mouse button presses must be at
1547 approximately the same screen position. The value of
1548 @code{double-click-fuzz} specifies the maximum number of pixels the
1549 mouse may be moved (horizontally or vertically) between two successive
1550 clicks to make a double-click.
1552 This variable is also the threshold for motion of the mouse to count
1556 @defopt double-click-time
1557 To generate repeat events, the number of milliseconds between
1558 successive button presses must be less than the value of
1559 @code{double-click-time}. Setting @code{double-click-time} to
1560 @code{nil} disables multi-click detection entirely. Setting it to
1561 @code{t} removes the time limit; Emacs then detects multi-clicks by
1566 @subsection Motion Events
1567 @cindex motion event
1568 @cindex mouse motion events
1570 Emacs sometimes generates @dfn{mouse motion} events to describe motion
1571 of the mouse without any button activity. Mouse motion events are
1572 represented by lists that look like this:
1575 (mouse-movement POSITION)
1578 The second element of the list describes the current position of the
1579 mouse, just as in a click event (@pxref{Click Events}).
1581 The special form @code{track-mouse} enables generation of motion events
1582 within its body. Outside of @code{track-mouse} forms, Emacs does not
1583 generate events for mere motion of the mouse, and these events do not
1584 appear. @xref{Mouse Tracking}.
1587 @subsection Focus Events
1590 Window systems provide general ways for the user to control which window
1591 gets keyboard input. This choice of window is called the @dfn{focus}.
1592 When the user does something to switch between Emacs frames, that
1593 generates a @dfn{focus event}. The normal definition of a focus event,
1594 in the global keymap, is to select a new frame within Emacs, as the user
1595 would expect. @xref{Input Focus}.
1597 Focus events are represented in Lisp as lists that look like this:
1600 (switch-frame @var{new-frame})
1604 where @var{new-frame} is the frame switched to.
1606 Some X window managers are set up so that just moving the mouse into a
1607 window is enough to set the focus there. Usually, there is no need
1608 for a Lisp program to know about the focus change until some other
1609 kind of input arrives. Emacs generates a focus event only when the
1610 user actually types a keyboard key or presses a mouse button in the
1611 new frame; just moving the mouse between frames does not generate a
1614 A focus event in the middle of a key sequence would garble the
1615 sequence. So Emacs never generates a focus event in the middle of a key
1616 sequence. If the user changes focus in the middle of a key
1617 sequence---that is, after a prefix key---then Emacs reorders the events
1618 so that the focus event comes either before or after the multi-event key
1619 sequence, and not within it.
1622 @subsection Miscellaneous System Events
1624 A few other event types represent occurrences within the system.
1627 @cindex @code{delete-frame} event
1628 @item (delete-frame (@var{frame}))
1629 This kind of event indicates that the user gave the window manager
1630 a command to delete a particular window, which happens to be an Emacs frame.
1632 The standard definition of the @code{delete-frame} event is to delete @var{frame}.
1634 @cindex @code{iconify-frame} event
1635 @item (iconify-frame (@var{frame}))
1636 This kind of event indicates that the user iconified @var{frame} using
1637 the window manager. Its standard definition is @code{ignore}; since the
1638 frame has already been iconified, Emacs has no work to do. The purpose
1639 of this event type is so that you can keep track of such events if you
1642 @cindex @code{make-frame-visible} event
1643 @item (make-frame-visible (@var{frame}))
1644 This kind of event indicates that the user deiconified @var{frame} using
1645 the window manager. Its standard definition is @code{ignore}; since the
1646 frame has already been made visible, Emacs has no work to do.
1648 @cindex @code{wheel-up} event
1649 @cindex @code{wheel-down} event
1650 @item (wheel-up @var{position})
1651 @item (wheel-down @var{position})
1652 These kinds of event are generated by moving a mouse wheel. Their
1653 usual meaning is a kind of scroll or zoom.
1655 The element @var{position} is a list describing the position of the
1656 event, in the same format as used in a mouse-click event (@pxref{Click
1659 @vindex mouse-wheel-up-event
1660 @vindex mouse-wheel-down-event
1661 This kind of event is generated only on some kinds of systems. On some
1662 systems, @code{mouse-4} and @code{mouse-5} are used instead. For
1663 portable code, use the variables @code{mouse-wheel-up-event} and
1664 @code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine
1665 what event types to expect for the mouse wheel.
1667 @cindex @code{drag-n-drop} event
1668 @item (drag-n-drop @var{position} @var{files})
1669 This kind of event is generated when a group of files is
1670 selected in an application outside of Emacs, and then dragged and
1671 dropped onto an Emacs frame.
1673 The element @var{position} is a list describing the position of the
1674 event, in the same format as used in a mouse-click event (@pxref{Click
1675 Events}), and @var{files} is the list of file names that were dragged
1676 and dropped. The usual way to handle this event is by visiting these
1679 This kind of event is generated, at present, only on some kinds of
1682 @cindex @code{help-echo} event
1684 This kind of event is generated when a mouse pointer moves onto a
1685 portion of buffer text which has a @code{help-echo} text property.
1686 The generated event has this form:
1689 (help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos})
1693 The precise meaning of the event parameters and the way these
1694 parameters are used to display the help-echo text are described in
1695 @ref{Text help-echo}.
1697 @cindex @code{sigusr1} event
1698 @cindex @code{sigusr2} event
1699 @cindex user signals
1702 These events are generated when the Emacs process receives
1703 the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no
1704 additional data because signals do not carry additional information.
1705 They can be useful for debugging (@pxref{Error Debugging}).
1707 To catch a user signal, bind the corresponding event to an interactive
1708 command in the @code{special-event-map} (@pxref{Active Keymaps}).
1709 The command is called with no arguments, and the specific signal event is
1710 available in @code{last-input-event}. For example:
1713 (defun sigusr-handler ()
1715 (message "Caught signal %S" last-input-event))
1717 (define-key special-event-map [sigusr1] 'sigusr-handler)
1720 To test the signal handler, you can make Emacs send a signal to itself:
1723 (signal-process (emacs-pid) 'sigusr1)
1726 @cindex @code{language-change} event
1727 @item language-change
1728 This kind of event is generated on MS-Windows when the input language
1729 has changed. This typically means that the keyboard keys will send to
1730 Emacs characters from a different language. The generated event has
1734 (language-change @var{frame} @var{codepage} @var{language-id})
1738 Here @var{frame} is the frame which was current when the input
1739 language changed; @var{codepage} is the new codepage number; and
1740 @var{language-id} is the numerical ID of the new input language. The
1741 coding-system (@pxref{Coding Systems}) that corresponds to
1742 @var{codepage} is @code{cp@var{codepage}} or
1743 @code{windows-@var{codepage}}. To convert @var{language-id} to a
1744 string (e.g., to use it for various language-dependent features, such
1745 as @code{set-language-environment}), use the
1746 @code{w32-get-locale-info} function, like this:
1749 ;; Get the abbreviated language name, such as "ENU" for English
1750 (w32-get-locale-info language-id)
1751 ;; Get the full English name of the language,
1752 ;; such as "English (United States)"
1753 (w32-get-locale-info language-id 4097)
1754 ;; Get the full localized name of the language
1755 (w32-get-locale-info language-id t)
1759 If one of these events arrives in the middle of a key sequence---that
1760 is, after a prefix key---then Emacs reorders the events so that this
1761 event comes either before or after the multi-event key sequence, not
1764 @node Event Examples
1765 @subsection Event Examples
1767 If the user presses and releases the left mouse button over the same
1768 location, that generates a sequence of events like this:
1771 (down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
1772 (mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180))
1775 While holding the control key down, the user might hold down the
1776 second mouse button, and drag the mouse from one line to the next.
1777 That produces two events, as shown here:
1780 (C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
1781 (C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
1782 (#<window 18 on NEWS> 3510 (0 . 28) -729648))
1785 While holding down the meta and shift keys, the user might press the
1786 second mouse button on the window's mode line, and then drag the mouse
1787 into another window. That produces a pair of events like these:
1790 (M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
1791 (M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
1792 (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
1796 To handle a SIGUSR1 signal, define an interactive function, and
1797 bind it to the @code{signal usr1} event sequence:
1800 (defun usr1-handler ()
1802 (message "Got USR1 signal"))
1803 (global-set-key [signal usr1] 'usr1-handler)
1806 @node Classifying Events
1807 @subsection Classifying Events
1810 Every event has an @dfn{event type}, which classifies the event for
1811 key binding purposes. For a keyboard event, the event type equals the
1812 event value; thus, the event type for a character is the character, and
1813 the event type for a function key symbol is the symbol itself. For
1814 events that are lists, the event type is the symbol in the @sc{car} of
1815 the list. Thus, the event type is always a symbol or a character.
1817 Two events of the same type are equivalent where key bindings are
1818 concerned; thus, they always run the same command. That does not
1819 necessarily mean they do the same things, however, as some commands look
1820 at the whole event to decide what to do. For example, some commands use
1821 the location of a mouse event to decide where in the buffer to act.
1823 Sometimes broader classifications of events are useful. For example,
1824 you might want to ask whether an event involved the @key{META} key,
1825 regardless of which other key or mouse button was used.
1827 The functions @code{event-modifiers} and @code{event-basic-type} are
1828 provided to get such information conveniently.
1830 @defun event-modifiers event
1831 This function returns a list of the modifiers that @var{event} has. The
1832 modifiers are symbols; they include @code{shift}, @code{control},
1833 @code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition,
1834 the modifiers list of a mouse event symbol always contains one of
1835 @code{click}, @code{drag}, and @code{down}. For double or triple
1836 events, it also contains @code{double} or @code{triple}.
1838 The argument @var{event} may be an entire event object, or just an
1839 event type. If @var{event} is a symbol that has never been used in an
1840 event that has been read as input in the current Emacs session, then
1841 @code{event-modifiers} can return @code{nil}, even when @var{event}
1842 actually has modifiers.
1844 Here are some examples:
1847 (event-modifiers ?a)
1849 (event-modifiers ?A)
1851 (event-modifiers ?\C-a)
1853 (event-modifiers ?\C-%)
1855 (event-modifiers ?\C-\S-a)
1856 @result{} (control shift)
1857 (event-modifiers 'f5)
1859 (event-modifiers 's-f5)
1861 (event-modifiers 'M-S-f5)
1862 @result{} (meta shift)
1863 (event-modifiers 'mouse-1)
1865 (event-modifiers 'down-mouse-1)
1869 The modifiers list for a click event explicitly contains @code{click},
1870 but the event symbol name itself does not contain @samp{click}.
1873 @defun event-basic-type event
1874 This function returns the key or mouse button that @var{event}
1875 describes, with all modifiers removed. The @var{event} argument is as
1876 in @code{event-modifiers}. For example:
1879 (event-basic-type ?a)
1881 (event-basic-type ?A)
1883 (event-basic-type ?\C-a)
1885 (event-basic-type ?\C-\S-a)
1887 (event-basic-type 'f5)
1889 (event-basic-type 's-f5)
1891 (event-basic-type 'M-S-f5)
1893 (event-basic-type 'down-mouse-1)
1898 @defun mouse-movement-p object
1899 This function returns non-@code{nil} if @var{object} is a mouse movement
1903 @defun event-convert-list list
1904 This function converts a list of modifier names and a basic event type
1905 to an event type which specifies all of them. The basic event type
1906 must be the last element of the list. For example,
1909 (event-convert-list '(control ?a))
1911 (event-convert-list '(control meta ?a))
1912 @result{} -134217727
1913 (event-convert-list '(control super f1))
1918 @node Accessing Mouse
1919 @subsection Accessing Mouse Events
1920 @cindex mouse events, data in
1922 This section describes convenient functions for accessing the data in
1923 a mouse button or motion event.
1925 These two functions return the starting or ending position of a
1926 mouse-button event, as a list of this form (@pxref{Click Events}):
1929 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
1930 @var{object} @var{text-pos} (@var{col} . @var{row})
1931 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
1934 @defun event-start event
1935 This returns the starting position of @var{event}.
1937 If @var{event} is a click or button-down event, this returns the
1938 location of the event. If @var{event} is a drag event, this returns the
1939 drag's starting position.
1942 @defun event-end event
1943 This returns the ending position of @var{event}.
1945 If @var{event} is a drag event, this returns the position where the user
1946 released the mouse button. If @var{event} is a click or button-down
1947 event, the value is actually the starting position, which is the only
1948 position such events have.
1951 @cindex mouse position list, accessing
1952 These functions take a position list as described above, and
1953 return various parts of it.
1955 @defun posn-window position
1956 Return the window that @var{position} is in.
1959 @defun posn-area position
1960 Return the window area recorded in @var{position}. It returns @code{nil}
1961 when the event occurred in the text area of the window; otherwise, it
1962 is a symbol identifying the area in which the event occurred.
1965 @defun posn-point position
1966 Return the buffer position in @var{position}. When the event occurred
1967 in the text area of the window, in a marginal area, or on a fringe,
1968 this is an integer specifying a buffer position. Otherwise, the value
1972 @defun posn-x-y position
1973 Return the pixel-based x and y coordinates in @var{position}, as a
1974 cons cell @code{(@var{x} . @var{y})}. These coordinates are relative
1975 to the window given by @code{posn-window}.
1977 This example shows how to convert the window-relative coordinates in
1978 the text area of a window into frame-relative coordinates:
1981 (defun frame-relative-coordinates (position)
1982 "Return frame-relative coordinates from POSITION.
1983 POSITION is assumed to lie in a window text area."
1984 (let* ((x-y (posn-x-y position))
1985 (window (posn-window position))
1986 (edges (window-inside-pixel-edges window)))
1987 (cons (+ (car x-y) (car edges))
1988 (+ (cdr x-y) (cadr edges)))))
1992 @defun posn-col-row position
1993 This function returns a cons cell @code{(@var{col} . @var{row})},
1994 containing the estimated column and row corresponding to buffer
1995 position @var{position}. The return value is given in units of the
1996 frame's default character width and height, as computed from the
1997 @var{x} and @var{y} values corresponding to @var{position}. (So, if
1998 the actual characters have non-default sizes, the actual row and
1999 column may differ from these computed values.)
2001 Note that @var{row} is counted from the top of the text area. If the
2002 window possesses a header line (@pxref{Header Lines}), it is
2003 @emph{not} counted as the first line.
2006 @defun posn-actual-col-row position
2007 Return the actual row and column in @var{position}, as a cons cell
2008 @code{(@var{col} . @var{row})}. The values are the actual row and
2009 column numbers in the window. @xref{Click Events}, for details. It
2010 returns @code{nil} if @var{position} does not include actual positions
2014 @defun posn-string position
2015 Return the string object in @var{position}, either @code{nil}, or a
2016 cons cell @code{(@var{string} . @var{string-pos})}.
2019 @defun posn-image position
2020 Return the image object in @var{position}, either @code{nil}, or an
2021 image @code{(image ...)}.
2024 @defun posn-object position
2025 Return the image or string object in @var{position}, either
2026 @code{nil}, an image @code{(image ...)}, or a cons cell
2027 @code{(@var{string} . @var{string-pos})}.
2030 @defun posn-object-x-y position
2031 Return the pixel-based x and y coordinates relative to the upper left
2032 corner of the object in @var{position} as a cons cell @code{(@var{dx}
2033 . @var{dy})}. If the @var{position} is a buffer position, return the
2034 relative position in the character at that position.
2037 @defun posn-object-width-height position
2038 Return the pixel width and height of the object in @var{position} as a
2039 cons cell @code{(@var{width} . @var{height})}. If the @var{position}
2040 is a buffer position, return the size of the character at that position.
2043 @cindex timestamp of a mouse event
2044 @defun posn-timestamp position
2045 Return the timestamp in @var{position}. This is the time at which the
2046 event occurred, in milliseconds.
2049 These functions compute a position list given particular buffer
2050 position or screen position. You can access the data in this position
2051 list with the functions described above.
2053 @defun posn-at-point &optional pos window
2054 This function returns a position list for position @var{pos} in
2055 @var{window}. @var{pos} defaults to point in @var{window};
2056 @var{window} defaults to the selected window.
2058 @code{posn-at-point} returns @code{nil} if @var{pos} is not visible in
2062 @defun posn-at-x-y x y &optional frame-or-window whole
2063 This function returns position information corresponding to pixel
2064 coordinates @var{x} and @var{y} in a specified frame or window,
2065 @var{frame-or-window}, which defaults to the selected window.
2066 The coordinates @var{x} and @var{y} are relative to the
2067 frame or window used.
2068 If @var{whole} is @code{nil}, the coordinates are relative
2069 to the window text area, otherwise they are relative to
2070 the entire window area including scroll bars, margins and fringes.
2073 @node Accessing Scroll
2074 @subsection Accessing Scroll Bar Events
2075 @cindex scroll bar events, data in
2077 These functions are useful for decoding scroll bar events.
2079 @defun scroll-bar-event-ratio event
2080 This function returns the fractional vertical position of a scroll bar
2081 event within the scroll bar. The value is a cons cell
2082 @code{(@var{portion} . @var{whole})} containing two integers whose ratio
2083 is the fractional position.
2086 @defun scroll-bar-scale ratio total
2087 This function multiplies (in effect) @var{ratio} by @var{total},
2088 rounding the result to an integer. The argument @var{ratio} is not a
2089 number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
2090 value returned by @code{scroll-bar-event-ratio}.
2092 This function is handy for scaling a position on a scroll bar into a
2093 buffer position. Here's how to do that:
2098 (posn-x-y (event-start event))
2099 (- (point-max) (point-min))))
2102 Recall that scroll bar events have two integers forming a ratio, in place
2103 of a pair of x and y coordinates.
2106 @node Strings of Events
2107 @subsection Putting Keyboard Events in Strings
2108 @cindex keyboard events in strings
2109 @cindex strings with keyboard events
2111 In most of the places where strings are used, we conceptualize the
2112 string as containing text characters---the same kind of characters found
2113 in buffers or files. Occasionally Lisp programs use strings that
2114 conceptually contain keyboard characters; for example, they may be key
2115 sequences or keyboard macro definitions. However, storing keyboard
2116 characters in a string is a complex matter, for reasons of historical
2117 compatibility, and it is not always possible.
2119 We recommend that new programs avoid dealing with these complexities
2120 by not storing keyboard events in strings. Here is how to do that:
2124 Use vectors instead of strings for key sequences, when you plan to use
2125 them for anything other than as arguments to @code{lookup-key} and
2126 @code{define-key}. For example, you can use
2127 @code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
2128 @code{this-command-keys-vector} instead of @code{this-command-keys}.
2131 Use vectors to write key sequence constants containing meta characters,
2132 even when passing them directly to @code{define-key}.
2135 When you have to look at the contents of a key sequence that might be a
2136 string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
2137 first, to convert it to a list.
2140 The complexities stem from the modifier bits that keyboard input
2141 characters can include. Aside from the Meta modifier, none of these
2142 modifier bits can be included in a string, and the Meta modifier is
2143 allowed only in special cases.
2145 The earliest GNU Emacs versions represented meta characters as codes
2146 in the range of 128 to 255. At that time, the basic character codes
2147 ranged from 0 to 127, so all keyboard character codes did fit in a
2148 string. Many Lisp programs used @samp{\M-} in string constants to stand
2149 for meta characters, especially in arguments to @code{define-key} and
2150 similar functions, and key sequences and sequences of events were always
2151 represented as strings.
2153 When we added support for larger basic character codes beyond 127, and
2154 additional modifier bits, we had to change the representation of meta
2155 characters. Now the flag that represents the Meta modifier in a
2163 and such numbers cannot be included in a string.
2165 To support programs with @samp{\M-} in string constants, there are
2166 special rules for including certain meta characters in a string.
2167 Here are the rules for interpreting a string as a sequence of input
2172 If the keyboard character value is in the range of 0 to 127, it can go
2173 in the string unchanged.
2176 The meta variants of those characters, with codes in the range of
2185 @math{2^{27} + 127},
2190 can also go in the string, but you must change their
2191 numeric values. You must set the
2205 bit, resulting in a value between 128 and 255. Only a unibyte string
2206 can include these codes.
2209 Non-@acronym{ASCII} characters above 256 can be included in a multibyte string.
2212 Other keyboard character events cannot fit in a string. This includes
2213 keyboard events in the range of 128 to 255.
2216 Functions such as @code{read-key-sequence} that construct strings of
2217 keyboard input characters follow these rules: they construct vectors
2218 instead of strings, when the events won't fit in a string.
2220 When you use the read syntax @samp{\M-} in a string, it produces a
2221 code in the range of 128 to 255---the same code that you get if you
2222 modify the corresponding keyboard event to put it in the string. Thus,
2223 meta events in strings work consistently regardless of how they get into
2226 However, most programs would do well to avoid these issues by
2227 following the recommendations at the beginning of this section.
2230 @section Reading Input
2232 @cindex keyboard input
2234 The editor command loop reads key sequences using the function
2235 @code{read-key-sequence}, which uses @code{read-event}. These and other
2236 functions for event input are also available for use in Lisp programs.
2237 See also @code{momentary-string-display} in @ref{Temporary Displays},
2238 and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
2239 functions and variables for controlling terminal input modes and
2240 debugging terminal input.
2242 For higher-level input facilities, see @ref{Minibuffers}.
2245 * Key Sequence Input:: How to read one key sequence.
2246 * Reading One Event:: How to read just one event.
2247 * Event Mod:: How Emacs modifies events as they are read.
2248 * Invoking the Input Method:: How reading an event uses the input method.
2249 * Quoted Character Input:: Asking the user to specify a character.
2250 * Event Input Misc:: How to reread or throw away input events.
2253 @node Key Sequence Input
2254 @subsection Key Sequence Input
2255 @cindex key sequence input
2257 The command loop reads input a key sequence at a time, by calling
2258 @code{read-key-sequence}. Lisp programs can also call this function;
2259 for example, @code{describe-key} uses it to read the key to describe.
2261 @defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
2262 This function reads a key sequence and returns it as a string or
2263 vector. It keeps reading events until it has accumulated a complete key
2264 sequence; that is, enough to specify a non-prefix command using the
2265 currently active keymaps. (Remember that a key sequence that starts
2266 with a mouse event is read using the keymaps of the buffer in the
2267 window that the mouse was in, not the current buffer.)
2269 If the events are all characters and all can fit in a string, then
2270 @code{read-key-sequence} returns a string (@pxref{Strings of Events}).
2271 Otherwise, it returns a vector, since a vector can hold all kinds of
2272 events---characters, symbols, and lists. The elements of the string or
2273 vector are the events in the key sequence.
2275 Reading a key sequence includes translating the events in various
2276 ways. @xref{Translation Keymaps}.
2278 The argument @var{prompt} is either a string to be displayed in the
2279 echo area as a prompt, or @code{nil}, meaning not to display a prompt.
2280 The argument @var{continue-echo}, if non-@code{nil}, means to echo
2281 this key as a continuation of the previous key.
2283 Normally any upper case event is converted to lower case if the
2284 original event is undefined and the lower case equivalent is defined.
2285 The argument @var{dont-downcase-last}, if non-@code{nil}, means do not
2286 convert the last event to lower case. This is appropriate for reading
2287 a key sequence to be defined.
2289 The argument @var{switch-frame-ok}, if non-@code{nil}, means that this
2290 function should process a @code{switch-frame} event if the user
2291 switches frames before typing anything. If the user switches frames
2292 in the middle of a key sequence, or at the start of the sequence but
2293 @var{switch-frame-ok} is @code{nil}, then the event will be put off
2294 until after the current key sequence.
2296 The argument @var{command-loop}, if non-@code{nil}, means that this
2297 key sequence is being read by something that will read commands one
2298 after another. It should be @code{nil} if the caller will read just
2301 In the following example, Emacs displays the prompt @samp{?} in the
2302 echo area, and then the user types @kbd{C-x C-f}.
2305 (read-key-sequence "?")
2308 ---------- Echo Area ----------
2310 ---------- Echo Area ----------
2316 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
2317 typed while reading with this function works like any other character,
2318 and does not set @code{quit-flag}. @xref{Quitting}.
2321 @defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
2322 This is like @code{read-key-sequence} except that it always
2323 returns the key sequence as a vector, never as a string.
2324 @xref{Strings of Events}.
2327 @cindex upper case key sequence
2328 @cindex downcasing in @code{lookup-key}
2329 @cindex shift-translation
2330 If an input character is upper-case (or has the shift modifier) and
2331 has no key binding, but its lower-case equivalent has one, then
2332 @code{read-key-sequence} converts the character to lower case. Note
2333 that @code{lookup-key} does not perform case conversion in this way.
2335 @vindex this-command-keys-shift-translated
2336 When reading input results in such a @dfn{shift-translation}, Emacs
2337 sets the variable @code{this-command-keys-shift-translated} to a
2338 non-@code{nil} value. Lisp programs can examine this variable if they
2339 need to modify their behavior when invoked by shift-translated keys.
2340 For example, the function @code{handle-shift-selection} examines the
2341 value of this variable to determine how to activate or deactivate the
2342 region (@pxref{The Mark, handle-shift-selection}).
2344 The function @code{read-key-sequence} also transforms some mouse events.
2345 It converts unbound drag events into click events, and discards unbound
2346 button-down events entirely. It also reshuffles focus events and
2347 miscellaneous window events so that they never appear in a key sequence
2348 with any other events.
2350 @cindex @code{header-line} prefix key
2351 @cindex @code{mode-line} prefix key
2352 @cindex @code{vertical-line} prefix key
2353 @cindex @code{horizontal-scroll-bar} prefix key
2354 @cindex @code{vertical-scroll-bar} prefix key
2355 @cindex @code{menu-bar} prefix key
2356 @cindex mouse events, in special parts of frame
2357 When mouse events occur in special parts of a window, such as a mode
2358 line or a scroll bar, the event type shows nothing special---it is the
2359 same symbol that would normally represent that combination of mouse
2360 button and modifier keys. The information about the window part is kept
2361 elsewhere in the event---in the coordinates. But
2362 @code{read-key-sequence} translates this information into imaginary
2363 ``prefix keys'', all of which are symbols: @code{header-line},
2364 @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
2365 @code{vertical-line}, and @code{vertical-scroll-bar}. You can define
2366 meanings for mouse clicks in special window parts by defining key
2367 sequences using these imaginary prefix keys.
2369 For example, if you call @code{read-key-sequence} and then click the
2370 mouse on the window's mode line, you get two events, like this:
2373 (read-key-sequence "Click on the mode line: ")
2374 @result{} [mode-line
2376 (#<window 6 on NEWS> mode-line
2377 (40 . 63) 5959987))]
2380 @defvar num-input-keys
2382 This variable's value is the number of key sequences processed so far in
2383 this Emacs session. This includes key sequences read from the terminal
2384 and key sequences read from keyboard macros being executed.
2387 @node Reading One Event
2388 @subsection Reading One Event
2389 @cindex reading a single event
2390 @cindex event, reading only one
2392 The lowest level functions for command input are @code{read-event},
2393 @code{read-char}, and @code{read-char-exclusive}.
2395 @defun read-event &optional prompt inherit-input-method seconds
2396 This function reads and returns the next event of command input, waiting
2397 if necessary until an event is available. Events can come directly from
2398 the user or from a keyboard macro.
2400 If the optional argument @var{prompt} is non-@code{nil}, it should be a
2401 string to display in the echo area as a prompt. Otherwise,
2402 @code{read-event} does not display any message to indicate it is waiting
2403 for input; instead, it prompts by echoing: it displays descriptions of
2404 the events that led to or were read by the current command. @xref{The
2407 If @var{inherit-input-method} is non-@code{nil}, then the current input
2408 method (if any) is employed to make it possible to enter a
2409 non-@acronym{ASCII} character. Otherwise, input method handling is disabled
2410 for reading this event.
2412 If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
2413 moves the cursor temporarily to the echo area, to the end of any message
2414 displayed there. Otherwise @code{read-event} does not move the cursor.
2416 If @var{seconds} is non-@code{nil}, it should be a number specifying
2417 the maximum time to wait for input, in seconds. If no input arrives
2418 within that time, @code{read-event} stops waiting and returns
2419 @code{nil}. A floating-point value for @var{seconds} means to wait
2420 for a fractional number of seconds. Some systems support only a whole
2421 number of seconds; on these systems, @var{seconds} is rounded down.
2422 If @var{seconds} is @code{nil}, @code{read-event} waits as long as
2423 necessary for input to arrive.
2425 If @var{seconds} is @code{nil}, Emacs is considered idle while waiting
2426 for user input to arrive. Idle timers---those created with
2427 @code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this
2428 period. However, if @var{seconds} is non-@code{nil}, the state of
2429 idleness remains unchanged. If Emacs is non-idle when
2430 @code{read-event} is called, it remains non-idle throughout the
2431 operation of @code{read-event}; if Emacs is idle (which can happen if
2432 the call happens inside an idle timer), it remains idle.
2434 If @code{read-event} gets an event that is defined as a help character,
2435 then in some cases @code{read-event} processes the event directly without
2436 returning. @xref{Help Functions}. Certain other events, called
2437 @dfn{special events}, are also processed directly within
2438 @code{read-event} (@pxref{Special Events}).
2440 Here is what happens if you call @code{read-event} and then press the
2441 right-arrow function key:
2451 @defun read-char &optional prompt inherit-input-method seconds
2452 This function reads and returns a character of command input. If the
2453 user generates an event which is not a character (i.e. a mouse click or
2454 function key event), @code{read-char} signals an error. The arguments
2455 work as in @code{read-event}.
2457 In the first example, the user types the character @kbd{1} (@acronym{ASCII}
2458 code 49). The second example shows a keyboard macro definition that
2459 calls @code{read-char} from the minibuffer using @code{eval-expression}.
2460 @code{read-char} reads the keyboard macro's very next character, which
2461 is @kbd{1}. Then @code{eval-expression} displays its return value in
2471 ;; @r{We assume here you use @kbd{M-:} to evaluate this.}
2472 (symbol-function 'foo)
2473 @result{} "^[:(read-char)^M1"
2476 (execute-kbd-macro 'foo)
2483 @defun read-char-exclusive &optional prompt inherit-input-method seconds
2484 This function reads and returns a character of command input. If the
2485 user generates an event which is not a character,
2486 @code{read-char-exclusive} ignores it and reads another event, until it
2487 gets a character. The arguments work as in @code{read-event}.
2490 None of the above functions suppress quitting.
2492 @defvar num-nonmacro-input-events
2493 This variable holds the total number of input events received so far
2494 from the terminal---not counting those generated by keyboard macros.
2497 We emphasize that, unlike @code{read-key-sequence}, the functions
2498 @code{read-event}, @code{read-char}, and @code{read-char-exclusive} do
2499 not perform the translations described in @ref{Translation Keymaps}.
2500 If you wish to read a single key taking these translations into
2501 account, use the function @code{read-key}:
2503 @defun read-key &optional prompt
2504 This function reads a single key. It is ``intermediate'' between
2505 @code{read-key-sequence} and @code{read-event}. Unlike the former, it
2506 reads a single key, not a key sequence. Unlike the latter, it does
2507 not return a raw event, but decodes and translates the user input
2508 according to @code{input-decode-map}, @code{local-function-key-map},
2509 and @code{key-translation-map} (@pxref{Translation Keymaps}).
2511 The argument @var{prompt} is either a string to be displayed in the
2512 echo area as a prompt, or @code{nil}, meaning not to display a prompt.
2515 @defun read-char-choice prompt chars &optional inhibit-quit
2516 This function uses @code{read-key} to read and return a single
2517 character. It ignores any input that is not a member of @var{chars},
2518 a list of accepted characters. Optionally, it will also ignore
2519 keyboard-quit events while it is waiting for valid input. If you bind
2520 @code{help-form} (@pxref{Help Functions}) to a non-@code{nil} value
2521 while calling @code{read-char-choice}, then pressing @code{help-char}
2522 causes it to evaluate @code{help-form} and display the result. It
2523 then continues to wait for a valid input character, or keyboard-quit.
2527 @subsection Modifying and Translating Input Events
2529 Emacs modifies every event it reads according to
2530 @code{extra-keyboard-modifiers}, then translates it through
2531 @code{keyboard-translate-table} (if applicable), before returning it
2532 from @code{read-event}.
2535 @defvar extra-keyboard-modifiers
2536 This variable lets Lisp programs ``press'' the modifier keys on the
2537 keyboard. The value is a character. Only the modifiers of the
2538 character matter. Each time the user types a keyboard key, it is
2539 altered as if those modifier keys were held down. For instance, if
2540 you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all
2541 keyboard input characters typed during the scope of the binding will
2542 have the control and meta modifiers applied to them. The character
2543 @code{?\C-@@}, equivalent to the integer 0, does not count as a control
2544 character for this purpose, but as a character with no modifiers.
2545 Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
2548 When using a window system, the program can ``press'' any of the
2549 modifier keys in this way. Otherwise, only the @key{CTL} and @key{META}
2550 keys can be virtually pressed.
2552 Note that this variable applies only to events that really come from
2553 the keyboard, and has no effect on mouse events or any other events.
2556 @defvar keyboard-translate-table
2557 This terminal-local variable is the translate table for keyboard
2558 characters. It lets you reshuffle the keys on the keyboard without
2559 changing any command bindings. Its value is normally a char-table, or
2560 else @code{nil}. (It can also be a string or vector, but this is
2561 considered obsolete.)
2563 If @code{keyboard-translate-table} is a char-table
2564 (@pxref{Char-Tables}), then each character read from the keyboard is
2565 looked up in this char-table. If the value found there is
2566 non-@code{nil}, then it is used instead of the actual input character.
2568 Note that this translation is the first thing that happens to a
2569 character after it is read from the terminal. Record-keeping features
2570 such as @code{recent-keys} and dribble files record the characters after
2573 Note also that this translation is done before the characters are
2574 supplied to input methods (@pxref{Input Methods}). Use
2575 @code{translation-table-for-input} (@pxref{Translation of Characters}),
2576 if you want to translate characters after input methods operate.
2579 @defun keyboard-translate from to
2580 This function modifies @code{keyboard-translate-table} to translate
2581 character code @var{from} into character code @var{to}. It creates
2582 the keyboard translate table if necessary.
2585 Here's an example of using the @code{keyboard-translate-table} to
2586 make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste
2590 (keyboard-translate ?\C-x 'control-x)
2591 (keyboard-translate ?\C-c 'control-c)
2592 (keyboard-translate ?\C-v 'control-v)
2593 (global-set-key [control-x] 'kill-region)
2594 (global-set-key [control-c] 'kill-ring-save)
2595 (global-set-key [control-v] 'yank)
2599 On a graphical terminal that supports extended @acronym{ASCII} input,
2600 you can still get the standard Emacs meanings of one of those
2601 characters by typing it with the shift key. That makes it a different
2602 character as far as keyboard translation is concerned, but it has the
2605 @xref{Translation Keymaps}, for mechanisms that translate event sequences
2606 at the level of @code{read-key-sequence}.
2608 @node Invoking the Input Method
2609 @subsection Invoking the Input Method
2611 The event-reading functions invoke the current input method, if any
2612 (@pxref{Input Methods}). If the value of @code{input-method-function}
2613 is non-@code{nil}, it should be a function; when @code{read-event} reads
2614 a printing character (including @key{SPC}) with no modifier bits, it
2615 calls that function, passing the character as an argument.
2617 @defvar input-method-function
2618 If this is non-@code{nil}, its value specifies the current input method
2621 @strong{Warning:} don't bind this variable with @code{let}. It is often
2622 buffer-local, and if you bind it around reading input (which is exactly
2623 when you @emph{would} bind it), switching buffers asynchronously while
2624 Emacs is waiting will cause the value to be restored in the wrong
2628 The input method function should return a list of events which should
2629 be used as input. (If the list is @code{nil}, that means there is no
2630 input, so @code{read-event} waits for another event.) These events are
2631 processed before the events in @code{unread-command-events}
2632 (@pxref{Event Input Misc}). Events
2633 returned by the input method function are not passed to the input method
2634 function again, even if they are printing characters with no modifier
2637 If the input method function calls @code{read-event} or
2638 @code{read-key-sequence}, it should bind @code{input-method-function} to
2639 @code{nil} first, to prevent recursion.
2641 The input method function is not called when reading the second and
2642 subsequent events of a key sequence. Thus, these characters are not
2643 subject to input method processing. The input method function should
2644 test the values of @code{overriding-local-map} and
2645 @code{overriding-terminal-local-map}; if either of these variables is
2646 non-@code{nil}, the input method should put its argument into a list and
2647 return that list with no further processing.
2649 @node Quoted Character Input
2650 @subsection Quoted Character Input
2651 @cindex quoted character input
2653 You can use the function @code{read-quoted-char} to ask the user to
2654 specify a character, and allow the user to specify a control or meta
2655 character conveniently, either literally or as an octal character code.
2656 The command @code{quoted-insert} uses this function.
2658 @defun read-quoted-char &optional prompt
2659 @cindex octal character input
2660 @cindex control characters, reading
2661 @cindex nonprinting characters, reading
2662 This function is like @code{read-char}, except that if the first
2663 character read is an octal digit (0-7), it reads any number of octal
2664 digits (but stopping if a non-octal digit is found), and returns the
2665 character represented by that numeric character code. If the
2666 character that terminates the sequence of octal digits is @key{RET},
2667 it is discarded. Any other terminating character is used as input
2668 after this function returns.
2670 Quitting is suppressed when the first character is read, so that the
2671 user can enter a @kbd{C-g}. @xref{Quitting}.
2673 If @var{prompt} is supplied, it specifies a string for prompting the
2674 user. The prompt string is always displayed in the echo area, followed
2675 by a single @samp{-}.
2677 In the following example, the user types in the octal number 177 (which
2681 (read-quoted-char "What character")
2684 ---------- Echo Area ----------
2685 What character @kbd{1 7 7}-
2686 ---------- Echo Area ----------
2694 @node Event Input Misc
2695 @subsection Miscellaneous Event Input Features
2697 This section describes how to ``peek ahead'' at events without using
2698 them up, how to check for pending input, and how to discard pending
2699 input. See also the function @code{read-passwd} (@pxref{Reading a
2702 @defvar unread-command-events
2704 @cindex peeking at input
2705 This variable holds a list of events waiting to be read as command
2706 input. The events are used in the order they appear in the list, and
2707 removed one by one as they are used.
2709 The variable is needed because in some cases a function reads an event
2710 and then decides not to use it. Storing the event in this variable
2711 causes it to be processed normally, by the command loop or by the
2712 functions to read command input.
2714 @cindex prefix argument unreading
2715 For example, the function that implements numeric prefix arguments reads
2716 any number of digits. When it finds a non-digit event, it must unread
2717 the event so that it can be read normally by the command loop.
2718 Likewise, incremental search uses this feature to unread events with no
2719 special meaning in a search, because these events should exit the search
2720 and then execute normally.
2722 The reliable and easy way to extract events from a key sequence so as
2723 to put them in @code{unread-command-events} is to use
2724 @code{listify-key-sequence} (see below).
2726 Normally you add events to the front of this list, so that the events
2727 most recently unread will be reread first.
2729 Events read from this list are not normally added to the current
2730 command's key sequence (as returned by e.g. @code{this-command-keys}),
2731 as the events will already have been added once as they were read for
2732 the first time. An element of the form @code{(@code{t} . @var{event})}
2733 forces @var{event} to be added to the current command's key sequence.
2736 @defun listify-key-sequence key
2737 This function converts the string or vector @var{key} to a list of
2738 individual events, which you can put in @code{unread-command-events}.
2742 @defvar unread-command-char
2743 This variable holds a character to be read as command input.
2744 A value of -1 means ``empty''.
2746 This variable is mostly obsolete now that you can use
2747 @code{unread-command-events} instead; it exists only to support programs
2748 written for Emacs versions 18 and earlier.
2752 @defun input-pending-p
2753 @cindex waiting for command key input
2754 This function determines whether any command input is currently
2755 available to be read. It returns immediately, with value @code{t} if
2756 there is available input, @code{nil} otherwise. On rare occasions it
2757 may return @code{t} when no input is available.
2760 @defvar last-input-event
2761 @defvarx last-input-char
2762 This variable records the last terminal input event read, whether
2763 as part of a command or explicitly by a Lisp program.
2765 In the example below, the Lisp program reads the character @kbd{1},
2766 @acronym{ASCII} code 49. It becomes the value of @code{last-input-event},
2767 while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
2768 this expression) remains the value of @code{last-command-event}.
2772 (progn (print (read-char))
2773 (print last-command-event)
2781 The alias @code{last-input-char} is obsolete.
2784 @defmac while-no-input body@dots{}
2785 This construct runs the @var{body} forms and returns the value of the
2786 last one---but only if no input arrives. If any input arrives during
2787 the execution of the @var{body} forms, it aborts them (working much
2788 like a quit). The @code{while-no-input} form returns @code{nil} if
2789 aborted by a real quit, and returns @code{t} if aborted by arrival of
2792 If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil},
2793 arrival of input during those parts won't cause an abort until
2794 the end of that part.
2796 If you want to be able to distinguish all possible values computed
2797 by @var{body} from both kinds of abort conditions, write the code
2803 (progn . @var{body})))
2807 @defun discard-input
2808 @cindex flushing input
2809 @cindex discarding input
2810 @cindex keyboard macro, terminating
2811 This function discards the contents of the terminal input buffer and
2812 cancels any keyboard macro that might be in the process of definition.
2813 It returns @code{nil}.
2815 In the following example, the user may type a number of characters right
2816 after starting the evaluation of the form. After the @code{sleep-for}
2817 finishes sleeping, @code{discard-input} discards any characters typed
2821 (progn (sleep-for 2)
2827 @node Special Events
2828 @section Special Events
2830 @cindex special events
2831 Certain @dfn{special events} are handled at a very low level---as soon
2832 as they are read. The @code{read-event} function processes these
2833 events itself, and never returns them. Instead, it keeps waiting for
2834 the first event that is not special and returns that one.
2836 Special events do not echo, they are never grouped into key
2837 sequences, and they never appear in the value of
2838 @code{last-command-event} or @code{(this-command-keys)}. They do not
2839 discard a numeric argument, they cannot be unread with
2840 @code{unread-command-events}, they may not appear in a keyboard macro,
2841 and they are not recorded in a keyboard macro while you are defining
2844 Special events do, however, appear in @code{last-input-event}
2845 immediately after they are read, and this is the way for the event's
2846 definition to find the actual event.
2848 The events types @code{iconify-frame}, @code{make-frame-visible},
2849 @code{delete-frame}, @code{drag-n-drop}, @code{language-change}, and
2850 user signals like @code{sigusr1} are normally handled in this way.
2851 The keymap which defines how to handle special events---and which
2852 events are special---is in the variable @code{special-event-map}
2853 (@pxref{Active Keymaps}).
2856 @section Waiting for Elapsed Time or Input
2859 The wait functions are designed to wait for a certain amount of time
2860 to pass or until there is input. For example, you may wish to pause in
2861 the middle of a computation to allow the user time to view the display.
2862 @code{sit-for} pauses and updates the screen, and returns immediately if
2863 input comes in, while @code{sleep-for} pauses without updating the
2866 @defun sit-for seconds &optional nodisp
2867 This function performs redisplay (provided there is no pending input
2868 from the user), then waits @var{seconds} seconds, or until input is
2869 available. The usual purpose of @code{sit-for} is to give the user
2870 time to read text that you display. The value is @code{t} if
2871 @code{sit-for} waited the full time with no input arriving
2872 (@pxref{Event Input Misc}). Otherwise, the value is @code{nil}.
2874 The argument @var{seconds} need not be an integer. If it is a floating
2875 point number, @code{sit-for} waits for a fractional number of seconds.
2876 Some systems support only a whole number of seconds; on these systems,
2877 @var{seconds} is rounded down.
2879 The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)},
2880 i.e. it requests a redisplay, without any delay, if there is no pending input.
2881 @xref{Forcing Redisplay}.
2883 If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
2884 redisplay, but it still returns as soon as input is available (or when
2885 the timeout elapses).
2887 In batch mode (@pxref{Batch Mode}), @code{sit-for} cannot be
2888 interrupted, even by input from the standard input descriptor. It is
2889 thus equivalent to @code{sleep-for}, which is described below.
2891 It is also possible to call @code{sit-for} with three arguments,
2892 as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})},
2893 but that is considered obsolete.
2896 @defun sleep-for seconds &optional millisec
2897 This function simply pauses for @var{seconds} seconds without updating
2898 the display. It pays no attention to available input. It returns
2901 The argument @var{seconds} need not be an integer. If it is a floating
2902 point number, @code{sleep-for} waits for a fractional number of seconds.
2903 Some systems support only a whole number of seconds; on these systems,
2904 @var{seconds} is rounded down.
2906 The optional argument @var{millisec} specifies an additional waiting
2907 period measured in milliseconds. This adds to the period specified by
2908 @var{seconds}. If the system doesn't support waiting fractions of a
2909 second, you get an error if you specify nonzero @var{millisec}.
2911 Use @code{sleep-for} when you wish to guarantee a delay.
2914 @xref{Time of Day}, for functions to get the current time.
2920 @cindex interrupt Lisp functions
2922 Typing @kbd{C-g} while a Lisp function is running causes Emacs to
2923 @dfn{quit} whatever it is doing. This means that control returns to the
2924 innermost active command loop.
2926 Typing @kbd{C-g} while the command loop is waiting for keyboard input
2927 does not cause a quit; it acts as an ordinary input character. In the
2928 simplest case, you cannot tell the difference, because @kbd{C-g}
2929 normally runs the command @code{keyboard-quit}, whose effect is to quit.
2930 However, when @kbd{C-g} follows a prefix key, they combine to form an
2931 undefined key. The effect is to cancel the prefix key as well as any
2934 In the minibuffer, @kbd{C-g} has a different definition: it aborts out
2935 of the minibuffer. This means, in effect, that it exits the minibuffer
2936 and then quits. (Simply quitting would return to the command loop
2937 @emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit
2938 directly when the command reader is reading input is so that its meaning
2939 can be redefined in the minibuffer in this way. @kbd{C-g} following a
2940 prefix key is not redefined in the minibuffer, and it has its normal
2941 effect of canceling the prefix key and prefix argument. This too
2942 would not be possible if @kbd{C-g} always quit directly.
2944 When @kbd{C-g} does directly quit, it does so by setting the variable
2945 @code{quit-flag} to @code{t}. Emacs checks this variable at appropriate
2946 times and quits if it is not @code{nil}. Setting @code{quit-flag}
2947 non-@code{nil} in any way thus causes a quit.
2949 At the level of C code, quitting cannot happen just anywhere; only at the
2950 special places that check @code{quit-flag}. The reason for this is
2951 that quitting at other places might leave an inconsistency in Emacs's
2952 internal state. Because quitting is delayed until a safe place, quitting
2953 cannot make Emacs crash.
2955 Certain functions such as @code{read-key-sequence} or
2956 @code{read-quoted-char} prevent quitting entirely even though they wait
2957 for input. Instead of quitting, @kbd{C-g} serves as the requested
2958 input. In the case of @code{read-key-sequence}, this serves to bring
2959 about the special behavior of @kbd{C-g} in the command loop. In the
2960 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
2961 to quote a @kbd{C-g}.
2963 @cindex preventing quitting
2964 You can prevent quitting for a portion of a Lisp function by binding
2965 the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
2966 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
2967 usual result of this---a quit---is prevented. Eventually,
2968 @code{inhibit-quit} will become @code{nil} again, such as when its
2969 binding is unwound at the end of a @code{let} form. At that time, if
2970 @code{quit-flag} is still non-@code{nil}, the requested quit happens
2971 immediately. This behavior is ideal when you wish to make sure that
2972 quitting does not happen within a ``critical section'' of the program.
2974 @cindex @code{read-quoted-char} quitting
2975 In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
2976 handled in a special way that does not involve quitting. This is done
2977 by reading the input with @code{inhibit-quit} bound to @code{t}, and
2978 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
2979 becomes @code{nil} again. This excerpt from the definition of
2980 @code{read-quoted-char} shows how this is done; it also shows that
2981 normal quitting is permitted after the first character of input.
2984 (defun read-quoted-char (&optional prompt)
2985 "@dots{}@var{documentation}@dots{}"
2986 (let ((message-log-max nil) done (first t) (code 0) char)
2988 (let ((inhibit-quit first)
2990 (and prompt (message "%s-" prompt))
2991 (setq char (read-event))
2992 (if inhibit-quit (setq quit-flag nil)))
2993 @r{@dots{}set the variable @code{code}@dots{}})
2998 If this variable is non-@code{nil}, then Emacs quits immediately, unless
2999 @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
3000 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
3003 @defvar inhibit-quit
3004 This variable determines whether Emacs should quit when @code{quit-flag}
3005 is set to a value other than @code{nil}. If @code{inhibit-quit} is
3006 non-@code{nil}, then @code{quit-flag} has no special effect.
3009 @defmac with-local-quit body@dots{}
3010 This macro executes @var{body} forms in sequence, but allows quitting, at
3011 least locally, within @var{body} even if @code{inhibit-quit} was
3012 non-@code{nil} outside this construct. It returns the value of the
3013 last form in @var{body}, unless exited by quitting, in which case
3014 it returns @code{nil}.
3016 If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit},
3017 it only executes the @var{body}, and setting @code{quit-flag} causes
3018 a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so
3019 that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag}
3020 triggers a special kind of local quit. This ends the execution of
3021 @var{body} and exits the @code{with-local-quit} body with
3022 @code{quit-flag} still non-@code{nil}, so that another (ordinary) quit
3023 will happen as soon as that is allowed. If @code{quit-flag} is
3024 already non-@code{nil} at the beginning of @var{body}, the local quit
3025 happens immediately and the body doesn't execute at all.
3027 This macro is mainly useful in functions that can be called from
3028 timers, process filters, process sentinels, @code{pre-command-hook},
3029 @code{post-command-hook}, and other places where @code{inhibit-quit} is
3030 normally bound to @code{t}.
3033 @deffn Command keyboard-quit
3034 This function signals the @code{quit} condition with @code{(signal 'quit
3035 nil)}. This is the same thing that quitting does. (See @code{signal}
3039 You can specify a character other than @kbd{C-g} to use for quitting.
3040 See the function @code{set-input-mode} in @ref{Terminal Input}.
3042 @node Prefix Command Arguments
3043 @section Prefix Command Arguments
3044 @cindex prefix argument
3045 @cindex raw prefix argument
3046 @cindex numeric prefix argument
3048 Most Emacs commands can use a @dfn{prefix argument}, a number
3049 specified before the command itself. (Don't confuse prefix arguments
3050 with prefix keys.) The prefix argument is at all times represented by a
3051 value, which may be @code{nil}, meaning there is currently no prefix
3052 argument. Each command may use the prefix argument or ignore it.
3054 There are two representations of the prefix argument: @dfn{raw} and
3055 @dfn{numeric}. The editor command loop uses the raw representation
3056 internally, and so do the Lisp variables that store the information, but
3057 commands can request either representation.
3059 Here are the possible values of a raw prefix argument:
3063 @code{nil}, meaning there is no prefix argument. Its numeric value is
3064 1, but numerous commands make a distinction between @code{nil} and the
3068 An integer, which stands for itself.
3071 A list of one element, which is an integer. This form of prefix
3072 argument results from one or a succession of @kbd{C-u}s with no
3073 digits. The numeric value is the integer in the list, but some
3074 commands make a distinction between such a list and an integer alone.
3077 The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was
3078 typed, without following digits. The equivalent numeric value is
3079 @minus{}1, but some commands make a distinction between the integer
3080 @minus{}1 and the symbol @code{-}.
3083 We illustrate these possibilities by calling the following function with
3088 (defun display-prefix (arg)
3089 "Display the value of the raw prefix arg."
3096 Here are the results of calling @code{display-prefix} with various
3097 raw prefix arguments:
3100 M-x display-prefix @print{} nil
3102 C-u M-x display-prefix @print{} (4)
3104 C-u C-u M-x display-prefix @print{} (16)
3106 C-u 3 M-x display-prefix @print{} 3
3108 M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
3110 C-u - M-x display-prefix @print{} -
3112 M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
3114 C-u - 7 M-x display-prefix @print{} -7
3116 M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
3119 Emacs uses two variables to store the prefix argument:
3120 @code{prefix-arg} and @code{current-prefix-arg}. Commands such as
3121 @code{universal-argument} that set up prefix arguments for other
3122 commands store them in @code{prefix-arg}. In contrast,
3123 @code{current-prefix-arg} conveys the prefix argument to the current
3124 command, so setting it has no effect on the prefix arguments for future
3127 Normally, commands specify which representation to use for the prefix
3128 argument, either numeric or raw, in the @code{interactive} specification.
3129 (@xref{Using Interactive}.) Alternatively, functions may look at the
3130 value of the prefix argument directly in the variable
3131 @code{current-prefix-arg}, but this is less clean.
3133 @defun prefix-numeric-value arg
3134 This function returns the numeric meaning of a valid raw prefix argument
3135 value, @var{arg}. The argument may be a symbol, a number, or a list.
3136 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
3137 value @minus{}1 is returned; if it is a number, that number is returned;
3138 if it is a list, the @sc{car} of that list (which should be a number) is
3142 @defvar current-prefix-arg
3143 This variable holds the raw prefix argument for the @emph{current}
3144 command. Commands may examine it directly, but the usual method for
3145 accessing it is with @code{(interactive "P")}.
3149 The value of this variable is the raw prefix argument for the
3150 @emph{next} editing command. Commands such as @code{universal-argument}
3151 that specify prefix arguments for the following command work by setting
3155 @defvar last-prefix-arg
3156 The raw prefix argument value used by the previous command.
3159 The following commands exist to set up prefix arguments for the
3160 following command. Do not call them for any other reason.
3162 @deffn Command universal-argument
3163 This command reads input and specifies a prefix argument for the
3164 following command. Don't call this command yourself unless you know
3168 @deffn Command digit-argument arg
3169 This command adds to the prefix argument for the following command. The
3170 argument @var{arg} is the raw prefix argument as it was before this
3171 command; it is used to compute the updated prefix argument. Don't call
3172 this command yourself unless you know what you are doing.
3175 @deffn Command negative-argument arg
3176 This command adds to the numeric argument for the next command. The
3177 argument @var{arg} is the raw prefix argument as it was before this
3178 command; its value is negated to form the new prefix argument. Don't
3179 call this command yourself unless you know what you are doing.
3182 @node Recursive Editing
3183 @section Recursive Editing
3184 @cindex recursive command loop
3185 @cindex recursive editing level
3186 @cindex command loop, recursive
3188 The Emacs command loop is entered automatically when Emacs starts up.
3189 This top-level invocation of the command loop never exits; it keeps
3190 running as long as Emacs does. Lisp programs can also invoke the
3191 command loop. Since this makes more than one activation of the command
3192 loop, we call it @dfn{recursive editing}. A recursive editing level has
3193 the effect of suspending whatever command invoked it and permitting the
3194 user to do arbitrary editing before resuming that command.
3196 The commands available during recursive editing are the same ones
3197 available in the top-level editing loop and defined in the keymaps.
3198 Only a few special commands exit the recursive editing level; the others
3199 return to the recursive editing level when they finish. (The special
3200 commands for exiting are always available, but they do nothing when
3201 recursive editing is not in progress.)
3203 All command loops, including recursive ones, set up all-purpose error
3204 handlers so that an error in a command run from the command loop will
3207 @cindex minibuffer input
3208 Minibuffer input is a special kind of recursive editing. It has a few
3209 special wrinkles, such as enabling display of the minibuffer and the
3210 minibuffer window, but fewer than you might suppose. Certain keys
3211 behave differently in the minibuffer, but that is only because of the
3212 minibuffer's local map; if you switch windows, you get the usual Emacs
3215 @cindex @code{throw} example
3217 @cindex exit recursive editing
3219 To invoke a recursive editing level, call the function
3220 @code{recursive-edit}. This function contains the command loop; it also
3221 contains a call to @code{catch} with tag @code{exit}, which makes it
3222 possible to exit the recursive editing level by throwing to @code{exit}
3223 (@pxref{Catch and Throw}). If you throw a value other than @code{t},
3224 then @code{recursive-edit} returns normally to the function that called
3225 it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
3226 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
3227 control returns to the command loop one level up. This is called
3228 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
3230 Most applications should not use recursive editing, except as part of
3231 using the minibuffer. Usually it is more convenient for the user if you
3232 change the major mode of the current buffer temporarily to a special
3233 major mode, which should have a command to go back to the previous mode.
3234 (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
3235 give the user different text to edit ``recursively'', create and select
3236 a new buffer in a special mode. In this mode, define a command to
3237 complete the processing and go back to the previous buffer. (The
3238 @kbd{m} command in Rmail does this.)
3240 Recursive edits are useful in debugging. You can insert a call to
3241 @code{debug} into a function definition as a sort of breakpoint, so that
3242 you can look around when the function gets there. @code{debug} invokes
3243 a recursive edit but also provides the other features of the debugger.
3245 Recursive editing levels are also used when you type @kbd{C-r} in
3246 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
3248 @deffn Command recursive-edit
3249 @cindex suspend evaluation
3250 This function invokes the editor command loop. It is called
3251 automatically by the initialization of Emacs, to let the user begin
3252 editing. When called from a Lisp program, it enters a recursive editing
3255 If the current buffer is not the same as the selected window's buffer,
3256 @code{recursive-edit} saves and restores the current buffer. Otherwise,
3257 if you switch buffers, the buffer you switched to is current after
3258 @code{recursive-edit} returns.
3260 In the following example, the function @code{simple-rec} first
3261 advances point one word, then enters a recursive edit, printing out a
3262 message in the echo area. The user can then do any editing desired, and
3263 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
3266 (defun simple-rec ()
3268 (message "Recursive edit in progress")
3271 @result{} simple-rec
3277 @deffn Command exit-recursive-edit
3278 This function exits from the innermost recursive edit (including
3279 minibuffer input). Its definition is effectively @code{(throw 'exit
3283 @deffn Command abort-recursive-edit
3284 This function aborts the command that requested the innermost recursive
3285 edit (including minibuffer input), by signaling @code{quit}
3286 after exiting the recursive edit. Its definition is effectively
3287 @code{(throw 'exit t)}. @xref{Quitting}.
3290 @deffn Command top-level
3291 This function exits all recursive editing levels; it does not return a
3292 value, as it jumps completely out of any computation directly back to
3293 the main command loop.
3296 @defun recursion-depth
3297 This function returns the current depth of recursive edits. When no
3298 recursive edit is active, it returns 0.
3301 @node Disabling Commands
3302 @section Disabling Commands
3303 @cindex disabled command
3305 @dfn{Disabling a command} marks the command as requiring user
3306 confirmation before it can be executed. Disabling is used for commands
3307 which might be confusing to beginning users, to prevent them from using
3308 the commands by accident.
3311 The low-level mechanism for disabling a command is to put a
3312 non-@code{nil} @code{disabled} property on the Lisp symbol for the
3313 command. These properties are normally set up by the user's
3314 init file (@pxref{Init File}) with Lisp expressions such as this:
3317 (put 'upcase-region 'disabled t)
3321 For a few commands, these properties are present by default (you can
3322 remove them in your init file if you wish).
3324 If the value of the @code{disabled} property is a string, the message
3325 saying the command is disabled includes that string. For example:
3328 (put 'delete-region 'disabled
3329 "Text deleted this way cannot be yanked back!\n")
3332 @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on
3333 what happens when a disabled command is invoked interactively.
3334 Disabling a command has no effect on calling it as a function from Lisp
3337 @deffn Command enable-command command
3338 Allow @var{command} (a symbol) to be executed without special
3339 confirmation from now on, and alter the user's init file (@pxref{Init
3340 File}) so that this will apply to future sessions.
3343 @deffn Command disable-command command
3344 Require special confirmation to execute @var{command} from now on, and
3345 alter the user's init file so that this will apply to future sessions.
3348 @defvar disabled-command-function
3349 The value of this variable should be a function. When the user
3350 invokes a disabled command interactively, this function is called
3351 instead of the disabled command. It can use @code{this-command-keys}
3352 to determine what the user typed to run the command, and thus find the
3355 The value may also be @code{nil}. Then all commands work normally,
3358 By default, the value is a function that asks the user whether to
3362 @node Command History
3363 @section Command History
3364 @cindex command history
3365 @cindex complex command
3366 @cindex history of commands
3368 The command loop keeps a history of the complex commands that have
3369 been executed, to make it convenient to repeat these commands. A
3370 @dfn{complex command} is one for which the interactive argument reading
3371 uses the minibuffer. This includes any @kbd{M-x} command, any
3372 @kbd{M-:} command, and any command whose @code{interactive}
3373 specification reads an argument from the minibuffer. Explicit use of
3374 the minibuffer during the execution of the command itself does not cause
3375 the command to be considered complex.
3377 @defvar command-history
3378 This variable's value is a list of recent complex commands, each
3379 represented as a form to evaluate. It continues to accumulate all
3380 complex commands for the duration of the editing session, but when it
3381 reaches the maximum size (@pxref{Minibuffer History}), the oldest
3382 elements are deleted as new ones are added.
3387 @result{} ((switch-to-buffer "chistory.texi")
3388 (describe-key "^X^[")
3389 (visit-tags-table "~/emacs/src/")
3390 (find-tag "repeat-complex-command"))
3395 This history list is actually a special case of minibuffer history
3396 (@pxref{Minibuffer History}), with one special twist: the elements are
3397 expressions rather than strings.
3399 There are a number of commands devoted to the editing and recall of
3400 previous commands. The commands @code{repeat-complex-command}, and
3401 @code{list-command-history} are described in the user manual
3402 (@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the
3403 minibuffer, the usual minibuffer history commands are available.
3405 @node Keyboard Macros
3406 @section Keyboard Macros
3407 @cindex keyboard macros
3409 A @dfn{keyboard macro} is a canned sequence of input events that can
3410 be considered a command and made the definition of a key. The Lisp
3411 representation of a keyboard macro is a string or vector containing the
3412 events. Don't confuse keyboard macros with Lisp macros
3415 @defun execute-kbd-macro kbdmacro &optional count loopfunc
3416 This function executes @var{kbdmacro} as a sequence of events. If
3417 @var{kbdmacro} is a string or vector, then the events in it are executed
3418 exactly as if they had been input by the user. The sequence is
3419 @emph{not} expected to be a single key sequence; normally a keyboard
3420 macro definition consists of several key sequences concatenated.
3422 If @var{kbdmacro} is a symbol, then its function definition is used in
3423 place of @var{kbdmacro}. If that is another symbol, this process repeats.
3424 Eventually the result should be a string or vector. If the result is
3425 not a symbol, string, or vector, an error is signaled.
3427 The argument @var{count} is a repeat count; @var{kbdmacro} is executed that
3428 many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is
3429 executed once. If it is 0, @var{kbdmacro} is executed over and over until it
3430 encounters an error or a failing search.
3432 If @var{loopfunc} is non-@code{nil}, it is a function that is called,
3433 without arguments, prior to each iteration of the macro. If
3434 @var{loopfunc} returns @code{nil}, then this stops execution of the macro.
3436 @xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
3439 @defvar executing-kbd-macro
3440 This variable contains the string or vector that defines the keyboard
3441 macro that is currently executing. It is @code{nil} if no macro is
3442 currently executing. A command can test this variable so as to behave
3443 differently when run from an executing macro. Do not set this variable
3447 @defvar defining-kbd-macro
3448 This variable is non-@code{nil} if and only if a keyboard macro is
3449 being defined. A command can test this variable so as to behave
3450 differently while a macro is being defined. The value is
3451 @code{append} while appending to the definition of an existing macro.
3452 The commands @code{start-kbd-macro}, @code{kmacro-start-macro} and
3453 @code{end-kbd-macro} set this variable---do not set it yourself.
3455 The variable is always local to the current terminal and cannot be
3456 buffer-local. @xref{Multiple Terminals}.
3459 @defvar last-kbd-macro
3460 This variable is the definition of the most recently defined keyboard
3461 macro. Its value is a string or vector, or @code{nil}.
3463 The variable is always local to the current terminal and cannot be
3464 buffer-local. @xref{Multiple Terminals}.
3467 @defvar kbd-macro-termination-hook
3468 This normal hook is run when a keyboard macro terminates, regardless
3469 of what caused it to terminate (reaching the macro end or an error
3470 which ended the macro prematurely).