2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
5 @c See the file elisp.texi for copying conditions.
8 @cindex editor command loop
11 When you run Emacs, it enters the @dfn{editor command loop} almost
12 immediately. This loop reads key sequences, executes their definitions,
13 and displays the results. In this chapter, we describe how these things
14 are done, and the subroutines that allow Lisp programs to do them.
17 * Command Overview:: How the command loop reads commands.
18 * Defining Commands:: Specifying how a function should read arguments.
19 * Interactive Call:: Calling a command, so that it will read arguments.
20 * Distinguish Interactive:: Making a command distinguish interactive calls.
21 * Command Loop Info:: Variables set by the command loop for you to examine.
22 * Adjusting Point:: Adjustment of point after a command.
23 * Input Events:: What input looks like when you read it.
24 * Reading Input:: How to read input events from the keyboard or mouse.
25 * Special Events:: Events processed immediately and individually.
26 * Waiting:: Waiting for user input or elapsed time.
27 * Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
28 * Prefix Command Arguments:: How the commands to set prefix args work.
29 * Recursive Editing:: Entering a recursive edit,
30 and why you usually shouldn't.
31 * Disabling Commands:: How the command loop handles disabled commands.
32 * Command History:: How the command history is set up, and how accessed.
33 * Keyboard Macros:: How keyboard macros are implemented.
36 @node Command Overview
37 @section Command Loop Overview
39 The first thing the command loop must do is read a key sequence,
40 which is a sequence of input events that translates into a command.
41 It does this by calling the function @code{read-key-sequence}. Lisp
42 programs can also call this function (@pxref{Key Sequence Input}).
43 They can also read input at a lower level with @code{read-key} or
44 @code{read-event} (@pxref{Reading One Event}), or discard pending
45 input with @code{discard-input} (@pxref{Event Input Misc}).
47 The key sequence is translated into a command through the currently
48 active keymaps. @xref{Key Lookup}, for information on how this is done.
49 The result should be a keyboard macro or an interactively callable
50 function. If the key is @kbd{M-x}, then it reads the name of another
51 command, which it then calls. This is done by the command
52 @code{execute-extended-command} (@pxref{Interactive Call}).
54 Prior to executing the command, Emacs runs @code{undo-boundary} to
55 create an undo boundary. @xref{Maintaining Undo}.
57 To execute a command, Emacs first reads its arguments by calling
58 @code{command-execute} (@pxref{Interactive Call}). For commands
59 written in Lisp, the @code{interactive} specification says how to read
60 the arguments. This may use the prefix argument (@pxref{Prefix
61 Command Arguments}) or may read with prompting in the minibuffer
62 (@pxref{Minibuffers}). For example, the command @code{find-file} has
63 an @code{interactive} specification which says to read a file name
64 using the minibuffer. The function body of @code{find-file} does not
65 use the minibuffer, so if you call @code{find-file} as a function from
66 Lisp code, you must supply the file name string as an ordinary Lisp
69 If the command is a keyboard macro (i.e., a string or vector),
70 Emacs executes it using @code{execute-kbd-macro} (@pxref{Keyboard
73 @defvar pre-command-hook
74 This normal hook is run by the editor command loop before it executes
75 each command. At that time, @code{this-command} contains the command
76 that is about to run, and @code{last-command} describes the previous
77 command. @xref{Command Loop Info}.
80 @defvar post-command-hook
81 This normal hook is run by the editor command loop after it executes
82 each command (including commands terminated prematurely by quitting or
83 by errors). At that time, @code{this-command} refers to the command
84 that just ran, and @code{last-command} refers to the command before
87 This hook is also run when Emacs first enters the command loop (at
88 which point @code{this-command} and @code{last-command} are both
92 Quitting is suppressed while running @code{pre-command-hook} and
93 @code{post-command-hook}. If an error happens while executing one of
94 these hooks, it does not terminate execution of the hook; instead
95 the error is silenced and the function in which the error occurred
96 is removed from the hook.
98 A request coming into the Emacs server (@pxref{Emacs Server,,,
99 emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard
102 @node Defining Commands
103 @section Defining Commands
104 @cindex defining commands
105 @cindex commands, defining
106 @cindex functions, making them interactive
107 @cindex interactive function
109 The special form @code{interactive} turns a Lisp function into a
110 command. The @code{interactive} form must be located at top-level in
111 the function body, usually as the first form in the body; this applies
112 to both lambda expressions (@pxref{Lambda Expressions}) and
113 @code{defun} forms (@pxref{Defining Functions}). This form does
114 nothing during the actual execution of the function; its presence
115 serves as a flag, telling the Emacs command loop that the function can
116 be called interactively. The argument of the @code{interactive} form
117 specifies how the arguments for an interactive call should be read.
119 @cindex @code{interactive-form} property
120 Alternatively, an @code{interactive} form may be specified in a
121 function symbol's @code{interactive-form} property. A non-@code{nil}
122 value for this property takes precedence over any @code{interactive}
123 form in the function body itself. This feature is seldom used.
125 @cindex @code{interactive-only} property
126 Sometimes, a function is only intended to be called interactively,
127 never directly from Lisp. In that case, give the function a
128 non-@code{nil} @code{interactive-only} property. This causes the
129 byte compiler to warn if the command is called from Lisp. The value
130 of the property can be: a string, which the byte-compiler will
131 use directly in its warning (it should end with a period,
132 and not start with a capital, e.g. ``use @dots{} instead.''); @code{t};
133 any other symbol, which should be an alternative function to use in
137 * Using Interactive:: General rules for @code{interactive}.
138 * Interactive Codes:: The standard letter-codes for reading arguments
140 * Interactive Examples:: Examples of how to read interactive arguments.
141 * Generic Commands:: Select among command alternatives.
144 @node Using Interactive
145 @subsection Using @code{interactive}
146 @cindex arguments, interactive entry
147 @cindex interactive spec, using
149 This section describes how to write the @code{interactive} form that
150 makes a Lisp function an interactively-callable command, and how to
151 examine a command's @code{interactive} form.
153 @defspec interactive arg-descriptor
154 This special form declares that a function is a command, and that it
155 may therefore be called interactively (via @kbd{M-x} or by entering a
156 key sequence bound to it). The argument @var{arg-descriptor} declares
157 how to compute the arguments to the command when the command is called
160 A command may be called from Lisp programs like any other function, but
161 then the caller supplies the arguments and @var{arg-descriptor} has no
164 @cindex @code{interactive-form}, symbol property
165 The @code{interactive} form must be located at top-level in the
166 function body, or in the function symbol's @code{interactive-form}
167 property (@pxref{Symbol Properties}). It has its effect because the
168 command loop looks for it before calling the function
169 (@pxref{Interactive Call}). Once the function is called, all its body
170 forms are executed; at this time, if the @code{interactive} form
171 occurs within the body, the form simply returns @code{nil} without
172 even evaluating its argument.
174 By convention, you should put the @code{interactive} form in the
175 function body, as the first top-level form. If there is an
176 @code{interactive} form in both the @code{interactive-form} symbol
177 property and the function body, the former takes precedence. The
178 @code{interactive-form} symbol property can be used to add an
179 interactive form to an existing function, or change how its arguments
180 are processed interactively, without redefining the function.
183 There are three possibilities for the argument @var{arg-descriptor}:
187 It may be omitted or @code{nil}; then the command is called with no
188 arguments. This leads quickly to an error if the command requires one
192 It may be a string; its contents are a sequence of elements separated
193 by newlines, one for each argument@footnote{Some elements actually
194 supply two arguments.}. Each element consists of a code character
195 (@pxref{Interactive Codes}) optionally followed by a prompt (which
196 some code characters use and some ignore). Here is an example:
199 (interactive "P\nbFrobnicate buffer: ")
203 The code letter @samp{P} sets the command's first argument to the raw
204 command prefix (@pxref{Prefix Command Arguments}). @samp{bFrobnicate
205 buffer: } prompts the user with @samp{Frobnicate buffer: } to enter
206 the name of an existing buffer, which becomes the second and final
209 The prompt string can use @samp{%} to include previous argument values
210 (starting with the first argument) in the prompt. This is done using
211 @code{format} (@pxref{Formatting Strings}). For example, here is how
212 you could read the name of an existing buffer followed by a new name to
217 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
221 @cindex @samp{*} in @code{interactive}
222 @cindex read-only buffers in interactive
223 If @samp{*} appears at the beginning of the string, then an error is
224 signaled if the buffer is read-only.
226 @cindex @samp{@@} in @code{interactive}
227 If @samp{@@} appears at the beginning of the string, and if the key
228 sequence used to invoke the command includes any mouse events, then
229 the window associated with the first of those events is selected
230 before the command is run.
232 @cindex @samp{^} in @code{interactive}
233 @cindex shift-selection, and @code{interactive} spec
234 If @samp{^} appears at the beginning of the string, and if the command
235 was invoked through @dfn{shift-translation}, set the mark and activate
236 the region temporarily, or extend an already active region, before the
237 command is run. If the command was invoked without shift-translation,
238 and the region is temporarily active, deactivate the region before the
239 command is run. Shift-translation is controlled on the user level by
240 @code{shift-select-mode}; see @ref{Shift Selection,,, emacs, The GNU
243 You can use @samp{*}, @samp{@@}, and @code{^} together; the order does
244 not matter. Actual reading of arguments is controlled by the rest of
245 the prompt string (starting with the first character that is not
246 @samp{*}, @samp{@@}, or @samp{^}).
249 It may be a Lisp expression that is not a string; then it should be a
250 form that is evaluated to get a list of arguments to pass to the
251 command. Usually this form will call various functions to read input
252 from the user, most often through the minibuffer (@pxref{Minibuffers})
253 or directly from the keyboard (@pxref{Reading Input}).
255 Providing point or the mark as an argument value is also common, but
256 if you do this @emph{and} read input (whether using the minibuffer or
257 not), be sure to get the integer values of point or the mark after
258 reading. The current buffer may be receiving subprocess output; if
259 subprocess output arrives while the command is waiting for input, it
260 could relocate point and the mark.
262 Here's an example of what @emph{not} to do:
266 (list (region-beginning) (region-end)
267 (read-string "Foo: " nil 'my-history)))
271 Here's how to avoid the problem, by examining point and the mark after
272 reading the keyboard input:
276 (let ((string (read-string "Foo: " nil 'my-history)))
277 (list (region-beginning) (region-end) string)))
280 @strong{Warning:} the argument values should not include any data
281 types that can't be printed and then read. Some facilities save
282 @code{command-history} in a file to be read in the subsequent
283 sessions; if a command's arguments contain a data type that prints
284 using @samp{#<@dots{}>} syntax, those facilities won't work.
286 There are, however, a few exceptions: it is ok to use a limited set of
287 expressions such as @code{(point)}, @code{(mark)},
288 @code{(region-beginning)}, and @code{(region-end)}, because Emacs
289 recognizes them specially and puts the expression (rather than its
290 value) into the command history. To see whether the expression you
291 wrote is one of these exceptions, run the command, then examine
292 @code{(car command-history)}.
295 @cindex examining the @code{interactive} form
296 @defun interactive-form function
297 This function returns the @code{interactive} form of @var{function}.
298 If @var{function} is an interactively callable function
299 (@pxref{Interactive Call}), the value is the command's
300 @code{interactive} form @code{(interactive @var{spec})}, which
301 specifies how to compute its arguments. Otherwise, the value is
302 @code{nil}. If @var{function} is a symbol, its function definition is
306 @node Interactive Codes
307 @subsection Code Characters for @code{interactive}
308 @cindex interactive code description
309 @cindex description for interactive codes
310 @cindex codes, interactive, description of
311 @cindex characters for interactive codes
313 The code character descriptions below contain a number of key words,
314 defined here as follows:
318 @cindex interactive completion
319 Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name
320 completion because the argument is read using @code{completing-read}
321 (@pxref{Completion}). @kbd{?} displays a list of possible completions.
324 Require the name of an existing object. An invalid name is not
325 accepted; the commands to exit the minibuffer do not exit if the current
329 @cindex default argument string
330 A default value of some sort is used if the user enters no text in the
331 minibuffer. The default depends on the code character.
334 This code letter computes an argument without reading any input.
335 Therefore, it does not use a prompt string, and any prompt string you
338 Even though the code letter doesn't use a prompt string, you must follow
339 it with a newline if it is not the last code character in the string.
342 A prompt immediately follows the code character. The prompt ends either
343 with the end of the string or with a newline.
346 This code character is meaningful only at the beginning of the
347 interactive string, and it does not look for a prompt or a newline.
348 It is a single, isolated character.
351 @cindex reading interactive arguments
352 Here are the code character descriptions for use with @code{interactive}:
356 Signal an error if the current buffer is read-only. Special.
359 Select the window mentioned in the first mouse event in the key
360 sequence that invoked this command. Special.
363 If the command was invoked through shift-translation, set the mark and
364 activate the region temporarily, or extend an already active region,
365 before the command is run. If the command was invoked without
366 shift-translation, and the region is temporarily active, deactivate
367 the region before the command is run. Special.
370 A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
374 The name of an existing buffer. By default, uses the name of the
375 current buffer (@pxref{Buffers}). Existing, Completion, Default,
379 A buffer name. The buffer need not exist. By default, uses the name of
380 a recently used buffer other than the current buffer. Completion,
384 A character. The cursor does not move into the echo area. Prompt.
387 A command name (i.e., a symbol satisfying @code{commandp}). Existing,
391 @cindex position argument
392 The position of point, as an integer (@pxref{Point}). No I/O.
395 A directory name. The default is the current default directory of the
396 current buffer, @code{default-directory} (@pxref{File Name Expansion}).
397 Existing, Completion, Default, Prompt.
400 The first or next non-keyboard event in the key sequence that invoked
401 the command. More precisely, @samp{e} gets events that are lists, so
402 you can look at the data in the lists. @xref{Input Events}. No I/O.
404 You use @samp{e} for mouse events and for special system events
405 (@pxref{Misc Events}). The event list that the command receives
406 depends on the event. @xref{Input Events}, which describes the forms
407 of the list for each event in the corresponding subsections.
409 You can use @samp{e} more than once in a single command's interactive
410 specification. If the key sequence that invoked the command has
411 @var{n} events that are lists, the @var{n}th @samp{e} provides the
412 @var{n}th such event. Events that are not lists, such as function keys
413 and @acronym{ASCII} characters, do not count where @samp{e} is concerned.
416 A file name of an existing file (@pxref{File Names}). The default
417 directory is @code{default-directory}. Existing, Completion, Default,
421 A file name. The file need not exist. Completion, Default, Prompt.
424 A file name. The file need not exist. If the user enters just a
425 directory name, then the value is just that directory name, with no
426 file name within the directory added. Completion, Default, Prompt.
429 An irrelevant argument. This code always supplies @code{nil} as
430 the argument's value. No I/O.
433 A key sequence (@pxref{Key Sequences}). This keeps reading events
434 until a command (or undefined command) is found in the current key
435 maps. The key sequence argument is represented as a string or vector.
436 The cursor does not move into the echo area. Prompt.
438 If @samp{k} reads a key sequence that ends with a down-event, it also
439 reads and discards the following up-event. You can get access to that
440 up-event with the @samp{U} code character.
442 This kind of input is used by commands such as @code{describe-key} and
443 @code{global-set-key}.
446 A key sequence, whose definition you intend to change. This works like
447 @samp{k}, except that it suppresses, for the last input event in the key
448 sequence, the conversions that are normally used (when necessary) to
449 convert an undefined key into a defined one.
452 @cindex marker argument
453 The position of the mark, as an integer. No I/O.
456 Arbitrary text, read in the minibuffer using the current buffer's input
457 method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
458 Emacs Manual}). Prompt.
461 A number, read with the minibuffer. If the input is not a number, the
462 user has to try again. @samp{n} never uses the prefix argument.
466 The numeric prefix argument; but if there is no prefix argument, read
467 a number as with @kbd{n}. The value is always a number. @xref{Prefix
468 Command Arguments}. Prompt.
471 @cindex numeric prefix argument usage
472 The numeric prefix argument. (Note that this @samp{p} is lower case.)
476 @cindex raw prefix argument usage
477 The raw prefix argument. (Note that this @samp{P} is upper case.) No
481 @cindex region argument
482 Point and the mark, as two numeric arguments, smallest first. This is
483 the only code letter that specifies two successive arguments rather than
487 Arbitrary text, read in the minibuffer and returned as a string
488 (@pxref{Text from Minibuffer}). Terminate the input with either
489 @kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of
490 these characters in the input.) Prompt.
493 An interned symbol whose name is read in the minibuffer. Terminate
494 the input with either @kbd{C-j} or @key{RET}. Other characters that
495 normally terminate a symbol (e.g., whitespace, parentheses and
496 brackets) do not do so here. Prompt.
499 A key sequence or @code{nil}. Can be used after a @samp{k} or
500 @samp{K} argument to get the up-event that was discarded (if any)
501 after @samp{k} or @samp{K} read a down-event. If no up-event has been
502 discarded, @samp{U} provides @code{nil} as the argument. No I/O.
505 A variable declared to be a user option (i.e., satisfying the
506 predicate @code{custom-variable-p}). This reads the variable using
507 @code{read-variable}. @xref{Definition of read-variable}. Existing,
511 A Lisp object, specified with its read syntax, terminated with a
512 @kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from
516 @cindex evaluated expression argument
517 A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates
518 the form so that its value becomes the argument for the command.
522 A coding system name (a symbol). If the user enters null input, the
523 argument value is @code{nil}. @xref{Coding Systems}. Completion,
527 A coding system name (a symbol)---but only if this command has a prefix
528 argument. With no prefix argument, @samp{Z} provides @code{nil} as the
529 argument value. Completion, Existing, Prompt.
532 @node Interactive Examples
533 @subsection Examples of Using @code{interactive}
534 @cindex examples of using @code{interactive}
535 @cindex @code{interactive}, examples of using
537 Here are some examples of @code{interactive}:
541 (defun foo1 () ; @r{@code{foo1} takes no arguments,}
542 (interactive) ; @r{just moves forward two words.}
548 (defun foo2 (n) ; @r{@code{foo2} takes one argument,}
549 (interactive "^p") ; @r{which is the numeric prefix.}
550 ; @r{under @code{shift-select-mode},}
551 ; @r{will activate or extend region.}
552 (forward-word (* 2 n)))
557 (defun foo3 (n) ; @r{@code{foo3} takes one argument,}
558 (interactive "nCount:") ; @r{which is read with the Minibuffer.}
559 (forward-word (* 2 n)))
564 (defun three-b (b1 b2 b3)
565 "Select three existing buffers.
566 Put them into three windows, selecting the last one."
568 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
569 (delete-other-windows)
570 (split-window (selected-window) 8)
571 (switch-to-buffer b1)
573 (split-window (selected-window) 8)
574 (switch-to-buffer b2)
576 (switch-to-buffer b3))
579 (three-b "*scratch*" "declarations.texi" "*mail*")
584 @node Generic Commands
585 @subsection Select among Command Alternatives
586 @cindex generic commands
587 @cindex alternatives, defining
589 The macro @code{define-alternatives} can be used to define
590 @dfn{generic commands}. These are interactive functions whose
591 implementation can be selected from several alternatives, as a matter
594 @defmac define-alternatives command &rest customizations
595 Define the new command @var{command}, a symbol.
597 When a user runs @kbd{M-x @var{command} @key{RET}} for the first time,
598 Emacs prompts for which real form of the command to use, and records
599 the selection by way of a custom variable. Using a prefix argument
600 repeats this process of choosing an alternative.
602 The variable @code{@var{command}-alternatives} should contain an alist
603 with alternative implementations of @var{command}.
604 Until this variable is set, @code{define-alternatives} has no effect.
606 If @var{customizations} is non-@code{nil}, it should consist of
607 alternating @code{defcustom} keywords (typically @code{:group} and
608 @code{:version}) and values to add to the declaration of
609 @code{@var{command}-alternatives}.
612 @node Interactive Call
613 @section Interactive Call
614 @cindex interactive call
616 After the command loop has translated a key sequence into a command,
617 it invokes that command using the function @code{command-execute}. If
618 the command is a function, @code{command-execute} calls
619 @code{call-interactively}, which reads the arguments and calls the
620 command. You can also call these functions yourself.
622 Note that the term ``command'', in this context, refers to an
623 interactively callable function (or function-like object), or a
624 keyboard macro. It does not refer to the key sequence used to invoke
625 a command (@pxref{Keymaps}).
627 @defun commandp object &optional for-call-interactively
628 This function returns @code{t} if @var{object} is a command.
629 Otherwise, it returns @code{nil}.
631 Commands include strings and vectors (which are treated as keyboard
632 macros), lambda expressions that contain a top-level
633 @code{interactive} form (@pxref{Using Interactive}), byte-code
634 function objects made from such lambda expressions, autoload objects
635 that are declared as interactive (non-@code{nil} fourth argument to
636 @code{autoload}), and some primitive functions. Also, a symbol is
637 considered a command if it has a non-@code{nil}
638 @code{interactive-form} property, or if its function definition
639 satisfies @code{commandp}.
641 If @var{for-call-interactively} is non-@code{nil}, then
642 @code{commandp} returns @code{t} only for objects that
643 @code{call-interactively} could call---thus, not for keyboard macros.
645 See @code{documentation} in @ref{Accessing Documentation}, for a
646 realistic example of using @code{commandp}.
649 @defun call-interactively command &optional record-flag keys
650 This function calls the interactively callable function @var{command},
651 providing arguments according to its interactive calling specifications.
652 It returns whatever @var{command} returns.
654 If, for instance, you have a function with the following signature:
657 (defun foo (begin end)
665 (call-interactively 'foo)
668 will call @code{foo} with the region (@code{point} and @code{mark}) as
671 An error is signaled if @var{command} is not a function or if it
672 cannot be called interactively (i.e., is not a command). Note that
673 keyboard macros (strings and vectors) are not accepted, even though
674 they are considered commands, because they are not functions. If
675 @var{command} is a symbol, then @code{call-interactively} uses its
678 @cindex record command history
679 If @var{record-flag} is non-@code{nil}, then this command and its
680 arguments are unconditionally added to the list @code{command-history}.
681 Otherwise, the command is added only if it uses the minibuffer to read
682 an argument. @xref{Command History}.
684 The argument @var{keys}, if given, should be a vector which specifies
685 the sequence of events to supply if the command inquires which events
686 were used to invoke it. If @var{keys} is omitted or @code{nil}, the
687 default is the return value of @code{this-command-keys-vector}.
688 @xref{Definition of this-command-keys-vector}.
691 @defun command-execute command &optional record-flag keys special
692 @cindex keyboard macro execution
693 This function executes @var{command}. The argument @var{command} must
694 satisfy the @code{commandp} predicate; i.e., it must be an interactively
695 callable function or a keyboard macro.
697 A string or vector as @var{command} is executed with
698 @code{execute-kbd-macro}. A function is passed to
699 @code{call-interactively} (see above), along with the
700 @var{record-flag} and @var{keys} arguments.
702 If @var{command} is a symbol, its function definition is used in its
703 place. A symbol with an @code{autoload} definition counts as a
704 command if it was declared to stand for an interactively callable
705 function. Such a definition is handled by loading the specified
706 library and then rechecking the definition of the symbol.
708 The argument @var{special}, if given, means to ignore the prefix
709 argument and not clear it. This is used for executing special events
710 (@pxref{Special Events}).
713 @deffn Command execute-extended-command prefix-argument
714 @cindex read command name
715 This function reads a command name from the minibuffer using
716 @code{completing-read} (@pxref{Completion}). Then it uses
717 @code{command-execute} to call the specified command. Whatever that
718 command returns becomes the value of @code{execute-extended-command}.
720 @cindex execute with prefix argument
721 If the command asks for a prefix argument, it receives the value
722 @var{prefix-argument}. If @code{execute-extended-command} is called
723 interactively, the current raw prefix argument is used for
724 @var{prefix-argument}, and thus passed on to whatever command is run.
726 @c !!! Should this be @kindex?
728 @code{execute-extended-command} is the normal definition of @kbd{M-x},
729 so it uses the string @w{@samp{M-x }} as a prompt. (It would be better
730 to take the prompt from the events used to invoke
731 @code{execute-extended-command}, but that is painful to implement.) A
732 description of the value of the prefix argument, if any, also becomes
737 (execute-extended-command 3)
738 ---------- Buffer: Minibuffer ----------
739 3 M-x forward-word RET
740 ---------- Buffer: Minibuffer ----------
746 @node Distinguish Interactive
747 @section Distinguish Interactive Calls
748 @cindex distinguish interactive calls
749 @cindex is this call interactive
751 Sometimes a command should display additional visual feedback (such
752 as an informative message in the echo area) for interactive calls
753 only. There are three ways to do this. The recommended way to test
754 whether the function was called using @code{call-interactively} is to
755 give it an optional argument @code{print-message} and use the
756 @code{interactive} spec to make it non-@code{nil} in interactive
757 calls. Here's an example:
760 (defun foo (&optional print-message)
767 We use @code{"p"} because the numeric prefix argument is never
768 @code{nil}. Defined in this way, the function does display the
769 message when called from a keyboard macro.
771 The above method with the additional argument is usually best,
772 because it allows callers to say ``treat this call as interactive''.
773 But you can also do the job by testing @code{called-interactively-p}.
775 @defun called-interactively-p kind
776 This function returns @code{t} when the calling function was called
777 using @code{call-interactively}.
779 The argument @var{kind} should be either the symbol @code{interactive}
780 or the symbol @code{any}. If it is @code{interactive}, then
781 @code{called-interactively-p} returns @code{t} only if the call was
782 made directly by the user---e.g., if the user typed a key sequence
783 bound to the calling function, but @emph{not} if the user ran a
784 keyboard macro that called the function (@pxref{Keyboard Macros}). If
785 @var{kind} is @code{any}, @code{called-interactively-p} returns
786 @code{t} for any kind of interactive call, including keyboard macros.
788 If in doubt, use @code{any}; the only known proper use of
789 @code{interactive} is if you need to decide whether to display a
790 helpful message while a function is running.
792 A function is never considered to be called interactively if it was
793 called via Lisp evaluation (or with @code{apply} or @code{funcall}).
797 Here is an example of using @code{called-interactively-p}:
803 (when (called-interactively-p 'any)
804 (message "Interactive!")
805 'foo-called-interactively))
809 ;; @r{Type @kbd{M-x foo}.}
810 @print{} Interactive!
820 Here is another example that contrasts direct and indirect calls to
821 @code{called-interactively-p}.
827 (message "%s" (list (foo) (called-interactively-p 'any))))
831 ;; @r{Type @kbd{M-x bar}.}
836 @node Command Loop Info
837 @section Information from the Command Loop
838 @cindex command loop variables
840 The editor command loop sets several Lisp variables to keep status
841 records for itself and for commands that are run. With the exception of
842 @code{this-command} and @code{last-command} it's generally a bad idea to
843 change any of these variables in a Lisp program.
846 This variable records the name of the previous command executed by the
847 command loop (the one before the current command). Normally the value
848 is a symbol with a function definition, but this is not guaranteed.
850 The value is copied from @code{this-command} when a command returns to
851 the command loop, except when the command has specified a prefix
852 argument for the following command.
854 This variable is always local to the current terminal and cannot be
855 buffer-local. @xref{Multiple Terminals}.
858 @defvar real-last-command
859 This variable is set up by Emacs just like @code{last-command},
860 but never altered by Lisp programs.
863 @defvar last-repeatable-command
864 This variable stores the most recently executed command that was not
865 part of an input event. This is the command @code{repeat} will try to
866 repeat, @xref{Repeating,,, emacs, The GNU Emacs Manual}.
870 @cindex current command
871 This variable records the name of the command now being executed by
872 the editor command loop. Like @code{last-command}, it is normally a symbol
873 with a function definition.
875 The command loop sets this variable just before running a command, and
876 copies its value into @code{last-command} when the command finishes
877 (unless the command specified a prefix argument for the following
880 @cindex kill command repetition
881 Some commands set this variable during their execution, as a flag for
882 whatever command runs next. In particular, the functions for killing text
883 set @code{this-command} to @code{kill-region} so that any kill commands
884 immediately following will know to append the killed text to the
888 If you do not want a particular command to be recognized as the previous
889 command in the case where it got an error, you must code that command to
890 prevent this. One way is to set @code{this-command} to @code{t} at the
891 beginning of the command, and set @code{this-command} back to its proper
892 value at the end, like this:
895 (defun foo (args@dots{})
896 (interactive @dots{})
897 (let ((old-this-command this-command))
898 (setq this-command t)
899 @r{@dots{}do the work@dots{}}
900 (setq this-command old-this-command)))
904 We do not bind @code{this-command} with @code{let} because that would
905 restore the old value in case of error---a feature of @code{let} which
906 in this case does precisely what we want to avoid.
908 @defvar this-original-command
909 This has the same value as @code{this-command} except when command
910 remapping occurs (@pxref{Remapping Commands}). In that case,
911 @code{this-command} gives the command actually run (the result of
912 remapping), and @code{this-original-command} gives the command that
913 was specified to run but remapped into another command.
916 @defun this-command-keys
917 This function returns a string or vector containing the key sequence
918 that invoked the present command, plus any previous commands that
919 generated the prefix argument for this command. Any events read by the
920 command using @code{read-event} without a timeout get tacked on to the end.
922 However, if the command has called @code{read-key-sequence}, it
923 returns the last read key sequence. @xref{Key Sequence Input}. The
924 value is a string if all events in the sequence were characters that
925 fit in a string. @xref{Input Events}.
930 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
936 @defun this-command-keys-vector
937 @anchor{Definition of this-command-keys-vector}
938 Like @code{this-command-keys}, except that it always returns the events
939 in a vector, so you don't need to deal with the complexities of storing
940 input events in a string (@pxref{Strings of Events}).
943 @defun clear-this-command-keys &optional keep-record
944 This function empties out the table of events for
945 @code{this-command-keys} to return. Unless @var{keep-record} is
946 non-@code{nil}, it also empties the records that the function
947 @code{recent-keys} (@pxref{Recording Input}) will subsequently return.
948 This is useful after reading a password, to prevent the password from
949 echoing inadvertently as part of the next command in certain cases.
952 @defvar last-nonmenu-event
953 This variable holds the last input event read as part of a key sequence,
954 not counting events resulting from mouse menus.
956 One use of this variable is for telling @code{x-popup-menu} where to pop
957 up a menu. It is also used internally by @code{y-or-n-p}
958 (@pxref{Yes-or-No Queries}).
961 @defvar last-command-event
962 This variable is set to the last input event that was read by the
963 command loop as part of a command. The principal use of this variable
964 is in @code{self-insert-command}, which uses it to decide which
970 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
976 The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
979 @defvar last-event-frame
980 This variable records which frame the last input event was directed to.
981 Usually this is the frame that was selected when the event was
982 generated, but if that frame has redirected input focus to another
983 frame, the value is the frame to which the event was redirected.
986 If the last event came from a keyboard macro, the value is @code{macro}.
989 @node Adjusting Point
990 @section Adjusting Point After Commands
991 @cindex adjusting point
992 @cindex invisible/intangible text, and point
993 @cindex @code{display} property, and point display
994 @cindex @code{composition} property, and point display
996 It is not easy to display a value of point in the middle of a
997 sequence of text that has the @code{display}, @code{composition} or
998 is invisible. Therefore, after a command finishes and returns to the
999 command loop, if point is within such a sequence, the command loop
1000 normally moves point to the edge of the sequence.
1002 A command can inhibit this feature by setting the variable
1003 @code{disable-point-adjustment}:
1005 @defvar disable-point-adjustment
1006 If this variable is non-@code{nil} when a command returns to the
1007 command loop, then the command loop does not check for those text
1008 properties, and does not move point out of sequences that have them.
1010 The command loop sets this variable to @code{nil} before each command,
1011 so if a command sets it, the effect applies only to that command.
1014 @defvar global-disable-point-adjustment
1015 If you set this variable to a non-@code{nil} value, the feature of
1016 moving point out of these sequences is completely turned off.
1020 @section Input Events
1022 @cindex input events
1024 The Emacs command loop reads a sequence of @dfn{input events} that
1025 represent keyboard or mouse activity, or system events sent to Emacs.
1026 The events for keyboard activity are characters or symbols; other
1027 events are always lists. This section describes the representation
1028 and meaning of input events in detail.
1030 @defun eventp object
1031 This function returns non-@code{nil} if @var{object} is an input event
1034 Note that any symbol might be used as an event or an event type.
1035 @code{eventp} cannot distinguish whether a symbol is intended by Lisp
1036 code to be used as an event. Instead, it distinguishes whether the
1037 symbol has actually been used in an event that has been read as input in
1038 the current Emacs session. If a symbol has not yet been so used,
1039 @code{eventp} returns @code{nil}.
1043 * Keyboard Events:: Ordinary characters--keys with symbols on them.
1044 * Function Keys:: Function keys--keys with names, not symbols.
1045 * Mouse Events:: Overview of mouse events.
1046 * Click Events:: Pushing and releasing a mouse button.
1047 * Drag Events:: Moving the mouse before releasing the button.
1048 * Button-Down Events:: A button was pushed and not yet released.
1049 * Repeat Events:: Double and triple click (or drag, or down).
1050 * Motion Events:: Just moving the mouse, not pushing a button.
1051 * Focus Events:: Moving the mouse between frames.
1052 * Misc Events:: Other events the system can generate.
1053 * Event Examples:: Examples of the lists for mouse events.
1054 * Classifying Events:: Finding the modifier keys in an event symbol.
1056 * Accessing Mouse:: Functions to extract info from mouse events.
1057 * Accessing Scroll:: Functions to get info from scroll bar events.
1058 * Strings of Events:: Special considerations for putting
1059 keyboard character events in a string.
1062 @node Keyboard Events
1063 @subsection Keyboard Events
1064 @cindex keyboard events
1066 There are two kinds of input you can get from the keyboard: ordinary
1067 keys, and function keys. Ordinary keys correspond to characters; the
1068 events they generate are represented in Lisp as characters. The event
1069 type of a character event is the character itself (an integer); see
1070 @ref{Classifying Events}.
1072 @cindex modifier bits (of input character)
1073 @cindex basic code (of input character)
1074 An input character event consists of a @dfn{basic code} between 0 and
1075 524287, plus any or all of these @dfn{modifier bits}:
1086 bit in the character code indicates a character
1087 typed with the meta key held down.
1097 bit in the character code indicates a non-@acronym{ASCII}
1100 @sc{ascii} control characters such as @kbd{C-a} have special basic
1101 codes of their own, so Emacs needs no special bit to indicate them.
1102 Thus, the code for @kbd{C-a} is just 1.
1104 But if you type a control combination not in @acronym{ASCII}, such as
1105 @kbd{%} with the control key, the numeric value you get is the code
1113 (assuming the terminal supports non-@acronym{ASCII}
1114 control characters).
1124 bit in the character code indicates an @acronym{ASCII} control
1125 character typed with the shift key held down.
1127 For letters, the basic code itself indicates upper versus lower case;
1128 for digits and punctuation, the shift key selects an entirely different
1129 character with a different basic code. In order to keep within the
1130 @acronym{ASCII} character set whenever possible, Emacs avoids using the
1137 bit for those characters.
1139 However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
1140 @kbd{C-a}, so Emacs uses the
1147 bit in @kbd{C-A} and not in
1158 bit in the character code indicates a character
1159 typed with the hyper key held down.
1169 bit in the character code indicates a character
1170 typed with the super key held down.
1180 bit in the character code indicates a character typed with the alt key
1181 held down. (The key labeled @key{Alt} on most keyboards is actually
1182 treated as the meta key, not this.)
1185 It is best to avoid mentioning specific bit numbers in your program.
1186 To test the modifier bits of a character, use the function
1187 @code{event-modifiers} (@pxref{Classifying Events}). When making key
1188 bindings, you can use the read syntax for characters with modifier bits
1189 (@samp{\C-}, @samp{\M-}, and so on). For making key bindings with
1190 @code{define-key}, you can use lists such as @code{(control hyper ?x)} to
1191 specify the characters (@pxref{Changing Key Bindings}). The function
1192 @code{event-convert-list} converts such a list into an event type
1193 (@pxref{Classifying Events}).
1196 @subsection Function Keys
1198 @cindex function keys
1199 Most keyboards also have @dfn{function keys}---keys that have names or
1200 symbols that are not characters. Function keys are represented in
1201 Emacs Lisp as symbols; the symbol's name is the function key's label,
1202 in lower case. For example, pressing a key labeled @key{F1} generates
1203 an input event represented by the symbol @code{f1}.
1205 The event type of a function key event is the event symbol itself.
1206 @xref{Classifying Events}.
1208 Here are a few special cases in the symbol-naming convention for
1212 @item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
1213 These keys correspond to common @acronym{ASCII} control characters that have
1214 special keys on most keyboards.
1216 In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the
1217 terminal can distinguish between them, Emacs conveys the distinction to
1218 Lisp programs by representing the former as the integer 9, and the
1219 latter as the symbol @code{tab}.
1221 Most of the time, it's not useful to distinguish the two. So normally
1222 @code{local-function-key-map} (@pxref{Translation Keymaps}) is set up
1223 to map @code{tab} into 9. Thus, a key binding for character code 9
1224 (the character @kbd{C-i}) also applies to @code{tab}. Likewise for
1225 the other symbols in this group. The function @code{read-char}
1226 likewise converts these events into characters.
1228 In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace}
1229 converts into the character code 127 (@key{DEL}), not into code 8
1230 (@key{BS}). This is what most users prefer.
1232 @item @code{left}, @code{up}, @code{right}, @code{down}
1234 @item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
1235 Keypad keys (to the right of the regular keyboard).
1236 @item @code{kp-0}, @code{kp-1}, @dots{}
1237 Keypad keys with digits.
1238 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
1240 @item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
1241 Keypad arrow keys. Emacs normally translates these into the
1242 corresponding non-keypad keys @code{home}, @code{left}, @dots{}
1243 @item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
1244 Additional keypad duplicates of keys ordinarily found elsewhere. Emacs
1245 normally translates these into the like-named non-keypad keys.
1248 You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
1249 @key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to
1250 represent them is with prefixes in the symbol name:
1256 The control modifier.
1267 Thus, the symbol for the key @key{F3} with @key{META} held down is
1268 @code{M-f3}. When you use more than one prefix, we recommend you
1269 write them in alphabetical order; but the order does not matter in
1270 arguments to the key-binding lookup and modification functions.
1273 @subsection Mouse Events
1275 Emacs supports four kinds of mouse events: click events, drag events,
1276 button-down events, and motion events. All mouse events are represented
1277 as lists. The @sc{car} of the list is the event type; this says which
1278 mouse button was involved, and which modifier keys were used with it.
1279 The event type can also distinguish double or triple button presses
1280 (@pxref{Repeat Events}). The rest of the list elements give position
1281 and time information.
1283 For key lookup, only the event type matters: two events of the same type
1284 necessarily run the same command. The command can access the full
1285 values of these events using the @samp{e} interactive code.
1286 @xref{Interactive Codes}.
1288 A key sequence that starts with a mouse event is read using the keymaps
1289 of the buffer in the window that the mouse was in, not the current
1290 buffer. This does not imply that clicking in a window selects that
1291 window or its buffer---that is entirely under the control of the command
1292 binding of the key sequence.
1295 @subsection Click Events
1297 @cindex mouse click event
1299 When the user presses a mouse button and releases it at the same
1300 location, that generates a @dfn{click} event. All mouse click event
1301 share the same format:
1304 (@var{event-type} @var{position} @var{click-count})
1308 @item @var{event-type}
1309 This is a symbol that indicates which mouse button was used. It is
1310 one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the
1311 buttons are numbered left to right.
1313 You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-},
1314 @samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift
1315 and super, just as you would with function keys.
1317 This symbol also serves as the event type of the event. Key bindings
1318 describe events by their types; thus, if there is a key binding for
1319 @code{mouse-1}, that binding would apply to all events whose
1320 @var{event-type} is @code{mouse-1}.
1322 @item @var{position}
1323 @cindex mouse position list
1324 This is a @dfn{mouse position list} specifying where the mouse click
1325 occurred; see below for details.
1327 @item @var{click-count}
1328 This is the number of rapid repeated presses so far of the same mouse
1329 button. @xref{Repeat Events}.
1332 To access the contents of a mouse position list in the
1333 @var{position} slot of a click event, you should typically use the
1334 functions documented in @ref{Accessing Mouse}. The explicit format of
1335 the list depends on where the click occurred. For clicks in the text
1336 area, mode line, header line, or in the fringe or marginal areas, the
1337 mouse position list has the form
1340 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
1341 @var{object} @var{text-pos} (@var{col} . @var{row})
1342 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
1346 The meanings of these list elements are as follows:
1350 The window in which the click occurred.
1352 @item @var{pos-or-area}
1353 The buffer position of the character clicked on in the text area; or,
1354 if the click was outside the text area, the window area where it
1355 occurred. It is one of the symbols @code{mode-line},
1356 @code{header-line}, @code{vertical-line}, @code{left-margin},
1357 @code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
1359 In one special case, @var{pos-or-area} is a list containing a symbol
1360 (one of the symbols listed above) instead of just the symbol. This
1361 happens after the imaginary prefix keys for the event are registered
1362 by Emacs. @xref{Key Sequence Input}.
1364 @item @var{x}, @var{y}
1365 The relative pixel coordinates of the click. For clicks in the text
1366 area of a window, the coordinate origin @code{(0 . 0)} is taken to be
1367 the top left corner of the text area. @xref{Window Sizes}. For
1368 clicks in a mode line or header line, the coordinate origin is the top
1369 left corner of the window itself. For fringes, margins, and the
1370 vertical border, @var{x} does not have meaningful data. For fringes
1371 and margins, @var{y} is relative to the bottom edge of the header
1372 line. In all cases, the @var{x} and @var{y} coordinates increase
1373 rightward and downward respectively.
1375 @item @var{timestamp}
1376 The time at which the event occurred, as an integer number of
1377 milliseconds since a system-dependent initial time.
1380 Either @code{nil} if there is no string-type text property at the
1381 click position, or a cons cell of the form (@var{string}
1382 . @var{string-pos}) if there is one:
1386 The string which was clicked on, including any properties.
1388 @item @var{string-pos}
1389 The position in the string where the click occurred.
1392 @item @var{text-pos}
1393 For clicks on a marginal area or on a fringe, this is the buffer
1394 position of the first visible character in the corresponding line in
1395 the window. For other events, it is the current buffer position in
1398 @item @var{col}, @var{row}
1399 These are the actual column and row coordinate numbers of the glyph
1400 under the @var{x}, @var{y} position. If @var{x} lies beyond the last
1401 column of actual text on its line, @var{col} is reported by adding
1402 fictional extra columns that have the default character width. Row 0
1403 is taken to be the header line if the window has one, or the topmost
1404 row of the text area otherwise. Column 0 is taken to be the leftmost
1405 column of the text area for clicks on a window text area, or the
1406 leftmost mode line or header line column for clicks there. For clicks
1407 on fringes or vertical borders, these have no meaningful data. For
1408 clicks on margins, @var{col} is measured from the left edge of the
1409 margin area and @var{row} is measured from the top of the margin area.
1412 This is the image object on which the click occurred. It is either
1413 @code{nil} if there is no image at the position clicked on, or it is
1414 an image object as returned by @code{find-image} if click was in an image.
1416 @item @var{dx}, @var{dy}
1417 These are the pixel coordinates of the click, relative to
1418 the top left corner of @var{object}, which is @code{(0 . 0)}. If
1419 @var{object} is @code{nil}, the coordinates are relative to the top
1420 left corner of the character glyph clicked on.
1422 @item @var{width}, @var{height}
1423 These are the pixel width and height of @var{object} or, if this is
1424 @code{nil}, those of the character glyph clicked on.
1427 For clicks on a scroll bar, @var{position} has this form:
1430 (@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
1435 The window whose scroll bar was clicked on.
1438 This is the symbol @code{vertical-scroll-bar}.
1441 The number of pixels from the top of the scroll bar to the click
1442 position. On some toolkits, including GTK+, Emacs cannot extract this
1443 data, so the value is always @code{0}.
1446 The total length, in pixels, of the scroll bar. On some toolkits,
1447 including GTK+, Emacs cannot extract this data, so the value is always
1450 @item @var{timestamp}
1451 The time at which the event occurred, in milliseconds. On some
1452 toolkits, including GTK+, Emacs cannot extract this data, so the value
1456 The part of the scroll bar on which the click occurred. It is one of
1457 the symbols @code{handle} (the scroll bar handle), @code{above-handle}
1458 (the area above the handle), @code{below-handle} (the area below the
1459 handle), @code{up} (the up arrow at one end of the scroll bar), or
1460 @code{down} (the down arrow at one end of the scroll bar).
1461 @c The `top', `bottom', and `end-scroll' codes don't seem to be used.
1466 @subsection Drag Events
1468 @cindex mouse drag event
1470 With Emacs, you can have a drag event without even changing your
1471 clothes. A @dfn{drag event} happens every time the user presses a mouse
1472 button and then moves the mouse to a different character position before
1473 releasing the button. Like all mouse events, drag events are
1474 represented in Lisp as lists. The lists record both the starting mouse
1475 position and the final position, like this:
1479 (@var{window1} START-POSITION)
1480 (@var{window2} END-POSITION))
1483 For a drag event, the name of the symbol @var{event-type} contains the
1484 prefix @samp{drag-}. For example, dragging the mouse with button 2
1485 held down generates a @code{drag-mouse-2} event. The second and third
1486 elements of the event give the starting and ending position of the
1487 drag, as mouse position lists (@pxref{Click Events}). You can access
1488 the second element of any mouse event in the same way, with no need to
1489 distinguish drag events from others.
1491 The @samp{drag-} prefix follows the modifier key prefixes such as
1492 @samp{C-} and @samp{M-}.
1494 If @code{read-key-sequence} receives a drag event that has no key
1495 binding, and the corresponding click event does have a binding, it
1496 changes the drag event into a click event at the drag's starting
1497 position. This means that you don't have to distinguish between click
1498 and drag events unless you want to.
1500 @node Button-Down Events
1501 @subsection Button-Down Events
1502 @cindex button-down event
1504 Click and drag events happen when the user releases a mouse button.
1505 They cannot happen earlier, because there is no way to distinguish a
1506 click from a drag until the button is released.
1508 If you want to take action as soon as a button is pressed, you need to
1509 handle @dfn{button-down} events.@footnote{Button-down is the
1510 conservative antithesis of drag.} These occur as soon as a button is
1511 pressed. They are represented by lists that look exactly like click
1512 events (@pxref{Click Events}), except that the @var{event-type} symbol
1513 name contains the prefix @samp{down-}. The @samp{down-} prefix follows
1514 modifier key prefixes such as @samp{C-} and @samp{M-}.
1516 The function @code{read-key-sequence} ignores any button-down events
1517 that don't have command bindings; therefore, the Emacs command loop
1518 ignores them too. This means that you need not worry about defining
1519 button-down events unless you want them to do something. The usual
1520 reason to define a button-down event is so that you can track mouse
1521 motion (by reading motion events) until the button is released.
1522 @xref{Motion Events}.
1525 @subsection Repeat Events
1526 @cindex repeat events
1527 @cindex double-click events
1528 @cindex triple-click events
1529 @cindex mouse events, repeated
1531 If you press the same mouse button more than once in quick succession
1532 without moving the mouse, Emacs generates special @dfn{repeat} mouse
1533 events for the second and subsequent presses.
1535 The most common repeat events are @dfn{double-click} events. Emacs
1536 generates a double-click event when you click a button twice; the event
1537 happens when you release the button (as is normal for all click
1540 The event type of a double-click event contains the prefix
1541 @samp{double-}. Thus, a double click on the second mouse button with
1542 @key{meta} held down comes to the Lisp program as
1543 @code{M-double-mouse-2}. If a double-click event has no binding, the
1544 binding of the corresponding ordinary click event is used to execute
1545 it. Thus, you need not pay attention to the double click feature
1546 unless you really want to.
1548 When the user performs a double click, Emacs generates first an ordinary
1549 click event, and then a double-click event. Therefore, you must design
1550 the command binding of the double click event to assume that the
1551 single-click command has already run. It must produce the desired
1552 results of a double click, starting from the results of a single click.
1554 This is convenient, if the meaning of a double click somehow ``builds
1555 on'' the meaning of a single click---which is recommended user interface
1556 design practice for double clicks.
1558 If you click a button, then press it down again and start moving the
1559 mouse with the button held down, then you get a @dfn{double-drag} event
1560 when you ultimately release the button. Its event type contains
1561 @samp{double-drag} instead of just @samp{drag}. If a double-drag event
1562 has no binding, Emacs looks for an alternate binding as if the event
1563 were an ordinary drag.
1565 Before the double-click or double-drag event, Emacs generates a
1566 @dfn{double-down} event when the user presses the button down for the
1567 second time. Its event type contains @samp{double-down} instead of just
1568 @samp{down}. If a double-down event has no binding, Emacs looks for an
1569 alternate binding as if the event were an ordinary button-down event.
1570 If it finds no binding that way either, the double-down event is
1573 To summarize, when you click a button and then press it again right
1574 away, Emacs generates a down event and a click event for the first
1575 click, a double-down event when you press the button again, and finally
1576 either a double-click or a double-drag event.
1578 If you click a button twice and then press it again, all in quick
1579 succession, Emacs generates a @dfn{triple-down} event, followed by
1580 either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of
1581 these events contain @samp{triple} instead of @samp{double}. If any
1582 triple event has no binding, Emacs uses the binding that it would use
1583 for the corresponding double event.
1585 If you click a button three or more times and then press it again, the
1586 events for the presses beyond the third are all triple events. Emacs
1587 does not have separate event types for quadruple, quintuple, etc.@:
1588 events. However, you can look at the event list to find out precisely
1589 how many times the button was pressed.
1591 @defun event-click-count event
1592 This function returns the number of consecutive button presses that led
1593 up to @var{event}. If @var{event} is a double-down, double-click or
1594 double-drag event, the value is 2. If @var{event} is a triple event,
1595 the value is 3 or greater. If @var{event} is an ordinary mouse event
1596 (not a repeat event), the value is 1.
1599 @defopt double-click-fuzz
1600 To generate repeat events, successive mouse button presses must be at
1601 approximately the same screen position. The value of
1602 @code{double-click-fuzz} specifies the maximum number of pixels the
1603 mouse may be moved (horizontally or vertically) between two successive
1604 clicks to make a double-click.
1606 This variable is also the threshold for motion of the mouse to count
1610 @defopt double-click-time
1611 To generate repeat events, the number of milliseconds between
1612 successive button presses must be less than the value of
1613 @code{double-click-time}. Setting @code{double-click-time} to
1614 @code{nil} disables multi-click detection entirely. Setting it to
1615 @code{t} removes the time limit; Emacs then detects multi-clicks by
1620 @subsection Motion Events
1621 @cindex motion event
1622 @cindex mouse motion events
1624 Emacs sometimes generates @dfn{mouse motion} events to describe motion
1625 of the mouse without any button activity. Mouse motion events are
1626 represented by lists that look like this:
1629 (mouse-movement POSITION)
1633 @var{position} is a mouse position list (@pxref{Click Events}),
1634 specifying the current position of the mouse cursor.
1636 The special form @code{track-mouse} enables generation of motion
1637 events within its body. Outside of @code{track-mouse} forms, Emacs
1638 does not generate events for mere motion of the mouse, and these
1639 events do not appear. @xref{Mouse Tracking}.
1642 @subsection Focus Events
1645 Window systems provide general ways for the user to control which window
1646 gets keyboard input. This choice of window is called the @dfn{focus}.
1647 When the user does something to switch between Emacs frames, that
1648 generates a @dfn{focus event}. The normal definition of a focus event,
1649 in the global keymap, is to select a new frame within Emacs, as the user
1650 would expect. @xref{Input Focus}.
1652 Focus events are represented in Lisp as lists that look like this:
1655 (switch-frame @var{new-frame})
1659 where @var{new-frame} is the frame switched to.
1661 Some X window managers are set up so that just moving the mouse into a
1662 window is enough to set the focus there. Usually, there is no need
1663 for a Lisp program to know about the focus change until some other
1664 kind of input arrives. Emacs generates a focus event only when the
1665 user actually types a keyboard key or presses a mouse button in the
1666 new frame; just moving the mouse between frames does not generate a
1669 A focus event in the middle of a key sequence would garble the
1670 sequence. So Emacs never generates a focus event in the middle of a key
1671 sequence. If the user changes focus in the middle of a key
1672 sequence---that is, after a prefix key---then Emacs reorders the events
1673 so that the focus event comes either before or after the multi-event key
1674 sequence, and not within it.
1677 @subsection Miscellaneous System Events
1679 A few other event types represent occurrences within the system.
1682 @cindex @code{delete-frame} event
1683 @item (delete-frame (@var{frame}))
1684 This kind of event indicates that the user gave the window manager
1685 a command to delete a particular window, which happens to be an Emacs frame.
1687 The standard definition of the @code{delete-frame} event is to delete @var{frame}.
1689 @cindex @code{iconify-frame} event
1690 @item (iconify-frame (@var{frame}))
1691 This kind of event indicates that the user iconified @var{frame} using
1692 the window manager. Its standard definition is @code{ignore}; since the
1693 frame has already been iconified, Emacs has no work to do. The purpose
1694 of this event type is so that you can keep track of such events if you
1697 @cindex @code{make-frame-visible} event
1698 @item (make-frame-visible (@var{frame}))
1699 This kind of event indicates that the user deiconified @var{frame} using
1700 the window manager. Its standard definition is @code{ignore}; since the
1701 frame has already been made visible, Emacs has no work to do.
1703 @cindex @code{wheel-up} event
1704 @cindex @code{wheel-down} event
1705 @item (wheel-up @var{position})
1706 @itemx (wheel-down @var{position})
1707 These kinds of event are generated by moving a mouse wheel. The
1708 @var{position} element is a mouse position list (@pxref{Click
1709 Events}), specifying the position of the mouse cursor when the event
1712 @vindex mouse-wheel-up-event
1713 @vindex mouse-wheel-down-event
1714 This kind of event is generated only on some kinds of systems. On some
1715 systems, @code{mouse-4} and @code{mouse-5} are used instead. For
1716 portable code, use the variables @code{mouse-wheel-up-event} and
1717 @code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine
1718 what event types to expect for the mouse wheel.
1720 @cindex @code{drag-n-drop} event
1721 @item (drag-n-drop @var{position} @var{files})
1722 This kind of event is generated when a group of files is
1723 selected in an application outside of Emacs, and then dragged and
1724 dropped onto an Emacs frame.
1726 The element @var{position} is a list describing the position of the
1727 event, in the same format as used in a mouse-click event (@pxref{Click
1728 Events}), and @var{files} is the list of file names that were dragged
1729 and dropped. The usual way to handle this event is by visiting these
1732 This kind of event is generated, at present, only on some kinds of
1735 @cindex @code{help-echo} event
1737 This kind of event is generated when a mouse pointer moves onto a
1738 portion of buffer text which has a @code{help-echo} text property.
1739 The generated event has this form:
1742 (help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos})
1746 The precise meaning of the event parameters and the way these
1747 parameters are used to display the help-echo text are described in
1748 @ref{Text help-echo}.
1750 @cindex @code{sigusr1} event
1751 @cindex @code{sigusr2} event
1752 @cindex user signals
1755 These events are generated when the Emacs process receives
1756 the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no
1757 additional data because signals do not carry additional information.
1758 They can be useful for debugging (@pxref{Error Debugging}).
1760 To catch a user signal, bind the corresponding event to an interactive
1761 command in the @code{special-event-map} (@pxref{Active Keymaps}).
1762 The command is called with no arguments, and the specific signal event is
1763 available in @code{last-input-event}. For example:
1766 (defun sigusr-handler ()
1768 (message "Caught signal %S" last-input-event))
1770 (define-key special-event-map [sigusr1] 'sigusr-handler)
1773 To test the signal handler, you can make Emacs send a signal to itself:
1776 (signal-process (emacs-pid) 'sigusr1)
1779 @cindex @code{language-change} event
1780 @item language-change
1781 This kind of event is generated on MS-Windows when the input language
1782 has changed. This typically means that the keyboard keys will send to
1783 Emacs characters from a different language. The generated event has
1787 (language-change @var{frame} @var{codepage} @var{language-id})
1791 Here @var{frame} is the frame which was current when the input
1792 language changed; @var{codepage} is the new codepage number; and
1793 @var{language-id} is the numerical ID of the new input language. The
1794 coding-system (@pxref{Coding Systems}) that corresponds to
1795 @var{codepage} is @code{cp@var{codepage}} or
1796 @code{windows-@var{codepage}}. To convert @var{language-id} to a
1797 string (e.g., to use it for various language-dependent features, such
1798 as @code{set-language-environment}), use the
1799 @code{w32-get-locale-info} function, like this:
1802 ;; Get the abbreviated language name, such as "ENU" for English
1803 (w32-get-locale-info language-id)
1804 ;; Get the full English name of the language,
1805 ;; such as "English (United States)"
1806 (w32-get-locale-info language-id 4097)
1807 ;; Get the full localized name of the language
1808 (w32-get-locale-info language-id t)
1812 If one of these events arrives in the middle of a key sequence---that
1813 is, after a prefix key---then Emacs reorders the events so that this
1814 event comes either before or after the multi-event key sequence, not
1817 @node Event Examples
1818 @subsection Event Examples
1820 If the user presses and releases the left mouse button over the same
1821 location, that generates a sequence of events like this:
1824 (down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
1825 (mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180))
1828 While holding the control key down, the user might hold down the
1829 second mouse button, and drag the mouse from one line to the next.
1830 That produces two events, as shown here:
1833 (C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
1834 (C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
1835 (#<window 18 on NEWS> 3510 (0 . 28) -729648))
1838 While holding down the meta and shift keys, the user might press the
1839 second mouse button on the window's mode line, and then drag the mouse
1840 into another window. That produces a pair of events like these:
1843 (M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
1844 (M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
1845 (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
1849 To handle a SIGUSR1 signal, define an interactive function, and
1850 bind it to the @code{signal usr1} event sequence:
1853 (defun usr1-handler ()
1855 (message "Got USR1 signal"))
1856 (global-set-key [signal usr1] 'usr1-handler)
1859 @node Classifying Events
1860 @subsection Classifying Events
1862 @cindex classifying events
1864 Every event has an @dfn{event type}, which classifies the event for
1865 key binding purposes. For a keyboard event, the event type equals the
1866 event value; thus, the event type for a character is the character, and
1867 the event type for a function key symbol is the symbol itself. For
1868 events that are lists, the event type is the symbol in the @sc{car} of
1869 the list. Thus, the event type is always a symbol or a character.
1871 Two events of the same type are equivalent where key bindings are
1872 concerned; thus, they always run the same command. That does not
1873 necessarily mean they do the same things, however, as some commands look
1874 at the whole event to decide what to do. For example, some commands use
1875 the location of a mouse event to decide where in the buffer to act.
1877 Sometimes broader classifications of events are useful. For example,
1878 you might want to ask whether an event involved the @key{META} key,
1879 regardless of which other key or mouse button was used.
1881 The functions @code{event-modifiers} and @code{event-basic-type} are
1882 provided to get such information conveniently.
1884 @defun event-modifiers event
1885 This function returns a list of the modifiers that @var{event} has. The
1886 modifiers are symbols; they include @code{shift}, @code{control},
1887 @code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition,
1888 the modifiers list of a mouse event symbol always contains one of
1889 @code{click}, @code{drag}, and @code{down}. For double or triple
1890 events, it also contains @code{double} or @code{triple}.
1892 The argument @var{event} may be an entire event object, or just an
1893 event type. If @var{event} is a symbol that has never been used in an
1894 event that has been read as input in the current Emacs session, then
1895 @code{event-modifiers} can return @code{nil}, even when @var{event}
1896 actually has modifiers.
1898 Here are some examples:
1901 (event-modifiers ?a)
1903 (event-modifiers ?A)
1905 (event-modifiers ?\C-a)
1907 (event-modifiers ?\C-%)
1909 (event-modifiers ?\C-\S-a)
1910 @result{} (control shift)
1911 (event-modifiers 'f5)
1913 (event-modifiers 's-f5)
1915 (event-modifiers 'M-S-f5)
1916 @result{} (meta shift)
1917 (event-modifiers 'mouse-1)
1919 (event-modifiers 'down-mouse-1)
1923 The modifiers list for a click event explicitly contains @code{click},
1924 but the event symbol name itself does not contain @samp{click}.
1927 @defun event-basic-type event
1928 This function returns the key or mouse button that @var{event}
1929 describes, with all modifiers removed. The @var{event} argument is as
1930 in @code{event-modifiers}. For example:
1933 (event-basic-type ?a)
1935 (event-basic-type ?A)
1937 (event-basic-type ?\C-a)
1939 (event-basic-type ?\C-\S-a)
1941 (event-basic-type 'f5)
1943 (event-basic-type 's-f5)
1945 (event-basic-type 'M-S-f5)
1947 (event-basic-type 'down-mouse-1)
1952 @defun mouse-movement-p object
1953 This function returns non-@code{nil} if @var{object} is a mouse movement
1957 @defun event-convert-list list
1958 This function converts a list of modifier names and a basic event type
1959 to an event type which specifies all of them. The basic event type
1960 must be the last element of the list. For example,
1963 (event-convert-list '(control ?a))
1965 (event-convert-list '(control meta ?a))
1966 @result{} -134217727
1967 (event-convert-list '(control super f1))
1972 @node Accessing Mouse
1973 @subsection Accessing Mouse Events
1974 @cindex mouse events, data in
1975 @cindex keyboard events, data in
1977 This section describes convenient functions for accessing the data in
1978 a mouse button or motion event. Keyboard event data can be accessed
1979 using the same functions, but data elements that aren't applicable to
1980 keyboard events are zero or @code{nil}.
1982 The following two functions return a mouse position list
1983 (@pxref{Click Events}), specifying the position of a mouse event.
1985 @defun event-start event
1986 This returns the starting position of @var{event}.
1988 If @var{event} is a click or button-down event, this returns the
1989 location of the event. If @var{event} is a drag event, this returns the
1990 drag's starting position.
1993 @defun event-end event
1994 This returns the ending position of @var{event}.
1996 If @var{event} is a drag event, this returns the position where the user
1997 released the mouse button. If @var{event} is a click or button-down
1998 event, the value is actually the starting position, which is the only
1999 position such events have.
2003 This function returns non-@code{nil} if @var{object} is a mouse
2004 position list, in either of the formats documented in @ref{Click
2005 Events}); and @code{nil} otherwise.
2008 @cindex mouse position list, accessing
2009 These functions take a mouse position list as argument, and return
2010 various parts of it:
2012 @defun posn-window position
2013 Return the window that @var{position} is in.
2016 @defun posn-area position
2017 Return the window area recorded in @var{position}. It returns @code{nil}
2018 when the event occurred in the text area of the window; otherwise, it
2019 is a symbol identifying the area in which the event occurred.
2022 @defun posn-point position
2023 Return the buffer position in @var{position}. When the event occurred
2024 in the text area of the window, in a marginal area, or on a fringe,
2025 this is an integer specifying a buffer position. Otherwise, the value
2029 @defun posn-x-y position
2030 Return the pixel-based x and y coordinates in @var{position}, as a
2031 cons cell @code{(@var{x} . @var{y})}. These coordinates are relative
2032 to the window given by @code{posn-window}.
2034 This example shows how to convert the window-relative coordinates in
2035 the text area of a window into frame-relative coordinates:
2038 (defun frame-relative-coordinates (position)
2039 "Return frame-relative coordinates from POSITION.
2040 POSITION is assumed to lie in a window text area."
2041 (let* ((x-y (posn-x-y position))
2042 (window (posn-window position))
2043 (edges (window-inside-pixel-edges window)))
2044 (cons (+ (car x-y) (car edges))
2045 (+ (cdr x-y) (cadr edges)))))
2049 @defun posn-col-row position
2050 This function returns a cons cell @code{(@var{col} . @var{row})},
2051 containing the estimated column and row corresponding to buffer
2052 position in @var{position}. The return value is given in units of the
2053 frame's default character width and default line height (including
2054 spacing), as computed from the @var{x} and @var{y} values
2055 corresponding to @var{position}. (So, if the actual characters have
2056 non-default sizes, the actual row and column may differ from these
2059 Note that @var{row} is counted from the top of the text area. If the
2060 window given by @var{position} possesses a header line (@pxref{Header
2061 Lines}), it is @emph{not} included in the @var{row} count.
2064 @defun posn-actual-col-row position
2065 Return the actual row and column in @var{position}, as a cons cell
2066 @code{(@var{col} . @var{row})}. The values are the actual row and
2067 column numbers in the window given by @var{position}. @xref{Click
2068 Events}, for details. The function returns @code{nil} if
2069 @var{position} does not include actual position values.
2072 @defun posn-string position
2073 Return the string object in @var{position}, either @code{nil}, or a
2074 cons cell @code{(@var{string} . @var{string-pos})}.
2077 @defun posn-image position
2078 Return the image object in @var{position}, either @code{nil}, or an
2079 image @code{(image ...)}.
2082 @defun posn-object position
2083 Return the image or string object in @var{position}, either
2084 @code{nil}, an image @code{(image ...)}, or a cons cell
2085 @code{(@var{string} . @var{string-pos})}.
2088 @defun posn-object-x-y position
2089 Return the pixel-based x and y coordinates relative to the upper left
2090 corner of the object in @var{position} as a cons cell @code{(@var{dx}
2091 . @var{dy})}. If the @var{position} is a buffer position, return the
2092 relative position in the character at that position.
2095 @defun posn-object-width-height position
2096 Return the pixel width and height of the object in @var{position} as a
2097 cons cell @code{(@var{width} . @var{height})}. If the @var{position}
2098 is a buffer position, return the size of the character at that position.
2101 @cindex timestamp of a mouse event
2102 @defun posn-timestamp position
2103 Return the timestamp in @var{position}. This is the time at which the
2104 event occurred, in milliseconds.
2107 These functions compute a position list given particular buffer
2108 position or screen position. You can access the data in this position
2109 list with the functions described above.
2111 @defun posn-at-point &optional pos window
2112 This function returns a position list for position @var{pos} in
2113 @var{window}. @var{pos} defaults to point in @var{window};
2114 @var{window} defaults to the selected window.
2116 @code{posn-at-point} returns @code{nil} if @var{pos} is not visible in
2120 @defun posn-at-x-y x y &optional frame-or-window whole
2121 This function returns position information corresponding to pixel
2122 coordinates @var{x} and @var{y} in a specified frame or window,
2123 @var{frame-or-window}, which defaults to the selected window.
2124 The coordinates @var{x} and @var{y} are relative to the
2125 frame or window used.
2126 If @var{whole} is @code{nil}, the coordinates are relative
2127 to the window text area, otherwise they are relative to
2128 the entire window area including scroll bars, margins and fringes.
2131 @node Accessing Scroll
2132 @subsection Accessing Scroll Bar Events
2133 @cindex scroll bar events, data in
2135 These functions are useful for decoding scroll bar events.
2137 @defun scroll-bar-event-ratio event
2138 This function returns the fractional vertical position of a scroll bar
2139 event within the scroll bar. The value is a cons cell
2140 @code{(@var{portion} . @var{whole})} containing two integers whose ratio
2141 is the fractional position.
2144 @defun scroll-bar-scale ratio total
2145 This function multiplies (in effect) @var{ratio} by @var{total},
2146 rounding the result to an integer. The argument @var{ratio} is not a
2147 number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
2148 value returned by @code{scroll-bar-event-ratio}.
2150 This function is handy for scaling a position on a scroll bar into a
2151 buffer position. Here's how to do that:
2156 (posn-x-y (event-start event))
2157 (- (point-max) (point-min))))
2160 Recall that scroll bar events have two integers forming a ratio, in place
2161 of a pair of x and y coordinates.
2164 @node Strings of Events
2165 @subsection Putting Keyboard Events in Strings
2166 @cindex keyboard events in strings
2167 @cindex strings with keyboard events
2169 In most of the places where strings are used, we conceptualize the
2170 string as containing text characters---the same kind of characters found
2171 in buffers or files. Occasionally Lisp programs use strings that
2172 conceptually contain keyboard characters; for example, they may be key
2173 sequences or keyboard macro definitions. However, storing keyboard
2174 characters in a string is a complex matter, for reasons of historical
2175 compatibility, and it is not always possible.
2177 We recommend that new programs avoid dealing with these complexities
2178 by not storing keyboard events in strings. Here is how to do that:
2182 Use vectors instead of strings for key sequences, when you plan to use
2183 them for anything other than as arguments to @code{lookup-key} and
2184 @code{define-key}. For example, you can use
2185 @code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
2186 @code{this-command-keys-vector} instead of @code{this-command-keys}.
2189 Use vectors to write key sequence constants containing meta characters,
2190 even when passing them directly to @code{define-key}.
2193 When you have to look at the contents of a key sequence that might be a
2194 string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
2195 first, to convert it to a list.
2198 The complexities stem from the modifier bits that keyboard input
2199 characters can include. Aside from the Meta modifier, none of these
2200 modifier bits can be included in a string, and the Meta modifier is
2201 allowed only in special cases.
2203 The earliest GNU Emacs versions represented meta characters as codes
2204 in the range of 128 to 255. At that time, the basic character codes
2205 ranged from 0 to 127, so all keyboard character codes did fit in a
2206 string. Many Lisp programs used @samp{\M-} in string constants to stand
2207 for meta characters, especially in arguments to @code{define-key} and
2208 similar functions, and key sequences and sequences of events were always
2209 represented as strings.
2211 When we added support for larger basic character codes beyond 127, and
2212 additional modifier bits, we had to change the representation of meta
2213 characters. Now the flag that represents the Meta modifier in a
2221 and such numbers cannot be included in a string.
2223 To support programs with @samp{\M-} in string constants, there are
2224 special rules for including certain meta characters in a string.
2225 Here are the rules for interpreting a string as a sequence of input
2230 If the keyboard character value is in the range of 0 to 127, it can go
2231 in the string unchanged.
2234 The meta variants of those characters, with codes in the range of
2243 @math{2^{27} + 127},
2248 can also go in the string, but you must change their
2249 numeric values. You must set the
2263 bit, resulting in a value between 128 and 255. Only a unibyte string
2264 can include these codes.
2267 Non-@acronym{ASCII} characters above 256 can be included in a multibyte string.
2270 Other keyboard character events cannot fit in a string. This includes
2271 keyboard events in the range of 128 to 255.
2274 Functions such as @code{read-key-sequence} that construct strings of
2275 keyboard input characters follow these rules: they construct vectors
2276 instead of strings, when the events won't fit in a string.
2278 When you use the read syntax @samp{\M-} in a string, it produces a
2279 code in the range of 128 to 255---the same code that you get if you
2280 modify the corresponding keyboard event to put it in the string. Thus,
2281 meta events in strings work consistently regardless of how they get into
2284 However, most programs would do well to avoid these issues by
2285 following the recommendations at the beginning of this section.
2288 @section Reading Input
2290 @cindex keyboard input
2292 The editor command loop reads key sequences using the function
2293 @code{read-key-sequence}, which uses @code{read-event}. These and other
2294 functions for event input are also available for use in Lisp programs.
2295 See also @code{momentary-string-display} in @ref{Temporary Displays},
2296 and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
2297 functions and variables for controlling terminal input modes and
2298 debugging terminal input.
2300 For higher-level input facilities, see @ref{Minibuffers}.
2303 * Key Sequence Input:: How to read one key sequence.
2304 * Reading One Event:: How to read just one event.
2305 * Event Mod:: How Emacs modifies events as they are read.
2306 * Invoking the Input Method:: How reading an event uses the input method.
2307 * Quoted Character Input:: Asking the user to specify a character.
2308 * Event Input Misc:: How to reread or throw away input events.
2311 @node Key Sequence Input
2312 @subsection Key Sequence Input
2313 @cindex key sequence input
2315 The command loop reads input a key sequence at a time, by calling
2316 @code{read-key-sequence}. Lisp programs can also call this function;
2317 for example, @code{describe-key} uses it to read the key to describe.
2319 @defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
2320 This function reads a key sequence and returns it as a string or
2321 vector. It keeps reading events until it has accumulated a complete key
2322 sequence; that is, enough to specify a non-prefix command using the
2323 currently active keymaps. (Remember that a key sequence that starts
2324 with a mouse event is read using the keymaps of the buffer in the
2325 window that the mouse was in, not the current buffer.)
2327 If the events are all characters and all can fit in a string, then
2328 @code{read-key-sequence} returns a string (@pxref{Strings of Events}).
2329 Otherwise, it returns a vector, since a vector can hold all kinds of
2330 events---characters, symbols, and lists. The elements of the string or
2331 vector are the events in the key sequence.
2333 Reading a key sequence includes translating the events in various
2334 ways. @xref{Translation Keymaps}.
2336 The argument @var{prompt} is either a string to be displayed in the
2337 echo area as a prompt, or @code{nil}, meaning not to display a prompt.
2338 The argument @var{continue-echo}, if non-@code{nil}, means to echo
2339 this key as a continuation of the previous key.
2341 Normally any upper case event is converted to lower case if the
2342 original event is undefined and the lower case equivalent is defined.
2343 The argument @var{dont-downcase-last}, if non-@code{nil}, means do not
2344 convert the last event to lower case. This is appropriate for reading
2345 a key sequence to be defined.
2347 The argument @var{switch-frame-ok}, if non-@code{nil}, means that this
2348 function should process a @code{switch-frame} event if the user
2349 switches frames before typing anything. If the user switches frames
2350 in the middle of a key sequence, or at the start of the sequence but
2351 @var{switch-frame-ok} is @code{nil}, then the event will be put off
2352 until after the current key sequence.
2354 The argument @var{command-loop}, if non-@code{nil}, means that this
2355 key sequence is being read by something that will read commands one
2356 after another. It should be @code{nil} if the caller will read just
2359 In the following example, Emacs displays the prompt @samp{?} in the
2360 echo area, and then the user types @kbd{C-x C-f}.
2363 (read-key-sequence "?")
2366 ---------- Echo Area ----------
2368 ---------- Echo Area ----------
2374 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
2375 typed while reading with this function works like any other character,
2376 and does not set @code{quit-flag}. @xref{Quitting}.
2379 @defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
2380 This is like @code{read-key-sequence} except that it always
2381 returns the key sequence as a vector, never as a string.
2382 @xref{Strings of Events}.
2385 @cindex upper case key sequence
2386 @cindex downcasing in @code{lookup-key}
2387 @cindex shift-translation
2388 If an input character is upper-case (or has the shift modifier) and
2389 has no key binding, but its lower-case equivalent has one, then
2390 @code{read-key-sequence} converts the character to lower case. Note
2391 that @code{lookup-key} does not perform case conversion in this way.
2393 @vindex this-command-keys-shift-translated
2394 When reading input results in such a @dfn{shift-translation}, Emacs
2395 sets the variable @code{this-command-keys-shift-translated} to a
2396 non-@code{nil} value. Lisp programs can examine this variable if they
2397 need to modify their behavior when invoked by shift-translated keys.
2398 For example, the function @code{handle-shift-selection} examines the
2399 value of this variable to determine how to activate or deactivate the
2400 region (@pxref{The Mark, handle-shift-selection}).
2402 The function @code{read-key-sequence} also transforms some mouse events.
2403 It converts unbound drag events into click events, and discards unbound
2404 button-down events entirely. It also reshuffles focus events and
2405 miscellaneous window events so that they never appear in a key sequence
2406 with any other events.
2408 @cindex @code{header-line} prefix key
2409 @cindex @code{mode-line} prefix key
2410 @cindex @code{vertical-line} prefix key
2411 @cindex @code{horizontal-scroll-bar} prefix key
2412 @cindex @code{vertical-scroll-bar} prefix key
2413 @cindex @code{menu-bar} prefix key
2414 @cindex mouse events, in special parts of frame
2415 When mouse events occur in special parts of a window, such as a mode
2416 line or a scroll bar, the event type shows nothing special---it is the
2417 same symbol that would normally represent that combination of mouse
2418 button and modifier keys. The information about the window part is kept
2419 elsewhere in the event---in the coordinates. But
2420 @code{read-key-sequence} translates this information into imaginary
2421 ``prefix keys'', all of which are symbols: @code{header-line},
2422 @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
2423 @code{vertical-line}, and @code{vertical-scroll-bar}. You can define
2424 meanings for mouse clicks in special window parts by defining key
2425 sequences using these imaginary prefix keys.
2427 For example, if you call @code{read-key-sequence} and then click the
2428 mouse on the window's mode line, you get two events, like this:
2431 (read-key-sequence "Click on the mode line: ")
2432 @result{} [mode-line
2434 (#<window 6 on NEWS> mode-line
2435 (40 . 63) 5959987))]
2438 @defvar num-input-keys
2439 This variable's value is the number of key sequences processed so far in
2440 this Emacs session. This includes key sequences read from the terminal
2441 and key sequences read from keyboard macros being executed.
2444 @node Reading One Event
2445 @subsection Reading One Event
2446 @cindex reading a single event
2447 @cindex event, reading only one
2449 The lowest level functions for command input are @code{read-event},
2450 @code{read-char}, and @code{read-char-exclusive}.
2452 @defun read-event &optional prompt inherit-input-method seconds
2453 This function reads and returns the next event of command input,
2454 waiting if necessary until an event is available.
2456 The returned event may come directly from the user, or from a keyboard
2457 macro. It is not decoded by the keyboard's input coding system
2458 (@pxref{Terminal I/O Encoding}).
2460 If the optional argument @var{prompt} is non-@code{nil}, it should be a
2461 string to display in the echo area as a prompt. Otherwise,
2462 @code{read-event} does not display any message to indicate it is waiting
2463 for input; instead, it prompts by echoing: it displays descriptions of
2464 the events that led to or were read by the current command. @xref{The
2467 If @var{inherit-input-method} is non-@code{nil}, then the current input
2468 method (if any) is employed to make it possible to enter a
2469 non-@acronym{ASCII} character. Otherwise, input method handling is disabled
2470 for reading this event.
2472 If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
2473 moves the cursor temporarily to the echo area, to the end of any message
2474 displayed there. Otherwise @code{read-event} does not move the cursor.
2476 If @var{seconds} is non-@code{nil}, it should be a number specifying
2477 the maximum time to wait for input, in seconds. If no input arrives
2478 within that time, @code{read-event} stops waiting and returns
2479 @code{nil}. A floating point @var{seconds} means to wait
2480 for a fractional number of seconds. Some systems support only a whole
2481 number of seconds; on these systems, @var{seconds} is rounded down.
2482 If @var{seconds} is @code{nil}, @code{read-event} waits as long as
2483 necessary for input to arrive.
2485 If @var{seconds} is @code{nil}, Emacs is considered idle while waiting
2486 for user input to arrive. Idle timers---those created with
2487 @code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this
2488 period. However, if @var{seconds} is non-@code{nil}, the state of
2489 idleness remains unchanged. If Emacs is non-idle when
2490 @code{read-event} is called, it remains non-idle throughout the
2491 operation of @code{read-event}; if Emacs is idle (which can happen if
2492 the call happens inside an idle timer), it remains idle.
2494 If @code{read-event} gets an event that is defined as a help character,
2495 then in some cases @code{read-event} processes the event directly without
2496 returning. @xref{Help Functions}. Certain other events, called
2497 @dfn{special events}, are also processed directly within
2498 @code{read-event} (@pxref{Special Events}).
2500 Here is what happens if you call @code{read-event} and then press the
2501 right-arrow function key:
2511 @defun read-char &optional prompt inherit-input-method seconds
2512 This function reads and returns a character of command input. If the
2513 user generates an event which is not a character (i.e., a mouse click or
2514 function key event), @code{read-char} signals an error. The arguments
2515 work as in @code{read-event}.
2517 In the first example, the user types the character @kbd{1} (@acronym{ASCII}
2518 code 49). The second example shows a keyboard macro definition that
2519 calls @code{read-char} from the minibuffer using @code{eval-expression}.
2520 @code{read-char} reads the keyboard macro's very next character, which
2521 is @kbd{1}. Then @code{eval-expression} displays its return value in
2531 ;; @r{We assume here you use @kbd{M-:} to evaluate this.}
2532 (symbol-function 'foo)
2533 @result{} "^[:(read-char)^M1"
2536 (execute-kbd-macro 'foo)
2543 @defun read-char-exclusive &optional prompt inherit-input-method seconds
2544 This function reads and returns a character of command input. If the
2545 user generates an event which is not a character,
2546 @code{read-char-exclusive} ignores it and reads another event, until it
2547 gets a character. The arguments work as in @code{read-event}.
2550 None of the above functions suppress quitting.
2552 @defvar num-nonmacro-input-events
2553 This variable holds the total number of input events received so far
2554 from the terminal---not counting those generated by keyboard macros.
2557 We emphasize that, unlike @code{read-key-sequence}, the functions
2558 @code{read-event}, @code{read-char}, and @code{read-char-exclusive} do
2559 not perform the translations described in @ref{Translation Keymaps}.
2560 If you wish to read a single key taking these translations into
2561 account, use the function @code{read-key}:
2563 @defun read-key &optional prompt
2564 This function reads a single key. It is ``intermediate'' between
2565 @code{read-key-sequence} and @code{read-event}. Unlike the former, it
2566 reads a single key, not a key sequence. Unlike the latter, it does
2567 not return a raw event, but decodes and translates the user input
2568 according to @code{input-decode-map}, @code{local-function-key-map},
2569 and @code{key-translation-map} (@pxref{Translation Keymaps}).
2571 The argument @var{prompt} is either a string to be displayed in the
2572 echo area as a prompt, or @code{nil}, meaning not to display a prompt.
2575 @defun read-char-choice prompt chars &optional inhibit-quit
2576 This function uses @code{read-key} to read and return a single
2577 character. It ignores any input that is not a member of @var{chars},
2578 a list of accepted characters. Optionally, it will also ignore
2579 keyboard-quit events while it is waiting for valid input. If you bind
2580 @code{help-form} (@pxref{Help Functions}) to a non-@code{nil} value
2581 while calling @code{read-char-choice}, then pressing @code{help-char}
2582 causes it to evaluate @code{help-form} and display the result. It
2583 then continues to wait for a valid input character, or keyboard-quit.
2587 @subsection Modifying and Translating Input Events
2588 @cindex modifiers of events
2589 @cindex translating input events
2590 @cindex event translation
2592 Emacs modifies every event it reads according to
2593 @code{extra-keyboard-modifiers}, then translates it through
2594 @code{keyboard-translate-table} (if applicable), before returning it
2595 from @code{read-event}.
2597 @defvar extra-keyboard-modifiers
2598 This variable lets Lisp programs ``press'' the modifier keys on the
2599 keyboard. The value is a character. Only the modifiers of the
2600 character matter. Each time the user types a keyboard key, it is
2601 altered as if those modifier keys were held down. For instance, if
2602 you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all
2603 keyboard input characters typed during the scope of the binding will
2604 have the control and meta modifiers applied to them. The character
2605 @code{?\C-@@}, equivalent to the integer 0, does not count as a control
2606 character for this purpose, but as a character with no modifiers.
2607 Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
2610 When using a window system, the program can ``press'' any of the
2611 modifier keys in this way. Otherwise, only the @key{CTL} and @key{META}
2612 keys can be virtually pressed.
2614 Note that this variable applies only to events that really come from
2615 the keyboard, and has no effect on mouse events or any other events.
2618 @defvar keyboard-translate-table
2619 This terminal-local variable is the translate table for keyboard
2620 characters. It lets you reshuffle the keys on the keyboard without
2621 changing any command bindings. Its value is normally a char-table, or
2622 else @code{nil}. (It can also be a string or vector, but this is
2623 considered obsolete.)
2625 If @code{keyboard-translate-table} is a char-table
2626 (@pxref{Char-Tables}), then each character read from the keyboard is
2627 looked up in this char-table. If the value found there is
2628 non-@code{nil}, then it is used instead of the actual input character.
2630 Note that this translation is the first thing that happens to a
2631 character after it is read from the terminal. Record-keeping features
2632 such as @code{recent-keys} and dribble files record the characters after
2635 Note also that this translation is done before the characters are
2636 supplied to input methods (@pxref{Input Methods}). Use
2637 @code{translation-table-for-input} (@pxref{Translation of Characters}),
2638 if you want to translate characters after input methods operate.
2641 @defun keyboard-translate from to
2642 This function modifies @code{keyboard-translate-table} to translate
2643 character code @var{from} into character code @var{to}. It creates
2644 the keyboard translate table if necessary.
2647 Here's an example of using the @code{keyboard-translate-table} to
2648 make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste
2652 (keyboard-translate ?\C-x 'control-x)
2653 (keyboard-translate ?\C-c 'control-c)
2654 (keyboard-translate ?\C-v 'control-v)
2655 (global-set-key [control-x] 'kill-region)
2656 (global-set-key [control-c] 'kill-ring-save)
2657 (global-set-key [control-v] 'yank)
2661 On a graphical terminal that supports extended @acronym{ASCII} input,
2662 you can still get the standard Emacs meanings of one of those
2663 characters by typing it with the shift key. That makes it a different
2664 character as far as keyboard translation is concerned, but it has the
2667 @xref{Translation Keymaps}, for mechanisms that translate event sequences
2668 at the level of @code{read-key-sequence}.
2670 @node Invoking the Input Method
2671 @subsection Invoking the Input Method
2672 @cindex invoking input method
2674 The event-reading functions invoke the current input method, if any
2675 (@pxref{Input Methods}). If the value of @code{input-method-function}
2676 is non-@code{nil}, it should be a function; when @code{read-event} reads
2677 a printing character (including @key{SPC}) with no modifier bits, it
2678 calls that function, passing the character as an argument.
2680 @defvar input-method-function
2681 If this is non-@code{nil}, its value specifies the current input method
2684 @strong{Warning:} don't bind this variable with @code{let}. It is often
2685 buffer-local, and if you bind it around reading input (which is exactly
2686 when you @emph{would} bind it), switching buffers asynchronously while
2687 Emacs is waiting will cause the value to be restored in the wrong
2691 The input method function should return a list of events which should
2692 be used as input. (If the list is @code{nil}, that means there is no
2693 input, so @code{read-event} waits for another event.) These events are
2694 processed before the events in @code{unread-command-events}
2695 (@pxref{Event Input Misc}). Events
2696 returned by the input method function are not passed to the input method
2697 function again, even if they are printing characters with no modifier
2700 If the input method function calls @code{read-event} or
2701 @code{read-key-sequence}, it should bind @code{input-method-function} to
2702 @code{nil} first, to prevent recursion.
2704 The input method function is not called when reading the second and
2705 subsequent events of a key sequence. Thus, these characters are not
2706 subject to input method processing. The input method function should
2707 test the values of @code{overriding-local-map} and
2708 @code{overriding-terminal-local-map}; if either of these variables is
2709 non-@code{nil}, the input method should put its argument into a list and
2710 return that list with no further processing.
2712 @node Quoted Character Input
2713 @subsection Quoted Character Input
2714 @cindex quoted character input
2716 You can use the function @code{read-quoted-char} to ask the user to
2717 specify a character, and allow the user to specify a control or meta
2718 character conveniently, either literally or as an octal character code.
2719 The command @code{quoted-insert} uses this function.
2721 @defun read-quoted-char &optional prompt
2722 @cindex octal character input
2723 @cindex control characters, reading
2724 @cindex nonprinting characters, reading
2725 This function is like @code{read-char}, except that if the first
2726 character read is an octal digit (0--7), it reads any number of octal
2727 digits (but stopping if a non-octal digit is found), and returns the
2728 character represented by that numeric character code. If the
2729 character that terminates the sequence of octal digits is @key{RET},
2730 it is discarded. Any other terminating character is used as input
2731 after this function returns.
2733 Quitting is suppressed when the first character is read, so that the
2734 user can enter a @kbd{C-g}. @xref{Quitting}.
2736 If @var{prompt} is supplied, it specifies a string for prompting the
2737 user. The prompt string is always displayed in the echo area, followed
2738 by a single @samp{-}.
2740 In the following example, the user types in the octal number 177 (which
2744 (read-quoted-char "What character")
2747 ---------- Echo Area ----------
2748 What character @kbd{1 7 7}-
2749 ---------- Echo Area ----------
2757 @node Event Input Misc
2758 @subsection Miscellaneous Event Input Features
2760 This section describes how to ``peek ahead'' at events without using
2761 them up, how to check for pending input, and how to discard pending
2762 input. See also the function @code{read-passwd} (@pxref{Reading a
2765 @defvar unread-command-events
2767 @cindex peeking at input
2768 This variable holds a list of events waiting to be read as command
2769 input. The events are used in the order they appear in the list, and
2770 removed one by one as they are used.
2772 The variable is needed because in some cases a function reads an event
2773 and then decides not to use it. Storing the event in this variable
2774 causes it to be processed normally, by the command loop or by the
2775 functions to read command input.
2777 @cindex prefix argument unreading
2778 For example, the function that implements numeric prefix arguments reads
2779 any number of digits. When it finds a non-digit event, it must unread
2780 the event so that it can be read normally by the command loop.
2781 Likewise, incremental search uses this feature to unread events with no
2782 special meaning in a search, because these events should exit the search
2783 and then execute normally.
2785 The reliable and easy way to extract events from a key sequence so as
2786 to put them in @code{unread-command-events} is to use
2787 @code{listify-key-sequence} (see below).
2789 Normally you add events to the front of this list, so that the events
2790 most recently unread will be reread first.
2792 Events read from this list are not normally added to the current
2793 command's key sequence (as returned by, e.g., @code{this-command-keys}),
2794 as the events will already have been added once as they were read for
2795 the first time. An element of the form @code{(@code{t} . @var{event})}
2796 forces @var{event} to be added to the current command's key sequence.
2799 @defun listify-key-sequence key
2800 This function converts the string or vector @var{key} to a list of
2801 individual events, which you can put in @code{unread-command-events}.
2804 @defun input-pending-p &optional check-timers
2805 @cindex waiting for command key input
2806 This function determines whether any command input is currently
2807 available to be read. It returns immediately, with value @code{t} if
2808 there is available input, @code{nil} otherwise. On rare occasions it
2809 may return @code{t} when no input is available.
2811 If the optional argument @var{check-timers} is non-@code{nil}, then if
2812 no input is available, Emacs runs any timers which are ready.
2816 @defvar last-input-event
2817 This variable records the last terminal input event read, whether
2818 as part of a command or explicitly by a Lisp program.
2820 In the example below, the Lisp program reads the character @kbd{1},
2821 @acronym{ASCII} code 49. It becomes the value of @code{last-input-event},
2822 while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
2823 this expression) remains the value of @code{last-command-event}.
2827 (progn (print (read-char))
2828 (print last-command-event)
2837 @defmac while-no-input body@dots{}
2838 This construct runs the @var{body} forms and returns the value of the
2839 last one---but only if no input arrives. If any input arrives during
2840 the execution of the @var{body} forms, it aborts them (working much
2841 like a quit). The @code{while-no-input} form returns @code{nil} if
2842 aborted by a real quit, and returns @code{t} if aborted by arrival of
2845 If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil},
2846 arrival of input during those parts won't cause an abort until
2847 the end of that part.
2849 If you want to be able to distinguish all possible values computed
2850 by @var{body} from both kinds of abort conditions, write the code
2856 (progn . @var{body})))
2860 @defun discard-input
2861 @cindex flushing input
2862 @cindex discarding input
2863 @cindex keyboard macro, terminating
2864 This function discards the contents of the terminal input buffer and
2865 cancels any keyboard macro that might be in the process of definition.
2866 It returns @code{nil}.
2868 In the following example, the user may type a number of characters right
2869 after starting the evaluation of the form. After the @code{sleep-for}
2870 finishes sleeping, @code{discard-input} discards any characters typed
2874 (progn (sleep-for 2)
2880 @node Special Events
2881 @section Special Events
2883 @cindex special events
2884 Certain @dfn{special events} are handled at a very low level---as soon
2885 as they are read. The @code{read-event} function processes these
2886 events itself, and never returns them. Instead, it keeps waiting for
2887 the first event that is not special and returns that one.
2889 Special events do not echo, they are never grouped into key
2890 sequences, and they never appear in the value of
2891 @code{last-command-event} or @code{(this-command-keys)}. They do not
2892 discard a numeric argument, they cannot be unread with
2893 @code{unread-command-events}, they may not appear in a keyboard macro,
2894 and they are not recorded in a keyboard macro while you are defining
2897 Special events do, however, appear in @code{last-input-event}
2898 immediately after they are read, and this is the way for the event's
2899 definition to find the actual event.
2901 The events types @code{iconify-frame}, @code{make-frame-visible},
2902 @code{delete-frame}, @code{drag-n-drop}, @code{language-change}, and
2903 user signals like @code{sigusr1} are normally handled in this way.
2904 The keymap which defines how to handle special events---and which
2905 events are special---is in the variable @code{special-event-map}
2906 (@pxref{Active Keymaps}).
2909 @section Waiting for Elapsed Time or Input
2912 The wait functions are designed to wait for a certain amount of time
2913 to pass or until there is input. For example, you may wish to pause in
2914 the middle of a computation to allow the user time to view the display.
2915 @code{sit-for} pauses and updates the screen, and returns immediately if
2916 input comes in, while @code{sleep-for} pauses without updating the
2919 @defun sit-for seconds &optional nodisp
2920 This function performs redisplay (provided there is no pending input
2921 from the user), then waits @var{seconds} seconds, or until input is
2922 available. The usual purpose of @code{sit-for} is to give the user
2923 time to read text that you display. The value is @code{t} if
2924 @code{sit-for} waited the full time with no input arriving
2925 (@pxref{Event Input Misc}). Otherwise, the value is @code{nil}.
2927 The argument @var{seconds} need not be an integer. If it is floating
2928 point, @code{sit-for} waits for a fractional number of seconds.
2929 Some systems support only a whole number of seconds; on these systems,
2930 @var{seconds} is rounded down.
2932 The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)},
2933 i.e., it requests a redisplay, without any delay, if there is no pending input.
2934 @xref{Forcing Redisplay}.
2936 If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
2937 redisplay, but it still returns as soon as input is available (or when
2938 the timeout elapses).
2940 In batch mode (@pxref{Batch Mode}), @code{sit-for} cannot be
2941 interrupted, even by input from the standard input descriptor. It is
2942 thus equivalent to @code{sleep-for}, which is described below.
2944 It is also possible to call @code{sit-for} with three arguments,
2945 as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})},
2946 but that is considered obsolete.
2949 @defun sleep-for seconds &optional millisec
2950 This function simply pauses for @var{seconds} seconds without updating
2951 the display. It pays no attention to available input. It returns
2954 The argument @var{seconds} need not be an integer. If it is floating
2955 point, @code{sleep-for} waits for a fractional number of seconds.
2956 Some systems support only a whole number of seconds; on these systems,
2957 @var{seconds} is rounded down.
2959 The optional argument @var{millisec} specifies an additional waiting
2960 period measured in milliseconds. This adds to the period specified by
2961 @var{seconds}. If the system doesn't support waiting fractions of a
2962 second, you get an error if you specify nonzero @var{millisec}.
2964 Use @code{sleep-for} when you wish to guarantee a delay.
2967 @xref{Time of Day}, for functions to get the current time.
2973 @cindex interrupt Lisp functions
2975 Typing @kbd{C-g} while a Lisp function is running causes Emacs to
2976 @dfn{quit} whatever it is doing. This means that control returns to the
2977 innermost active command loop.
2979 Typing @kbd{C-g} while the command loop is waiting for keyboard input
2980 does not cause a quit; it acts as an ordinary input character. In the
2981 simplest case, you cannot tell the difference, because @kbd{C-g}
2982 normally runs the command @code{keyboard-quit}, whose effect is to quit.
2983 However, when @kbd{C-g} follows a prefix key, they combine to form an
2984 undefined key. The effect is to cancel the prefix key as well as any
2987 In the minibuffer, @kbd{C-g} has a different definition: it aborts out
2988 of the minibuffer. This means, in effect, that it exits the minibuffer
2989 and then quits. (Simply quitting would return to the command loop
2990 @emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit
2991 directly when the command reader is reading input is so that its meaning
2992 can be redefined in the minibuffer in this way. @kbd{C-g} following a
2993 prefix key is not redefined in the minibuffer, and it has its normal
2994 effect of canceling the prefix key and prefix argument. This too
2995 would not be possible if @kbd{C-g} always quit directly.
2997 When @kbd{C-g} does directly quit, it does so by setting the variable
2998 @code{quit-flag} to @code{t}. Emacs checks this variable at appropriate
2999 times and quits if it is not @code{nil}. Setting @code{quit-flag}
3000 non-@code{nil} in any way thus causes a quit.
3002 At the level of C code, quitting cannot happen just anywhere; only at the
3003 special places that check @code{quit-flag}. The reason for this is
3004 that quitting at other places might leave an inconsistency in Emacs's
3005 internal state. Because quitting is delayed until a safe place, quitting
3006 cannot make Emacs crash.
3008 Certain functions such as @code{read-key-sequence} or
3009 @code{read-quoted-char} prevent quitting entirely even though they wait
3010 for input. Instead of quitting, @kbd{C-g} serves as the requested
3011 input. In the case of @code{read-key-sequence}, this serves to bring
3012 about the special behavior of @kbd{C-g} in the command loop. In the
3013 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
3014 to quote a @kbd{C-g}.
3016 @cindex preventing quitting
3017 You can prevent quitting for a portion of a Lisp function by binding
3018 the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
3019 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
3020 usual result of this---a quit---is prevented. Eventually,
3021 @code{inhibit-quit} will become @code{nil} again, such as when its
3022 binding is unwound at the end of a @code{let} form. At that time, if
3023 @code{quit-flag} is still non-@code{nil}, the requested quit happens
3024 immediately. This behavior is ideal when you wish to make sure that
3025 quitting does not happen within a ``critical section'' of the program.
3027 @cindex @code{read-quoted-char} quitting
3028 In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
3029 handled in a special way that does not involve quitting. This is done
3030 by reading the input with @code{inhibit-quit} bound to @code{t}, and
3031 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
3032 becomes @code{nil} again. This excerpt from the definition of
3033 @code{read-quoted-char} shows how this is done; it also shows that
3034 normal quitting is permitted after the first character of input.
3037 (defun read-quoted-char (&optional prompt)
3038 "@dots{}@var{documentation}@dots{}"
3039 (let ((message-log-max nil) done (first t) (code 0) char)
3041 (let ((inhibit-quit first)
3043 (and prompt (message "%s-" prompt))
3044 (setq char (read-event))
3045 (if inhibit-quit (setq quit-flag nil)))
3046 @r{@dots{}set the variable @code{code}@dots{}})
3051 If this variable is non-@code{nil}, then Emacs quits immediately, unless
3052 @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
3053 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
3056 @defvar inhibit-quit
3057 This variable determines whether Emacs should quit when @code{quit-flag}
3058 is set to a value other than @code{nil}. If @code{inhibit-quit} is
3059 non-@code{nil}, then @code{quit-flag} has no special effect.
3062 @defmac with-local-quit body@dots{}
3063 This macro executes @var{body} forms in sequence, but allows quitting, at
3064 least locally, within @var{body} even if @code{inhibit-quit} was
3065 non-@code{nil} outside this construct. It returns the value of the
3066 last form in @var{body}, unless exited by quitting, in which case
3067 it returns @code{nil}.
3069 If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit},
3070 it only executes the @var{body}, and setting @code{quit-flag} causes
3071 a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so
3072 that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag}
3073 triggers a special kind of local quit. This ends the execution of
3074 @var{body} and exits the @code{with-local-quit} body with
3075 @code{quit-flag} still non-@code{nil}, so that another (ordinary) quit
3076 will happen as soon as that is allowed. If @code{quit-flag} is
3077 already non-@code{nil} at the beginning of @var{body}, the local quit
3078 happens immediately and the body doesn't execute at all.
3080 This macro is mainly useful in functions that can be called from
3081 timers, process filters, process sentinels, @code{pre-command-hook},
3082 @code{post-command-hook}, and other places where @code{inhibit-quit} is
3083 normally bound to @code{t}.
3086 @deffn Command keyboard-quit
3087 This function signals the @code{quit} condition with @code{(signal 'quit
3088 nil)}. This is the same thing that quitting does. (See @code{signal}
3092 You can specify a character other than @kbd{C-g} to use for quitting.
3093 See the function @code{set-input-mode} in @ref{Input Modes}.
3095 @node Prefix Command Arguments
3096 @section Prefix Command Arguments
3097 @cindex prefix argument
3098 @cindex raw prefix argument
3099 @cindex numeric prefix argument
3101 Most Emacs commands can use a @dfn{prefix argument}, a number
3102 specified before the command itself. (Don't confuse prefix arguments
3103 with prefix keys.) The prefix argument is at all times represented by a
3104 value, which may be @code{nil}, meaning there is currently no prefix
3105 argument. Each command may use the prefix argument or ignore it.
3107 There are two representations of the prefix argument: @dfn{raw} and
3108 @dfn{numeric}. The editor command loop uses the raw representation
3109 internally, and so do the Lisp variables that store the information, but
3110 commands can request either representation.
3112 Here are the possible values of a raw prefix argument:
3116 @code{nil}, meaning there is no prefix argument. Its numeric value is
3117 1, but numerous commands make a distinction between @code{nil} and the
3121 An integer, which stands for itself.
3124 A list of one element, which is an integer. This form of prefix
3125 argument results from one or a succession of @kbd{C-u}s with no
3126 digits. The numeric value is the integer in the list, but some
3127 commands make a distinction between such a list and an integer alone.
3130 The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was
3131 typed, without following digits. The equivalent numeric value is
3132 @minus{}1, but some commands make a distinction between the integer
3133 @minus{}1 and the symbol @code{-}.
3136 We illustrate these possibilities by calling the following function with
3141 (defun display-prefix (arg)
3142 "Display the value of the raw prefix arg."
3149 Here are the results of calling @code{display-prefix} with various
3150 raw prefix arguments:
3153 M-x display-prefix @print{} nil
3155 C-u M-x display-prefix @print{} (4)
3157 C-u C-u M-x display-prefix @print{} (16)
3159 C-u 3 M-x display-prefix @print{} 3
3161 M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
3163 C-u - M-x display-prefix @print{} -
3165 M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
3167 C-u - 7 M-x display-prefix @print{} -7
3169 M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
3172 Emacs uses two variables to store the prefix argument:
3173 @code{prefix-arg} and @code{current-prefix-arg}. Commands such as
3174 @code{universal-argument} that set up prefix arguments for other
3175 commands store them in @code{prefix-arg}. In contrast,
3176 @code{current-prefix-arg} conveys the prefix argument to the current
3177 command, so setting it has no effect on the prefix arguments for future
3180 Normally, commands specify which representation to use for the prefix
3181 argument, either numeric or raw, in the @code{interactive} specification.
3182 (@xref{Using Interactive}.) Alternatively, functions may look at the
3183 value of the prefix argument directly in the variable
3184 @code{current-prefix-arg}, but this is less clean.
3186 @defun prefix-numeric-value arg
3187 This function returns the numeric meaning of a valid raw prefix argument
3188 value, @var{arg}. The argument may be a symbol, a number, or a list.
3189 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
3190 value @minus{}1 is returned; if it is a number, that number is returned;
3191 if it is a list, the @sc{car} of that list (which should be a number) is
3195 @defvar current-prefix-arg
3196 This variable holds the raw prefix argument for the @emph{current}
3197 command. Commands may examine it directly, but the usual method for
3198 accessing it is with @code{(interactive "P")}.
3202 The value of this variable is the raw prefix argument for the
3203 @emph{next} editing command. Commands such as @code{universal-argument}
3204 that specify prefix arguments for the following command work by setting
3208 @defvar last-prefix-arg
3209 The raw prefix argument value used by the previous command.
3212 The following commands exist to set up prefix arguments for the
3213 following command. Do not call them for any other reason.
3215 @deffn Command universal-argument
3216 This command reads input and specifies a prefix argument for the
3217 following command. Don't call this command yourself unless you know
3221 @deffn Command digit-argument arg
3222 This command adds to the prefix argument for the following command. The
3223 argument @var{arg} is the raw prefix argument as it was before this
3224 command; it is used to compute the updated prefix argument. Don't call
3225 this command yourself unless you know what you are doing.
3228 @deffn Command negative-argument arg
3229 This command adds to the numeric argument for the next command. The
3230 argument @var{arg} is the raw prefix argument as it was before this
3231 command; its value is negated to form the new prefix argument. Don't
3232 call this command yourself unless you know what you are doing.
3235 @node Recursive Editing
3236 @section Recursive Editing
3237 @cindex recursive command loop
3238 @cindex recursive editing level
3239 @cindex command loop, recursive
3241 The Emacs command loop is entered automatically when Emacs starts up.
3242 This top-level invocation of the command loop never exits; it keeps
3243 running as long as Emacs does. Lisp programs can also invoke the
3244 command loop. Since this makes more than one activation of the command
3245 loop, we call it @dfn{recursive editing}. A recursive editing level has
3246 the effect of suspending whatever command invoked it and permitting the
3247 user to do arbitrary editing before resuming that command.
3249 The commands available during recursive editing are the same ones
3250 available in the top-level editing loop and defined in the keymaps.
3251 Only a few special commands exit the recursive editing level; the others
3252 return to the recursive editing level when they finish. (The special
3253 commands for exiting are always available, but they do nothing when
3254 recursive editing is not in progress.)
3256 All command loops, including recursive ones, set up all-purpose error
3257 handlers so that an error in a command run from the command loop will
3260 @cindex minibuffer input
3261 Minibuffer input is a special kind of recursive editing. It has a few
3262 special wrinkles, such as enabling display of the minibuffer and the
3263 minibuffer window, but fewer than you might suppose. Certain keys
3264 behave differently in the minibuffer, but that is only because of the
3265 minibuffer's local map; if you switch windows, you get the usual Emacs
3268 @cindex @code{throw} example
3270 @cindex exit recursive editing
3272 To invoke a recursive editing level, call the function
3273 @code{recursive-edit}. This function contains the command loop; it also
3274 contains a call to @code{catch} with tag @code{exit}, which makes it
3275 possible to exit the recursive editing level by throwing to @code{exit}
3276 (@pxref{Catch and Throw}). If you throw a value other than @code{t},
3277 then @code{recursive-edit} returns normally to the function that called
3278 it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
3279 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
3280 control returns to the command loop one level up. This is called
3281 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
3283 Most applications should not use recursive editing, except as part of
3284 using the minibuffer. Usually it is more convenient for the user if you
3285 change the major mode of the current buffer temporarily to a special
3286 major mode, which should have a command to go back to the previous mode.
3287 (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
3288 give the user different text to edit ``recursively'', create and select
3289 a new buffer in a special mode. In this mode, define a command to
3290 complete the processing and go back to the previous buffer. (The
3291 @kbd{m} command in Rmail does this.)
3293 Recursive edits are useful in debugging. You can insert a call to
3294 @code{debug} into a function definition as a sort of breakpoint, so that
3295 you can look around when the function gets there. @code{debug} invokes
3296 a recursive edit but also provides the other features of the debugger.
3298 Recursive editing levels are also used when you type @kbd{C-r} in
3299 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
3301 @deffn Command recursive-edit
3302 @cindex suspend evaluation
3303 This function invokes the editor command loop. It is called
3304 automatically by the initialization of Emacs, to let the user begin
3305 editing. When called from a Lisp program, it enters a recursive editing
3308 If the current buffer is not the same as the selected window's buffer,
3309 @code{recursive-edit} saves and restores the current buffer. Otherwise,
3310 if you switch buffers, the buffer you switched to is current after
3311 @code{recursive-edit} returns.
3313 In the following example, the function @code{simple-rec} first
3314 advances point one word, then enters a recursive edit, printing out a
3315 message in the echo area. The user can then do any editing desired, and
3316 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
3319 (defun simple-rec ()
3321 (message "Recursive edit in progress")
3324 @result{} simple-rec
3330 @deffn Command exit-recursive-edit
3331 This function exits from the innermost recursive edit (including
3332 minibuffer input). Its definition is effectively @code{(throw 'exit
3336 @deffn Command abort-recursive-edit
3337 This function aborts the command that requested the innermost recursive
3338 edit (including minibuffer input), by signaling @code{quit}
3339 after exiting the recursive edit. Its definition is effectively
3340 @code{(throw 'exit t)}. @xref{Quitting}.
3343 @deffn Command top-level
3344 This function exits all recursive editing levels; it does not return a
3345 value, as it jumps completely out of any computation directly back to
3346 the main command loop.
3349 @defun recursion-depth
3350 This function returns the current depth of recursive edits. When no
3351 recursive edit is active, it returns 0.
3354 @node Disabling Commands
3355 @section Disabling Commands
3356 @cindex disabled command
3358 @dfn{Disabling a command} marks the command as requiring user
3359 confirmation before it can be executed. Disabling is used for commands
3360 which might be confusing to beginning users, to prevent them from using
3361 the commands by accident.
3364 The low-level mechanism for disabling a command is to put a
3365 non-@code{nil} @code{disabled} property on the Lisp symbol for the
3366 command. These properties are normally set up by the user's
3367 init file (@pxref{Init File}) with Lisp expressions such as this:
3370 (put 'upcase-region 'disabled t)
3374 For a few commands, these properties are present by default (you can
3375 remove them in your init file if you wish).
3377 If the value of the @code{disabled} property is a string, the message
3378 saying the command is disabled includes that string. For example:
3381 (put 'delete-region 'disabled
3382 "Text deleted this way cannot be yanked back!\n")
3385 @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on
3386 what happens when a disabled command is invoked interactively.
3387 Disabling a command has no effect on calling it as a function from Lisp
3390 @deffn Command enable-command command
3391 Allow @var{command} (a symbol) to be executed without special
3392 confirmation from now on, and alter the user's init file (@pxref{Init
3393 File}) so that this will apply to future sessions.
3396 @deffn Command disable-command command
3397 Require special confirmation to execute @var{command} from now on, and
3398 alter the user's init file so that this will apply to future sessions.
3401 @defvar disabled-command-function
3402 The value of this variable should be a function. When the user
3403 invokes a disabled command interactively, this function is called
3404 instead of the disabled command. It can use @code{this-command-keys}
3405 to determine what the user typed to run the command, and thus find the
3408 The value may also be @code{nil}. Then all commands work normally,
3411 By default, the value is a function that asks the user whether to
3415 @node Command History
3416 @section Command History
3417 @cindex command history
3418 @cindex complex command
3419 @cindex history of commands
3421 The command loop keeps a history of the complex commands that have
3422 been executed, to make it convenient to repeat these commands. A
3423 @dfn{complex command} is one for which the interactive argument reading
3424 uses the minibuffer. This includes any @kbd{M-x} command, any
3425 @kbd{M-:} command, and any command whose @code{interactive}
3426 specification reads an argument from the minibuffer. Explicit use of
3427 the minibuffer during the execution of the command itself does not cause
3428 the command to be considered complex.
3430 @defvar command-history
3431 This variable's value is a list of recent complex commands, each
3432 represented as a form to evaluate. It continues to accumulate all
3433 complex commands for the duration of the editing session, but when it
3434 reaches the maximum size (@pxref{Minibuffer History}), the oldest
3435 elements are deleted as new ones are added.
3440 @result{} ((switch-to-buffer "chistory.texi")
3441 (describe-key "^X^[")
3442 (visit-tags-table "~/emacs/src/")
3443 (find-tag "repeat-complex-command"))
3448 This history list is actually a special case of minibuffer history
3449 (@pxref{Minibuffer History}), with one special twist: the elements are
3450 expressions rather than strings.
3452 There are a number of commands devoted to the editing and recall of
3453 previous commands. The commands @code{repeat-complex-command}, and
3454 @code{list-command-history} are described in the user manual
3455 (@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the
3456 minibuffer, the usual minibuffer history commands are available.
3458 @node Keyboard Macros
3459 @section Keyboard Macros
3460 @cindex keyboard macros
3462 A @dfn{keyboard macro} is a canned sequence of input events that can
3463 be considered a command and made the definition of a key. The Lisp
3464 representation of a keyboard macro is a string or vector containing the
3465 events. Don't confuse keyboard macros with Lisp macros
3468 @defun execute-kbd-macro kbdmacro &optional count loopfunc
3469 This function executes @var{kbdmacro} as a sequence of events. If
3470 @var{kbdmacro} is a string or vector, then the events in it are executed
3471 exactly as if they had been input by the user. The sequence is
3472 @emph{not} expected to be a single key sequence; normally a keyboard
3473 macro definition consists of several key sequences concatenated.
3475 If @var{kbdmacro} is a symbol, then its function definition is used in
3476 place of @var{kbdmacro}. If that is another symbol, this process repeats.
3477 Eventually the result should be a string or vector. If the result is
3478 not a symbol, string, or vector, an error is signaled.
3480 The argument @var{count} is a repeat count; @var{kbdmacro} is executed that
3481 many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is
3482 executed once. If it is 0, @var{kbdmacro} is executed over and over until it
3483 encounters an error or a failing search.
3485 If @var{loopfunc} is non-@code{nil}, it is a function that is called,
3486 without arguments, prior to each iteration of the macro. If
3487 @var{loopfunc} returns @code{nil}, then this stops execution of the macro.
3489 @xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
3492 @defvar executing-kbd-macro
3493 This variable contains the string or vector that defines the keyboard
3494 macro that is currently executing. It is @code{nil} if no macro is
3495 currently executing. A command can test this variable so as to behave
3496 differently when run from an executing macro. Do not set this variable
3500 @defvar defining-kbd-macro
3501 This variable is non-@code{nil} if and only if a keyboard macro is
3502 being defined. A command can test this variable so as to behave
3503 differently while a macro is being defined. The value is
3504 @code{append} while appending to the definition of an existing macro.
3505 The commands @code{start-kbd-macro}, @code{kmacro-start-macro} and
3506 @code{end-kbd-macro} set this variable---do not set it yourself.
3508 The variable is always local to the current terminal and cannot be
3509 buffer-local. @xref{Multiple Terminals}.
3512 @defvar last-kbd-macro
3513 This variable is the definition of the most recently defined keyboard
3514 macro. Its value is a string or vector, or @code{nil}.
3516 The variable is always local to the current terminal and cannot be
3517 buffer-local. @xref{Multiple Terminals}.
3520 @defvar kbd-macro-termination-hook
3521 This normal hook is run when a keyboard macro terminates, regardless
3522 of what caused it to terminate (reaching the macro end or an error
3523 which ended the macro prematurely).