2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
4 @c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/commands
7 @node Command Loop, Keymaps, Minibuffers, Top
9 @cindex editor command loop
12 When you run Emacs, it enters the @dfn{editor command loop} almost
13 immediately. This loop reads key sequences, executes their definitions,
14 and displays the results. In this chapter, we describe how these things
15 are done, and the subroutines that allow Lisp programs to do them.
18 * Command Overview:: How the command loop reads commands.
19 * Defining Commands:: Specifying how a function should read arguments.
20 * Interactive Call:: Calling a command, so that it will read arguments.
21 * Distinguish Interactive:: Making a command distinguish interactive calls.
22 * Command Loop Info:: Variables set by the command loop for you to examine.
23 * Adjusting Point:: Adjustment of point after a command.
24 * Input Events:: What input looks like when you read it.
25 * Reading Input:: How to read input events from the keyboard or mouse.
26 * Special Events:: Events processed immediately and individually.
27 * Waiting:: Waiting for user input or elapsed time.
28 * Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
29 * Prefix Command Arguments:: How the commands to set prefix args work.
30 * Recursive Editing:: Entering a recursive edit,
31 and why you usually shouldn't.
32 * Disabling Commands:: How the command loop handles disabled commands.
33 * Command History:: How the command history is set up, and how accessed.
34 * Keyboard Macros:: How keyboard macros are implemented.
37 @node Command Overview
38 @section Command Loop Overview
40 The first thing the command loop must do is read a key sequence, which
41 is a sequence of events that translates into a command. It does this by
42 calling the function @code{read-key-sequence}. Your Lisp code can also
43 call this function (@pxref{Key Sequence Input}). Lisp programs can also
44 do input at a lower level with @code{read-event} (@pxref{Reading One
45 Event}) or discard pending input with @code{discard-input}
46 (@pxref{Event Input Misc}).
48 The key sequence is translated into a command through the currently
49 active keymaps. @xref{Key Lookup}, for information on how this is done.
50 The result should be a keyboard macro or an interactively callable
51 function. If the key is @kbd{M-x}, then it reads the name of another
52 command, which it then calls. This is done by the command
53 @code{execute-extended-command} (@pxref{Interactive Call}).
55 To execute a command requires first reading the arguments for it.
56 This is done by calling @code{command-execute} (@pxref{Interactive
57 Call}). For commands written in Lisp, the @code{interactive}
58 specification says how to read the arguments. This may use the prefix
59 argument (@pxref{Prefix Command Arguments}) or may read with prompting
60 in the minibuffer (@pxref{Minibuffers}). For example, the command
61 @code{find-file} has an @code{interactive} specification which says to
62 read a file name using the minibuffer. The command's function body does
63 not use the minibuffer; if you call this command from Lisp code as a
64 function, you must supply the file name string as an ordinary Lisp
67 If the command is a string or vector (i.e., a keyboard macro) then
68 @code{execute-kbd-macro} is used to execute it. You can call this
69 function yourself (@pxref{Keyboard Macros}).
71 To terminate the execution of a running command, type @kbd{C-g}. This
72 character causes @dfn{quitting} (@pxref{Quitting}).
74 @defvar pre-command-hook
75 The editor command loop runs this normal hook before each command. At
76 that time, @code{this-command} contains the command that is about to
77 run, and @code{last-command} describes the previous command.
78 @xref{Command Loop Info}.
81 @defvar post-command-hook
82 The editor command loop runs this normal hook after each command
83 (including commands terminated prematurely by quitting or by errors),
84 and also when the command loop is first entered. At that time,
85 @code{this-command} refers to the command that just ran, and
86 @code{last-command} refers to the command before that.
89 Quitting is suppressed while running @code{pre-command-hook} and
90 @code{post-command-hook}. If an error happens while executing one of
91 these hooks, it terminates execution of the hook, and clears the hook
92 variable to @code{nil} so as to prevent an infinite loop of errors.
94 A request coming into the Emacs server (@pxref{Emacs Server,,,
95 emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard
98 @node Defining Commands
99 @section Defining Commands
100 @cindex defining commands
101 @cindex commands, defining
102 @cindex functions, making them interactive
103 @cindex interactive function
105 A Lisp function becomes a command when its body contains, at top
106 level, a form that calls the special form @code{interactive}, or if
107 the function's symbol has an @code{interactive-form} property. This
108 form does nothing when actually executed, but its presence serves as a
109 flag to indicate that interactive calling is permitted. Its argument
110 controls the reading of arguments for an interactive call.
113 * Using Interactive:: General rules for @code{interactive}.
114 * Interactive Codes:: The standard letter-codes for reading arguments
116 * Interactive Examples:: Examples of how to read interactive arguments.
119 @node Using Interactive
120 @subsection Using @code{interactive}
121 @cindex arguments, interactive entry
123 This section describes how to write the @code{interactive} form that
124 makes a Lisp function an interactively-callable command, and how to
125 examine a command's @code{interactive} form.
127 @defspec interactive arg-descriptor
128 This special form declares that the function in which it appears is a
129 command, and that it may therefore be called interactively (via
130 @kbd{M-x} or by entering a key sequence bound to it). The argument
131 @var{arg-descriptor} declares how to compute the arguments to the
132 command when the command is called interactively.
134 A command may be called from Lisp programs like any other function, but
135 then the caller supplies the arguments and @var{arg-descriptor} has no
138 The @code{interactive} form has its effect because the command loop
139 (actually, its subroutine @code{call-interactively}) scans through the
140 function definition looking for it, before calling the function. Once
141 the function is called, all its body forms including the
142 @code{interactive} form are executed, but at this time
143 @code{interactive} simply returns @code{nil} without even evaluating its
146 @cindex @code{interactive-form}, function property
147 An interactive form can be added to a function post-facto via the
148 @code{interactive-form} property of the function's symbol.
149 @xref{Symbol Plists}.
152 There are three possibilities for the argument @var{arg-descriptor}:
156 It may be omitted or @code{nil}; then the command is called with no
157 arguments. This leads quickly to an error if the command requires one
161 It may be a string; then its contents should consist of a code character
162 followed by a prompt (which some code characters use and some ignore).
163 The prompt ends either with the end of the string or with a newline.
164 Here is a simple example:
167 (interactive "bFrobnicate buffer: ")
171 The code letter @samp{b} says to read the name of an existing buffer,
172 with completion. The buffer name is the sole argument passed to the
173 command. The rest of the string is a prompt.
175 If there is a newline character in the string, it terminates the prompt.
176 If the string does not end there, then the rest of the string should
177 contain another code character and prompt, specifying another argument.
178 You can specify any number of arguments in this way.
181 The prompt string can use @samp{%} to include previous argument values
182 (starting with the first argument) in the prompt. This is done using
183 @code{format} (@pxref{Formatting Strings}). For example, here is how
184 you could read the name of an existing buffer followed by a new name to
189 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
193 @cindex @samp{*} in @code{interactive}
194 @cindex read-only buffers in interactive
195 If @samp{*} appears at the beginning of the string, then an error is
196 signaled if the buffer is read-only.
198 @cindex @samp{@@} in @code{interactive}
200 If @samp{@@} appears at the beginning of the string, and if the key
201 sequence used to invoke the command includes any mouse events, then
202 the window associated with the first of those events is selected
203 before the command is run.
205 @cindex @samp{^} in @code{interactive}
206 @cindex shift-selection, and @code{interactive} spec
207 If @samp{^} appears at the beginning of the string, and if the command
208 was invoked through @dfn{shift-translation}, set the mark and activate
209 the region temporarily, or extend an already active region, before the
210 command is run. If the command was invoked without shift-translation,
211 and the region is temporarily active, deactivate the region before the
212 command is run. Shift-translation is controlled on the user level by
213 @code{shift-select-mode}; see @ref{Shift Selection,,, emacs, The GNU
216 You can use @samp{*}, @samp{@@}, and @code{^} together; the order does
217 not matter. Actual reading of arguments is controlled by the rest of
218 the prompt string (starting with the first character that is not
219 @samp{*}, @samp{@@}, or @samp{^}).
222 It may be a Lisp expression that is not a string; then it should be a
223 form that is evaluated to get a list of arguments to pass to the
224 command. Usually this form will call various functions to read input
225 from the user, most often through the minibuffer (@pxref{Minibuffers})
226 or directly from the keyboard (@pxref{Reading Input}).
228 Providing point or the mark as an argument value is also common, but
229 if you do this @emph{and} read input (whether using the minibuffer or
230 not), be sure to get the integer values of point or the mark after
231 reading. The current buffer may be receiving subprocess output; if
232 subprocess output arrives while the command is waiting for input, it
233 could relocate point and the mark.
235 Here's an example of what @emph{not} to do:
239 (list (region-beginning) (region-end)
240 (read-string "Foo: " nil 'my-history)))
244 Here's how to avoid the problem, by examining point and the mark after
245 reading the keyboard input:
249 (let ((string (read-string "Foo: " nil 'my-history)))
250 (list (region-beginning) (region-end) string)))
253 @strong{Warning:} the argument values should not include any data
254 types that can't be printed and then read. Some facilities save
255 @code{command-history} in a file to be read in the subsequent
256 sessions; if a command's arguments contain a data type that prints
257 using @samp{#<@dots{}>} syntax, those facilities won't work.
259 There are, however, a few exceptions: it is ok to use a limited set of
260 expressions such as @code{(point)}, @code{(mark)},
261 @code{(region-beginning)}, and @code{(region-end)}, because Emacs
262 recognizes them specially and puts the expression (rather than its
263 value) into the command history. To see whether the expression you
264 wrote is one of these exceptions, run the command, then examine
265 @code{(car command-history)}.
268 @cindex examining the @code{interactive} form
269 @defun interactive-form function
270 This function returns the @code{interactive} form of @var{function}.
271 If @var{function} is an interactively callable function
272 (@pxref{Interactive Call}), the value is the command's
273 @code{interactive} form @code{(interactive @var{spec})}, which
274 specifies how to compute its arguments. Otherwise, the value is
275 @code{nil}. If @var{function} is a symbol, its function definition is
279 @node Interactive Codes
280 @comment node-name, next, previous, up
281 @subsection Code Characters for @code{interactive}
282 @cindex interactive code description
283 @cindex description for interactive codes
284 @cindex codes, interactive, description of
285 @cindex characters for interactive codes
287 The code character descriptions below contain a number of key words,
288 defined here as follows:
292 @cindex interactive completion
293 Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name
294 completion because the argument is read using @code{completing-read}
295 (@pxref{Completion}). @kbd{?} displays a list of possible completions.
298 Require the name of an existing object. An invalid name is not
299 accepted; the commands to exit the minibuffer do not exit if the current
303 @cindex default argument string
304 A default value of some sort is used if the user enters no text in the
305 minibuffer. The default depends on the code character.
308 This code letter computes an argument without reading any input.
309 Therefore, it does not use a prompt string, and any prompt string you
312 Even though the code letter doesn't use a prompt string, you must follow
313 it with a newline if it is not the last code character in the string.
316 A prompt immediately follows the code character. The prompt ends either
317 with the end of the string or with a newline.
320 This code character is meaningful only at the beginning of the
321 interactive string, and it does not look for a prompt or a newline.
322 It is a single, isolated character.
325 @cindex reading interactive arguments
326 Here are the code character descriptions for use with @code{interactive}:
330 Signal an error if the current buffer is read-only. Special.
333 Select the window mentioned in the first mouse event in the key
334 sequence that invoked this command. Special.
337 If the command was invoked through shift-translation, set the mark and
338 activate the region temporarily, or extend an already active region,
339 before the command is run. If the command was invoked without
340 shift-translation, and the region is temporarily active, deactivate
341 the region before the command is run. Special.
344 A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
348 The name of an existing buffer. By default, uses the name of the
349 current buffer (@pxref{Buffers}). Existing, Completion, Default,
353 A buffer name. The buffer need not exist. By default, uses the name of
354 a recently used buffer other than the current buffer. Completion,
358 A character. The cursor does not move into the echo area. Prompt.
361 A command name (i.e., a symbol satisfying @code{commandp}). Existing,
365 @cindex position argument
366 The position of point, as an integer (@pxref{Point}). No I/O.
369 A directory name. The default is the current default directory of the
370 current buffer, @code{default-directory} (@pxref{File Name Expansion}).
371 Existing, Completion, Default, Prompt.
374 The first or next mouse event in the key sequence that invoked the command.
375 More precisely, @samp{e} gets events that are lists, so you can look at
376 the data in the lists. @xref{Input Events}. No I/O.
378 You can use @samp{e} more than once in a single command's interactive
379 specification. If the key sequence that invoked the command has
380 @var{n} events that are lists, the @var{n}th @samp{e} provides the
381 @var{n}th such event. Events that are not lists, such as function keys
382 and @acronym{ASCII} characters, do not count where @samp{e} is concerned.
385 A file name of an existing file (@pxref{File Names}). The default
386 directory is @code{default-directory}. Existing, Completion, Default,
390 A file name. The file need not exist. Completion, Default, Prompt.
393 A file name. The file need not exist. If the user enters just a
394 directory name, then the value is just that directory name, with no
395 file name within the directory added. Completion, Default, Prompt.
398 An irrelevant argument. This code always supplies @code{nil} as
399 the argument's value. No I/O.
402 A key sequence (@pxref{Key Sequences}). This keeps reading events
403 until a command (or undefined command) is found in the current key
404 maps. The key sequence argument is represented as a string or vector.
405 The cursor does not move into the echo area. Prompt.
407 If @samp{k} reads a key sequence that ends with a down-event, it also
408 reads and discards the following up-event. You can get access to that
409 up-event with the @samp{U} code character.
411 This kind of input is used by commands such as @code{describe-key} and
412 @code{global-set-key}.
415 A key sequence, whose definition you intend to change. This works like
416 @samp{k}, except that it suppresses, for the last input event in the key
417 sequence, the conversions that are normally used (when necessary) to
418 convert an undefined key into a defined one.
421 @cindex marker argument
422 The position of the mark, as an integer. No I/O.
425 Arbitrary text, read in the minibuffer using the current buffer's input
426 method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
427 Emacs Manual}). Prompt.
430 A number, read with the minibuffer. If the input is not a number, the
431 user has to try again. @samp{n} never uses the prefix argument.
435 The numeric prefix argument; but if there is no prefix argument, read
436 a number as with @kbd{n}. The value is always a number. @xref{Prefix
437 Command Arguments}. Prompt.
440 @cindex numeric prefix argument usage
441 The numeric prefix argument. (Note that this @samp{p} is lower case.)
445 @cindex raw prefix argument usage
446 The raw prefix argument. (Note that this @samp{P} is upper case.) No
450 @cindex region argument
451 Point and the mark, as two numeric arguments, smallest first. This is
452 the only code letter that specifies two successive arguments rather than
456 Arbitrary text, read in the minibuffer and returned as a string
457 (@pxref{Text from Minibuffer}). Terminate the input with either
458 @kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of
459 these characters in the input.) Prompt.
462 An interned symbol whose name is read in the minibuffer. Any whitespace
463 character terminates the input. (Use @kbd{C-q} to include whitespace in
464 the string.) Other characters that normally terminate a symbol (e.g.,
465 parentheses and brackets) do not do so here. Prompt.
468 A key sequence or @code{nil}. Can be used after a @samp{k} or
469 @samp{K} argument to get the up-event that was discarded (if any)
470 after @samp{k} or @samp{K} read a down-event. If no up-event has been
471 discarded, @samp{U} provides @code{nil} as the argument. No I/O.
474 A variable declared to be a user option (i.e., satisfying the
475 predicate @code{user-variable-p}). This reads the variable using
476 @code{read-variable}. @xref{Definition of read-variable}. Existing,
480 A Lisp object, specified with its read syntax, terminated with a
481 @kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from
485 @cindex evaluated expression argument
486 A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates
487 the form so that its value becomes the argument for the command.
491 A coding system name (a symbol). If the user enters null input, the
492 argument value is @code{nil}. @xref{Coding Systems}. Completion,
496 A coding system name (a symbol)---but only if this command has a prefix
497 argument. With no prefix argument, @samp{Z} provides @code{nil} as the
498 argument value. Completion, Existing, Prompt.
501 @node Interactive Examples
502 @comment node-name, next, previous, up
503 @subsection Examples of Using @code{interactive}
504 @cindex examples of using @code{interactive}
505 @cindex @code{interactive}, examples of using
507 Here are some examples of @code{interactive}:
511 (defun foo1 () ; @r{@code{foo1} takes no arguments,}
512 (interactive) ; @r{just moves forward two words.}
518 (defun foo2 (n) ; @r{@code{foo2} takes one argument,}
519 (interactive "^p") ; @r{which is the numeric prefix.}
520 ; @r{under @code{shift-select-mode},}
521 ; @r{will activate or extend region.}
522 (forward-word (* 2 n)))
527 (defun foo3 (n) ; @r{@code{foo3} takes one argument,}
528 (interactive "nCount:") ; @r{which is read with the Minibuffer.}
529 (forward-word (* 2 n)))
534 (defun three-b (b1 b2 b3)
535 "Select three existing buffers.
536 Put them into three windows, selecting the last one."
538 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
539 (delete-other-windows)
540 (split-window (selected-window) 8)
541 (switch-to-buffer b1)
543 (split-window (selected-window) 8)
544 (switch-to-buffer b2)
546 (switch-to-buffer b3))
549 (three-b "*scratch*" "declarations.texi" "*mail*")
554 @node Interactive Call
555 @section Interactive Call
556 @cindex interactive call
558 After the command loop has translated a key sequence into a command it
559 invokes that command using the function @code{command-execute}. If the
560 command is a function, @code{command-execute} calls
561 @code{call-interactively}, which reads the arguments and calls the
562 command. You can also call these functions yourself.
564 @defun commandp object &optional for-call-interactively
565 Returns @code{t} if @var{object} is suitable for calling interactively;
566 that is, if @var{object} is a command. Otherwise, returns @code{nil}.
568 The interactively callable objects include strings and vectors (treated
569 as keyboard macros), lambda expressions that contain a top-level call to
570 @code{interactive}, byte-code function objects made from such lambda
571 expressions, autoload objects that are declared as interactive
572 (non-@code{nil} fourth argument to @code{autoload}), and some of the
575 A symbol satisfies @code{commandp} if its function definition
576 satisfies @code{commandp}. Keys and keymaps are not commands.
577 Rather, they are used to look up commands (@pxref{Keymaps}).
579 If @var{for-call-interactively} is non-@code{nil}, then
580 @code{commandp} returns @code{t} only for objects that
581 @code{call-interactively} could call---thus, not for keyboard macros.
583 See @code{documentation} in @ref{Accessing Documentation}, for a
584 realistic example of using @code{commandp}.
587 @defun call-interactively command &optional record-flag keys
588 This function calls the interactively callable function @var{command},
589 reading arguments according to its interactive calling specifications.
590 It returns whatever @var{command} returns. An error is signaled if
591 @var{command} is not a function or if it cannot be called
592 interactively (i.e., is not a command). Note that keyboard macros
593 (strings and vectors) are not accepted, even though they are
594 considered commands, because they are not functions. If @var{command}
595 is a symbol, then @code{call-interactively} uses its function definition.
597 @cindex record command history
598 If @var{record-flag} is non-@code{nil}, then this command and its
599 arguments are unconditionally added to the list @code{command-history}.
600 Otherwise, the command is added only if it uses the minibuffer to read
601 an argument. @xref{Command History}.
603 The argument @var{keys}, if given, should be a vector which specifies
604 the sequence of events to supply if the command inquires which events
605 were used to invoke it. If @var{keys} is omitted or @code{nil}, the
606 default is the return value of @code{this-command-keys-vector}.
607 @xref{Definition of this-command-keys-vector}.
610 @defun command-execute command &optional record-flag keys special
611 @cindex keyboard macro execution
612 This function executes @var{command}. The argument @var{command} must
613 satisfy the @code{commandp} predicate; i.e., it must be an interactively
614 callable function or a keyboard macro.
616 A string or vector as @var{command} is executed with
617 @code{execute-kbd-macro}. A function is passed to
618 @code{call-interactively}, along with the optional @var{record-flag}
621 A symbol is handled by using its function definition in its place. A
622 symbol with an @code{autoload} definition counts as a command if it was
623 declared to stand for an interactively callable function. Such a
624 definition is handled by loading the specified library and then
625 rechecking the definition of the symbol.
627 The argument @var{special}, if given, means to ignore the prefix
628 argument and not clear it. This is used for executing special events
629 (@pxref{Special Events}).
632 @deffn Command execute-extended-command prefix-argument
633 @cindex read command name
634 This function reads a command name from the minibuffer using
635 @code{completing-read} (@pxref{Completion}). Then it uses
636 @code{command-execute} to call the specified command. Whatever that
637 command returns becomes the value of @code{execute-extended-command}.
639 @cindex execute with prefix argument
640 If the command asks for a prefix argument, it receives the value
641 @var{prefix-argument}. If @code{execute-extended-command} is called
642 interactively, the current raw prefix argument is used for
643 @var{prefix-argument}, and thus passed on to whatever command is run.
645 @c !!! Should this be @kindex?
647 @code{execute-extended-command} is the normal definition of @kbd{M-x},
648 so it uses the string @w{@samp{M-x }} as a prompt. (It would be better
649 to take the prompt from the events used to invoke
650 @code{execute-extended-command}, but that is painful to implement.) A
651 description of the value of the prefix argument, if any, also becomes
656 (execute-extended-command 3)
657 ---------- Buffer: Minibuffer ----------
658 3 M-x forward-word RET
659 ---------- Buffer: Minibuffer ----------
665 @node Distinguish Interactive
666 @section Distinguish Interactive Calls
668 Sometimes a command should display additional visual feedback (such
669 as an informative message in the echo area) for interactive calls
670 only. There are three ways to do this. The recommended way to test
671 whether the function was called using @code{call-interactively} is to
672 give it an optional argument @code{print-message} and use the
673 @code{interactive} spec to make it non-@code{nil} in interactive
674 calls. Here's an example:
677 (defun foo (&optional print-message)
684 We use @code{"p"} because the numeric prefix argument is never
685 @code{nil}. Defined in this way, the function does display the
686 message when called from a keyboard macro.
688 The above method with the additional argument is usually best,
689 because it allows callers to say ``treat this call as interactive.''
690 But you can also do the job in a simpler way by testing
691 @code{called-interactively-p}.
693 @defun called-interactively-p
694 This function returns @code{t} when the calling function was called
695 using @code{call-interactively}.
697 If the containing function was called by Lisp evaluation (or with
698 @code{apply} or @code{funcall}), then it was not called interactively.
701 Here's an example of using @code{called-interactively-p}:
707 (when (called-interactively-p)
714 ;; @r{Type @kbd{M-x foo}.}
724 Here is another example that contrasts direct and indirect
725 calls to @code{called-interactively-p}.
731 (setq foobar (list (foo) (called-interactively-p))))
736 ;; @r{Type @kbd{M-x bar}.}
737 ;; @r{This does not display a message.}
746 If you want to treat commands run in keyboard macros just like calls
747 from Lisp programs, test @code{interactive-p} instead of
748 @code{called-interactively-p}.
751 This function returns @code{t} if the containing function (the one
752 whose code includes the call to @code{interactive-p}) was called in
753 direct response to user input. This means that it was called with the
754 function @code{call-interactively}, and that a keyboard macro is
755 not running, and that Emacs is not running in batch mode.
758 @node Command Loop Info
759 @comment node-name, next, previous, up
760 @section Information from the Command Loop
762 The editor command loop sets several Lisp variables to keep status
763 records for itself and for commands that are run. With the exception of
764 @code{this-command} and @code{last-command} it's generally a bad idea to
765 change any of these variables in a Lisp program.
768 This variable records the name of the previous command executed by the
769 command loop (the one before the current command). Normally the value
770 is a symbol with a function definition, but this is not guaranteed.
772 The value is copied from @code{this-command} when a command returns to
773 the command loop, except when the command has specified a prefix
774 argument for the following command.
776 This variable is always local to the current terminal and cannot be
777 buffer-local. @xref{Multiple Displays}.
780 @defvar real-last-command
781 This variable is set up by Emacs just like @code{last-command},
782 but never altered by Lisp programs.
785 @defvar last-repeatable-command
786 This variable stores the most recently executed command that was not
787 part of an input event. This is the command @code{repeat} will try to
788 repeat, @xref{Repeating,,, emacs, The GNU Emacs Manual}.
792 @cindex current command
793 This variable records the name of the command now being executed by
794 the editor command loop. Like @code{last-command}, it is normally a symbol
795 with a function definition.
797 The command loop sets this variable just before running a command, and
798 copies its value into @code{last-command} when the command finishes
799 (unless the command specified a prefix argument for the following
802 @cindex kill command repetition
803 Some commands set this variable during their execution, as a flag for
804 whatever command runs next. In particular, the functions for killing text
805 set @code{this-command} to @code{kill-region} so that any kill commands
806 immediately following will know to append the killed text to the
810 If you do not want a particular command to be recognized as the previous
811 command in the case where it got an error, you must code that command to
812 prevent this. One way is to set @code{this-command} to @code{t} at the
813 beginning of the command, and set @code{this-command} back to its proper
814 value at the end, like this:
817 (defun foo (args@dots{})
818 (interactive @dots{})
819 (let ((old-this-command this-command))
820 (setq this-command t)
821 @r{@dots{}do the work@dots{}}
822 (setq this-command old-this-command)))
826 We do not bind @code{this-command} with @code{let} because that would
827 restore the old value in case of error---a feature of @code{let} which
828 in this case does precisely what we want to avoid.
830 @defvar this-original-command
831 This has the same value as @code{this-command} except when command
832 remapping occurs (@pxref{Remapping Commands}). In that case,
833 @code{this-command} gives the command actually run (the result of
834 remapping), and @code{this-original-command} gives the command that
835 was specified to run but remapped into another command.
838 @defun this-command-keys
839 This function returns a string or vector containing the key sequence
840 that invoked the present command, plus any previous commands that
841 generated the prefix argument for this command. Any events read by the
842 command using @code{read-event} without a timeout get tacked on to the end.
844 However, if the command has called @code{read-key-sequence}, it
845 returns the last read key sequence. @xref{Key Sequence Input}. The
846 value is a string if all events in the sequence were characters that
847 fit in a string. @xref{Input Events}.
852 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
858 @defun this-command-keys-vector
859 @anchor{Definition of this-command-keys-vector}
860 Like @code{this-command-keys}, except that it always returns the events
861 in a vector, so you don't need to deal with the complexities of storing
862 input events in a string (@pxref{Strings of Events}).
865 @defun clear-this-command-keys &optional keep-record
866 This function empties out the table of events for
867 @code{this-command-keys} to return. Unless @var{keep-record} is
868 non-@code{nil}, it also empties the records that the function
869 @code{recent-keys} (@pxref{Recording Input}) will subsequently return.
870 This is useful after reading a password, to prevent the password from
871 echoing inadvertently as part of the next command in certain cases.
874 @defvar last-nonmenu-event
875 This variable holds the last input event read as part of a key sequence,
876 not counting events resulting from mouse menus.
878 One use of this variable is for telling @code{x-popup-menu} where to pop
879 up a menu. It is also used internally by @code{y-or-n-p}
880 (@pxref{Yes-or-No Queries}).
883 @defvar last-command-event
884 @defvarx last-command-char
885 This variable is set to the last input event that was read by the
886 command loop as part of a command. The principal use of this variable
887 is in @code{self-insert-command}, which uses it to decide which
893 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
899 The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
901 The alias @code{last-command-char} is obsolete.
905 @defvar last-event-frame
906 This variable records which frame the last input event was directed to.
907 Usually this is the frame that was selected when the event was
908 generated, but if that frame has redirected input focus to another
909 frame, the value is the frame to which the event was redirected.
912 If the last event came from a keyboard macro, the value is @code{macro}.
915 @node Adjusting Point
916 @section Adjusting Point After Commands
917 @cindex adjusting point
918 @cindex invisible/intangible text, and point
919 @cindex @code{display} property, and point display
920 @cindex @code{composition} property, and point display
922 It is not easy to display a value of point in the middle of a
923 sequence of text that has the @code{display}, @code{composition} or
924 @code{intangible} property, or is invisible. Therefore, after a
925 command finishes and returns to the command loop, if point is within
926 such a sequence, the command loop normally moves point to the edge of
929 A command can inhibit this feature by setting the variable
930 @code{disable-point-adjustment}:
932 @defvar disable-point-adjustment
933 If this variable is non-@code{nil} when a command returns to the
934 command loop, then the command loop does not check for those text
935 properties, and does not move point out of sequences that have them.
937 The command loop sets this variable to @code{nil} before each command,
938 so if a command sets it, the effect applies only to that command.
941 @defvar global-disable-point-adjustment
942 If you set this variable to a non-@code{nil} value, the feature of
943 moving point out of these sequences is completely turned off.
947 @section Input Events
951 The Emacs command loop reads a sequence of @dfn{input events} that
952 represent keyboard or mouse activity. The events for keyboard activity
953 are characters or symbols; mouse events are always lists. This section
954 describes the representation and meaning of input events in detail.
957 This function returns non-@code{nil} if @var{object} is an input event
960 Note that any symbol might be used as an event or an event type.
961 @code{eventp} cannot distinguish whether a symbol is intended by Lisp
962 code to be used as an event. Instead, it distinguishes whether the
963 symbol has actually been used in an event that has been read as input in
964 the current Emacs session. If a symbol has not yet been so used,
965 @code{eventp} returns @code{nil}.
969 * Keyboard Events:: Ordinary characters--keys with symbols on them.
970 * Function Keys:: Function keys--keys with names, not symbols.
971 * Mouse Events:: Overview of mouse events.
972 * Click Events:: Pushing and releasing a mouse button.
973 * Drag Events:: Moving the mouse before releasing the button.
974 * Button-Down Events:: A button was pushed and not yet released.
975 * Repeat Events:: Double and triple click (or drag, or down).
976 * Motion Events:: Just moving the mouse, not pushing a button.
977 * Focus Events:: Moving the mouse between frames.
978 * Misc Events:: Other events the system can generate.
979 * Event Examples:: Examples of the lists for mouse events.
980 * Classifying Events:: Finding the modifier keys in an event symbol.
982 * Accessing Mouse:: Functions to extract info from mouse events.
983 * Accessing Scroll:: Functions to get info from scroll bar events.
984 * Strings of Events:: Special considerations for putting
985 keyboard character events in a string.
988 @node Keyboard Events
989 @subsection Keyboard Events
990 @cindex keyboard events
992 There are two kinds of input you can get from the keyboard: ordinary
993 keys, and function keys. Ordinary keys correspond to characters; the
994 events they generate are represented in Lisp as characters. The event
995 type of a character event is the character itself (an integer); see
996 @ref{Classifying Events}.
998 @cindex modifier bits (of input character)
999 @cindex basic code (of input character)
1000 An input character event consists of a @dfn{basic code} between 0 and
1001 524287, plus any or all of these @dfn{modifier bits}:
1012 bit in the character code indicates a character
1013 typed with the meta key held down.
1023 bit in the character code indicates a non-@acronym{ASCII}
1026 @sc{ascii} control characters such as @kbd{C-a} have special basic
1027 codes of their own, so Emacs needs no special bit to indicate them.
1028 Thus, the code for @kbd{C-a} is just 1.
1030 But if you type a control combination not in @acronym{ASCII}, such as
1031 @kbd{%} with the control key, the numeric value you get is the code
1039 (assuming the terminal supports non-@acronym{ASCII}
1040 control characters).
1050 bit in the character code indicates an @acronym{ASCII} control
1051 character typed with the shift key held down.
1053 For letters, the basic code itself indicates upper versus lower case;
1054 for digits and punctuation, the shift key selects an entirely different
1055 character with a different basic code. In order to keep within the
1056 @acronym{ASCII} character set whenever possible, Emacs avoids using the
1063 bit for those characters.
1065 However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
1066 @kbd{C-a}, so Emacs uses the
1073 bit in @kbd{C-A} and not in
1084 bit in the character code indicates a character
1085 typed with the hyper key held down.
1095 bit in the character code indicates a character
1096 typed with the super key held down.
1106 bit in the character code indicates a character typed with
1107 the alt key held down. (On some terminals, the key labeled @key{ALT}
1108 is actually the meta key.)
1111 It is best to avoid mentioning specific bit numbers in your program.
1112 To test the modifier bits of a character, use the function
1113 @code{event-modifiers} (@pxref{Classifying Events}). When making key
1114 bindings, you can use the read syntax for characters with modifier bits
1115 (@samp{\C-}, @samp{\M-}, and so on). For making key bindings with
1116 @code{define-key}, you can use lists such as @code{(control hyper ?x)} to
1117 specify the characters (@pxref{Changing Key Bindings}). The function
1118 @code{event-convert-list} converts such a list into an event type
1119 (@pxref{Classifying Events}).
1122 @subsection Function Keys
1124 @cindex function keys
1125 Most keyboards also have @dfn{function keys}---keys that have names or
1126 symbols that are not characters. Function keys are represented in Emacs
1127 Lisp as symbols; the symbol's name is the function key's label, in lower
1128 case. For example, pressing a key labeled @key{F1} places the symbol
1129 @code{f1} in the input stream.
1131 The event type of a function key event is the event symbol itself.
1132 @xref{Classifying Events}.
1134 Here are a few special cases in the symbol-naming convention for
1138 @item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
1139 These keys correspond to common @acronym{ASCII} control characters that have
1140 special keys on most keyboards.
1142 In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the
1143 terminal can distinguish between them, Emacs conveys the distinction to
1144 Lisp programs by representing the former as the integer 9, and the
1145 latter as the symbol @code{tab}.
1147 Most of the time, it's not useful to distinguish the two. So normally
1148 @code{local-function-key-map} (@pxref{Translation Keymaps}) is set up
1149 to map @code{tab} into 9. Thus, a key binding for character code 9
1150 (the character @kbd{C-i}) also applies to @code{tab}. Likewise for
1151 the other symbols in this group. The function @code{read-char}
1152 likewise converts these events into characters.
1154 In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace}
1155 converts into the character code 127 (@key{DEL}), not into code 8
1156 (@key{BS}). This is what most users prefer.
1158 @item @code{left}, @code{up}, @code{right}, @code{down}
1160 @item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
1161 Keypad keys (to the right of the regular keyboard).
1162 @item @code{kp-0}, @code{kp-1}, @dots{}
1163 Keypad keys with digits.
1164 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
1166 @item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
1167 Keypad arrow keys. Emacs normally translates these into the
1168 corresponding non-keypad keys @code{home}, @code{left}, @dots{}
1169 @item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
1170 Additional keypad duplicates of keys ordinarily found elsewhere. Emacs
1171 normally translates these into the like-named non-keypad keys.
1174 You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
1175 @key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to
1176 represent them is with prefixes in the symbol name:
1182 The control modifier.
1193 Thus, the symbol for the key @key{F3} with @key{META} held down is
1194 @code{M-f3}. When you use more than one prefix, we recommend you
1195 write them in alphabetical order; but the order does not matter in
1196 arguments to the key-binding lookup and modification functions.
1199 @subsection Mouse Events
1201 Emacs supports four kinds of mouse events: click events, drag events,
1202 button-down events, and motion events. All mouse events are represented
1203 as lists. The @sc{car} of the list is the event type; this says which
1204 mouse button was involved, and which modifier keys were used with it.
1205 The event type can also distinguish double or triple button presses
1206 (@pxref{Repeat Events}). The rest of the list elements give position
1207 and time information.
1209 For key lookup, only the event type matters: two events of the same type
1210 necessarily run the same command. The command can access the full
1211 values of these events using the @samp{e} interactive code.
1212 @xref{Interactive Codes}.
1214 A key sequence that starts with a mouse event is read using the keymaps
1215 of the buffer in the window that the mouse was in, not the current
1216 buffer. This does not imply that clicking in a window selects that
1217 window or its buffer---that is entirely under the control of the command
1218 binding of the key sequence.
1221 @subsection Click Events
1223 @cindex mouse click event
1225 When the user presses a mouse button and releases it at the same
1226 location, that generates a @dfn{click} event. All mouse click event
1227 share the same format:
1230 (@var{event-type} @var{position} @var{click-count})
1234 @item @var{event-type}
1235 This is a symbol that indicates which mouse button was used. It is
1236 one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the
1237 buttons are numbered left to right.
1239 You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-},
1240 @samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift
1241 and super, just as you would with function keys.
1243 This symbol also serves as the event type of the event. Key bindings
1244 describe events by their types; thus, if there is a key binding for
1245 @code{mouse-1}, that binding would apply to all events whose
1246 @var{event-type} is @code{mouse-1}.
1248 @item @var{position}
1249 This is the position where the mouse click occurred. The actual
1250 format of @var{position} depends on what part of a window was clicked
1253 For mouse click events in the text area, mode line, header line, or in
1254 the marginal areas, @var{position} has this form:
1257 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
1258 @var{object} @var{text-pos} (@var{col} . @var{row})
1259 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
1264 This is the window in which the click occurred.
1266 @item @var{pos-or-area}
1267 This is the buffer position of the character clicked on in the text
1268 area, or if clicked outside the text area, it is the window area in
1269 which the click occurred. It is one of the symbols @code{mode-line},
1270 @code{header-line}, @code{vertical-line}, @code{left-margin},
1271 @code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
1273 In one special case, @var{pos-or-area} is a list containing a symbol (one
1274 of the symbols listed above) instead of just the symbol. This happens
1275 after the imaginary prefix keys for the event are inserted into the
1276 input stream. @xref{Key Sequence Input}.
1279 @item @var{x}, @var{y}
1280 These are the pixel coordinates of the click, relative to
1281 the top left corner of @var{window}, which is @code{(0 . 0)}.
1282 For the mode or header line, @var{y} does not have meaningful data.
1283 For the vertical line, @var{x} does not have meaningful data.
1285 @item @var{timestamp}
1286 This is the time at which the event occurred, in milliseconds.
1289 This is the object on which the click occurred. It is either
1290 @code{nil} if there is no string property, or it has the form
1291 (@var{string} . @var{string-pos}) when there is a string-type text
1292 property at the click position.
1296 This is the string on which the click occurred, including any
1299 @item @var{string-pos}
1300 This is the position in the string on which the click occurred,
1301 relevant if properties at the click need to be looked up.
1304 @item @var{text-pos}
1305 For clicks on a marginal area or on a fringe, this is the buffer
1306 position of the first visible character in the corresponding line in
1307 the window. For other events, it is the current buffer position in
1310 @item @var{col}, @var{row}
1311 These are the actual coordinates of the glyph under the @var{x},
1312 @var{y} position, possibly padded with default character width
1313 glyphs if @var{x} is beyond the last glyph on the line.
1316 This is the image object on which the click occurred. It is either
1317 @code{nil} if there is no image at the position clicked on, or it is
1318 an image object as returned by @code{find-image} if click was in an image.
1320 @item @var{dx}, @var{dy}
1321 These are the pixel coordinates of the click, relative to
1322 the top left corner of @var{object}, which is @code{(0 . 0)}. If
1323 @var{object} is @code{nil}, the coordinates are relative to the top
1324 left corner of the character glyph clicked on.
1326 @item @var{width}, @var{height}
1327 These are the pixel width and height of @var{object} or, if this is
1328 @code{nil}, those of the character glyph clicked on.
1332 For mouse clicks on a scroll-bar, @var{position} has this form:
1335 (@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
1340 This is the window whose scroll-bar was clicked on.
1343 This is the scroll bar where the click occurred. It is one of the
1344 symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.
1347 This is the distance of the click from the top or left end of
1351 This is the length of the entire scroll bar.
1353 @item @var{timestamp}
1354 This is the time at which the event occurred, in milliseconds.
1357 This is the part of the scroll-bar which was clicked on. It is one
1358 of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
1359 @code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
1362 @item @var{click-count}
1363 This is the number of rapid repeated presses so far of the same mouse
1364 button. @xref{Repeat Events}.
1368 @subsection Drag Events
1370 @cindex mouse drag event
1372 With Emacs, you can have a drag event without even changing your
1373 clothes. A @dfn{drag event} happens every time the user presses a mouse
1374 button and then moves the mouse to a different character position before
1375 releasing the button. Like all mouse events, drag events are
1376 represented in Lisp as lists. The lists record both the starting mouse
1377 position and the final position, like this:
1381 (@var{window1} START-POSITION)
1382 (@var{window2} END-POSITION))
1385 For a drag event, the name of the symbol @var{event-type} contains the
1386 prefix @samp{drag-}. For example, dragging the mouse with button 2
1387 held down generates a @code{drag-mouse-2} event. The second and third
1388 elements of the event give the starting and ending position of the
1389 drag. They have the same form as @var{position} in a click event
1390 (@pxref{Click Events}) that is not on the scroll bar part of the
1391 window. You can access the second element of any mouse event in the
1392 same way, with no need to distinguish drag events from others.
1394 The @samp{drag-} prefix follows the modifier key prefixes such as
1395 @samp{C-} and @samp{M-}.
1397 If @code{read-key-sequence} receives a drag event that has no key
1398 binding, and the corresponding click event does have a binding, it
1399 changes the drag event into a click event at the drag's starting
1400 position. This means that you don't have to distinguish between click
1401 and drag events unless you want to.
1403 @node Button-Down Events
1404 @subsection Button-Down Events
1405 @cindex button-down event
1407 Click and drag events happen when the user releases a mouse button.
1408 They cannot happen earlier, because there is no way to distinguish a
1409 click from a drag until the button is released.
1411 If you want to take action as soon as a button is pressed, you need to
1412 handle @dfn{button-down} events.@footnote{Button-down is the
1413 conservative antithesis of drag.} These occur as soon as a button is
1414 pressed. They are represented by lists that look exactly like click
1415 events (@pxref{Click Events}), except that the @var{event-type} symbol
1416 name contains the prefix @samp{down-}. The @samp{down-} prefix follows
1417 modifier key prefixes such as @samp{C-} and @samp{M-}.
1419 The function @code{read-key-sequence} ignores any button-down events
1420 that don't have command bindings; therefore, the Emacs command loop
1421 ignores them too. This means that you need not worry about defining
1422 button-down events unless you want them to do something. The usual
1423 reason to define a button-down event is so that you can track mouse
1424 motion (by reading motion events) until the button is released.
1425 @xref{Motion Events}.
1428 @subsection Repeat Events
1429 @cindex repeat events
1430 @cindex double-click events
1431 @cindex triple-click events
1432 @cindex mouse events, repeated
1434 If you press the same mouse button more than once in quick succession
1435 without moving the mouse, Emacs generates special @dfn{repeat} mouse
1436 events for the second and subsequent presses.
1438 The most common repeat events are @dfn{double-click} events. Emacs
1439 generates a double-click event when you click a button twice; the event
1440 happens when you release the button (as is normal for all click
1443 The event type of a double-click event contains the prefix
1444 @samp{double-}. Thus, a double click on the second mouse button with
1445 @key{meta} held down comes to the Lisp program as
1446 @code{M-double-mouse-2}. If a double-click event has no binding, the
1447 binding of the corresponding ordinary click event is used to execute
1448 it. Thus, you need not pay attention to the double click feature
1449 unless you really want to.
1451 When the user performs a double click, Emacs generates first an ordinary
1452 click event, and then a double-click event. Therefore, you must design
1453 the command binding of the double click event to assume that the
1454 single-click command has already run. It must produce the desired
1455 results of a double click, starting from the results of a single click.
1457 This is convenient, if the meaning of a double click somehow ``builds
1458 on'' the meaning of a single click---which is recommended user interface
1459 design practice for double clicks.
1461 If you click a button, then press it down again and start moving the
1462 mouse with the button held down, then you get a @dfn{double-drag} event
1463 when you ultimately release the button. Its event type contains
1464 @samp{double-drag} instead of just @samp{drag}. If a double-drag event
1465 has no binding, Emacs looks for an alternate binding as if the event
1466 were an ordinary drag.
1468 Before the double-click or double-drag event, Emacs generates a
1469 @dfn{double-down} event when the user presses the button down for the
1470 second time. Its event type contains @samp{double-down} instead of just
1471 @samp{down}. If a double-down event has no binding, Emacs looks for an
1472 alternate binding as if the event were an ordinary button-down event.
1473 If it finds no binding that way either, the double-down event is
1476 To summarize, when you click a button and then press it again right
1477 away, Emacs generates a down event and a click event for the first
1478 click, a double-down event when you press the button again, and finally
1479 either a double-click or a double-drag event.
1481 If you click a button twice and then press it again, all in quick
1482 succession, Emacs generates a @dfn{triple-down} event, followed by
1483 either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of
1484 these events contain @samp{triple} instead of @samp{double}. If any
1485 triple event has no binding, Emacs uses the binding that it would use
1486 for the corresponding double event.
1488 If you click a button three or more times and then press it again, the
1489 events for the presses beyond the third are all triple events. Emacs
1490 does not have separate event types for quadruple, quintuple, etc.@:
1491 events. However, you can look at the event list to find out precisely
1492 how many times the button was pressed.
1494 @defun event-click-count event
1495 This function returns the number of consecutive button presses that led
1496 up to @var{event}. If @var{event} is a double-down, double-click or
1497 double-drag event, the value is 2. If @var{event} is a triple event,
1498 the value is 3 or greater. If @var{event} is an ordinary mouse event
1499 (not a repeat event), the value is 1.
1502 @defopt double-click-fuzz
1503 To generate repeat events, successive mouse button presses must be at
1504 approximately the same screen position. The value of
1505 @code{double-click-fuzz} specifies the maximum number of pixels the
1506 mouse may be moved (horizontally or vertically) between two successive
1507 clicks to make a double-click.
1509 This variable is also the threshold for motion of the mouse to count
1513 @defopt double-click-time
1514 To generate repeat events, the number of milliseconds between
1515 successive button presses must be less than the value of
1516 @code{double-click-time}. Setting @code{double-click-time} to
1517 @code{nil} disables multi-click detection entirely. Setting it to
1518 @code{t} removes the time limit; Emacs then detects multi-clicks by
1523 @subsection Motion Events
1524 @cindex motion event
1525 @cindex mouse motion events
1527 Emacs sometimes generates @dfn{mouse motion} events to describe motion
1528 of the mouse without any button activity. Mouse motion events are
1529 represented by lists that look like this:
1532 (mouse-movement (POSITION))
1535 The second element of the list describes the current position of the
1536 mouse, just as in a click event (@pxref{Click Events}).
1538 The special form @code{track-mouse} enables generation of motion events
1539 within its body. Outside of @code{track-mouse} forms, Emacs does not
1540 generate events for mere motion of the mouse, and these events do not
1541 appear. @xref{Mouse Tracking}.
1544 @subsection Focus Events
1547 Window systems provide general ways for the user to control which window
1548 gets keyboard input. This choice of window is called the @dfn{focus}.
1549 When the user does something to switch between Emacs frames, that
1550 generates a @dfn{focus event}. The normal definition of a focus event,
1551 in the global keymap, is to select a new frame within Emacs, as the user
1552 would expect. @xref{Input Focus}.
1554 Focus events are represented in Lisp as lists that look like this:
1557 (switch-frame @var{new-frame})
1561 where @var{new-frame} is the frame switched to.
1563 Most X window managers are set up so that just moving the mouse into a
1564 window is enough to set the focus there. Emacs appears to do this,
1565 because it changes the cursor to solid in the new frame. However, there
1566 is no need for the Lisp program to know about the focus change until
1567 some other kind of input arrives. So Emacs generates a focus event only
1568 when the user actually types a keyboard key or presses a mouse button in
1569 the new frame; just moving the mouse between frames does not generate a
1572 A focus event in the middle of a key sequence would garble the
1573 sequence. So Emacs never generates a focus event in the middle of a key
1574 sequence. If the user changes focus in the middle of a key
1575 sequence---that is, after a prefix key---then Emacs reorders the events
1576 so that the focus event comes either before or after the multi-event key
1577 sequence, and not within it.
1580 @subsection Miscellaneous System Events
1582 A few other event types represent occurrences within the system.
1585 @cindex @code{delete-frame} event
1586 @item (delete-frame (@var{frame}))
1587 This kind of event indicates that the user gave the window manager
1588 a command to delete a particular window, which happens to be an Emacs frame.
1590 The standard definition of the @code{delete-frame} event is to delete @var{frame}.
1592 @cindex @code{iconify-frame} event
1593 @item (iconify-frame (@var{frame}))
1594 This kind of event indicates that the user iconified @var{frame} using
1595 the window manager. Its standard definition is @code{ignore}; since the
1596 frame has already been iconified, Emacs has no work to do. The purpose
1597 of this event type is so that you can keep track of such events if you
1600 @cindex @code{make-frame-visible} event
1601 @item (make-frame-visible (@var{frame}))
1602 This kind of event indicates that the user deiconified @var{frame} using
1603 the window manager. Its standard definition is @code{ignore}; since the
1604 frame has already been made visible, Emacs has no work to do.
1606 @cindex @code{wheel-up} event
1607 @cindex @code{wheel-down} event
1608 @item (wheel-up @var{position})
1609 @item (wheel-down @var{position})
1610 These kinds of event are generated by moving a mouse wheel. Their
1611 usual meaning is a kind of scroll or zoom.
1613 The element @var{position} is a list describing the position of the
1614 event, in the same format as used in a mouse-click event.
1616 This kind of event is generated only on some kinds of systems. On some
1617 systems, @code{mouse-4} and @code{mouse-5} are used instead. For
1618 portable code, use the variables @code{mouse-wheel-up-event} and
1619 @code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine
1620 what event types to expect for the mouse wheel.
1622 @cindex @code{drag-n-drop} event
1623 @item (drag-n-drop @var{position} @var{files})
1624 This kind of event is generated when a group of files is
1625 selected in an application outside of Emacs, and then dragged and
1626 dropped onto an Emacs frame.
1628 The element @var{position} is a list describing the position of the
1629 event, in the same format as used in a mouse-click event, and
1630 @var{files} is the list of file names that were dragged and dropped.
1631 The usual way to handle this event is by visiting these files.
1633 This kind of event is generated, at present, only on some kinds of
1636 @cindex @code{help-echo} event
1638 This kind of event is generated when a mouse pointer moves onto a
1639 portion of buffer text which has a @code{help-echo} text property.
1640 The generated event has this form:
1643 (help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos})
1647 The precise meaning of the event parameters and the way these
1648 parameters are used to display the help-echo text are described in
1649 @ref{Text help-echo}.
1651 @cindex @code{sigusr1} event
1652 @cindex @code{sigusr2} event
1653 @cindex user signals
1656 These events are generated when the Emacs process receives
1657 the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no
1658 additional data because signals do not carry additional information.
1660 To catch a user signal, bind the corresponding event to an interactive
1661 command in the @code{special-event-map} (@pxref{Active Keymaps}).
1662 The command is called with no arguments, and the specific signal event is
1663 available in @code{last-input-event}. For example:
1666 (defun sigusr-handler ()
1668 (message "Caught signal %S" last-input-event))
1670 (define-key special-event-map [sigusr1] 'sigusr-handler)
1673 To test the signal handler, you can make Emacs send a signal to itself:
1676 (signal-process (emacs-pid) 'sigusr1)
1680 If one of these events arrives in the middle of a key sequence---that
1681 is, after a prefix key---then Emacs reorders the events so that this
1682 event comes either before or after the multi-event key sequence, not
1685 @node Event Examples
1686 @subsection Event Examples
1688 If the user presses and releases the left mouse button over the same
1689 location, that generates a sequence of events like this:
1692 (down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
1693 (mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180))
1696 While holding the control key down, the user might hold down the
1697 second mouse button, and drag the mouse from one line to the next.
1698 That produces two events, as shown here:
1701 (C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
1702 (C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
1703 (#<window 18 on NEWS> 3510 (0 . 28) -729648))
1706 While holding down the meta and shift keys, the user might press the
1707 second mouse button on the window's mode line, and then drag the mouse
1708 into another window. That produces a pair of events like these:
1711 (M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
1712 (M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
1713 (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
1717 To handle a SIGUSR1 signal, define an interactive function, and
1718 bind it to the @code{signal usr1} event sequence:
1721 (defun usr1-handler ()
1723 (message "Got USR1 signal"))
1724 (global-set-key [signal usr1] 'usr1-handler)
1727 @node Classifying Events
1728 @subsection Classifying Events
1731 Every event has an @dfn{event type}, which classifies the event for
1732 key binding purposes. For a keyboard event, the event type equals the
1733 event value; thus, the event type for a character is the character, and
1734 the event type for a function key symbol is the symbol itself. For
1735 events that are lists, the event type is the symbol in the @sc{car} of
1736 the list. Thus, the event type is always a symbol or a character.
1738 Two events of the same type are equivalent where key bindings are
1739 concerned; thus, they always run the same command. That does not
1740 necessarily mean they do the same things, however, as some commands look
1741 at the whole event to decide what to do. For example, some commands use
1742 the location of a mouse event to decide where in the buffer to act.
1744 Sometimes broader classifications of events are useful. For example,
1745 you might want to ask whether an event involved the @key{META} key,
1746 regardless of which other key or mouse button was used.
1748 The functions @code{event-modifiers} and @code{event-basic-type} are
1749 provided to get such information conveniently.
1751 @defun event-modifiers event
1752 This function returns a list of the modifiers that @var{event} has. The
1753 modifiers are symbols; they include @code{shift}, @code{control},
1754 @code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition,
1755 the modifiers list of a mouse event symbol always contains one of
1756 @code{click}, @code{drag}, and @code{down}. For double or triple
1757 events, it also contains @code{double} or @code{triple}.
1759 The argument @var{event} may be an entire event object, or just an
1760 event type. If @var{event} is a symbol that has never been used in an
1761 event that has been read as input in the current Emacs session, then
1762 @code{event-modifiers} can return @code{nil}, even when @var{event}
1763 actually has modifiers.
1765 Here are some examples:
1768 (event-modifiers ?a)
1770 (event-modifiers ?A)
1772 (event-modifiers ?\C-a)
1774 (event-modifiers ?\C-%)
1776 (event-modifiers ?\C-\S-a)
1777 @result{} (control shift)
1778 (event-modifiers 'f5)
1780 (event-modifiers 's-f5)
1782 (event-modifiers 'M-S-f5)
1783 @result{} (meta shift)
1784 (event-modifiers 'mouse-1)
1786 (event-modifiers 'down-mouse-1)
1790 The modifiers list for a click event explicitly contains @code{click},
1791 but the event symbol name itself does not contain @samp{click}.
1794 @defun event-basic-type event
1795 This function returns the key or mouse button that @var{event}
1796 describes, with all modifiers removed. The @var{event} argument is as
1797 in @code{event-modifiers}. For example:
1800 (event-basic-type ?a)
1802 (event-basic-type ?A)
1804 (event-basic-type ?\C-a)
1806 (event-basic-type ?\C-\S-a)
1808 (event-basic-type 'f5)
1810 (event-basic-type 's-f5)
1812 (event-basic-type 'M-S-f5)
1814 (event-basic-type 'down-mouse-1)
1819 @defun mouse-movement-p object
1820 This function returns non-@code{nil} if @var{object} is a mouse movement
1824 @defun event-convert-list list
1825 This function converts a list of modifier names and a basic event type
1826 to an event type which specifies all of them. The basic event type
1827 must be the last element of the list. For example,
1830 (event-convert-list '(control ?a))
1832 (event-convert-list '(control meta ?a))
1833 @result{} -134217727
1834 (event-convert-list '(control super f1))
1839 @node Accessing Mouse
1840 @subsection Accessing Mouse Events
1841 @cindex mouse events, data in
1843 This section describes convenient functions for accessing the data in
1844 a mouse button or motion event.
1846 These two functions return the starting or ending position of a
1847 mouse-button event, as a list of this form:
1850 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
1851 @var{object} @var{text-pos} (@var{col} . @var{row})
1852 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
1855 @defun event-start event
1856 This returns the starting position of @var{event}.
1858 If @var{event} is a click or button-down event, this returns the
1859 location of the event. If @var{event} is a drag event, this returns the
1860 drag's starting position.
1863 @defun event-end event
1864 This returns the ending position of @var{event}.
1866 If @var{event} is a drag event, this returns the position where the user
1867 released the mouse button. If @var{event} is a click or button-down
1868 event, the value is actually the starting position, which is the only
1869 position such events have.
1872 @cindex mouse position list, accessing
1873 These functions take a position list as described above, and
1874 return various parts of it.
1876 @defun posn-window position
1877 Return the window that @var{position} is in.
1880 @defun posn-area position
1881 Return the window area recorded in @var{position}. It returns @code{nil}
1882 when the event occurred in the text area of the window; otherwise, it
1883 is a symbol identifying the area in which the event occurred.
1886 @defun posn-point position
1887 Return the buffer position in @var{position}. When the event occurred
1888 in the text area of the window, in a marginal area, or on a fringe,
1889 this is an integer specifying a buffer position. Otherwise, the value
1893 @defun posn-x-y position
1894 Return the pixel-based x and y coordinates in @var{position}, as a
1895 cons cell @code{(@var{x} . @var{y})}. These coordinates are relative
1896 to the window given by @code{posn-window}.
1898 This example shows how to convert these window-relative coordinates
1899 into frame-relative coordinates:
1902 (defun frame-relative-coordinates (position)
1903 "Return frame-relative coordinates from POSITION."
1904 (let* ((x-y (posn-x-y position))
1905 (window (posn-window position))
1906 (edges (window-inside-pixel-edges window)))
1907 (cons (+ (car x-y) (car edges))
1908 (+ (cdr x-y) (cadr edges)))))
1912 @defun posn-col-row position
1913 Return the row and column (in units of the frame's default character
1914 height and width) of @var{position}, as a cons cell @code{(@var{col} .
1915 @var{row})}. These are computed from the @var{x} and @var{y} values
1916 actually found in @var{position}.
1919 @defun posn-actual-col-row position
1920 Return the actual row and column in @var{position}, as a cons cell
1921 @code{(@var{col} . @var{row})}. The values are the actual row number
1922 in the window, and the actual character number in that row. It returns
1923 @code{nil} if @var{position} does not include actual positions values.
1924 You can use @code{posn-col-row} to get approximate values.
1927 @defun posn-string position
1928 Return the string object in @var{position}, either @code{nil}, or a
1929 cons cell @code{(@var{string} . @var{string-pos})}.
1932 @defun posn-image position
1933 Return the image object in @var{position}, either @code{nil}, or an
1934 image @code{(image ...)}.
1937 @defun posn-object position
1938 Return the image or string object in @var{position}, either
1939 @code{nil}, an image @code{(image ...)}, or a cons cell
1940 @code{(@var{string} . @var{string-pos})}.
1943 @defun posn-object-x-y position
1944 Return the pixel-based x and y coordinates relative to the upper left
1945 corner of the object in @var{position} as a cons cell @code{(@var{dx}
1946 . @var{dy})}. If the @var{position} is a buffer position, return the
1947 relative position in the character at that position.
1950 @defun posn-object-width-height position
1951 Return the pixel width and height of the object in @var{position} as a
1952 cons cell @code{(@var{width} . @var{height})}. If the @var{position}
1953 is a buffer position, return the size of the character at that position.
1956 @cindex timestamp of a mouse event
1957 @defun posn-timestamp position
1958 Return the timestamp in @var{position}. This is the time at which the
1959 event occurred, in milliseconds.
1962 These functions compute a position list given particular buffer
1963 position or screen position. You can access the data in this position
1964 list with the functions described above.
1966 @defun posn-at-point &optional pos window
1967 This function returns a position list for position @var{pos} in
1968 @var{window}. @var{pos} defaults to point in @var{window};
1969 @var{window} defaults to the selected window.
1971 @code{posn-at-point} returns @code{nil} if @var{pos} is not visible in
1975 @defun posn-at-x-y x y &optional frame-or-window whole
1976 This function returns position information corresponding to pixel
1977 coordinates @var{x} and @var{y} in a specified frame or window,
1978 @var{frame-or-window}, which defaults to the selected window.
1979 The coordinates @var{x} and @var{y} are relative to the
1980 frame or window used.
1981 If @var{whole} is @code{nil}, the coordinates are relative
1982 to the window text area, otherwise they are relative to
1983 the entire window area including scroll bars, margins and fringes.
1986 @node Accessing Scroll
1987 @subsection Accessing Scroll Bar Events
1988 @cindex scroll bar events, data in
1990 These functions are useful for decoding scroll bar events.
1992 @defun scroll-bar-event-ratio event
1993 This function returns the fractional vertical position of a scroll bar
1994 event within the scroll bar. The value is a cons cell
1995 @code{(@var{portion} . @var{whole})} containing two integers whose ratio
1996 is the fractional position.
1999 @defun scroll-bar-scale ratio total
2000 This function multiplies (in effect) @var{ratio} by @var{total},
2001 rounding the result to an integer. The argument @var{ratio} is not a
2002 number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
2003 value returned by @code{scroll-bar-event-ratio}.
2005 This function is handy for scaling a position on a scroll bar into a
2006 buffer position. Here's how to do that:
2011 (posn-x-y (event-start event))
2012 (- (point-max) (point-min))))
2015 Recall that scroll bar events have two integers forming a ratio, in place
2016 of a pair of x and y coordinates.
2019 @node Strings of Events
2020 @subsection Putting Keyboard Events in Strings
2021 @cindex keyboard events in strings
2022 @cindex strings with keyboard events
2024 In most of the places where strings are used, we conceptualize the
2025 string as containing text characters---the same kind of characters found
2026 in buffers or files. Occasionally Lisp programs use strings that
2027 conceptually contain keyboard characters; for example, they may be key
2028 sequences or keyboard macro definitions. However, storing keyboard
2029 characters in a string is a complex matter, for reasons of historical
2030 compatibility, and it is not always possible.
2032 We recommend that new programs avoid dealing with these complexities
2033 by not storing keyboard events in strings. Here is how to do that:
2037 Use vectors instead of strings for key sequences, when you plan to use
2038 them for anything other than as arguments to @code{lookup-key} and
2039 @code{define-key}. For example, you can use
2040 @code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
2041 @code{this-command-keys-vector} instead of @code{this-command-keys}.
2044 Use vectors to write key sequence constants containing meta characters,
2045 even when passing them directly to @code{define-key}.
2048 When you have to look at the contents of a key sequence that might be a
2049 string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
2050 first, to convert it to a list.
2053 The complexities stem from the modifier bits that keyboard input
2054 characters can include. Aside from the Meta modifier, none of these
2055 modifier bits can be included in a string, and the Meta modifier is
2056 allowed only in special cases.
2058 The earliest GNU Emacs versions represented meta characters as codes
2059 in the range of 128 to 255. At that time, the basic character codes
2060 ranged from 0 to 127, so all keyboard character codes did fit in a
2061 string. Many Lisp programs used @samp{\M-} in string constants to stand
2062 for meta characters, especially in arguments to @code{define-key} and
2063 similar functions, and key sequences and sequences of events were always
2064 represented as strings.
2066 When we added support for larger basic character codes beyond 127, and
2067 additional modifier bits, we had to change the representation of meta
2068 characters. Now the flag that represents the Meta modifier in a
2076 and such numbers cannot be included in a string.
2078 To support programs with @samp{\M-} in string constants, there are
2079 special rules for including certain meta characters in a string.
2080 Here are the rules for interpreting a string as a sequence of input
2085 If the keyboard character value is in the range of 0 to 127, it can go
2086 in the string unchanged.
2089 The meta variants of those characters, with codes in the range of
2098 @math{2^{27} + 127},
2103 can also go in the string, but you must change their
2104 numeric values. You must set the
2118 bit, resulting in a value between 128 and 255. Only a unibyte string
2119 can include these codes.
2122 Non-@acronym{ASCII} characters above 256 can be included in a multibyte string.
2125 Other keyboard character events cannot fit in a string. This includes
2126 keyboard events in the range of 128 to 255.
2129 Functions such as @code{read-key-sequence} that construct strings of
2130 keyboard input characters follow these rules: they construct vectors
2131 instead of strings, when the events won't fit in a string.
2133 When you use the read syntax @samp{\M-} in a string, it produces a
2134 code in the range of 128 to 255---the same code that you get if you
2135 modify the corresponding keyboard event to put it in the string. Thus,
2136 meta events in strings work consistently regardless of how they get into
2139 However, most programs would do well to avoid these issues by
2140 following the recommendations at the beginning of this section.
2143 @section Reading Input
2145 @cindex keyboard input
2147 The editor command loop reads key sequences using the function
2148 @code{read-key-sequence}, which uses @code{read-event}. These and other
2149 functions for event input are also available for use in Lisp programs.
2150 See also @code{momentary-string-display} in @ref{Temporary Displays},
2151 and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
2152 functions and variables for controlling terminal input modes and
2153 debugging terminal input.
2155 For higher-level input facilities, see @ref{Minibuffers}.
2158 * Key Sequence Input:: How to read one key sequence.
2159 * Reading One Event:: How to read just one event.
2160 * Event Mod:: How Emacs modifies events as they are read.
2161 * Invoking the Input Method:: How reading an event uses the input method.
2162 * Quoted Character Input:: Asking the user to specify a character.
2163 * Event Input Misc:: How to reread or throw away input events.
2166 @node Key Sequence Input
2167 @subsection Key Sequence Input
2168 @cindex key sequence input
2170 The command loop reads input a key sequence at a time, by calling
2171 @code{read-key-sequence}. Lisp programs can also call this function;
2172 for example, @code{describe-key} uses it to read the key to describe.
2174 @defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
2175 This function reads a key sequence and returns it as a string or
2176 vector. It keeps reading events until it has accumulated a complete key
2177 sequence; that is, enough to specify a non-prefix command using the
2178 currently active keymaps. (Remember that a key sequence that starts
2179 with a mouse event is read using the keymaps of the buffer in the
2180 window that the mouse was in, not the current buffer.)
2182 If the events are all characters and all can fit in a string, then
2183 @code{read-key-sequence} returns a string (@pxref{Strings of Events}).
2184 Otherwise, it returns a vector, since a vector can hold all kinds of
2185 events---characters, symbols, and lists. The elements of the string or
2186 vector are the events in the key sequence.
2188 Reading a key sequence includes translating the events in various
2189 ways. @xref{Translation Keymaps}.
2191 The argument @var{prompt} is either a string to be displayed in the
2192 echo area as a prompt, or @code{nil}, meaning not to display a prompt.
2193 The argument @var{continue-echo}, if non-@code{nil}, means to echo
2194 this key as a continuation of the previous key.
2196 Normally any upper case event is converted to lower case if the
2197 original event is undefined and the lower case equivalent is defined.
2198 The argument @var{dont-downcase-last}, if non-@code{nil}, means do not
2199 convert the last event to lower case. This is appropriate for reading
2200 a key sequence to be defined.
2202 The argument @var{switch-frame-ok}, if non-@code{nil}, means that this
2203 function should process a @code{switch-frame} event if the user
2204 switches frames before typing anything. If the user switches frames
2205 in the middle of a key sequence, or at the start of the sequence but
2206 @var{switch-frame-ok} is @code{nil}, then the event will be put off
2207 until after the current key sequence.
2209 The argument @var{command-loop}, if non-@code{nil}, means that this
2210 key sequence is being read by something that will read commands one
2211 after another. It should be @code{nil} if the caller will read just
2214 In the following example, Emacs displays the prompt @samp{?} in the
2215 echo area, and then the user types @kbd{C-x C-f}.
2218 (read-key-sequence "?")
2221 ---------- Echo Area ----------
2223 ---------- Echo Area ----------
2229 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
2230 typed while reading with this function works like any other character,
2231 and does not set @code{quit-flag}. @xref{Quitting}.
2234 @defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
2235 This is like @code{read-key-sequence} except that it always
2236 returns the key sequence as a vector, never as a string.
2237 @xref{Strings of Events}.
2240 @cindex upper case key sequence
2241 @cindex downcasing in @code{lookup-key}
2242 @cindex shift-translation
2243 If an input character is upper-case (or has the shift modifier) and
2244 has no key binding, but its lower-case equivalent has one, then
2245 @code{read-key-sequence} converts the character to lower case. Note
2246 that @code{lookup-key} does not perform case conversion in this way.
2248 @vindex this-command-keys-shift-translated
2249 When reading input results in such a @dfn{shift-translation}, Emacs
2250 sets the variable @code{this-command-keys-shift-translated} to a
2251 non-@code{nil} value. Lisp programs can examine this variable if they
2252 need to modify their behavior when invoked by shift-translated keys.
2253 For example, the function @code{handle-shift-selection} examines the
2254 value of this variable to determine how to activate or deactivate the
2255 region (@pxref{The Mark, handle-shift-selection}).
2257 The function @code{read-key-sequence} also transforms some mouse events.
2258 It converts unbound drag events into click events, and discards unbound
2259 button-down events entirely. It also reshuffles focus events and
2260 miscellaneous window events so that they never appear in a key sequence
2261 with any other events.
2263 @cindex @code{header-line} prefix key
2264 @cindex @code{mode-line} prefix key
2265 @cindex @code{vertical-line} prefix key
2266 @cindex @code{horizontal-scroll-bar} prefix key
2267 @cindex @code{vertical-scroll-bar} prefix key
2268 @cindex @code{menu-bar} prefix key
2269 @cindex mouse events, in special parts of frame
2270 When mouse events occur in special parts of a window, such as a mode
2271 line or a scroll bar, the event type shows nothing special---it is the
2272 same symbol that would normally represent that combination of mouse
2273 button and modifier keys. The information about the window part is kept
2274 elsewhere in the event---in the coordinates. But
2275 @code{read-key-sequence} translates this information into imaginary
2276 ``prefix keys,'' all of which are symbols: @code{header-line},
2277 @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
2278 @code{vertical-line}, and @code{vertical-scroll-bar}. You can define
2279 meanings for mouse clicks in special window parts by defining key
2280 sequences using these imaginary prefix keys.
2282 For example, if you call @code{read-key-sequence} and then click the
2283 mouse on the window's mode line, you get two events, like this:
2286 (read-key-sequence "Click on the mode line: ")
2287 @result{} [mode-line
2289 (#<window 6 on NEWS> mode-line
2290 (40 . 63) 5959987))]
2293 @defvar num-input-keys
2295 This variable's value is the number of key sequences processed so far in
2296 this Emacs session. This includes key sequences read from the terminal
2297 and key sequences read from keyboard macros being executed.
2300 @node Reading One Event
2301 @subsection Reading One Event
2302 @cindex reading a single event
2303 @cindex event, reading only one
2305 The lowest level functions for command input are those that read a
2308 None of the three functions below suppresses quitting.
2310 @defun read-event &optional prompt inherit-input-method seconds
2311 This function reads and returns the next event of command input, waiting
2312 if necessary until an event is available. Events can come directly from
2313 the user or from a keyboard macro.
2315 If the optional argument @var{prompt} is non-@code{nil}, it should be a
2316 string to display in the echo area as a prompt. Otherwise,
2317 @code{read-event} does not display any message to indicate it is waiting
2318 for input; instead, it prompts by echoing: it displays descriptions of
2319 the events that led to or were read by the current command. @xref{The
2322 If @var{inherit-input-method} is non-@code{nil}, then the current input
2323 method (if any) is employed to make it possible to enter a
2324 non-@acronym{ASCII} character. Otherwise, input method handling is disabled
2325 for reading this event.
2327 If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
2328 moves the cursor temporarily to the echo area, to the end of any message
2329 displayed there. Otherwise @code{read-event} does not move the cursor.
2331 If @var{seconds} is non-@code{nil}, it should be a number specifying
2332 the maximum time to wait for input, in seconds. If no input arrives
2333 within that time, @code{read-event} stops waiting and returns
2334 @code{nil}. A floating-point value for @var{seconds} means to wait
2335 for a fractional number of seconds. Some systems support only a whole
2336 number of seconds; on these systems, @var{seconds} is rounded down.
2337 If @var{seconds} is @code{nil}, @code{read-event} waits as long as
2338 necessary for input to arrive.
2340 If @var{seconds} is @code{nil}, Emacs is considered idle while waiting
2341 for user input to arrive. Idle timers---those created with
2342 @code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this
2343 period. However, if @var{seconds} is non-@code{nil}, the state of
2344 idleness remains unchanged. If Emacs is non-idle when
2345 @code{read-event} is called, it remains non-idle throughout the
2346 operation of @code{read-event}; if Emacs is idle (which can happen if
2347 the call happens inside an idle timer), it remains idle.
2349 If @code{read-event} gets an event that is defined as a help character,
2350 then in some cases @code{read-event} processes the event directly without
2351 returning. @xref{Help Functions}. Certain other events, called
2352 @dfn{special events}, are also processed directly within
2353 @code{read-event} (@pxref{Special Events}).
2355 Here is what happens if you call @code{read-event} and then press the
2356 right-arrow function key:
2366 @defun read-char &optional prompt inherit-input-method seconds
2367 This function reads and returns a character of command input. If the
2368 user generates an event which is not a character (i.e. a mouse click or
2369 function key event), @code{read-char} signals an error. The arguments
2370 work as in @code{read-event}.
2372 In the first example, the user types the character @kbd{1} (@acronym{ASCII}
2373 code 49). The second example shows a keyboard macro definition that
2374 calls @code{read-char} from the minibuffer using @code{eval-expression}.
2375 @code{read-char} reads the keyboard macro's very next character, which
2376 is @kbd{1}. Then @code{eval-expression} displays its return value in
2386 ;; @r{We assume here you use @kbd{M-:} to evaluate this.}
2387 (symbol-function 'foo)
2388 @result{} "^[:(read-char)^M1"
2391 (execute-kbd-macro 'foo)
2398 @defun read-char-exclusive &optional prompt inherit-input-method seconds
2399 This function reads and returns a character of command input. If the
2400 user generates an event which is not a character,
2401 @code{read-char-exclusive} ignores it and reads another event, until it
2402 gets a character. The arguments work as in @code{read-event}.
2405 @defvar num-nonmacro-input-events
2406 This variable holds the total number of input events received so far
2407 from the terminal---not counting those generated by keyboard macros.
2411 @subsection Modifying and Translating Input Events
2413 Emacs modifies every event it reads according to
2414 @code{extra-keyboard-modifiers}, then translates it through
2415 @code{keyboard-translate-table} (if applicable), before returning it
2416 from @code{read-event}.
2419 @defvar extra-keyboard-modifiers
2420 This variable lets Lisp programs ``press'' the modifier keys on the
2421 keyboard. The value is a character. Only the modifiers of the
2422 character matter. Each time the user types a keyboard key, it is
2423 altered as if those modifier keys were held down. For instance, if
2424 you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all
2425 keyboard input characters typed during the scope of the binding will
2426 have the control and meta modifiers applied to them. The character
2427 @code{?\C-@@}, equivalent to the integer 0, does not count as a control
2428 character for this purpose, but as a character with no modifiers.
2429 Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
2432 When using a window system, the program can ``press'' any of the
2433 modifier keys in this way. Otherwise, only the @key{CTL} and @key{META}
2434 keys can be virtually pressed.
2436 Note that this variable applies only to events that really come from
2437 the keyboard, and has no effect on mouse events or any other events.
2440 @defvar keyboard-translate-table
2441 This terminal-local variable is the translate table for keyboard
2442 characters. It lets you reshuffle the keys on the keyboard without
2443 changing any command bindings. Its value is normally a char-table, or
2444 else @code{nil}. (It can also be a string or vector, but this is
2445 considered obsolete.)
2447 If @code{keyboard-translate-table} is a char-table
2448 (@pxref{Char-Tables}), then each character read from the keyboard is
2449 looked up in this char-table. If the value found there is
2450 non-@code{nil}, then it is used instead of the actual input character.
2452 Note that this translation is the first thing that happens to a
2453 character after it is read from the terminal. Record-keeping features
2454 such as @code{recent-keys} and dribble files record the characters after
2457 Note also that this translation is done before the characters are
2458 supplied to input methods (@pxref{Input Methods}).
2461 @defun keyboard-translate from to
2462 This function modifies @code{keyboard-translate-table} to translate
2463 character code @var{from} into character code @var{to}. It creates
2464 the keyboard translate table if necessary.
2467 Here's an example of using the @code{keyboard-translate-table} to
2468 make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste
2472 (keyboard-translate ?\C-x 'control-x)
2473 (keyboard-translate ?\C-c 'control-c)
2474 (keyboard-translate ?\C-v 'control-v)
2475 (global-set-key [control-x] 'kill-region)
2476 (global-set-key [control-c] 'kill-ring-save)
2477 (global-set-key [control-v] 'yank)
2481 On a graphical terminal that supports extended @acronym{ASCII} input,
2482 you can still get the standard Emacs meanings of one of those
2483 characters by typing it with the shift key. That makes it a different
2484 character as far as keyboard translation is concerned, but it has the
2487 @xref{Translation Keymaps}, for mechanisms that translate event sequences
2488 at the level of @code{read-key-sequence}.
2490 @node Invoking the Input Method
2491 @subsection Invoking the Input Method
2493 The event-reading functions invoke the current input method, if any
2494 (@pxref{Input Methods}). If the value of @code{input-method-function}
2495 is non-@code{nil}, it should be a function; when @code{read-event} reads
2496 a printing character (including @key{SPC}) with no modifier bits, it
2497 calls that function, passing the character as an argument.
2499 @defvar input-method-function
2500 If this is non-@code{nil}, its value specifies the current input method
2503 @strong{Warning:} don't bind this variable with @code{let}. It is often
2504 buffer-local, and if you bind it around reading input (which is exactly
2505 when you @emph{would} bind it), switching buffers asynchronously while
2506 Emacs is waiting will cause the value to be restored in the wrong
2510 The input method function should return a list of events which should
2511 be used as input. (If the list is @code{nil}, that means there is no
2512 input, so @code{read-event} waits for another event.) These events are
2513 processed before the events in @code{unread-command-events}
2514 (@pxref{Event Input Misc}). Events
2515 returned by the input method function are not passed to the input method
2516 function again, even if they are printing characters with no modifier
2519 If the input method function calls @code{read-event} or
2520 @code{read-key-sequence}, it should bind @code{input-method-function} to
2521 @code{nil} first, to prevent recursion.
2523 The input method function is not called when reading the second and
2524 subsequent events of a key sequence. Thus, these characters are not
2525 subject to input method processing. The input method function should
2526 test the values of @code{overriding-local-map} and
2527 @code{overriding-terminal-local-map}; if either of these variables is
2528 non-@code{nil}, the input method should put its argument into a list and
2529 return that list with no further processing.
2531 @node Quoted Character Input
2532 @subsection Quoted Character Input
2533 @cindex quoted character input
2535 You can use the function @code{read-quoted-char} to ask the user to
2536 specify a character, and allow the user to specify a control or meta
2537 character conveniently, either literally or as an octal character code.
2538 The command @code{quoted-insert} uses this function.
2540 @defun read-quoted-char &optional prompt
2541 @cindex octal character input
2542 @cindex control characters, reading
2543 @cindex nonprinting characters, reading
2544 This function is like @code{read-char}, except that if the first
2545 character read is an octal digit (0-7), it reads any number of octal
2546 digits (but stopping if a non-octal digit is found), and returns the
2547 character represented by that numeric character code. If the
2548 character that terminates the sequence of octal digits is @key{RET},
2549 it is discarded. Any other terminating character is used as input
2550 after this function returns.
2552 Quitting is suppressed when the first character is read, so that the
2553 user can enter a @kbd{C-g}. @xref{Quitting}.
2555 If @var{prompt} is supplied, it specifies a string for prompting the
2556 user. The prompt string is always displayed in the echo area, followed
2557 by a single @samp{-}.
2559 In the following example, the user types in the octal number 177 (which
2563 (read-quoted-char "What character")
2566 ---------- Echo Area ----------
2567 What character @kbd{1 7 7}-
2568 ---------- Echo Area ----------
2576 @node Event Input Misc
2577 @subsection Miscellaneous Event Input Features
2579 This section describes how to ``peek ahead'' at events without using
2580 them up, how to check for pending input, and how to discard pending
2581 input. See also the function @code{read-passwd} (@pxref{Reading a
2584 @defvar unread-command-events
2586 @cindex peeking at input
2587 This variable holds a list of events waiting to be read as command
2588 input. The events are used in the order they appear in the list, and
2589 removed one by one as they are used.
2591 The variable is needed because in some cases a function reads an event
2592 and then decides not to use it. Storing the event in this variable
2593 causes it to be processed normally, by the command loop or by the
2594 functions to read command input.
2596 @cindex prefix argument unreading
2597 For example, the function that implements numeric prefix arguments reads
2598 any number of digits. When it finds a non-digit event, it must unread
2599 the event so that it can be read normally by the command loop.
2600 Likewise, incremental search uses this feature to unread events with no
2601 special meaning in a search, because these events should exit the search
2602 and then execute normally.
2604 The reliable and easy way to extract events from a key sequence so as to
2605 put them in @code{unread-command-events} is to use
2606 @code{listify-key-sequence} (@pxref{Strings of Events}).
2608 Normally you add events to the front of this list, so that the events
2609 most recently unread will be reread first.
2611 Events read from this list are not normally added to the current
2612 command's key sequence (as returned by e.g. @code{this-command-keys}),
2613 as the events will already have been added once as they were read for
2614 the first time. An element of the form @code{(@code{t} . @var{event})}
2615 forces @var{event} to be added to the current command's key sequence.
2618 @defun listify-key-sequence key
2619 This function converts the string or vector @var{key} to a list of
2620 individual events, which you can put in @code{unread-command-events}.
2623 @defvar unread-command-char
2624 This variable holds a character to be read as command input.
2625 A value of -1 means ``empty.''
2627 This variable is mostly obsolete now that you can use
2628 @code{unread-command-events} instead; it exists only to support programs
2629 written for Emacs versions 18 and earlier.
2632 @defun input-pending-p
2633 @cindex waiting for command key input
2634 This function determines whether any command input is currently
2635 available to be read. It returns immediately, with value @code{t} if
2636 there is available input, @code{nil} otherwise. On rare occasions it
2637 may return @code{t} when no input is available.
2640 @defvar last-input-event
2641 @defvarx last-input-char
2642 This variable records the last terminal input event read, whether
2643 as part of a command or explicitly by a Lisp program.
2645 In the example below, the Lisp program reads the character @kbd{1},
2646 @acronym{ASCII} code 49. It becomes the value of @code{last-input-event},
2647 while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
2648 this expression) remains the value of @code{last-command-event}.
2652 (progn (print (read-char))
2653 (print last-command-event)
2661 The alias @code{last-input-char} is obsolete.
2664 @defmac while-no-input body@dots{}
2665 This construct runs the @var{body} forms and returns the value of the
2666 last one---but only if no input arrives. If any input arrives during
2667 the execution of the @var{body} forms, it aborts them (working much
2668 like a quit). The @code{while-no-input} form returns @code{nil} if
2669 aborted by a real quit, and returns @code{t} if aborted by arrival of
2672 If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil},
2673 arrival of input during those parts won't cause an abort until
2674 the end of that part.
2676 If you want to be able to distinguish all possible values computed
2677 by @var{body} from both kinds of abort conditions, write the code
2683 (progn . @var{body})))
2687 @defun discard-input
2688 @cindex flushing input
2689 @cindex discarding input
2690 @cindex keyboard macro, terminating
2691 This function discards the contents of the terminal input buffer and
2692 cancels any keyboard macro that might be in the process of definition.
2693 It returns @code{nil}.
2695 In the following example, the user may type a number of characters right
2696 after starting the evaluation of the form. After the @code{sleep-for}
2697 finishes sleeping, @code{discard-input} discards any characters typed
2701 (progn (sleep-for 2)
2707 @node Special Events
2708 @section Special Events
2710 @cindex special events
2711 Special events are handled at a very low level---as soon as they are
2712 read. The @code{read-event} function processes these events itself, and
2713 never returns them. Instead, it keeps waiting for the first event
2714 that is not special and returns that one.
2716 Events that are handled in this way do not echo, they are never grouped
2717 into key sequences, and they never appear in the value of
2718 @code{last-command-event} or @code{(this-command-keys)}. They do not
2719 discard a numeric argument, they cannot be unread with
2720 @code{unread-command-events}, they may not appear in a keyboard macro,
2721 and they are not recorded in a keyboard macro while you are defining
2724 These events do, however, appear in @code{last-input-event} immediately
2725 after they are read, and this is the way for the event's definition to
2726 find the actual event.
2728 The events types @code{iconify-frame}, @code{make-frame-visible},
2729 @code{delete-frame}, @code{drag-n-drop}, and user signals like
2730 @code{sigusr1} are normally handled in this way. The keymap which
2731 defines how to handle special events---and which events are special---is
2732 in the variable @code{special-event-map} (@pxref{Active Keymaps}).
2735 @section Waiting for Elapsed Time or Input
2738 The wait functions are designed to wait for a certain amount of time
2739 to pass or until there is input. For example, you may wish to pause in
2740 the middle of a computation to allow the user time to view the display.
2741 @code{sit-for} pauses and updates the screen, and returns immediately if
2742 input comes in, while @code{sleep-for} pauses without updating the
2745 @defun sit-for seconds &optional nodisp
2746 This function performs redisplay (provided there is no pending input
2747 from the user), then waits @var{seconds} seconds, or until input is
2748 available. The usual purpose of @code{sit-for} is to give the user
2749 time to read text that you display. The value is @code{t} if
2750 @code{sit-for} waited the full time with no input arriving
2751 (@pxref{Event Input Misc}). Otherwise, the value is @code{nil}.
2753 The argument @var{seconds} need not be an integer. If it is a floating
2754 point number, @code{sit-for} waits for a fractional number of seconds.
2755 Some systems support only a whole number of seconds; on these systems,
2756 @var{seconds} is rounded down.
2758 The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)},
2759 i.e. it requests a redisplay, without any delay, if there is no pending input.
2760 @xref{Forcing Redisplay}.
2762 If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
2763 redisplay, but it still returns as soon as input is available (or when
2764 the timeout elapses).
2766 In batch mode (@pxref{Batch Mode}), @code{sit-for} cannot be
2767 interrupted, even by input from the standard input descriptor. It is
2768 thus equivalent to @code{sleep-for}, which is described below.
2770 It is also possible to call @code{sit-for} with three arguments,
2771 as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})},
2772 but that is considered obsolete.
2775 @defun sleep-for seconds &optional millisec
2776 This function simply pauses for @var{seconds} seconds without updating
2777 the display. It pays no attention to available input. It returns
2780 The argument @var{seconds} need not be an integer. If it is a floating
2781 point number, @code{sleep-for} waits for a fractional number of seconds.
2782 Some systems support only a whole number of seconds; on these systems,
2783 @var{seconds} is rounded down.
2785 The optional argument @var{millisec} specifies an additional waiting
2786 period measured in milliseconds. This adds to the period specified by
2787 @var{seconds}. If the system doesn't support waiting fractions of a
2788 second, you get an error if you specify nonzero @var{millisec}.
2790 Use @code{sleep-for} when you wish to guarantee a delay.
2793 @xref{Time of Day}, for functions to get the current time.
2799 @cindex interrupt Lisp functions
2801 Typing @kbd{C-g} while a Lisp function is running causes Emacs to
2802 @dfn{quit} whatever it is doing. This means that control returns to the
2803 innermost active command loop.
2805 Typing @kbd{C-g} while the command loop is waiting for keyboard input
2806 does not cause a quit; it acts as an ordinary input character. In the
2807 simplest case, you cannot tell the difference, because @kbd{C-g}
2808 normally runs the command @code{keyboard-quit}, whose effect is to quit.
2809 However, when @kbd{C-g} follows a prefix key, they combine to form an
2810 undefined key. The effect is to cancel the prefix key as well as any
2813 In the minibuffer, @kbd{C-g} has a different definition: it aborts out
2814 of the minibuffer. This means, in effect, that it exits the minibuffer
2815 and then quits. (Simply quitting would return to the command loop
2816 @emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit
2817 directly when the command reader is reading input is so that its meaning
2818 can be redefined in the minibuffer in this way. @kbd{C-g} following a
2819 prefix key is not redefined in the minibuffer, and it has its normal
2820 effect of canceling the prefix key and prefix argument. This too
2821 would not be possible if @kbd{C-g} always quit directly.
2823 When @kbd{C-g} does directly quit, it does so by setting the variable
2824 @code{quit-flag} to @code{t}. Emacs checks this variable at appropriate
2825 times and quits if it is not @code{nil}. Setting @code{quit-flag}
2826 non-@code{nil} in any way thus causes a quit.
2828 At the level of C code, quitting cannot happen just anywhere; only at the
2829 special places that check @code{quit-flag}. The reason for this is
2830 that quitting at other places might leave an inconsistency in Emacs's
2831 internal state. Because quitting is delayed until a safe place, quitting
2832 cannot make Emacs crash.
2834 Certain functions such as @code{read-key-sequence} or
2835 @code{read-quoted-char} prevent quitting entirely even though they wait
2836 for input. Instead of quitting, @kbd{C-g} serves as the requested
2837 input. In the case of @code{read-key-sequence}, this serves to bring
2838 about the special behavior of @kbd{C-g} in the command loop. In the
2839 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
2840 to quote a @kbd{C-g}.
2842 @cindex preventing quitting
2843 You can prevent quitting for a portion of a Lisp function by binding
2844 the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
2845 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
2846 usual result of this---a quit---is prevented. Eventually,
2847 @code{inhibit-quit} will become @code{nil} again, such as when its
2848 binding is unwound at the end of a @code{let} form. At that time, if
2849 @code{quit-flag} is still non-@code{nil}, the requested quit happens
2850 immediately. This behavior is ideal when you wish to make sure that
2851 quitting does not happen within a ``critical section'' of the program.
2853 @cindex @code{read-quoted-char} quitting
2854 In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
2855 handled in a special way that does not involve quitting. This is done
2856 by reading the input with @code{inhibit-quit} bound to @code{t}, and
2857 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
2858 becomes @code{nil} again. This excerpt from the definition of
2859 @code{read-quoted-char} shows how this is done; it also shows that
2860 normal quitting is permitted after the first character of input.
2863 (defun read-quoted-char (&optional prompt)
2864 "@dots{}@var{documentation}@dots{}"
2865 (let ((message-log-max nil) done (first t) (code 0) char)
2867 (let ((inhibit-quit first)
2869 (and prompt (message "%s-" prompt))
2870 (setq char (read-event))
2871 (if inhibit-quit (setq quit-flag nil)))
2872 @r{@dots{}set the variable @code{code}@dots{}})
2877 If this variable is non-@code{nil}, then Emacs quits immediately, unless
2878 @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
2879 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
2882 @defvar inhibit-quit
2883 This variable determines whether Emacs should quit when @code{quit-flag}
2884 is set to a value other than @code{nil}. If @code{inhibit-quit} is
2885 non-@code{nil}, then @code{quit-flag} has no special effect.
2888 @defmac with-local-quit body@dots{}
2889 This macro executes @var{body} forms in sequence, but allows quitting, at
2890 least locally, within @var{body} even if @code{inhibit-quit} was
2891 non-@code{nil} outside this construct. It returns the value of the
2892 last form in @var{body}, unless exited by quitting, in which case
2893 it returns @code{nil}.
2895 If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit},
2896 it only executes the @var{body}, and setting @code{quit-flag} causes
2897 a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so
2898 that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag}
2899 triggers a special kind of local quit. This ends the execution of
2900 @var{body} and exits the @code{with-local-quit} body with
2901 @code{quit-flag} still non-@code{nil}, so that another (ordinary) quit
2902 will happen as soon as that is allowed. If @code{quit-flag} is
2903 already non-@code{nil} at the beginning of @var{body}, the local quit
2904 happens immediately and the body doesn't execute at all.
2906 This macro is mainly useful in functions that can be called from
2907 timers, process filters, process sentinels, @code{pre-command-hook},
2908 @code{post-command-hook}, and other places where @code{inhibit-quit} is
2909 normally bound to @code{t}.
2912 @deffn Command keyboard-quit
2913 This function signals the @code{quit} condition with @code{(signal 'quit
2914 nil)}. This is the same thing that quitting does. (See @code{signal}
2918 You can specify a character other than @kbd{C-g} to use for quitting.
2919 See the function @code{set-input-mode} in @ref{Terminal Input}.
2921 @node Prefix Command Arguments
2922 @section Prefix Command Arguments
2923 @cindex prefix argument
2924 @cindex raw prefix argument
2925 @cindex numeric prefix argument
2927 Most Emacs commands can use a @dfn{prefix argument}, a number
2928 specified before the command itself. (Don't confuse prefix arguments
2929 with prefix keys.) The prefix argument is at all times represented by a
2930 value, which may be @code{nil}, meaning there is currently no prefix
2931 argument. Each command may use the prefix argument or ignore it.
2933 There are two representations of the prefix argument: @dfn{raw} and
2934 @dfn{numeric}. The editor command loop uses the raw representation
2935 internally, and so do the Lisp variables that store the information, but
2936 commands can request either representation.
2938 Here are the possible values of a raw prefix argument:
2942 @code{nil}, meaning there is no prefix argument. Its numeric value is
2943 1, but numerous commands make a distinction between @code{nil} and the
2947 An integer, which stands for itself.
2950 A list of one element, which is an integer. This form of prefix
2951 argument results from one or a succession of @kbd{C-u}'s with no
2952 digits. The numeric value is the integer in the list, but some
2953 commands make a distinction between such a list and an integer alone.
2956 The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was
2957 typed, without following digits. The equivalent numeric value is
2958 @minus{}1, but some commands make a distinction between the integer
2959 @minus{}1 and the symbol @code{-}.
2962 We illustrate these possibilities by calling the following function with
2967 (defun display-prefix (arg)
2968 "Display the value of the raw prefix arg."
2975 Here are the results of calling @code{display-prefix} with various
2976 raw prefix arguments:
2979 M-x display-prefix @print{} nil
2981 C-u M-x display-prefix @print{} (4)
2983 C-u C-u M-x display-prefix @print{} (16)
2985 C-u 3 M-x display-prefix @print{} 3
2987 M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
2989 C-u - M-x display-prefix @print{} -
2991 M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
2993 C-u - 7 M-x display-prefix @print{} -7
2995 M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
2998 Emacs uses two variables to store the prefix argument:
2999 @code{prefix-arg} and @code{current-prefix-arg}. Commands such as
3000 @code{universal-argument} that set up prefix arguments for other
3001 commands store them in @code{prefix-arg}. In contrast,
3002 @code{current-prefix-arg} conveys the prefix argument to the current
3003 command, so setting it has no effect on the prefix arguments for future
3006 Normally, commands specify which representation to use for the prefix
3007 argument, either numeric or raw, in the @code{interactive} specification.
3008 (@xref{Using Interactive}.) Alternatively, functions may look at the
3009 value of the prefix argument directly in the variable
3010 @code{current-prefix-arg}, but this is less clean.
3012 @defun prefix-numeric-value arg
3013 This function returns the numeric meaning of a valid raw prefix argument
3014 value, @var{arg}. The argument may be a symbol, a number, or a list.
3015 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
3016 value @minus{}1 is returned; if it is a number, that number is returned;
3017 if it is a list, the @sc{car} of that list (which should be a number) is
3021 @defvar current-prefix-arg
3022 This variable holds the raw prefix argument for the @emph{current}
3023 command. Commands may examine it directly, but the usual method for
3024 accessing it is with @code{(interactive "P")}.
3028 The value of this variable is the raw prefix argument for the
3029 @emph{next} editing command. Commands such as @code{universal-argument}
3030 that specify prefix arguments for the following command work by setting
3034 @defvar last-prefix-arg
3035 The raw prefix argument value used by the previous command.
3038 The following commands exist to set up prefix arguments for the
3039 following command. Do not call them for any other reason.
3041 @deffn Command universal-argument
3042 This command reads input and specifies a prefix argument for the
3043 following command. Don't call this command yourself unless you know
3047 @deffn Command digit-argument arg
3048 This command adds to the prefix argument for the following command. The
3049 argument @var{arg} is the raw prefix argument as it was before this
3050 command; it is used to compute the updated prefix argument. Don't call
3051 this command yourself unless you know what you are doing.
3054 @deffn Command negative-argument arg
3055 This command adds to the numeric argument for the next command. The
3056 argument @var{arg} is the raw prefix argument as it was before this
3057 command; its value is negated to form the new prefix argument. Don't
3058 call this command yourself unless you know what you are doing.
3061 @node Recursive Editing
3062 @section Recursive Editing
3063 @cindex recursive command loop
3064 @cindex recursive editing level
3065 @cindex command loop, recursive
3067 The Emacs command loop is entered automatically when Emacs starts up.
3068 This top-level invocation of the command loop never exits; it keeps
3069 running as long as Emacs does. Lisp programs can also invoke the
3070 command loop. Since this makes more than one activation of the command
3071 loop, we call it @dfn{recursive editing}. A recursive editing level has
3072 the effect of suspending whatever command invoked it and permitting the
3073 user to do arbitrary editing before resuming that command.
3075 The commands available during recursive editing are the same ones
3076 available in the top-level editing loop and defined in the keymaps.
3077 Only a few special commands exit the recursive editing level; the others
3078 return to the recursive editing level when they finish. (The special
3079 commands for exiting are always available, but they do nothing when
3080 recursive editing is not in progress.)
3082 All command loops, including recursive ones, set up all-purpose error
3083 handlers so that an error in a command run from the command loop will
3086 @cindex minibuffer input
3087 Minibuffer input is a special kind of recursive editing. It has a few
3088 special wrinkles, such as enabling display of the minibuffer and the
3089 minibuffer window, but fewer than you might suppose. Certain keys
3090 behave differently in the minibuffer, but that is only because of the
3091 minibuffer's local map; if you switch windows, you get the usual Emacs
3094 @cindex @code{throw} example
3096 @cindex exit recursive editing
3098 To invoke a recursive editing level, call the function
3099 @code{recursive-edit}. This function contains the command loop; it also
3100 contains a call to @code{catch} with tag @code{exit}, which makes it
3101 possible to exit the recursive editing level by throwing to @code{exit}
3102 (@pxref{Catch and Throw}). If you throw a value other than @code{t},
3103 then @code{recursive-edit} returns normally to the function that called
3104 it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
3105 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
3106 control returns to the command loop one level up. This is called
3107 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
3109 Most applications should not use recursive editing, except as part of
3110 using the minibuffer. Usually it is more convenient for the user if you
3111 change the major mode of the current buffer temporarily to a special
3112 major mode, which should have a command to go back to the previous mode.
3113 (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
3114 give the user different text to edit ``recursively,'' create and select
3115 a new buffer in a special mode. In this mode, define a command to
3116 complete the processing and go back to the previous buffer. (The
3117 @kbd{m} command in Rmail does this.)
3119 Recursive edits are useful in debugging. You can insert a call to
3120 @code{debug} into a function definition as a sort of breakpoint, so that
3121 you can look around when the function gets there. @code{debug} invokes
3122 a recursive edit but also provides the other features of the debugger.
3124 Recursive editing levels are also used when you type @kbd{C-r} in
3125 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
3127 @defun recursive-edit
3128 @cindex suspend evaluation
3129 This function invokes the editor command loop. It is called
3130 automatically by the initialization of Emacs, to let the user begin
3131 editing. When called from a Lisp program, it enters a recursive editing
3134 If the current buffer is not the same as the selected window's buffer,
3135 @code{recursive-edit} saves and restores the current buffer. Otherwise,
3136 if you switch buffers, the buffer you switched to is current after
3137 @code{recursive-edit} returns.
3139 In the following example, the function @code{simple-rec} first
3140 advances point one word, then enters a recursive edit, printing out a
3141 message in the echo area. The user can then do any editing desired, and
3142 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
3145 (defun simple-rec ()
3147 (message "Recursive edit in progress")
3150 @result{} simple-rec
3156 @deffn Command exit-recursive-edit
3157 This function exits from the innermost recursive edit (including
3158 minibuffer input). Its definition is effectively @code{(throw 'exit
3162 @deffn Command abort-recursive-edit
3163 This function aborts the command that requested the innermost recursive
3164 edit (including minibuffer input), by signaling @code{quit}
3165 after exiting the recursive edit. Its definition is effectively
3166 @code{(throw 'exit t)}. @xref{Quitting}.
3169 @deffn Command top-level
3170 This function exits all recursive editing levels; it does not return a
3171 value, as it jumps completely out of any computation directly back to
3172 the main command loop.
3175 @defun recursion-depth
3176 This function returns the current depth of recursive edits. When no
3177 recursive edit is active, it returns 0.
3180 @node Disabling Commands
3181 @section Disabling Commands
3182 @cindex disabled command
3184 @dfn{Disabling a command} marks the command as requiring user
3185 confirmation before it can be executed. Disabling is used for commands
3186 which might be confusing to beginning users, to prevent them from using
3187 the commands by accident.
3190 The low-level mechanism for disabling a command is to put a
3191 non-@code{nil} @code{disabled} property on the Lisp symbol for the
3192 command. These properties are normally set up by the user's
3193 init file (@pxref{Init File}) with Lisp expressions such as this:
3196 (put 'upcase-region 'disabled t)
3200 For a few commands, these properties are present by default (you can
3201 remove them in your init file if you wish).
3203 If the value of the @code{disabled} property is a string, the message
3204 saying the command is disabled includes that string. For example:
3207 (put 'delete-region 'disabled
3208 "Text deleted this way cannot be yanked back!\n")
3211 @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on
3212 what happens when a disabled command is invoked interactively.
3213 Disabling a command has no effect on calling it as a function from Lisp
3216 @deffn Command enable-command command
3217 Allow @var{command} (a symbol) to be executed without special
3218 confirmation from now on, and alter the user's init file (@pxref{Init
3219 File}) so that this will apply to future sessions.
3222 @deffn Command disable-command command
3223 Require special confirmation to execute @var{command} from now on, and
3224 alter the user's init file so that this will apply to future sessions.
3227 @defvar disabled-command-function
3228 The value of this variable should be a function. When the user
3229 invokes a disabled command interactively, this function is called
3230 instead of the disabled command. It can use @code{this-command-keys}
3231 to determine what the user typed to run the command, and thus find the
3234 The value may also be @code{nil}. Then all commands work normally,
3237 By default, the value is a function that asks the user whether to
3241 @node Command History
3242 @section Command History
3243 @cindex command history
3244 @cindex complex command
3245 @cindex history of commands
3247 The command loop keeps a history of the complex commands that have
3248 been executed, to make it convenient to repeat these commands. A
3249 @dfn{complex command} is one for which the interactive argument reading
3250 uses the minibuffer. This includes any @kbd{M-x} command, any
3251 @kbd{M-:} command, and any command whose @code{interactive}
3252 specification reads an argument from the minibuffer. Explicit use of
3253 the minibuffer during the execution of the command itself does not cause
3254 the command to be considered complex.
3256 @defvar command-history
3257 This variable's value is a list of recent complex commands, each
3258 represented as a form to evaluate. It continues to accumulate all
3259 complex commands for the duration of the editing session, but when it
3260 reaches the maximum size (@pxref{Minibuffer History}), the oldest
3261 elements are deleted as new ones are added.
3266 @result{} ((switch-to-buffer "chistory.texi")
3267 (describe-key "^X^[")
3268 (visit-tags-table "~/emacs/src/")
3269 (find-tag "repeat-complex-command"))
3274 This history list is actually a special case of minibuffer history
3275 (@pxref{Minibuffer History}), with one special twist: the elements are
3276 expressions rather than strings.
3278 There are a number of commands devoted to the editing and recall of
3279 previous commands. The commands @code{repeat-complex-command}, and
3280 @code{list-command-history} are described in the user manual
3281 (@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the
3282 minibuffer, the usual minibuffer history commands are available.
3284 @node Keyboard Macros
3285 @section Keyboard Macros
3286 @cindex keyboard macros
3288 A @dfn{keyboard macro} is a canned sequence of input events that can
3289 be considered a command and made the definition of a key. The Lisp
3290 representation of a keyboard macro is a string or vector containing the
3291 events. Don't confuse keyboard macros with Lisp macros
3294 @defun execute-kbd-macro kbdmacro &optional count loopfunc
3295 This function executes @var{kbdmacro} as a sequence of events. If
3296 @var{kbdmacro} is a string or vector, then the events in it are executed
3297 exactly as if they had been input by the user. The sequence is
3298 @emph{not} expected to be a single key sequence; normally a keyboard
3299 macro definition consists of several key sequences concatenated.
3301 If @var{kbdmacro} is a symbol, then its function definition is used in
3302 place of @var{kbdmacro}. If that is another symbol, this process repeats.
3303 Eventually the result should be a string or vector. If the result is
3304 not a symbol, string, or vector, an error is signaled.
3306 The argument @var{count} is a repeat count; @var{kbdmacro} is executed that
3307 many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is
3308 executed once. If it is 0, @var{kbdmacro} is executed over and over until it
3309 encounters an error or a failing search.
3311 If @var{loopfunc} is non-@code{nil}, it is a function that is called,
3312 without arguments, prior to each iteration of the macro. If
3313 @var{loopfunc} returns @code{nil}, then this stops execution of the macro.
3315 @xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
3318 @defvar executing-kbd-macro
3319 This variable contains the string or vector that defines the keyboard
3320 macro that is currently executing. It is @code{nil} if no macro is
3321 currently executing. A command can test this variable so as to behave
3322 differently when run from an executing macro. Do not set this variable
3326 @defvar defining-kbd-macro
3327 This variable is non-@code{nil} if and only if a keyboard macro is
3328 being defined. A command can test this variable so as to behave
3329 differently while a macro is being defined. The value is
3330 @code{append} while appending to the definition of an existing macro.
3331 The commands @code{start-kbd-macro}, @code{kmacro-start-macro} and
3332 @code{end-kbd-macro} set this variable---do not set it yourself.
3334 The variable is always local to the current terminal and cannot be
3335 buffer-local. @xref{Multiple Displays}.
3338 @defvar last-kbd-macro
3339 This variable is the definition of the most recently defined keyboard
3340 macro. Its value is a string or vector, or @code{nil}.
3342 The variable is always local to the current terminal and cannot be
3343 buffer-local. @xref{Multiple Displays}.
3346 @defvar kbd-macro-termination-hook
3347 This normal hook (@pxref{Standard Hooks}) is run when a keyboard
3348 macro terminates, regardless of what caused it to terminate (reaching
3349 the macro end or an error which ended the macro prematurely).
3353 arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1