2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
4 @c 2004, 2005, 2006 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 * Command Loop Info:: Variables set by the command loop for you to examine.
22 * Adjusting Point:: Adjustment of point after a command.
23 * Input Events:: What input looks like when you read it.
24 * Reading Input:: How to read input events from the keyboard or mouse.
25 * Special Events:: Events processed immediately and individually.
26 * Waiting:: Waiting for user input or elapsed time.
27 * Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
28 * Prefix Command Arguments:: How the commands to set prefix args work.
29 * Recursive Editing:: Entering a recursive edit,
30 and why you usually shouldn't.
31 * Disabling Commands:: How the command loop handles disabled commands.
32 * Command History:: How the command history is set up, and how accessed.
33 * Keyboard Macros:: How keyboard macros are implemented.
36 @node Command Overview
37 @section Command Loop Overview
39 The first thing the command loop must do is read a key sequence, which
40 is a sequence of events that translates into a command. It does this by
41 calling the function @code{read-key-sequence}. Your Lisp code can also
42 call this function (@pxref{Key Sequence Input}). Lisp programs can also
43 do input at a lower level with @code{read-event} (@pxref{Reading One
44 Event}) or discard pending input with @code{discard-input}
45 (@pxref{Event Input Misc}).
47 The key sequence is translated into a command through the currently
48 active keymaps. @xref{Key Lookup}, for information on how this is done.
49 The result should be a keyboard macro or an interactively callable
50 function. If the key is @kbd{M-x}, then it reads the name of another
51 command, which it then calls. This is done by the command
52 @code{execute-extended-command} (@pxref{Interactive Call}).
54 To execute a command requires first reading the arguments for it.
55 This is done by calling @code{command-execute} (@pxref{Interactive
56 Call}). For commands written in Lisp, the @code{interactive}
57 specification says how to read the arguments. This may use the prefix
58 argument (@pxref{Prefix Command Arguments}) or may read with prompting
59 in the minibuffer (@pxref{Minibuffers}). For example, the command
60 @code{find-file} has an @code{interactive} specification which says to
61 read a file name using the minibuffer. The command's function body does
62 not use the minibuffer; if you call this command from Lisp code as a
63 function, you must supply the file name string as an ordinary Lisp
66 If the command is a string or vector (i.e., a keyboard macro) then
67 @code{execute-kbd-macro} is used to execute it. You can call this
68 function yourself (@pxref{Keyboard Macros}).
70 To terminate the execution of a running command, type @kbd{C-g}. This
71 character causes @dfn{quitting} (@pxref{Quitting}).
73 @defvar pre-command-hook
74 The editor command loop runs this normal hook before each command. At
75 that time, @code{this-command} contains the command that is about to
76 run, and @code{last-command} describes the previous command.
77 @xref{Command Loop Info}.
80 @defvar post-command-hook
81 The editor command loop runs this normal hook after each command
82 (including commands terminated prematurely by quitting or by errors),
83 and also when the command loop is first entered. At that time,
84 @code{this-command} refers to the command that just ran, and
85 @code{last-command} refers to the command before that.
88 Quitting is suppressed while running @code{pre-command-hook} and
89 @code{post-command-hook}. If an error happens while executing one of
90 these hooks, it terminates execution of the hook, and clears the hook
91 variable to @code{nil} so as to prevent an infinite loop of errors.
93 A request coming into the Emacs server (@pxref{Emacs Server,,,
94 emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard
97 @node Defining Commands
98 @section Defining Commands
99 @cindex defining commands
100 @cindex commands, defining
101 @cindex functions, making them interactive
102 @cindex interactive function
104 A Lisp function becomes a command when its body contains, at top
105 level, a form that calls the special form @code{interactive}. This
106 form does nothing when actually executed, but its presence serves as a
107 flag to indicate that interactive calling is permitted. Its argument
108 controls the reading of arguments for an interactive call.
111 * Using Interactive:: General rules for @code{interactive}.
112 * Interactive Codes:: The standard letter-codes for reading arguments
114 * Interactive Examples:: Examples of how to read interactive arguments.
117 @node Using Interactive
118 @subsection Using @code{interactive}
120 This section describes how to write the @code{interactive} form that
121 makes a Lisp function an interactively-callable command, and how to
122 examine a command's @code{interactive} form.
124 @defspec interactive arg-descriptor
125 @cindex argument descriptors
126 This special form declares that the function in which it appears is a
127 command, and that it may therefore be called interactively (via
128 @kbd{M-x} or by entering a key sequence bound to it). The argument
129 @var{arg-descriptor} declares how to compute the arguments to the
130 command when the command is called interactively.
132 A command may be called from Lisp programs like any other function, but
133 then the caller supplies the arguments and @var{arg-descriptor} has no
136 The @code{interactive} form has its effect because the command loop
137 (actually, its subroutine @code{call-interactively}) scans through the
138 function definition looking for it, before calling the function. Once
139 the function is called, all its body forms including the
140 @code{interactive} form are executed, but at this time
141 @code{interactive} simply returns @code{nil} without even evaluating its
145 There are three possibilities for the argument @var{arg-descriptor}:
149 It may be omitted or @code{nil}; then the command is called with no
150 arguments. This leads quickly to an error if the command requires one
154 @cindex argument prompt
155 It may be a string; then its contents should consist of a code character
156 followed by a prompt (which some code characters use and some ignore).
157 The prompt ends either with the end of the string or with a newline.
158 Here is a simple example:
161 (interactive "bFrobnicate buffer: ")
165 The code letter @samp{b} says to read the name of an existing buffer,
166 with completion. The buffer name is the sole argument passed to the
167 command. The rest of the string is a prompt.
169 If there is a newline character in the string, it terminates the prompt.
170 If the string does not end there, then the rest of the string should
171 contain another code character and prompt, specifying another argument.
172 You can specify any number of arguments in this way.
175 The prompt string can use @samp{%} to include previous argument values
176 (starting with the first argument) in the prompt. This is done using
177 @code{format} (@pxref{Formatting Strings}). For example, here is how
178 you could read the name of an existing buffer followed by a new name to
183 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
187 @cindex @samp{*} in @code{interactive}
188 @cindex read-only buffers in interactive
189 If the first character in the string is @samp{*}, then an error is
190 signaled if the buffer is read-only.
192 @cindex @samp{@@} in @code{interactive}
194 If the first character in the string is @samp{@@}, and if the key
195 sequence used to invoke the command includes any mouse events, then
196 the window associated with the first of those events is selected
197 before the command is run.
199 You can use @samp{*} and @samp{@@} together; the order does not matter.
200 Actual reading of arguments is controlled by the rest of the prompt
201 string (starting with the first character that is not @samp{*} or
205 It may be a Lisp expression that is not a string; then it should be a
206 form that is evaluated to get a list of arguments to pass to the
207 command. Usually this form will call various functions to read input
208 from the user, most often through the minibuffer (@pxref{Minibuffers})
209 or directly from the keyboard (@pxref{Reading Input}).
210 @cindex argument evaluation form
212 Providing point or the mark as an argument value is also common, but
213 if you do this @emph{and} read input (whether using the minibuffer or
214 not), be sure to get the integer values of point or the mark after
215 reading. The current buffer may be receiving subprocess output; if
216 subprocess output arrives while the command is waiting for input, it
217 could relocate point and the mark.
219 Here's an example of what @emph{not} to do:
223 (list (region-beginning) (region-end)
224 (read-string "Foo: " nil 'my-history)))
228 Here's how to avoid the problem, by examining point and the mark after
229 reading the keyboard input:
233 (let ((string (read-string "Foo: " nil 'my-history)))
234 (list (region-beginning) (region-end) string)))
238 @cindex examining the @code{interactive} form
239 @defun interactive-form function
240 This function returns the @code{interactive} form of @var{function}.
241 If @var{function} is an interactively callable function
242 (@pxref{Interactive Call}), the value is the command's
243 @code{interactive} form @code{(interactive @var{spec})}, which
244 specifies how to compute its arguments. Otherwise, the value is
245 @code{nil}. If @var{function} is a symbol, its function definition is
249 @node Interactive Codes
250 @comment node-name, next, previous, up
251 @subsection Code Characters for @code{interactive}
252 @cindex interactive code description
253 @cindex description for interactive codes
254 @cindex codes, interactive, description of
255 @cindex characters for interactive codes
257 The code character descriptions below contain a number of key words,
258 defined here as follows:
262 @cindex interactive completion
263 Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name
264 completion because the argument is read using @code{completing-read}
265 (@pxref{Completion}). @kbd{?} displays a list of possible completions.
268 Require the name of an existing object. An invalid name is not
269 accepted; the commands to exit the minibuffer do not exit if the current
273 @cindex default argument string
274 A default value of some sort is used if the user enters no text in the
275 minibuffer. The default depends on the code character.
278 This code letter computes an argument without reading any input.
279 Therefore, it does not use a prompt string, and any prompt string you
282 Even though the code letter doesn't use a prompt string, you must follow
283 it with a newline if it is not the last code character in the string.
286 A prompt immediately follows the code character. The prompt ends either
287 with the end of the string or with a newline.
290 This code character is meaningful only at the beginning of the
291 interactive string, and it does not look for a prompt or a newline.
292 It is a single, isolated character.
295 @cindex reading interactive arguments
296 Here are the code character descriptions for use with @code{interactive}:
300 Signal an error if the current buffer is read-only. Special.
303 Select the window mentioned in the first mouse event in the key
304 sequence that invoked this command. Special.
307 A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
311 The name of an existing buffer. By default, uses the name of the
312 current buffer (@pxref{Buffers}). Existing, Completion, Default,
316 A buffer name. The buffer need not exist. By default, uses the name of
317 a recently used buffer other than the current buffer. Completion,
321 A character. The cursor does not move into the echo area. Prompt.
324 A command name (i.e., a symbol satisfying @code{commandp}). Existing,
328 @cindex position argument
329 The position of point, as an integer (@pxref{Point}). No I/O.
332 A directory name. The default is the current default directory of the
333 current buffer, @code{default-directory} (@pxref{File Name Expansion}).
334 Existing, Completion, Default, Prompt.
337 The first or next mouse event in the key sequence that invoked the command.
338 More precisely, @samp{e} gets events that are lists, so you can look at
339 the data in the lists. @xref{Input Events}. No I/O.
341 You can use @samp{e} more than once in a single command's interactive
342 specification. If the key sequence that invoked the command has
343 @var{n} events that are lists, the @var{n}th @samp{e} provides the
344 @var{n}th such event. Events that are not lists, such as function keys
345 and @acronym{ASCII} characters, do not count where @samp{e} is concerned.
348 A file name of an existing file (@pxref{File Names}). The default
349 directory is @code{default-directory}. Existing, Completion, Default,
353 A file name. The file need not exist. Completion, Default, Prompt.
356 A file name. The file need not exist. If the user enters just a
357 directory name, then the value is just that directory name, with no
358 file name within the directory added. Completion, Default, Prompt.
361 An irrelevant argument. This code always supplies @code{nil} as
362 the argument's value. No I/O.
365 A key sequence (@pxref{Keymap Terminology}). This keeps reading events
366 until a command (or undefined command) is found in the current key
367 maps. The key sequence argument is represented as a string or vector.
368 The cursor does not move into the echo area. Prompt.
370 If @samp{k} reads a key sequence that ends with a down-event, it also
371 reads and discards the following up-event. You can get access to that
372 up-event with the @samp{U} code character.
374 This kind of input is used by commands such as @code{describe-key} and
375 @code{global-set-key}.
378 A key sequence, whose definition you intend to change. This works like
379 @samp{k}, except that it suppresses, for the last input event in the key
380 sequence, the conversions that are normally used (when necessary) to
381 convert an undefined key into a defined one.
384 @cindex marker argument
385 The position of the mark, as an integer. No I/O.
388 Arbitrary text, read in the minibuffer using the current buffer's input
389 method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
390 Emacs Manual}). Prompt.
393 A number, read with the minibuffer. If the input is not a number, the
394 user has to try again. @samp{n} never uses the prefix argument.
398 The numeric prefix argument; but if there is no prefix argument, read
399 a number as with @kbd{n}. The value is always a number. @xref{Prefix
400 Command Arguments}. Prompt.
403 @cindex numeric prefix argument usage
404 The numeric prefix argument. (Note that this @samp{p} is lower case.)
408 @cindex raw prefix argument usage
409 The raw prefix argument. (Note that this @samp{P} is upper case.) No
413 @cindex region argument
414 Point and the mark, as two numeric arguments, smallest first. This is
415 the only code letter that specifies two successive arguments rather than
419 Arbitrary text, read in the minibuffer and returned as a string
420 (@pxref{Text from Minibuffer}). Terminate the input with either
421 @kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of
422 these characters in the input.) Prompt.
425 An interned symbol whose name is read in the minibuffer. Any whitespace
426 character terminates the input. (Use @kbd{C-q} to include whitespace in
427 the string.) Other characters that normally terminate a symbol (e.g.,
428 parentheses and brackets) do not do so here. Prompt.
431 A key sequence or @code{nil}. Can be used after a @samp{k} or
432 @samp{K} argument to get the up-event that was discarded (if any)
433 after @samp{k} or @samp{K} read a down-event. If no up-event has been
434 discarded, @samp{U} provides @code{nil} as the argument. No I/O.
437 A variable declared to be a user option (i.e., satisfying the
438 predicate @code{user-variable-p}). This reads the variable using
439 @code{read-variable}. @xref{Definition of read-variable}. Existing,
443 A Lisp object, specified with its read syntax, terminated with a
444 @kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from
448 @cindex evaluated expression argument
449 A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates
450 the form so that its value becomes the argument for the command.
454 A coding system name (a symbol). If the user enters null input, the
455 argument value is @code{nil}. @xref{Coding Systems}. Completion,
459 A coding system name (a symbol)---but only if this command has a prefix
460 argument. With no prefix argument, @samp{Z} provides @code{nil} as the
461 argument value. Completion, Existing, Prompt.
464 @node Interactive Examples
465 @comment node-name, next, previous, up
466 @subsection Examples of Using @code{interactive}
467 @cindex examples of using @code{interactive}
468 @cindex @code{interactive}, examples of using
470 Here are some examples of @code{interactive}:
474 (defun foo1 () ; @r{@code{foo1} takes no arguments,}
475 (interactive) ; @r{just moves forward two words.}
481 (defun foo2 (n) ; @r{@code{foo2} takes one argument,}
482 (interactive "p") ; @r{which is the numeric prefix.}
483 (forward-word (* 2 n)))
488 (defun foo3 (n) ; @r{@code{foo3} takes one argument,}
489 (interactive "nCount:") ; @r{which is read with the Minibuffer.}
490 (forward-word (* 2 n)))
495 (defun three-b (b1 b2 b3)
496 "Select three existing buffers.
497 Put them into three windows, selecting the last one."
499 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
500 (delete-other-windows)
501 (split-window (selected-window) 8)
502 (switch-to-buffer b1)
504 (split-window (selected-window) 8)
505 (switch-to-buffer b2)
507 (switch-to-buffer b3))
510 (three-b "*scratch*" "declarations.texi" "*mail*")
515 @node Interactive Call
516 @section Interactive Call
517 @cindex interactive call
519 After the command loop has translated a key sequence into a command it
520 invokes that command using the function @code{command-execute}. If the
521 command is a function, @code{command-execute} calls
522 @code{call-interactively}, which reads the arguments and calls the
523 command. You can also call these functions yourself.
525 @defun commandp object &optional for-call-interactively
526 Returns @code{t} if @var{object} is suitable for calling interactively;
527 that is, if @var{object} is a command. Otherwise, returns @code{nil}.
529 The interactively callable objects include strings and vectors (treated
530 as keyboard macros), lambda expressions that contain a top-level call to
531 @code{interactive}, byte-code function objects made from such lambda
532 expressions, autoload objects that are declared as interactive
533 (non-@code{nil} fourth argument to @code{autoload}), and some of the
536 A symbol satisfies @code{commandp} if its function definition
537 satisfies @code{commandp}. Keys and keymaps are not commands.
538 Rather, they are used to look up commands (@pxref{Keymaps}).
540 If @var{for-call-interactively} is non-@code{nil}, then
541 @code{commandp} returns @code{t} only for objects that
542 @code{call-interactively} could call---thus, not for keyboard macros.
544 See @code{documentation} in @ref{Accessing Documentation}, for a
545 realistic example of using @code{commandp}.
548 @defun call-interactively command &optional record-flag keys
549 This function calls the interactively callable function @var{command},
550 reading arguments according to its interactive calling specifications.
551 It returns whatever @var{command} returns. An error is signaled if
552 @var{command} is not a function or if it cannot be called
553 interactively (i.e., is not a command). Note that keyboard macros
554 (strings and vectors) are not accepted, even though they are
555 considered commands, because they are not functions. If @var{command}
556 is a symbol, then @code{call-interactively} uses its function definition.
558 @cindex record command history
559 If @var{record-flag} is non-@code{nil}, then this command and its
560 arguments are unconditionally added to the list @code{command-history}.
561 Otherwise, the command is added only if it uses the minibuffer to read
562 an argument. @xref{Command History}.
564 The argument @var{keys}, if given, specifies the sequence of events to
565 supply if the command inquires which events were used to invoke it.
566 If @var{keys} is omitted or @code{nil}, the return value of
567 @code{this-command-keys} is used. @xref{Definition of this-command-keys}.
570 @defun command-execute command &optional record-flag keys special
571 @cindex keyboard macro execution
572 This function executes @var{command}. The argument @var{command} must
573 satisfy the @code{commandp} predicate; i.e., it must be an interactively
574 callable function or a keyboard macro.
576 A string or vector as @var{command} is executed with
577 @code{execute-kbd-macro}. A function is passed to
578 @code{call-interactively}, along with the optional @var{record-flag}
581 A symbol is handled by using its function definition in its place. A
582 symbol with an @code{autoload} definition counts as a command if it was
583 declared to stand for an interactively callable function. Such a
584 definition is handled by loading the specified library and then
585 rechecking the definition of the symbol.
587 The argument @var{special}, if given, means to ignore the prefix
588 argument and not clear it. This is used for executing special events
589 (@pxref{Special Events}).
592 @deffn Command execute-extended-command prefix-argument
593 @cindex read command name
594 This function reads a command name from the minibuffer using
595 @code{completing-read} (@pxref{Completion}). Then it uses
596 @code{command-execute} to call the specified command. Whatever that
597 command returns becomes the value of @code{execute-extended-command}.
599 @cindex execute with prefix argument
600 If the command asks for a prefix argument, it receives the value
601 @var{prefix-argument}. If @code{execute-extended-command} is called
602 interactively, the current raw prefix argument is used for
603 @var{prefix-argument}, and thus passed on to whatever command is run.
605 @c !!! Should this be @kindex?
607 @code{execute-extended-command} is the normal definition of @kbd{M-x},
608 so it uses the string @w{@samp{M-x }} as a prompt. (It would be better
609 to take the prompt from the events used to invoke
610 @code{execute-extended-command}, but that is painful to implement.) A
611 description of the value of the prefix argument, if any, also becomes
616 (execute-extended-command 1)
617 ---------- Buffer: Minibuffer ----------
618 1 M-x forward-word RET
619 ---------- Buffer: Minibuffer ----------
626 This function returns @code{t} if the containing function (the one
627 whose code includes the call to @code{interactive-p}) was called in
628 direct response to user input. This means that it was called with the
629 function @code{call-interactively}, and that a keyboard macro is
630 not running, and that Emacs is not running in batch mode.
632 If the containing function was called by Lisp evaluation (or with
633 @code{apply} or @code{funcall}), then it was not called interactively.
636 The most common use of @code{interactive-p} is for deciding whether
637 to give the user additional visual feedback (such as by printing an
638 informative message). For example:
642 ;; @r{Here's the usual way to use @code{interactive-p}.}
645 (when (interactive-p)
651 ;; @r{This function is just to illustrate the behavior.}
654 (setq foobar (list (foo) (interactive-p))))
659 ;; @r{Type @kbd{M-x foo}.}
664 ;; @r{Type @kbd{M-x bar}.}
665 ;; @r{This does not display a message.}
674 If you want to test @emph{only} whether the function was called
675 using @code{call-interactively}, add an optional argument
676 @code{print-message} which should be non-@code{nil} in an interactive
677 call, and use the @code{interactive} spec to make sure it is
678 non-@code{nil}. Here's an example:
681 (defun foo (&optional print-message)
688 Defined in this way, the function does display the message when called
689 from a keyboard macro. We use @code{"p"} because the numeric prefix
690 argument is never @code{nil}.
692 @defun called-interactively-p
693 This function returns @code{t} when the calling function was called
694 using @code{call-interactively}.
696 When possible, instead of using this function, you should use the
697 method in the example above; that method makes it possible for a
698 caller to ``pretend'' that the function was called interactively.
701 @node Command Loop Info
702 @comment node-name, next, previous, up
703 @section Information from the Command Loop
705 The editor command loop sets several Lisp variables to keep status
706 records for itself and for commands that are run.
709 This variable records the name of the previous command executed by the
710 command loop (the one before the current command). Normally the value
711 is a symbol with a function definition, but this is not guaranteed.
713 The value is copied from @code{this-command} when a command returns to
714 the command loop, except when the command has specified a prefix
715 argument for the following command.
717 This variable is always local to the current terminal and cannot be
718 buffer-local. @xref{Multiple Displays}.
721 @defvar real-last-command
722 This variable is set up by Emacs just like @code{last-command},
723 but never altered by Lisp programs.
727 @cindex current command
728 This variable records the name of the command now being executed by
729 the editor command loop. Like @code{last-command}, it is normally a symbol
730 with a function definition.
732 The command loop sets this variable just before running a command, and
733 copies its value into @code{last-command} when the command finishes
734 (unless the command specified a prefix argument for the following
737 @cindex kill command repetition
738 Some commands set this variable during their execution, as a flag for
739 whatever command runs next. In particular, the functions for killing text
740 set @code{this-command} to @code{kill-region} so that any kill commands
741 immediately following will know to append the killed text to the
745 If you do not want a particular command to be recognized as the previous
746 command in the case where it got an error, you must code that command to
747 prevent this. One way is to set @code{this-command} to @code{t} at the
748 beginning of the command, and set @code{this-command} back to its proper
749 value at the end, like this:
752 (defun foo (args@dots{})
753 (interactive @dots{})
754 (let ((old-this-command this-command))
755 (setq this-command t)
756 @r{@dots{}do the work@dots{}}
757 (setq this-command old-this-command)))
761 We do not bind @code{this-command} with @code{let} because that would
762 restore the old value in case of error---a feature of @code{let} which
763 in this case does precisely what we want to avoid.
765 @defvar this-original-command
766 This has the same value as @code{this-command} except when command
767 remapping occurs (@pxref{Remapping Commands}). In that case,
768 @code{this-command} gives the command actually run (the result of
769 remapping), and @code{this-original-command} gives the command that
770 was specified to run but remapped into another command.
773 @defun this-command-keys
774 @anchor{Definition of this-command-keys}
775 This function returns a string or vector containing the key sequence
776 that invoked the present command, plus any previous commands that
777 generated the prefix argument for this command. However, if the
778 command has called @code{read-key-sequence}, it returns the last read
779 key sequence. @xref{Key Sequence Input}. The value is a string if
780 all events in the sequence were characters that fit in a string.
786 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
792 @defun this-command-keys-vector
793 Like @code{this-command-keys}, except that it always returns the events
794 in a vector, so you don't need to deal with the complexities of storing
795 input events in a string (@pxref{Strings of Events}).
798 @tindex clear-this-command-keys
799 @defun clear-this-command-keys &optional keep-record
800 This function empties out the table of events for
801 @code{this-command-keys} to return. Unless @var{keep-record} is
802 non-@code{nil}, it also empties the records that the function
803 @code{recent-keys} (@pxref{Recording Input}) will subsequently return.
804 This is useful after reading a password, to prevent the password from
805 echoing inadvertently as part of the next command in certain cases.
808 @defvar last-nonmenu-event
809 This variable holds the last input event read as part of a key sequence,
810 not counting events resulting from mouse menus.
812 One use of this variable is for telling @code{x-popup-menu} where to pop
813 up a menu. It is also used internally by @code{y-or-n-p}
814 (@pxref{Yes-or-No Queries}).
817 @defvar last-command-event
818 @defvarx last-command-char
819 This variable is set to the last input event that was read by the
820 command loop as part of a command. The principal use of this variable
821 is in @code{self-insert-command}, which uses it to decide which
827 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
833 The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
835 The alias @code{last-command-char} exists for compatibility with
840 @defvar last-event-frame
841 This variable records which frame the last input event was directed to.
842 Usually this is the frame that was selected when the event was
843 generated, but if that frame has redirected input focus to another
844 frame, the value is the frame to which the event was redirected.
847 If the last event came from a keyboard macro, the value is @code{macro}.
850 @node Adjusting Point
851 @section Adjusting Point After Commands
853 It is not easy to display a value of point in the middle of a
854 sequence of text that has the @code{display}, @code{composition} or
855 @code{intangible} property, or is invisible. Therefore, after a
856 command finishes and returns to the command loop, if point is within
857 such a sequence, the command loop normally moves point to the edge of
860 A command can inhibit this feature by setting the variable
861 @code{disable-point-adjustment}:
863 @defvar disable-point-adjustment
864 @tindex disable-point-adjustment
865 If this variable is non-@code{nil} when a command returns to the
866 command loop, then the command loop does not check for those text
867 properties, and does not move point out of sequences that have them.
869 The command loop sets this variable to @code{nil} before each command,
870 so if a command sets it, the effect applies only to that command.
873 @defvar global-disable-point-adjustment
874 @tindex global-disable-point-adjustment
875 If you set this variable to a non-@code{nil} value, the feature of
876 moving point out of these sequences is completely turned off.
880 @section Input Events
884 The Emacs command loop reads a sequence of @dfn{input events} that
885 represent keyboard or mouse activity. The events for keyboard activity
886 are characters or symbols; mouse events are always lists. This section
887 describes the representation and meaning of input events in detail.
890 This function returns non-@code{nil} if @var{object} is an input event
893 Note that any symbol might be used as an event or an event type.
894 @code{eventp} cannot distinguish whether a symbol is intended by Lisp
895 code to be used as an event. Instead, it distinguishes whether the
896 symbol has actually been used in an event that has been read as input in
897 the current Emacs session. If a symbol has not yet been so used,
898 @code{eventp} returns @code{nil}.
902 * Keyboard Events:: Ordinary characters--keys with symbols on them.
903 * Function Keys:: Function keys--keys with names, not symbols.
904 * Mouse Events:: Overview of mouse events.
905 * Click Events:: Pushing and releasing a mouse button.
906 * Drag Events:: Moving the mouse before releasing the button.
907 * Button-Down Events:: A button was pushed and not yet released.
908 * Repeat Events:: Double and triple click (or drag, or down).
909 * Motion Events:: Just moving the mouse, not pushing a button.
910 * Focus Events:: Moving the mouse between frames.
911 * Misc Events:: Other events the system can generate.
912 * Event Examples:: Examples of the lists for mouse events.
913 * Classifying Events:: Finding the modifier keys in an event symbol.
915 * Accessing Events:: Functions to extract info from events.
916 * Strings of Events:: Special considerations for putting
917 keyboard character events in a string.
920 @node Keyboard Events
921 @subsection Keyboard Events
923 There are two kinds of input you can get from the keyboard: ordinary
924 keys, and function keys. Ordinary keys correspond to characters; the
925 events they generate are represented in Lisp as characters. The event
926 type of a character event is the character itself (an integer); see
927 @ref{Classifying Events}.
929 @cindex modifier bits (of input character)
930 @cindex basic code (of input character)
931 An input character event consists of a @dfn{basic code} between 0 and
932 524287, plus any or all of these @dfn{modifier bits}:
943 bit in the character code indicates a character
944 typed with the meta key held down.
954 bit in the character code indicates a non-@acronym{ASCII}
957 @sc{ascii} control characters such as @kbd{C-a} have special basic
958 codes of their own, so Emacs needs no special bit to indicate them.
959 Thus, the code for @kbd{C-a} is just 1.
961 But if you type a control combination not in @acronym{ASCII}, such as
962 @kbd{%} with the control key, the numeric value you get is the code
970 (assuming the terminal supports non-@acronym{ASCII}
981 bit in the character code indicates an @acronym{ASCII} control
982 character typed with the shift key held down.
984 For letters, the basic code itself indicates upper versus lower case;
985 for digits and punctuation, the shift key selects an entirely different
986 character with a different basic code. In order to keep within the
987 @acronym{ASCII} character set whenever possible, Emacs avoids using the
994 bit for those characters.
996 However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
997 @kbd{C-a}, so Emacs uses the
1004 bit in @kbd{C-A} and not in
1015 bit in the character code indicates a character
1016 typed with the hyper key held down.
1026 bit in the character code indicates a character
1027 typed with the super key held down.
1037 bit in the character code indicates a character typed with
1038 the alt key held down. (On some terminals, the key labeled @key{ALT}
1039 is actually the meta key.)
1042 It is best to avoid mentioning specific bit numbers in your program.
1043 To test the modifier bits of a character, use the function
1044 @code{event-modifiers} (@pxref{Classifying Events}). When making key
1045 bindings, you can use the read syntax for characters with modifier bits
1046 (@samp{\C-}, @samp{\M-}, and so on). For making key bindings with
1047 @code{define-key}, you can use lists such as @code{(control hyper ?x)} to
1048 specify the characters (@pxref{Changing Key Bindings}). The function
1049 @code{event-convert-list} converts such a list into an event type
1050 (@pxref{Classifying Events}).
1053 @subsection Function Keys
1055 @cindex function keys
1056 Most keyboards also have @dfn{function keys}---keys that have names or
1057 symbols that are not characters. Function keys are represented in Emacs
1058 Lisp as symbols; the symbol's name is the function key's label, in lower
1059 case. For example, pressing a key labeled @key{F1} places the symbol
1060 @code{f1} in the input stream.
1062 The event type of a function key event is the event symbol itself.
1063 @xref{Classifying Events}.
1065 Here are a few special cases in the symbol-naming convention for
1069 @item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
1070 These keys correspond to common @acronym{ASCII} control characters that have
1071 special keys on most keyboards.
1073 In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the
1074 terminal can distinguish between them, Emacs conveys the distinction to
1075 Lisp programs by representing the former as the integer 9, and the
1076 latter as the symbol @code{tab}.
1078 Most of the time, it's not useful to distinguish the two. So normally
1079 @code{function-key-map} (@pxref{Translating Input}) is set up to map
1080 @code{tab} into 9. Thus, a key binding for character code 9 (the
1081 character @kbd{C-i}) also applies to @code{tab}. Likewise for the other
1082 symbols in this group. The function @code{read-char} likewise converts
1083 these events into characters.
1085 In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace}
1086 converts into the character code 127 (@key{DEL}), not into code 8
1087 (@key{BS}). This is what most users prefer.
1089 @item @code{left}, @code{up}, @code{right}, @code{down}
1091 @item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
1092 Keypad keys (to the right of the regular keyboard).
1093 @item @code{kp-0}, @code{kp-1}, @dots{}
1094 Keypad keys with digits.
1095 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
1097 @item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
1098 Keypad arrow keys. Emacs normally translates these into the
1099 corresponding non-keypad keys @code{home}, @code{left}, @dots{}
1100 @item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
1101 Additional keypad duplicates of keys ordinarily found elsewhere. Emacs
1102 normally translates these into the like-named non-keypad keys.
1105 You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
1106 @key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to
1107 represent them is with prefixes in the symbol name:
1113 The control modifier.
1124 Thus, the symbol for the key @key{F3} with @key{META} held down is
1125 @code{M-f3}. When you use more than one prefix, we recommend you
1126 write them in alphabetical order; but the order does not matter in
1127 arguments to the key-binding lookup and modification functions.
1130 @subsection Mouse Events
1132 Emacs supports four kinds of mouse events: click events, drag events,
1133 button-down events, and motion events. All mouse events are represented
1134 as lists. The @sc{car} of the list is the event type; this says which
1135 mouse button was involved, and which modifier keys were used with it.
1136 The event type can also distinguish double or triple button presses
1137 (@pxref{Repeat Events}). The rest of the list elements give position
1138 and time information.
1140 For key lookup, only the event type matters: two events of the same type
1141 necessarily run the same command. The command can access the full
1142 values of these events using the @samp{e} interactive code.
1143 @xref{Interactive Codes}.
1145 A key sequence that starts with a mouse event is read using the keymaps
1146 of the buffer in the window that the mouse was in, not the current
1147 buffer. This does not imply that clicking in a window selects that
1148 window or its buffer---that is entirely under the control of the command
1149 binding of the key sequence.
1152 @subsection Click Events
1154 @cindex mouse click event
1156 When the user presses a mouse button and releases it at the same
1157 location, that generates a @dfn{click} event. All mouse click event
1158 share the same format:
1161 (@var{event-type} @var{position} @var{click-count})
1165 @item @var{event-type}
1166 This is a symbol that indicates which mouse button was used. It is
1167 one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the
1168 buttons are numbered left to right.
1170 You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-},
1171 @samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift
1172 and super, just as you would with function keys.
1174 This symbol also serves as the event type of the event. Key bindings
1175 describe events by their types; thus, if there is a key binding for
1176 @code{mouse-1}, that binding would apply to all events whose
1177 @var{event-type} is @code{mouse-1}.
1179 @item @var{position}
1180 This is the position where the mouse click occurred. The actual
1181 format of @var{position} depends on what part of a window was clicked
1182 on. The various formats are described below.
1184 @item @var{click-count}
1185 This is the number of rapid repeated presses so far of the same mouse
1186 button. @xref{Repeat Events}.
1189 For mouse click events in the text area, mode line, header line, or in
1190 the marginal areas, @var{position} has this form:
1193 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
1194 @var{object} @var{text-pos} (@var{col} . @var{row})
1195 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
1200 This is the window in which the click occurred.
1202 @item @var{pos-or-area}
1203 This is the buffer position of the character clicked on in the text
1204 area, or if clicked outside the text area, it is the window area in
1205 which the click occurred. It is one of the symbols @code{mode-line},
1206 @code{header-line}, @code{vertical-line}, @code{left-margin},
1207 @code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
1209 @item @var{x}, @var{y}
1210 These are the pixel-denominated coordinates of the click, relative to
1211 the top left corner of @var{window}, which is @code{(0 . 0)}.
1212 For the mode or header line, @var{y} does not have meaningful data.
1213 For the vertical line, @var{x} does not have meaningful data.
1215 @item @var{timestamp}
1216 This is the time at which the event occurred, in milliseconds.
1219 This is the object on which the click occurred. It is either
1220 @code{nil} if there is no string property, or it has the form
1221 (@var{string} . @var{string-pos}) when there is a string-type text
1222 property at the click position.
1225 This is the string on which the click occurred, including any
1228 @item @var{string-pos}
1229 This is the position in the string on which the click occurred,
1230 relevant if properties at the click need to be looked up.
1232 @item @var{text-pos}
1233 For clicks on a marginal area or on a fringe, this is the buffer
1234 position of the first visible character in the corresponding line in
1235 the window. For other events, it is the current buffer position in
1238 @item @var{col}, @var{row}
1239 These are the actual coordinates of the glyph under the @var{x},
1240 @var{y} position, possibly padded with default character width
1241 glyphs if @var{x} is beyond the last glyph on the line.
1244 This is the image object on which the click occurred. It is either
1245 @code{nil} if there is no image at the position clicked on, or it is
1246 an image object as returned by @code{find-image} if click was in an image.
1248 @item @var{dx}, @var{dy}
1249 These are the pixel-denominated coordinates of the click, relative to
1250 the top left corner of @var{object}, which is @code{(0 . 0)}. If
1251 @var{object} is @code{nil}, the coordinates are relative to the top
1252 left corner of the character glyph clicked on.
1255 For mouse clicks on a scroll-bar, @var{position} has this form:
1258 (@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
1263 This is the window whose scroll-bar was clicked on.
1266 This is the scroll bar where the click occurred. It is one of the
1267 symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.
1270 This is the distance of the click from the top or left end of
1274 This is the length of the entire scroll bar.
1276 @item @var{timestamp}
1277 This is the time at which the event occurred, in milliseconds.
1280 This is the part of the scroll-bar which was clicked on. It is one
1281 of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
1282 @code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
1285 In one special case, @var{buffer-pos} is a list containing a symbol (one
1286 of the symbols listed above) instead of just the symbol. This happens
1287 after the imaginary prefix keys for the event are inserted into the
1288 input stream. @xref{Key Sequence Input}.
1291 @subsection Drag Events
1293 @cindex mouse drag event
1295 With Emacs, you can have a drag event without even changing your
1296 clothes. A @dfn{drag event} happens every time the user presses a mouse
1297 button and then moves the mouse to a different character position before
1298 releasing the button. Like all mouse events, drag events are
1299 represented in Lisp as lists. The lists record both the starting mouse
1300 position and the final position, like this:
1304 (@var{window1} @var{buffer-pos1} (@var{x1} . @var{y1}) @var{timestamp1})
1305 (@var{window2} @var{buffer-pos2} (@var{x2} . @var{y2}) @var{timestamp2})
1309 For a drag event, the name of the symbol @var{event-type} contains the
1310 prefix @samp{drag-}. For example, dragging the mouse with button 2 held
1311 down generates a @code{drag-mouse-2} event. The second and third
1312 elements of the event give the starting and ending position of the drag.
1313 Aside from that, the data have the same meanings as in a click event
1314 (@pxref{Click Events}). You can access the second element of any mouse
1315 event in the same way, with no need to distinguish drag events from
1318 The @samp{drag-} prefix follows the modifier key prefixes such as
1319 @samp{C-} and @samp{M-}.
1321 If @code{read-key-sequence} receives a drag event that has no key
1322 binding, and the corresponding click event does have a binding, it
1323 changes the drag event into a click event at the drag's starting
1324 position. This means that you don't have to distinguish between click
1325 and drag events unless you want to.
1327 @node Button-Down Events
1328 @subsection Button-Down Events
1329 @cindex button-down event
1331 Click and drag events happen when the user releases a mouse button.
1332 They cannot happen earlier, because there is no way to distinguish a
1333 click from a drag until the button is released.
1335 If you want to take action as soon as a button is pressed, you need to
1336 handle @dfn{button-down} events.@footnote{Button-down is the
1337 conservative antithesis of drag.} These occur as soon as a button is
1338 pressed. They are represented by lists that look exactly like click
1339 events (@pxref{Click Events}), except that the @var{event-type} symbol
1340 name contains the prefix @samp{down-}. The @samp{down-} prefix follows
1341 modifier key prefixes such as @samp{C-} and @samp{M-}.
1343 The function @code{read-key-sequence} ignores any button-down events
1344 that don't have command bindings; therefore, the Emacs command loop
1345 ignores them too. This means that you need not worry about defining
1346 button-down events unless you want them to do something. The usual
1347 reason to define a button-down event is so that you can track mouse
1348 motion (by reading motion events) until the button is released.
1349 @xref{Motion Events}.
1352 @subsection Repeat Events
1353 @cindex repeat events
1354 @cindex double-click events
1355 @cindex triple-click events
1356 @cindex mouse events, repeated
1358 If you press the same mouse button more than once in quick succession
1359 without moving the mouse, Emacs generates special @dfn{repeat} mouse
1360 events for the second and subsequent presses.
1362 The most common repeat events are @dfn{double-click} events. Emacs
1363 generates a double-click event when you click a button twice; the event
1364 happens when you release the button (as is normal for all click
1367 The event type of a double-click event contains the prefix
1368 @samp{double-}. Thus, a double click on the second mouse button with
1369 @key{meta} held down comes to the Lisp program as
1370 @code{M-double-mouse-2}. If a double-click event has no binding, the
1371 binding of the corresponding ordinary click event is used to execute
1372 it. Thus, you need not pay attention to the double click feature
1373 unless you really want to.
1375 When the user performs a double click, Emacs generates first an ordinary
1376 click event, and then a double-click event. Therefore, you must design
1377 the command binding of the double click event to assume that the
1378 single-click command has already run. It must produce the desired
1379 results of a double click, starting from the results of a single click.
1381 This is convenient, if the meaning of a double click somehow ``builds
1382 on'' the meaning of a single click---which is recommended user interface
1383 design practice for double clicks.
1385 If you click a button, then press it down again and start moving the
1386 mouse with the button held down, then you get a @dfn{double-drag} event
1387 when you ultimately release the button. Its event type contains
1388 @samp{double-drag} instead of just @samp{drag}. If a double-drag event
1389 has no binding, Emacs looks for an alternate binding as if the event
1390 were an ordinary drag.
1392 Before the double-click or double-drag event, Emacs generates a
1393 @dfn{double-down} event when the user presses the button down for the
1394 second time. Its event type contains @samp{double-down} instead of just
1395 @samp{down}. If a double-down event has no binding, Emacs looks for an
1396 alternate binding as if the event were an ordinary button-down event.
1397 If it finds no binding that way either, the double-down event is
1400 To summarize, when you click a button and then press it again right
1401 away, Emacs generates a down event and a click event for the first
1402 click, a double-down event when you press the button again, and finally
1403 either a double-click or a double-drag event.
1405 If you click a button twice and then press it again, all in quick
1406 succession, Emacs generates a @dfn{triple-down} event, followed by
1407 either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of
1408 these events contain @samp{triple} instead of @samp{double}. If any
1409 triple event has no binding, Emacs uses the binding that it would use
1410 for the corresponding double event.
1412 If you click a button three or more times and then press it again, the
1413 events for the presses beyond the third are all triple events. Emacs
1414 does not have separate event types for quadruple, quintuple, etc.@:
1415 events. However, you can look at the event list to find out precisely
1416 how many times the button was pressed.
1418 @defun event-click-count event
1419 This function returns the number of consecutive button presses that led
1420 up to @var{event}. If @var{event} is a double-down, double-click or
1421 double-drag event, the value is 2. If @var{event} is a triple event,
1422 the value is 3 or greater. If @var{event} is an ordinary mouse event
1423 (not a repeat event), the value is 1.
1426 @defopt double-click-fuzz
1427 To generate repeat events, successive mouse button presses must be at
1428 approximately the same screen position. The value of
1429 @code{double-click-fuzz} specifies the maximum number of pixels the
1430 mouse may be moved (horizontally or vertically) between two successive
1431 clicks to make a double-click.
1433 This variable is also the threshold for motion of the mouse to count
1437 @defopt double-click-time
1438 To generate repeat events, the number of milliseconds between
1439 successive button presses must be less than the value of
1440 @code{double-click-time}. Setting @code{double-click-time} to
1441 @code{nil} disables multi-click detection entirely. Setting it to
1442 @code{t} removes the time limit; Emacs then detects multi-clicks by
1447 @subsection Motion Events
1448 @cindex motion event
1449 @cindex mouse motion events
1451 Emacs sometimes generates @dfn{mouse motion} events to describe motion
1452 of the mouse without any button activity. Mouse motion events are
1453 represented by lists that look like this:
1456 (mouse-movement (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}))
1459 The second element of the list describes the current position of the
1460 mouse, just as in a click event (@pxref{Click Events}).
1462 The special form @code{track-mouse} enables generation of motion events
1463 within its body. Outside of @code{track-mouse} forms, Emacs does not
1464 generate events for mere motion of the mouse, and these events do not
1465 appear. @xref{Mouse Tracking}.
1468 @subsection Focus Events
1471 Window systems provide general ways for the user to control which window
1472 gets keyboard input. This choice of window is called the @dfn{focus}.
1473 When the user does something to switch between Emacs frames, that
1474 generates a @dfn{focus event}. The normal definition of a focus event,
1475 in the global keymap, is to select a new frame within Emacs, as the user
1476 would expect. @xref{Input Focus}.
1478 Focus events are represented in Lisp as lists that look like this:
1481 (switch-frame @var{new-frame})
1485 where @var{new-frame} is the frame switched to.
1487 Most X window managers are set up so that just moving the mouse into a
1488 window is enough to set the focus there. Emacs appears to do this,
1489 because it changes the cursor to solid in the new frame. However, there
1490 is no need for the Lisp program to know about the focus change until
1491 some other kind of input arrives. So Emacs generates a focus event only
1492 when the user actually types a keyboard key or presses a mouse button in
1493 the new frame; just moving the mouse between frames does not generate a
1496 A focus event in the middle of a key sequence would garble the
1497 sequence. So Emacs never generates a focus event in the middle of a key
1498 sequence. If the user changes focus in the middle of a key
1499 sequence---that is, after a prefix key---then Emacs reorders the events
1500 so that the focus event comes either before or after the multi-event key
1501 sequence, and not within it.
1504 @subsection Miscellaneous System Events
1506 A few other event types represent occurrences within the system.
1509 @cindex @code{delete-frame} event
1510 @item (delete-frame (@var{frame}))
1511 This kind of event indicates that the user gave the window manager
1512 a command to delete a particular window, which happens to be an Emacs frame.
1514 The standard definition of the @code{delete-frame} event is to delete @var{frame}.
1516 @cindex @code{iconify-frame} event
1517 @item (iconify-frame (@var{frame}))
1518 This kind of event indicates that the user iconified @var{frame} using
1519 the window manager. Its standard definition is @code{ignore}; since the
1520 frame has already been iconified, Emacs has no work to do. The purpose
1521 of this event type is so that you can keep track of such events if you
1524 @cindex @code{make-frame-visible} event
1525 @item (make-frame-visible (@var{frame}))
1526 This kind of event indicates that the user deiconified @var{frame} using
1527 the window manager. Its standard definition is @code{ignore}; since the
1528 frame has already been made visible, Emacs has no work to do.
1530 @cindex @code{wheel-up} event
1531 @cindex @code{wheel-down} event
1532 @item (wheel-up @var{position})
1533 @item (wheel-down @var{position})
1534 These kinds of event are generated by moving a mouse wheel. Their
1535 usual meaning is a kind of scroll or zoom.
1537 The element @var{position} is a list describing the position of the
1538 event, in the same format as used in a mouse-click event.
1540 This kind of event is generated only on some kinds of systems. On some
1541 systems, @code{mouse-4} and @code{mouse-5} are used instead. For
1542 portable code, use the variables @code{mouse-wheel-up-event} and
1543 @code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine
1544 what event types to expect for the mouse wheel.
1546 @cindex @code{drag-n-drop} event
1547 @item (drag-n-drop @var{position} @var{files})
1548 This kind of event is generated when a group of files is
1549 selected in an application outside of Emacs, and then dragged and
1550 dropped onto an Emacs frame.
1552 The element @var{position} is a list describing the position of the
1553 event, in the same format as used in a mouse-click event, and
1554 @var{files} is the list of file names that were dragged and dropped.
1555 The usual way to handle this event is by visiting these files.
1557 This kind of event is generated, at present, only on some kinds of
1560 @cindex @code{help-echo} event
1562 This kind of event is generated when a mouse pointer moves onto a
1563 portion of buffer text which has a @code{help-echo} text property.
1564 The generated event has this form:
1567 (help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos})
1571 The precise meaning of the event parameters and the way these
1572 parameters are used to display the help-echo text are described in
1573 @ref{Text help-echo}.
1575 @cindex @code{usr1-signal} event
1576 @cindex @code{usr2-signal} event
1579 These events are generated when the Emacs process receives the signals
1580 @code{SIGUSR1} and @code{SIGUSR2}. They contain no additional data
1581 because signals do not carry additional information.
1584 If one of these events arrives in the middle of a key sequence---that
1585 is, after a prefix key---then Emacs reorders the events so that this
1586 event comes either before or after the multi-event key sequence, not
1589 @node Event Examples
1590 @subsection Event Examples
1592 If the user presses and releases the left mouse button over the same
1593 location, that generates a sequence of events like this:
1596 (down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
1597 (mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180))
1600 While holding the control key down, the user might hold down the
1601 second mouse button, and drag the mouse from one line to the next.
1602 That produces two events, as shown here:
1605 (C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
1606 (C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
1607 (#<window 18 on NEWS> 3510 (0 . 28) -729648))
1610 While holding down the meta and shift keys, the user might press the
1611 second mouse button on the window's mode line, and then drag the mouse
1612 into another window. That produces a pair of events like these:
1615 (M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
1616 (M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
1617 (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
1621 @node Classifying Events
1622 @subsection Classifying Events
1625 Every event has an @dfn{event type}, which classifies the event for
1626 key binding purposes. For a keyboard event, the event type equals the
1627 event value; thus, the event type for a character is the character, and
1628 the event type for a function key symbol is the symbol itself. For
1629 events that are lists, the event type is the symbol in the @sc{car} of
1630 the list. Thus, the event type is always a symbol or a character.
1632 Two events of the same type are equivalent where key bindings are
1633 concerned; thus, they always run the same command. That does not
1634 necessarily mean they do the same things, however, as some commands look
1635 at the whole event to decide what to do. For example, some commands use
1636 the location of a mouse event to decide where in the buffer to act.
1638 Sometimes broader classifications of events are useful. For example,
1639 you might want to ask whether an event involved the @key{META} key,
1640 regardless of which other key or mouse button was used.
1642 The functions @code{event-modifiers} and @code{event-basic-type} are
1643 provided to get such information conveniently.
1645 @defun event-modifiers event
1646 This function returns a list of the modifiers that @var{event} has. The
1647 modifiers are symbols; they include @code{shift}, @code{control},
1648 @code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition,
1649 the modifiers list of a mouse event symbol always contains one of
1650 @code{click}, @code{drag}, and @code{down}. For double or triple
1651 events, it also contains @code{double} or @code{triple}.
1653 The argument @var{event} may be an entire event object, or just an
1654 event type. If @var{event} is a symbol that has never been used in an
1655 event that has been read as input in the current Emacs session, then
1656 @code{event-modifiers} can return @code{nil}, even when @var{event}
1657 actually has modifiers.
1659 Here are some examples:
1662 (event-modifiers ?a)
1664 (event-modifiers ?A)
1666 (event-modifiers ?\C-a)
1668 (event-modifiers ?\C-%)
1670 (event-modifiers ?\C-\S-a)
1671 @result{} (control shift)
1672 (event-modifiers 'f5)
1674 (event-modifiers 's-f5)
1676 (event-modifiers 'M-S-f5)
1677 @result{} (meta shift)
1678 (event-modifiers 'mouse-1)
1680 (event-modifiers 'down-mouse-1)
1684 The modifiers list for a click event explicitly contains @code{click},
1685 but the event symbol name itself does not contain @samp{click}.
1688 @defun event-basic-type event
1689 This function returns the key or mouse button that @var{event}
1690 describes, with all modifiers removed. The @var{event} argument is as
1691 in @code{event-modifiers}. For example:
1694 (event-basic-type ?a)
1696 (event-basic-type ?A)
1698 (event-basic-type ?\C-a)
1700 (event-basic-type ?\C-\S-a)
1702 (event-basic-type 'f5)
1704 (event-basic-type 's-f5)
1706 (event-basic-type 'M-S-f5)
1708 (event-basic-type 'down-mouse-1)
1713 @defun mouse-movement-p object
1714 This function returns non-@code{nil} if @var{object} is a mouse movement
1718 @defun event-convert-list list
1719 This function converts a list of modifier names and a basic event type
1720 to an event type which specifies all of them. The basic event type
1721 must be the last element of the list. For example,
1724 (event-convert-list '(control ?a))
1726 (event-convert-list '(control meta ?a))
1727 @result{} -134217727
1728 (event-convert-list '(control super f1))
1733 @node Accessing Events
1734 @subsection Accessing Events
1735 @cindex mouse events, accessing the data
1736 @cindex accessing data of mouse events
1738 This section describes convenient functions for accessing the data in
1739 a mouse button or motion event.
1741 These two functions return the starting or ending position of a
1742 mouse-button event, as a list of this form:
1745 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
1746 @var{object} @var{text-pos} (@var{col} . @var{row})
1747 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
1750 @defun event-start event
1751 This returns the starting position of @var{event}.
1753 If @var{event} is a click or button-down event, this returns the
1754 location of the event. If @var{event} is a drag event, this returns the
1755 drag's starting position.
1758 @defun event-end event
1759 This returns the ending position of @var{event}.
1761 If @var{event} is a drag event, this returns the position where the user
1762 released the mouse button. If @var{event} is a click or button-down
1763 event, the value is actually the starting position, which is the only
1764 position such events have.
1767 @cindex mouse position list, accessing
1768 These functions take a position list as described above, and
1769 return various parts of it.
1771 @defun posn-window position
1772 Return the window that @var{position} is in.
1775 @defun posn-area position
1776 Return the window area recorded in @var{position}. It returns @code{nil}
1777 when the event occurred in the text area of the window; otherwise, it
1778 is a symbol identifying the area in which the event occurred.
1781 @defun posn-point position
1782 Return the buffer position in @var{position}. When the event occurred
1783 in the text area of the window, in a marginal area, or on a fringe,
1784 this is an integer specifying a buffer position. Otherwise, the value
1788 @defun posn-x-y position
1789 Return the pixel-based x and y coordinates in @var{position}, as a
1790 cons cell @code{(@var{x} . @var{y})}. These coordinates are relative
1791 to the window given by @code{posn-window}.
1793 This example shows how to convert these window-relative coordinates
1794 into frame-relative coordinates:
1797 (defun frame-relative-coordinates (position)
1798 "Return frame-relative coordinates from POSITION."
1799 (let* ((x-y (posn-x-y position))
1800 (window (posn-window position))
1801 (edges (window-inside-pixel-edges window)))
1802 (cons (+ (car x-y) (car edges))
1803 (+ (cdr x-y) (cadr edges)))))
1807 @defun posn-col-row position
1808 Return the row and column (in units of the frame's default character
1809 height and width) of @var{position}, as a cons cell @code{(@var{col} .
1810 @var{row})}. These are computed from the @var{x} and @var{y} values
1811 actually found in @var{position}.
1814 @defun posn-actual-col-row position
1815 Return the actual row and column in @var{position}, as a cons cell
1816 @code{(@var{col} . @var{row})}. The values are the actual row number
1817 in the window, and the actual character number in that row. It returns
1818 @code{nil} if @var{position} does not include actual positions values.
1819 You can use @code{posn-col-row} to get approximate values.
1822 @defun posn-string position
1823 Return the string object in @var{position}, either @code{nil}, or a
1824 cons cell @code{(@var{string} . @var{string-pos})}.
1827 @defun posn-image position
1828 Return the image object in @var{position}, either @code{nil}, or an
1829 image @code{(image ...)}.
1832 @defun posn-object position
1833 Return the image or string object in @var{position}, either
1834 @code{nil}, an image @code{(image ...)}, or a cons cell
1835 @code{(@var{string} . @var{string-pos})}.
1838 @defun posn-object-x-y position
1839 Return the pixel-based x and y coordinates relative to the upper left
1840 corner of the object in @var{position} as a cons cell @code{(@var{dx}
1841 . @var{dy})}. If the @var{position} is a buffer position, return the
1842 relative position in the character at that position.
1845 @defun posn-object-width-height position
1846 Return the pixel width and height of the object in @var{position} as a
1847 cons cell @code{(@var{width} . @var{height})}. If the @var{position}
1848 is a buffer position, return the size of the character at that position.
1851 @cindex mouse event, timestamp
1852 @cindex timestamp of a mouse event
1853 @defun posn-timestamp position
1854 Return the timestamp in @var{position}. This is the time at which the
1855 event occurred, in milliseconds.
1858 These functions compute a position list given particular buffer
1859 position or screen position. You can access the data in this position
1860 list with the functions described above.
1862 @defun posn-at-point &optional pos window
1863 This function returns a position list for position @var{pos} in
1864 @var{window}. @var{pos} defaults to point in @var{window};
1865 @var{window} defaults to the selected window.
1867 @code{posn-at-point} returns @code{nil} if @var{pos} is not visible in
1871 @defun posn-at-x-y x y &optional frame-or-window whole
1872 This function returns position information corresponding to pixel
1873 coordinates @var{x} and @var{y} in a specified frame or window,
1874 @var{frame-or-window}, which defaults to the selected window.
1875 The coordinates @var{x} and @var{y} are relative to the
1876 frame or window used.
1877 If @var{whole} is @code{nil}, the coordinates are relative
1878 to the window text area, otherwise they are relative to
1879 the entire window area including scroll bars, margins and fringes.
1882 These functions are useful for decoding scroll bar events.
1884 @defun scroll-bar-event-ratio event
1885 This function returns the fractional vertical position of a scroll bar
1886 event within the scroll bar. The value is a cons cell
1887 @code{(@var{portion} . @var{whole})} containing two integers whose ratio
1888 is the fractional position.
1891 @defun scroll-bar-scale ratio total
1892 This function multiplies (in effect) @var{ratio} by @var{total},
1893 rounding the result to an integer. The argument @var{ratio} is not a
1894 number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
1895 value returned by @code{scroll-bar-event-ratio}.
1897 This function is handy for scaling a position on a scroll bar into a
1898 buffer position. Here's how to do that:
1903 (posn-x-y (event-start event))
1904 (- (point-max) (point-min))))
1907 Recall that scroll bar events have two integers forming a ratio, in place
1908 of a pair of x and y coordinates.
1911 @node Strings of Events
1912 @subsection Putting Keyboard Events in Strings
1913 @cindex keyboard events in strings
1914 @cindex strings with keyboard events
1916 In most of the places where strings are used, we conceptualize the
1917 string as containing text characters---the same kind of characters found
1918 in buffers or files. Occasionally Lisp programs use strings that
1919 conceptually contain keyboard characters; for example, they may be key
1920 sequences or keyboard macro definitions. However, storing keyboard
1921 characters in a string is a complex matter, for reasons of historical
1922 compatibility, and it is not always possible.
1924 We recommend that new programs avoid dealing with these complexities
1925 by not storing keyboard events in strings. Here is how to do that:
1929 Use vectors instead of strings for key sequences, when you plan to use
1930 them for anything other than as arguments to @code{lookup-key} and
1931 @code{define-key}. For example, you can use
1932 @code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
1933 @code{this-command-keys-vector} instead of @code{this-command-keys}.
1936 Use vectors to write key sequence constants containing meta characters,
1937 even when passing them directly to @code{define-key}.
1940 When you have to look at the contents of a key sequence that might be a
1941 string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
1942 first, to convert it to a list.
1945 The complexities stem from the modifier bits that keyboard input
1946 characters can include. Aside from the Meta modifier, none of these
1947 modifier bits can be included in a string, and the Meta modifier is
1948 allowed only in special cases.
1950 The earliest GNU Emacs versions represented meta characters as codes
1951 in the range of 128 to 255. At that time, the basic character codes
1952 ranged from 0 to 127, so all keyboard character codes did fit in a
1953 string. Many Lisp programs used @samp{\M-} in string constants to stand
1954 for meta characters, especially in arguments to @code{define-key} and
1955 similar functions, and key sequences and sequences of events were always
1956 represented as strings.
1958 When we added support for larger basic character codes beyond 127, and
1959 additional modifier bits, we had to change the representation of meta
1960 characters. Now the flag that represents the Meta modifier in a
1968 and such numbers cannot be included in a string.
1970 To support programs with @samp{\M-} in string constants, there are
1971 special rules for including certain meta characters in a string.
1972 Here are the rules for interpreting a string as a sequence of input
1977 If the keyboard character value is in the range of 0 to 127, it can go
1978 in the string unchanged.
1981 The meta variants of those characters, with codes in the range of
1990 @math{2^{27} + 127},
1995 can also go in the string, but you must change their
1996 numeric values. You must set the
2010 bit, resulting in a value between 128 and 255. Only a unibyte string
2011 can include these codes.
2014 Non-@acronym{ASCII} characters above 256 can be included in a multibyte string.
2017 Other keyboard character events cannot fit in a string. This includes
2018 keyboard events in the range of 128 to 255.
2021 Functions such as @code{read-key-sequence} that construct strings of
2022 keyboard input characters follow these rules: they construct vectors
2023 instead of strings, when the events won't fit in a string.
2025 When you use the read syntax @samp{\M-} in a string, it produces a
2026 code in the range of 128 to 255---the same code that you get if you
2027 modify the corresponding keyboard event to put it in the string. Thus,
2028 meta events in strings work consistently regardless of how they get into
2031 However, most programs would do well to avoid these issues by
2032 following the recommendations at the beginning of this section.
2035 @section Reading Input
2037 The editor command loop reads key sequences using the function
2038 @code{read-key-sequence}, which uses @code{read-event}. These and other
2039 functions for event input are also available for use in Lisp programs.
2040 See also @code{momentary-string-display} in @ref{Temporary Displays},
2041 and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
2042 functions and variables for controlling terminal input modes and
2043 debugging terminal input. @xref{Translating Input}, for features you
2044 can use for translating or modifying input events while reading them.
2046 For higher-level input facilities, see @ref{Minibuffers}.
2049 * Key Sequence Input:: How to read one key sequence.
2050 * Reading One Event:: How to read just one event.
2051 * Invoking the Input Method:: How reading an event uses the input method.
2052 * Quoted Character Input:: Asking the user to specify a character.
2053 * Event Input Misc:: How to reread or throw away input events.
2056 @node Key Sequence Input
2057 @subsection Key Sequence Input
2058 @cindex key sequence input
2060 The command loop reads input a key sequence at a time, by calling
2061 @code{read-key-sequence}. Lisp programs can also call this function;
2062 for example, @code{describe-key} uses it to read the key to describe.
2064 @defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
2065 @cindex key sequence
2066 This function reads a key sequence and returns it as a string or
2067 vector. It keeps reading events until it has accumulated a complete key
2068 sequence; that is, enough to specify a non-prefix command using the
2069 currently active keymaps. (Remember that a key sequence that starts
2070 with a mouse event is read using the keymaps of the buffer in the
2071 window that the mouse was in, not the current buffer.)
2073 If the events are all characters and all can fit in a string, then
2074 @code{read-key-sequence} returns a string (@pxref{Strings of Events}).
2075 Otherwise, it returns a vector, since a vector can hold all kinds of
2076 events---characters, symbols, and lists. The elements of the string or
2077 vector are the events in the key sequence.
2079 Reading a key sequence includes translating the events in various
2080 ways. @xref{Translating Input}.
2082 The argument @var{prompt} is either a string to be displayed in the
2083 echo area as a prompt, or @code{nil}, meaning not to display a prompt.
2084 The argument @var{continue-echo}, if non-@code{nil}, means to echo
2085 this key as a continuation of the previous key.
2087 Normally any upper case event is converted to lower case if the
2088 original event is undefined and the lower case equivalent is defined.
2089 The argument @var{dont-downcase-last}, if non-@code{nil}, means do not
2090 convert the last event to lower case. This is appropriate for reading
2091 a key sequence to be defined.
2093 The argument @var{switch-frame-ok}, if non-@code{nil}, means that this
2094 function should process a @code{switch-frame} event if the user
2095 switches frames before typing anything. If the user switches frames
2096 in the middle of a key sequence, or at the start of the sequence but
2097 @var{switch-frame-ok} is @code{nil}, then the event will be put off
2098 until after the current key sequence.
2100 The argument @var{command-loop}, if non-@code{nil}, means that this
2101 key sequence is being read by something that will read commands one
2102 after another. It should be @code{nil} if the caller will read just
2105 In the following example, Emacs displays the prompt @samp{?} in the
2106 echo area, and then the user types @kbd{C-x C-f}.
2109 (read-key-sequence "?")
2112 ---------- Echo Area ----------
2114 ---------- Echo Area ----------
2120 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
2121 typed while reading with this function works like any other character,
2122 and does not set @code{quit-flag}. @xref{Quitting}.
2125 @defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
2126 This is like @code{read-key-sequence} except that it always
2127 returns the key sequence as a vector, never as a string.
2128 @xref{Strings of Events}.
2131 @cindex upper case key sequence
2132 @cindex downcasing in @code{lookup-key}
2133 If an input character is upper-case (or has the shift modifier) and
2134 has no key binding, but its lower-case equivalent has one, then
2135 @code{read-key-sequence} converts the character to lower case. Note
2136 that @code{lookup-key} does not perform case conversion in this way.
2138 The function @code{read-key-sequence} also transforms some mouse events.
2139 It converts unbound drag events into click events, and discards unbound
2140 button-down events entirely. It also reshuffles focus events and
2141 miscellaneous window events so that they never appear in a key sequence
2142 with any other events.
2144 @cindex @code{header-line} prefix key
2145 @cindex @code{mode-line} prefix key
2146 @cindex @code{vertical-line} prefix key
2147 @cindex @code{horizontal-scroll-bar} prefix key
2148 @cindex @code{vertical-scroll-bar} prefix key
2149 @cindex @code{menu-bar} prefix key
2150 @cindex mouse events, in special parts of frame
2151 When mouse events occur in special parts of a window, such as a mode
2152 line or a scroll bar, the event type shows nothing special---it is the
2153 same symbol that would normally represent that combination of mouse
2154 button and modifier keys. The information about the window part is kept
2155 elsewhere in the event---in the coordinates. But
2156 @code{read-key-sequence} translates this information into imaginary
2157 ``prefix keys'', all of which are symbols: @code{header-line},
2158 @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
2159 @code{vertical-line}, and @code{vertical-scroll-bar}. You can define
2160 meanings for mouse clicks in special window parts by defining key
2161 sequences using these imaginary prefix keys.
2163 For example, if you call @code{read-key-sequence} and then click the
2164 mouse on the window's mode line, you get two events, like this:
2167 (read-key-sequence "Click on the mode line: ")
2168 @result{} [mode-line
2170 (#<window 6 on NEWS> mode-line
2171 (40 . 63) 5959987))]
2174 @defvar num-input-keys
2176 This variable's value is the number of key sequences processed so far in
2177 this Emacs session. This includes key sequences read from the terminal
2178 and key sequences read from keyboard macros being executed.
2181 @node Reading One Event
2182 @subsection Reading One Event
2183 @cindex reading a single event
2184 @cindex event, reading only one
2186 The lowest level functions for command input are those that read a
2189 None of the three functions below suppresses quitting.
2191 @defun read-event &optional prompt inherit-input-method
2192 This function reads and returns the next event of command input, waiting
2193 if necessary until an event is available. Events can come directly from
2194 the user or from a keyboard macro.
2196 If the optional argument @var{prompt} is non-@code{nil}, it should be a
2197 string to display in the echo area as a prompt. Otherwise,
2198 @code{read-event} does not display any message to indicate it is waiting
2199 for input; instead, it prompts by echoing: it displays descriptions of
2200 the events that led to or were read by the current command. @xref{The
2203 If @var{inherit-input-method} is non-@code{nil}, then the current input
2204 method (if any) is employed to make it possible to enter a
2205 non-@acronym{ASCII} character. Otherwise, input method handling is disabled
2206 for reading this event.
2208 If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
2209 moves the cursor temporarily to the echo area, to the end of any message
2210 displayed there. Otherwise @code{read-event} does not move the cursor.
2212 If @code{read-event} gets an event that is defined as a help character,
2213 then in some cases @code{read-event} processes the event directly without
2214 returning. @xref{Help Functions}. Certain other events, called
2215 @dfn{special events}, are also processed directly within
2216 @code{read-event} (@pxref{Special Events}).
2218 Here is what happens if you call @code{read-event} and then press the
2219 right-arrow function key:
2229 @defun read-char &optional prompt inherit-input-method
2230 This function reads and returns a character of command input. If the
2231 user generates an event which is not a character (i.e. a mouse click or
2232 function key event), @code{read-char} signals an error. The arguments
2233 work as in @code{read-event}.
2235 In the first example, the user types the character @kbd{1} (@acronym{ASCII}
2236 code 49). The second example shows a keyboard macro definition that
2237 calls @code{read-char} from the minibuffer using @code{eval-expression}.
2238 @code{read-char} reads the keyboard macro's very next character, which
2239 is @kbd{1}. Then @code{eval-expression} displays its return value in
2249 ;; @r{We assume here you use @kbd{M-:} to evaluate this.}
2250 (symbol-function 'foo)
2251 @result{} "^[:(read-char)^M1"
2254 (execute-kbd-macro 'foo)
2261 @defun read-char-exclusive &optional prompt inherit-input-method
2262 This function reads and returns a character of command input. If the
2263 user generates an event which is not a character,
2264 @code{read-char-exclusive} ignores it and reads another event, until it
2265 gets a character. The arguments work as in @code{read-event}.
2268 @defvar num-nonmacro-input-events
2269 This variable holds the total number of input events received so far
2270 from the terminal---not counting those generated by keyboard macros.
2273 @node Invoking the Input Method
2274 @subsection Invoking the Input Method
2276 The event-reading functions invoke the current input method, if any
2277 (@pxref{Input Methods}). If the value of @code{input-method-function}
2278 is non-@code{nil}, it should be a function; when @code{read-event} reads
2279 a printing character (including @key{SPC}) with no modifier bits, it
2280 calls that function, passing the character as an argument.
2282 @defvar input-method-function
2283 If this is non-@code{nil}, its value specifies the current input method
2286 @strong{Warning:} don't bind this variable with @code{let}. It is often
2287 buffer-local, and if you bind it around reading input (which is exactly
2288 when you @emph{would} bind it), switching buffers asynchronously while
2289 Emacs is waiting will cause the value to be restored in the wrong
2293 The input method function should return a list of events which should
2294 be used as input. (If the list is @code{nil}, that means there is no
2295 input, so @code{read-event} waits for another event.) These events are
2296 processed before the events in @code{unread-command-events}
2297 (@pxref{Event Input Misc}). Events
2298 returned by the input method function are not passed to the input method
2299 function again, even if they are printing characters with no modifier
2302 If the input method function calls @code{read-event} or
2303 @code{read-key-sequence}, it should bind @code{input-method-function} to
2304 @code{nil} first, to prevent recursion.
2306 The input method function is not called when reading the second and
2307 subsequent events of a key sequence. Thus, these characters are not
2308 subject to input method processing. The input method function should
2309 test the values of @code{overriding-local-map} and
2310 @code{overriding-terminal-local-map}; if either of these variables is
2311 non-@code{nil}, the input method should put its argument into a list and
2312 return that list with no further processing.
2314 @node Quoted Character Input
2315 @subsection Quoted Character Input
2316 @cindex quoted character input
2318 You can use the function @code{read-quoted-char} to ask the user to
2319 specify a character, and allow the user to specify a control or meta
2320 character conveniently, either literally or as an octal character code.
2321 The command @code{quoted-insert} uses this function.
2323 @defun read-quoted-char &optional prompt
2324 @cindex octal character input
2325 @cindex control characters, reading
2326 @cindex nonprinting characters, reading
2327 This function is like @code{read-char}, except that if the first
2328 character read is an octal digit (0-7), it reads any number of octal
2329 digits (but stopping if a non-octal digit is found), and returns the
2330 character represented by that numeric character code. If the
2331 character that terminates the sequence of octal digits is @key{RET},
2332 it is discarded. Any other terminating character is used as input
2333 after this function returns.
2335 Quitting is suppressed when the first character is read, so that the
2336 user can enter a @kbd{C-g}. @xref{Quitting}.
2338 If @var{prompt} is supplied, it specifies a string for prompting the
2339 user. The prompt string is always displayed in the echo area, followed
2340 by a single @samp{-}.
2342 In the following example, the user types in the octal number 177 (which
2346 (read-quoted-char "What character")
2349 ---------- Echo Area ----------
2350 What character @kbd{1 7 7}-
2351 ---------- Echo Area ----------
2359 @node Event Input Misc
2360 @subsection Miscellaneous Event Input Features
2362 This section describes how to ``peek ahead'' at events without using
2363 them up, how to check for pending input, and how to discard pending
2364 input. See also the function @code{read-passwd} (@pxref{Reading a
2367 @defvar unread-command-events
2369 @cindex peeking at input
2370 This variable holds a list of events waiting to be read as command
2371 input. The events are used in the order they appear in the list, and
2372 removed one by one as they are used.
2374 The variable is needed because in some cases a function reads an event
2375 and then decides not to use it. Storing the event in this variable
2376 causes it to be processed normally, by the command loop or by the
2377 functions to read command input.
2379 @cindex prefix argument unreading
2380 For example, the function that implements numeric prefix arguments reads
2381 any number of digits. When it finds a non-digit event, it must unread
2382 the event so that it can be read normally by the command loop.
2383 Likewise, incremental search uses this feature to unread events with no
2384 special meaning in a search, because these events should exit the search
2385 and then execute normally.
2387 The reliable and easy way to extract events from a key sequence so as to
2388 put them in @code{unread-command-events} is to use
2389 @code{listify-key-sequence} (@pxref{Strings of Events}).
2391 Normally you add events to the front of this list, so that the events
2392 most recently unread will be reread first.
2395 @defun listify-key-sequence key
2396 This function converts the string or vector @var{key} to a list of
2397 individual events, which you can put in @code{unread-command-events}.
2400 @defvar unread-command-char
2401 This variable holds a character to be read as command input.
2402 A value of -1 means ``empty''.
2404 This variable is mostly obsolete now that you can use
2405 @code{unread-command-events} instead; it exists only to support programs
2406 written for Emacs versions 18 and earlier.
2409 @defun input-pending-p
2410 @cindex waiting for command key input
2411 This function determines whether any command input is currently
2412 available to be read. It returns immediately, with value @code{t} if
2413 there is available input, @code{nil} otherwise. On rare occasions it
2414 may return @code{t} when no input is available.
2417 @defvar last-input-event
2418 @defvarx last-input-char
2419 This variable records the last terminal input event read, whether
2420 as part of a command or explicitly by a Lisp program.
2422 In the example below, the Lisp program reads the character @kbd{1},
2423 @acronym{ASCII} code 49. It becomes the value of @code{last-input-event},
2424 while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
2425 this expression) remains the value of @code{last-command-event}.
2429 (progn (print (read-char))
2430 (print last-command-event)
2438 The alias @code{last-input-char} exists for compatibility with
2442 @defmac while-no-input body@dots{}
2443 This construct runs the @var{body} forms and returns the value of the
2444 last one---but only if no input arrives. If any input arrives during
2445 the execution of the @var{body} forms, it aborts them (working much
2446 like a quit). The @code{while-no-input} form returns @code{nil} if
2447 aborted by a real quit, and returns @code{t} if aborted by arrival of
2450 If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil},
2451 arrival of input during those parts won't cause an abort until
2452 the end of that part.
2454 If you want to be able to distingish all possible values computed
2455 by @var{body} from both kinds of abort conditions, write the code
2461 (progn . @var{body})))
2465 @defun discard-input
2467 @cindex discard input
2468 @cindex terminate keyboard macro
2469 This function discards the contents of the terminal input buffer and
2470 cancels any keyboard macro that might be in the process of definition.
2471 It returns @code{nil}.
2473 In the following example, the user may type a number of characters right
2474 after starting the evaluation of the form. After the @code{sleep-for}
2475 finishes sleeping, @code{discard-input} discards any characters typed
2479 (progn (sleep-for 2)
2485 @node Special Events
2486 @section Special Events
2488 @cindex special events
2489 Special events are handled at a very low level---as soon as they are
2490 read. The @code{read-event} function processes these events itself, and
2491 never returns them. Instead, it keeps waiting for the first event
2492 that is not special and returns that one.
2494 Events that are handled in this way do not echo, they are never grouped
2495 into key sequences, and they never appear in the value of
2496 @code{last-command-event} or @code{(this-command-keys)}. They do not
2497 discard a numeric argument, they cannot be unread with
2498 @code{unread-command-events}, they may not appear in a keyboard macro,
2499 and they are not recorded in a keyboard macro while you are defining
2502 These events do, however, appear in @code{last-input-event} immediately
2503 after they are read, and this is the way for the event's definition to
2504 find the actual event.
2506 The events types @code{iconify-frame}, @code{make-frame-visible} and
2507 @code{delete-frame} are normally handled in this way. The keymap which
2508 defines how to handle special events---and which events are special---is
2509 in the variable @code{special-event-map} (@pxref{Active Keymaps}).
2512 @section Waiting for Elapsed Time or Input
2516 The wait functions are designed to wait for a certain amount of time
2517 to pass or until there is input. For example, you may wish to pause in
2518 the middle of a computation to allow the user time to view the display.
2519 @code{sit-for} pauses and updates the screen, and returns immediately if
2520 input comes in, while @code{sleep-for} pauses without updating the
2523 @defun sit-for seconds &optional nodisp
2524 This function performs redisplay (provided there is no pending input
2525 from the user), then waits @var{seconds} seconds, or until input is
2526 available. The value is @code{t} if @code{sit-for} waited the full
2527 time with no input arriving (see @code{input-pending-p} in @ref{Event
2528 Input Misc}). Otherwise, the value is @code{nil}.
2530 The argument @var{seconds} need not be an integer. If it is a floating
2531 point number, @code{sit-for} waits for a fractional number of seconds.
2532 Some systems support only a whole number of seconds; on these systems,
2533 @var{seconds} is rounded down.
2535 The expression @code{(sit-for 0)} is a convenient way to request a
2536 redisplay, without any delay. @xref{Forcing Redisplay}.
2538 If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
2539 redisplay, but it still returns as soon as input is available (or when
2540 the timeout elapses).
2542 Iconifying or deiconifying a frame makes @code{sit-for} return, because
2543 that generates an event. @xref{Misc Events}.
2545 The usual purpose of @code{sit-for} is to give the user time to read
2546 text that you display.
2548 It is also possible to call @code{sit-for} with three arguments,
2549 as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})},
2550 but that is considered obsolete.
2553 @defun sleep-for seconds &optional millisec
2554 This function simply pauses for @var{seconds} seconds without updating
2555 the display. It pays no attention to available input. It returns
2558 The argument @var{seconds} need not be an integer. If it is a floating
2559 point number, @code{sleep-for} waits for a fractional number of seconds.
2560 Some systems support only a whole number of seconds; on these systems,
2561 @var{seconds} is rounded down.
2563 The optional argument @var{millisec} specifies an additional waiting
2564 period measured in milliseconds. This adds to the period specified by
2565 @var{seconds}. If the system doesn't support waiting fractions of a
2566 second, you get an error if you specify nonzero @var{millisec}.
2568 Use @code{sleep-for} when you wish to guarantee a delay.
2571 @xref{Time of Day}, for functions to get the current time.
2577 @cindex interrupt Lisp functions
2579 Typing @kbd{C-g} while a Lisp function is running causes Emacs to
2580 @dfn{quit} whatever it is doing. This means that control returns to the
2581 innermost active command loop.
2583 Typing @kbd{C-g} while the command loop is waiting for keyboard input
2584 does not cause a quit; it acts as an ordinary input character. In the
2585 simplest case, you cannot tell the difference, because @kbd{C-g}
2586 normally runs the command @code{keyboard-quit}, whose effect is to quit.
2587 However, when @kbd{C-g} follows a prefix key, they combine to form an
2588 undefined key. The effect is to cancel the prefix key as well as any
2591 In the minibuffer, @kbd{C-g} has a different definition: it aborts out
2592 of the minibuffer. This means, in effect, that it exits the minibuffer
2593 and then quits. (Simply quitting would return to the command loop
2594 @emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit
2595 directly when the command reader is reading input is so that its meaning
2596 can be redefined in the minibuffer in this way. @kbd{C-g} following a
2597 prefix key is not redefined in the minibuffer, and it has its normal
2598 effect of canceling the prefix key and prefix argument. This too
2599 would not be possible if @kbd{C-g} always quit directly.
2601 When @kbd{C-g} does directly quit, it does so by setting the variable
2602 @code{quit-flag} to @code{t}. Emacs checks this variable at appropriate
2603 times and quits if it is not @code{nil}. Setting @code{quit-flag}
2604 non-@code{nil} in any way thus causes a quit.
2606 At the level of C code, quitting cannot happen just anywhere; only at the
2607 special places that check @code{quit-flag}. The reason for this is
2608 that quitting at other places might leave an inconsistency in Emacs's
2609 internal state. Because quitting is delayed until a safe place, quitting
2610 cannot make Emacs crash.
2612 Certain functions such as @code{read-key-sequence} or
2613 @code{read-quoted-char} prevent quitting entirely even though they wait
2614 for input. Instead of quitting, @kbd{C-g} serves as the requested
2615 input. In the case of @code{read-key-sequence}, this serves to bring
2616 about the special behavior of @kbd{C-g} in the command loop. In the
2617 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
2618 to quote a @kbd{C-g}.
2620 @cindex prevent quitting
2621 You can prevent quitting for a portion of a Lisp function by binding
2622 the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
2623 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
2624 usual result of this---a quit---is prevented. Eventually,
2625 @code{inhibit-quit} will become @code{nil} again, such as when its
2626 binding is unwound at the end of a @code{let} form. At that time, if
2627 @code{quit-flag} is still non-@code{nil}, the requested quit happens
2628 immediately. This behavior is ideal when you wish to make sure that
2629 quitting does not happen within a ``critical section'' of the program.
2631 @cindex @code{read-quoted-char} quitting
2632 In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
2633 handled in a special way that does not involve quitting. This is done
2634 by reading the input with @code{inhibit-quit} bound to @code{t}, and
2635 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
2636 becomes @code{nil} again. This excerpt from the definition of
2637 @code{read-quoted-char} shows how this is done; it also shows that
2638 normal quitting is permitted after the first character of input.
2641 (defun read-quoted-char (&optional prompt)
2642 "@dots{}@var{documentation}@dots{}"
2643 (let ((message-log-max nil) done (first t) (code 0) char)
2645 (let ((inhibit-quit first)
2647 (and prompt (message "%s-" prompt))
2648 (setq char (read-event))
2649 (if inhibit-quit (setq quit-flag nil)))
2650 @r{@dots{}set the variable @code{code}@dots{}})
2655 If this variable is non-@code{nil}, then Emacs quits immediately, unless
2656 @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
2657 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
2660 @defvar inhibit-quit
2661 This variable determines whether Emacs should quit when @code{quit-flag}
2662 is set to a value other than @code{nil}. If @code{inhibit-quit} is
2663 non-@code{nil}, then @code{quit-flag} has no special effect.
2666 @defmac with-local-quit body@dots{}
2667 This macro executes @var{body} forms in sequence, but allows quitting, at
2668 least locally, within @var{body} even if @code{inhibit-quit} was
2669 non-@code{nil} outside this construct. It returns the value of the
2670 last form in @var{body}, unless exited by quitting, in which case
2671 it returns @code{nil}.
2673 If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit},
2674 it only executes the @var{body}, and setting @code{quit-flag} causes
2675 a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so
2676 that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag}
2677 triggers a special kind of local quit. This ends the execution of
2678 @var{body} and exits the @code{with-local-quit} body with
2679 @code{quit-flag} still non-@code{nil}, so that another (ordinary) quit
2680 will happen as soon as that is allowed. If @code{quit-flag} is
2681 already non-@code{nil} at the beginning of @var{body}, the local quit
2682 happens immediately and the body doesn't execute at all.
2684 This macro is mainly useful in functions that can be called from
2685 timers, process filters, process sentinels, @code{pre-command-hook},
2686 @code{post-command-hook}, and other places where @code{inhibit-quit} is
2687 normally bound to @code{t}.
2690 @deffn Command keyboard-quit
2691 This function signals the @code{quit} condition with @code{(signal 'quit
2692 nil)}. This is the same thing that quitting does. (See @code{signal}
2696 You can specify a character other than @kbd{C-g} to use for quitting.
2697 See the function @code{set-input-mode} in @ref{Terminal Input}.
2699 @node Prefix Command Arguments
2700 @section Prefix Command Arguments
2701 @cindex prefix argument
2702 @cindex raw prefix argument
2703 @cindex numeric prefix argument
2705 Most Emacs commands can use a @dfn{prefix argument}, a number
2706 specified before the command itself. (Don't confuse prefix arguments
2707 with prefix keys.) The prefix argument is at all times represented by a
2708 value, which may be @code{nil}, meaning there is currently no prefix
2709 argument. Each command may use the prefix argument or ignore it.
2711 There are two representations of the prefix argument: @dfn{raw} and
2712 @dfn{numeric}. The editor command loop uses the raw representation
2713 internally, and so do the Lisp variables that store the information, but
2714 commands can request either representation.
2716 Here are the possible values of a raw prefix argument:
2720 @code{nil}, meaning there is no prefix argument. Its numeric value is
2721 1, but numerous commands make a distinction between @code{nil} and the
2725 An integer, which stands for itself.
2728 A list of one element, which is an integer. This form of prefix
2729 argument results from one or a succession of @kbd{C-u}'s with no
2730 digits. The numeric value is the integer in the list, but some
2731 commands make a distinction between such a list and an integer alone.
2734 The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was
2735 typed, without following digits. The equivalent numeric value is
2736 @minus{}1, but some commands make a distinction between the integer
2737 @minus{}1 and the symbol @code{-}.
2740 We illustrate these possibilities by calling the following function with
2745 (defun display-prefix (arg)
2746 "Display the value of the raw prefix arg."
2753 Here are the results of calling @code{display-prefix} with various
2754 raw prefix arguments:
2757 M-x display-prefix @print{} nil
2759 C-u M-x display-prefix @print{} (4)
2761 C-u C-u M-x display-prefix @print{} (16)
2763 C-u 3 M-x display-prefix @print{} 3
2765 M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
2767 C-u - M-x display-prefix @print{} -
2769 M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
2771 C-u - 7 M-x display-prefix @print{} -7
2773 M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
2776 Emacs uses two variables to store the prefix argument:
2777 @code{prefix-arg} and @code{current-prefix-arg}. Commands such as
2778 @code{universal-argument} that set up prefix arguments for other
2779 commands store them in @code{prefix-arg}. In contrast,
2780 @code{current-prefix-arg} conveys the prefix argument to the current
2781 command, so setting it has no effect on the prefix arguments for future
2784 Normally, commands specify which representation to use for the prefix
2785 argument, either numeric or raw, in the @code{interactive} specification.
2786 (@xref{Using Interactive}.) Alternatively, functions may look at the
2787 value of the prefix argument directly in the variable
2788 @code{current-prefix-arg}, but this is less clean.
2790 @defun prefix-numeric-value arg
2791 This function returns the numeric meaning of a valid raw prefix argument
2792 value, @var{arg}. The argument may be a symbol, a number, or a list.
2793 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
2794 value @minus{}1 is returned; if it is a number, that number is returned;
2795 if it is a list, the @sc{car} of that list (which should be a number) is
2799 @defvar current-prefix-arg
2800 This variable holds the raw prefix argument for the @emph{current}
2801 command. Commands may examine it directly, but the usual method for
2802 accessing it is with @code{(interactive "P")}.
2806 The value of this variable is the raw prefix argument for the
2807 @emph{next} editing command. Commands such as @code{universal-argument}
2808 that specify prefix arguments for the following command work by setting
2812 @defvar last-prefix-arg
2813 The raw prefix argument value used by the previous command.
2816 The following commands exist to set up prefix arguments for the
2817 following command. Do not call them for any other reason.
2819 @deffn Command universal-argument
2820 This command reads input and specifies a prefix argument for the
2821 following command. Don't call this command yourself unless you know
2825 @deffn Command digit-argument arg
2826 This command adds to the prefix argument for the following command. The
2827 argument @var{arg} is the raw prefix argument as it was before this
2828 command; it is used to compute the updated prefix argument. Don't call
2829 this command yourself unless you know what you are doing.
2832 @deffn Command negative-argument arg
2833 This command adds to the numeric argument for the next command. The
2834 argument @var{arg} is the raw prefix argument as it was before this
2835 command; its value is negated to form the new prefix argument. Don't
2836 call this command yourself unless you know what you are doing.
2839 @node Recursive Editing
2840 @section Recursive Editing
2841 @cindex recursive command loop
2842 @cindex recursive editing level
2843 @cindex command loop, recursive
2845 The Emacs command loop is entered automatically when Emacs starts up.
2846 This top-level invocation of the command loop never exits; it keeps
2847 running as long as Emacs does. Lisp programs can also invoke the
2848 command loop. Since this makes more than one activation of the command
2849 loop, we call it @dfn{recursive editing}. A recursive editing level has
2850 the effect of suspending whatever command invoked it and permitting the
2851 user to do arbitrary editing before resuming that command.
2853 The commands available during recursive editing are the same ones
2854 available in the top-level editing loop and defined in the keymaps.
2855 Only a few special commands exit the recursive editing level; the others
2856 return to the recursive editing level when they finish. (The special
2857 commands for exiting are always available, but they do nothing when
2858 recursive editing is not in progress.)
2860 All command loops, including recursive ones, set up all-purpose error
2861 handlers so that an error in a command run from the command loop will
2864 @cindex minibuffer input
2865 Minibuffer input is a special kind of recursive editing. It has a few
2866 special wrinkles, such as enabling display of the minibuffer and the
2867 minibuffer window, but fewer than you might suppose. Certain keys
2868 behave differently in the minibuffer, but that is only because of the
2869 minibuffer's local map; if you switch windows, you get the usual Emacs
2872 @cindex @code{throw} example
2874 @cindex exit recursive editing
2876 To invoke a recursive editing level, call the function
2877 @code{recursive-edit}. This function contains the command loop; it also
2878 contains a call to @code{catch} with tag @code{exit}, which makes it
2879 possible to exit the recursive editing level by throwing to @code{exit}
2880 (@pxref{Catch and Throw}). If you throw a value other than @code{t},
2881 then @code{recursive-edit} returns normally to the function that called
2882 it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
2883 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
2884 control returns to the command loop one level up. This is called
2885 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
2887 Most applications should not use recursive editing, except as part of
2888 using the minibuffer. Usually it is more convenient for the user if you
2889 change the major mode of the current buffer temporarily to a special
2890 major mode, which should have a command to go back to the previous mode.
2891 (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
2892 give the user different text to edit ``recursively'', create and select
2893 a new buffer in a special mode. In this mode, define a command to
2894 complete the processing and go back to the previous buffer. (The
2895 @kbd{m} command in Rmail does this.)
2897 Recursive edits are useful in debugging. You can insert a call to
2898 @code{debug} into a function definition as a sort of breakpoint, so that
2899 you can look around when the function gets there. @code{debug} invokes
2900 a recursive edit but also provides the other features of the debugger.
2902 Recursive editing levels are also used when you type @kbd{C-r} in
2903 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
2905 @defun recursive-edit
2906 @cindex suspend evaluation
2907 This function invokes the editor command loop. It is called
2908 automatically by the initialization of Emacs, to let the user begin
2909 editing. When called from a Lisp program, it enters a recursive editing
2912 In the following example, the function @code{simple-rec} first
2913 advances point one word, then enters a recursive edit, printing out a
2914 message in the echo area. The user can then do any editing desired, and
2915 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
2918 (defun simple-rec ()
2920 (message "Recursive edit in progress")
2923 @result{} simple-rec
2929 @deffn Command exit-recursive-edit
2930 This function exits from the innermost recursive edit (including
2931 minibuffer input). Its definition is effectively @code{(throw 'exit
2935 @deffn Command abort-recursive-edit
2936 This function aborts the command that requested the innermost recursive
2937 edit (including minibuffer input), by signaling @code{quit}
2938 after exiting the recursive edit. Its definition is effectively
2939 @code{(throw 'exit t)}. @xref{Quitting}.
2942 @deffn Command top-level
2943 This function exits all recursive editing levels; it does not return a
2944 value, as it jumps completely out of any computation directly back to
2945 the main command loop.
2948 @defun recursion-depth
2949 This function returns the current depth of recursive edits. When no
2950 recursive edit is active, it returns 0.
2953 @node Disabling Commands
2954 @section Disabling Commands
2955 @cindex disabled command
2957 @dfn{Disabling a command} marks the command as requiring user
2958 confirmation before it can be executed. Disabling is used for commands
2959 which might be confusing to beginning users, to prevent them from using
2960 the commands by accident.
2963 The low-level mechanism for disabling a command is to put a
2964 non-@code{nil} @code{disabled} property on the Lisp symbol for the
2965 command. These properties are normally set up by the user's
2966 init file (@pxref{Init File}) with Lisp expressions such as this:
2969 (put 'upcase-region 'disabled t)
2973 For a few commands, these properties are present by default (you can
2974 remove them in your init file if you wish).
2976 If the value of the @code{disabled} property is a string, the message
2977 saying the command is disabled includes that string. For example:
2980 (put 'delete-region 'disabled
2981 "Text deleted this way cannot be yanked back!\n")
2984 @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on
2985 what happens when a disabled command is invoked interactively.
2986 Disabling a command has no effect on calling it as a function from Lisp
2989 @deffn Command enable-command command
2990 Allow @var{command} (a symbol) to be executed without special
2991 confirmation from now on, and alter the user's init file (@pxref{Init
2992 File}) so that this will apply to future sessions.
2995 @deffn Command disable-command command
2996 Require special confirmation to execute @var{command} from now on, and
2997 alter the user's init file so that this will apply to future sessions.
3000 @defvar disabled-command-function
3001 The value of this variable should be a function. When the user
3002 invokes a disabled command interactively, this function is called
3003 instead of the disabled command. It can use @code{this-command-keys}
3004 to determine what the user typed to run the command, and thus find the
3007 The value may also be @code{nil}. Then all commands work normally,
3010 By default, the value is a function that asks the user whether to
3014 @node Command History
3015 @section Command History
3016 @cindex command history
3017 @cindex complex command
3018 @cindex history of commands
3020 The command loop keeps a history of the complex commands that have
3021 been executed, to make it convenient to repeat these commands. A
3022 @dfn{complex command} is one for which the interactive argument reading
3023 uses the minibuffer. This includes any @kbd{M-x} command, any
3024 @kbd{M-:} command, and any command whose @code{interactive}
3025 specification reads an argument from the minibuffer. Explicit use of
3026 the minibuffer during the execution of the command itself does not cause
3027 the command to be considered complex.
3029 @defvar command-history
3030 This variable's value is a list of recent complex commands, each
3031 represented as a form to evaluate. It continues to accumulate all
3032 complex commands for the duration of the editing session, but when it
3033 reaches the maximum size (@pxref{Minibuffer History}), the oldest
3034 elements are deleted as new ones are added.
3039 @result{} ((switch-to-buffer "chistory.texi")
3040 (describe-key "^X^[")
3041 (visit-tags-table "~/emacs/src/")
3042 (find-tag "repeat-complex-command"))
3047 This history list is actually a special case of minibuffer history
3048 (@pxref{Minibuffer History}), with one special twist: the elements are
3049 expressions rather than strings.
3051 There are a number of commands devoted to the editing and recall of
3052 previous commands. The commands @code{repeat-complex-command}, and
3053 @code{list-command-history} are described in the user manual
3054 (@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the
3055 minibuffer, the usual minibuffer history commands are available.
3057 @node Keyboard Macros
3058 @section Keyboard Macros
3059 @cindex keyboard macros
3061 A @dfn{keyboard macro} is a canned sequence of input events that can
3062 be considered a command and made the definition of a key. The Lisp
3063 representation of a keyboard macro is a string or vector containing the
3064 events. Don't confuse keyboard macros with Lisp macros
3067 @defun execute-kbd-macro kbdmacro &optional count loopfunc
3068 This function executes @var{kbdmacro} as a sequence of events. If
3069 @var{kbdmacro} is a string or vector, then the events in it are executed
3070 exactly as if they had been input by the user. The sequence is
3071 @emph{not} expected to be a single key sequence; normally a keyboard
3072 macro definition consists of several key sequences concatenated.
3074 If @var{kbdmacro} is a symbol, then its function definition is used in
3075 place of @var{kbdmacro}. If that is another symbol, this process repeats.
3076 Eventually the result should be a string or vector. If the result is
3077 not a symbol, string, or vector, an error is signaled.
3079 The argument @var{count} is a repeat count; @var{kbdmacro} is executed that
3080 many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is
3081 executed once. If it is 0, @var{kbdmacro} is executed over and over until it
3082 encounters an error or a failing search.
3084 If @var{loopfunc} is non-@code{nil}, it is a function that is called,
3085 without arguments, prior to each iteration of the macro. If
3086 @var{loopfunc} returns @code{nil}, then this stops execution of the macro.
3088 @xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
3091 @defvar executing-kbd-macro
3092 This variable contains the string or vector that defines the keyboard
3093 macro that is currently executing. It is @code{nil} if no macro is
3094 currently executing. A command can test this variable so as to behave
3095 differently when run from an executing macro. Do not set this variable
3099 @defvar defining-kbd-macro
3100 This variable is non-@code{nil} if and only if a keyboard macro is
3101 being defined. A command can test this variable so as to behave
3102 differently while a macro is being defined. The value is
3103 @code{append} while appending to the definition of an existing macro.
3104 The commands @code{start-kbd-macro}, @code{kmacro-start-macro} and
3105 @code{end-kbd-macro} set this variable---do not set it yourself.
3107 The variable is always local to the current terminal and cannot be
3108 buffer-local. @xref{Multiple Displays}.
3111 @defvar last-kbd-macro
3112 This variable is the definition of the most recently defined keyboard
3113 macro. Its value is a string or vector, or @code{nil}.
3115 The variable is always local to the current terminal and cannot be
3116 buffer-local. @xref{Multiple Displays}.
3119 @defvar kbd-macro-termination-hook
3120 This normal hook (@pxref{Standard Hooks}) is run when a keyboard
3121 macro terminates, regardless of what caused it to terminate (reaching
3122 the macro end or an error which ended the macro prematurely).
3126 arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1