2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/commands
6 @node Command Loop, Keymaps, Minibuffers, Top
8 @cindex editor command loop
11 When you run Emacs, it enters the @dfn{editor command loop} almost
12 immediately. This loop reads key sequences, executes their definitions,
13 and displays the results. In this chapter, we describe how these things
14 are done, and the subroutines that allow Lisp programs to do them.
17 * Command Overview:: How the command loop reads commands.
18 * Defining Commands:: Specifying how a function should read arguments.
19 * Interactive Call:: Calling a command, so that it will read arguments.
20 * Command Loop Info:: Variables set by the command loop for you to examine.
21 * Input Events:: What input looks like when you read it.
22 * Reading Input:: How to read input events from the keyboard or mouse.
23 * Waiting:: Waiting for user input or elapsed time.
24 * Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
25 * Prefix Command Arguments:: How the commands to set prefix args work.
26 * Recursive Editing:: Entering a recursive edit,
27 and why you usually shouldn't.
28 * Disabling Commands:: How the command loop handles disabled commands.
29 * Command History:: How the command history is set up, and how accessed.
30 * Keyboard Macros:: How keyboard macros are implemented.
33 @node Command Overview
34 @section Command Loop Overview
36 The first thing the command loop must do is read a key sequence, which
37 is a sequence of events that translates into a command. It does this by
38 calling the function @code{read-key-sequence}. Your Lisp code can also
39 call this function (@pxref{Key Sequence Input}). Lisp programs can also
40 do input at a lower level with @code{read-event} (@pxref{Reading One
41 Event}) or discard pending input with @code{discard-input}
42 (@pxref{Event Input Misc}).
44 The key sequence is translated into a command through the currently
45 active keymaps. @xref{Key Lookup}, for information on how this is done.
46 The result should be a keyboard macro or an interactively callable
47 function. If the key is @kbd{M-x}, then it reads the name of another
48 command, which it then calls. This is done by the command
49 @code{execute-extended-command} (@pxref{Interactive Call}).
51 To execute a command requires first reading the arguments for it.
52 This is done by calling @code{command-execute} (@pxref{Interactive
53 Call}). For commands written in Lisp, the @code{interactive}
54 specification says how to read the arguments. This may use the prefix
55 argument (@pxref{Prefix Command Arguments}) or may read with prompting
56 in the minibuffer (@pxref{Minibuffers}). For example, the command
57 @code{find-file} has an @code{interactive} specification which says to
58 read a file name using the minibuffer. The command's function body does
59 not use the minibuffer; if you call this command from Lisp code as a
60 function, you must supply the file name string as an ordinary Lisp
63 If the command is a string or vector (i.e., a keyboard macro) then
64 @code{execute-kbd-macro} is used to execute it. You can call this
65 function yourself (@pxref{Keyboard Macros}).
67 To terminate the execution of a running command, type @kbd{C-g}. This
68 character causes @dfn{quitting} (@pxref{Quitting}).
70 @defvar pre-command-hook
71 The editor command loop runs this normal hook before each command. At
72 that time, @code{this-command} contains the command that is about to
73 run, and @code{last-command} describes the previous command.
77 @defvar post-command-hook
78 The editor command loop runs this normal hook after each command
79 (including commands terminated prematurely by quitting or by errors),
80 and also when the command loop is first entered. At that time,
81 @code{this-command} describes the command that just ran, and
82 @code{last-command} describes the command before that. @xref{Hooks}.
85 An erroneous function in the @code{pre-command-hook} list could easily
86 make Emacs go into an infinite loop of errors. To protect you from this
87 sort of painful problem, Emacs sets the hook variable to @code{nil}
88 temporarily while running the functions in the hook. Thus, if a hook
89 function gets an error, the hook variable is left as @code{nil}. Emacs
90 does the same thing for @code{post-command-hook}.
92 Quitting is suppressed while running @code{pre-command-hook} and
93 @code{post-command-hook}; this is because otherwise a quit, happening by
94 chance within one of these hooks, would turn off the hook.
96 One inconvenient result of these protective features is that you
97 cannot have a function in @code{post-command-hook} or
98 @code{pre-command-hook} which changes the value of that variable. But
99 that's not a real limitation. If you want hook functions to change the
100 hook, simply add one fixed function to the hook, and code that function
101 to look in another hook variable for other functions to call. Here is
105 ;; @r{Set up the mechanism.}
106 (defvar current-post-command-function nil)
107 (defun run-current-post-command-function ()
108 (if current-post-command-function
109 (funcall current-post-command-function)))
110 (add-hooks 'post-command-hook
111 'run-current-post-command-function)
113 ;; @r{Here's a hook function which replaces itself}
114 ;; @r{with a different hook function to run next time.}
115 (defun first-post-command-function ()
116 (setq current-post-command-function
117 'second-post-command-function))
120 @node Defining Commands
121 @section Defining Commands
122 @cindex defining commands
123 @cindex commands, defining
124 @cindex functions, making them interactive
125 @cindex interactive function
127 A Lisp function becomes a command when its body contains, at top
128 level, a form that calls the special form @code{interactive}. This
129 form does nothing when actually executed, but its presence serves as a
130 flag to indicate that interactive calling is permitted. Its argument
131 controls the reading of arguments for an interactive call.
134 * Using Interactive:: General rules for @code{interactive}.
135 * Interactive Codes:: The standard letter-codes for reading arguments
137 * Interactive Examples:: Examples of how to read interactive arguments.
140 @node Using Interactive
141 @subsection Using @code{interactive}
143 This section describes how to write the @code{interactive} form that
144 makes a Lisp function an interactively-callable command.
146 @defspec interactive arg-descriptor
147 @cindex argument descriptors
148 This special form declares that the function in which it appears is a
149 command, and that it may therefore be called interactively (via
150 @kbd{M-x} or by entering a key sequence bound to it). The argument
151 @var{arg-descriptor} declares how to compute the arguments to the
152 command when the command is called interactively.
154 A command may be called from Lisp programs like any other function, but
155 then the caller supplies the arguments and @var{arg-descriptor} has no
158 The @code{interactive} form has its effect because the command loop
159 (actually, its subroutine @code{call-interactively}) scans through the
160 function definition looking for it, before calling the function. Once
161 the function is called, all its body forms including the
162 @code{interactive} form are executed, but at this time
163 @code{interactive} simply returns @code{nil} without even evaluating its
167 There are three possibilities for the argument @var{arg-descriptor}:
171 It may be omitted or @code{nil}; then the command is called with no
172 arguments. This leads quickly to an error if the command requires one
176 It may be a Lisp expression that is not a string; then it should be a
177 form that is evaluated to get a list of arguments to pass to the
179 @cindex argument evaluation form
181 If this expression reads keyboard input (this includes using the
182 minibuffer), keep in mind that the integer value of point or the mark
183 before reading input may be incorrect after reading input. This is
184 because the current buffer may be receiving subprocess output;
185 if subprocess output arrives while the command is waiting for input,
186 it could relocate point and the mark.
188 Here's an example of what @emph{not} to do:
192 (list (region-beginning) (region-end)
193 (read-string "Foo: " nil 'my-history)))
197 Here's how to avoid the problem, by examining point and the mark only
198 after reading the keyboard input:
202 (let ((string (read-string "Foo: " nil 'my-history)))
203 (list (region-beginning) (region-end) string)))
207 @cindex argument prompt
208 It may be a string; then its contents should consist of a code character
209 followed by a prompt (which some code characters use and some ignore).
210 The prompt ends either with the end of the string or with a newline.
211 Here is a simple example:
214 (interactive "bFrobnicate buffer: ")
218 The code letter @samp{b} says to read the name of an existing buffer,
219 with completion. The buffer name is the sole argument passed to the
220 command. The rest of the string is a prompt.
222 If there is a newline character in the string, it terminates the prompt.
223 If the string does not end there, then the rest of the string should
224 contain another code character and prompt, specifying another argument.
225 You can specify any number of arguments in this way.
228 The prompt string can use @samp{%} to include previous argument values
229 (starting with the first argument) in the prompt. This is done using
230 @code{format} (@pxref{Formatting Strings}). For example, here is how
231 you could read the name of an existing buffer followed by a new name to
236 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
240 @cindex @samp{*} in interactive
241 @cindex read-only buffers in interactive
242 If the first character in the string is @samp{*}, then an error is
243 signaled if the buffer is read-only.
245 @cindex @samp{@@} in interactive
247 If the first character in the string is @samp{@@}, and if the key
248 sequence used to invoke the command includes any mouse events, then
249 the window associated with the first of those events is selected
250 before the command is run.
252 You can use @samp{*} and @samp{@@} together; the order does not matter.
253 Actual reading of arguments is controlled by the rest of the prompt
254 string (starting with the first character that is not @samp{*} or
258 @node Interactive Codes
259 @comment node-name, next, previous, up
260 @subsection Code Characters for @code{interactive}
261 @cindex interactive code description
262 @cindex description for interactive codes
263 @cindex codes, interactive, description of
264 @cindex characters for interactive codes
266 The code character descriptions below contain a number of key words,
267 defined here as follows:
271 @cindex interactive completion
272 Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name
273 completion because the argument is read using @code{completing-read}
274 (@pxref{Completion}). @kbd{?} displays a list of possible completions.
277 Require the name of an existing object. An invalid name is not
278 accepted; the commands to exit the minibuffer do not exit if the current
282 @cindex default argument string
283 A default value of some sort is used if the user enters no text in the
284 minibuffer. The default depends on the code character.
287 This code letter computes an argument without reading any input.
288 Therefore, it does not use a prompt string, and any prompt string you
291 Even though the code letter doesn't use a prompt string, you must follow
292 it with a newline if it is not the last code character in the string.
295 A prompt immediately follows the code character. The prompt ends either
296 with the end of the string or with a newline.
299 This code character is meaningful only at the beginning of the
300 interactive string, and it does not look for a prompt or a newline.
301 It is a single, isolated character.
304 @cindex reading interactive arguments
305 Here are the code character descriptions for use with @code{interactive}:
309 Signal an error if the current buffer is read-only. Special.
312 Select the window mentioned in the first mouse event in the key
313 sequence that invoked this command. Special.
316 A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
320 The name of an existing buffer. By default, uses the name of the
321 current buffer (@pxref{Buffers}). Existing, Completion, Default,
325 A buffer name. The buffer need not exist. By default, uses the name of
326 a recently used buffer other than the current buffer. Completion,
330 A character. The cursor does not move into the echo area. Prompt.
333 A command name (i.e., a symbol satisfying @code{commandp}). Existing,
337 @cindex position argument
338 The position of point, as an integer (@pxref{Point}). No I/O.
341 A directory name. The default is the current default directory of the
342 current buffer, @code{default-directory} (@pxref{System Environment}).
343 Existing, Completion, Default, Prompt.
346 The first or next mouse event in the key sequence that invoked the command.
347 More precisely, @samp{e} gets events that are lists, so you can look at
348 the data in the lists. @xref{Input Events}. No I/O.
350 You can use @samp{e} more than once in a single command's interactive
351 specification. If the key sequence that invoked the command has
352 @var{n} events that are lists, the @var{n}th @samp{e} provides the
353 @var{n}th such event. Events that are not lists, such as function keys
354 and @sc{ASCII} characters, do not count where @samp{e} is concerned.
357 A file name of an existing file (@pxref{File Names}). The default
358 directory is @code{default-directory}. Existing, Completion, Default,
362 A file name. The file need not exist. Completion, Default, Prompt.
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 This kind of input is used by commands such as @code{describe-key} and
371 @code{global-set-key}.
374 @cindex marker argument
375 The position of the mark, as an integer. No I/O.
378 A number read with the minibuffer. If the input is not a number, the
379 user is asked to try again. The prefix argument, if any, is not used.
383 @cindex raw prefix argument usage
384 The raw prefix argument. If the prefix argument is @code{nil}, then
385 read a number as with @kbd{n}. Requires a number. @xref{Prefix Command
389 @cindex numeric prefix argument usage
390 The numeric prefix argument. (Note that this @samp{p} is lower case.)
394 The raw prefix argument. (Note that this @samp{P} is upper case.) No
398 @cindex region argument
399 Point and the mark, as two numeric arguments, smallest first. This is
400 the only code letter that specifies two successive arguments rather than
404 Arbitrary text, read in the minibuffer and returned as a string
405 (@pxref{Text from Minibuffer}). Terminate the input with either
406 @key{LFD} or @key{RET}. (@kbd{C-q} may be used to include either of
407 these characters in the input.) Prompt.
410 An interned symbol whose name is read in the minibuffer. Any whitespace
411 character terminates the input. (Use @kbd{C-q} to include whitespace in
412 the string.) Other characters that normally terminate a symbol (e.g.,
413 parentheses and brackets) do not do so here. Prompt.
416 A variable declared to be a user option (i.e., satisfying the predicate
417 @code{user-variable-p}). @xref{High-Level Completion}. Existing,
421 A Lisp object, specified with its read syntax, terminated with a
422 @key{LFD} or @key{RET}. The object is not evaluated. @xref{Object from
426 @cindex evaluated expression argument
427 A Lisp form is read as with @kbd{x}, but then evaluated so that its
428 value becomes the argument for the command. Prompt.
431 @node Interactive Examples
432 @comment node-name, next, previous, up
433 @subsection Examples of Using @code{interactive}
434 @cindex examples of using @code{interactive}
435 @cindex @code{interactive}, examples of using
437 Here are some examples of @code{interactive}:
441 (defun foo1 () ; @r{@code{foo1} takes no arguments,}
442 (interactive) ; @r{just moves forward two words.}
448 (defun foo2 (n) ; @r{@code{foo2} takes one argument,}
449 (interactive "p") ; @r{which is the numeric prefix.}
450 (forward-word (* 2 n)))
455 (defun foo3 (n) ; @r{@code{foo3} takes one argument,}
456 (interactive "nCount:") ; @r{which is read with the Minibuffer.}
457 (forward-word (* 2 n)))
462 (defun three-b (b1 b2 b3)
463 "Select three existing buffers.
464 Put them into three windows, selecting the last one."
466 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
467 (delete-other-windows)
468 (split-window (selected-window) 8)
469 (switch-to-buffer b1)
471 (split-window (selected-window) 8)
472 (switch-to-buffer b2)
474 (switch-to-buffer b3))
477 (three-b "*scratch*" "declarations.texi" "*mail*")
482 @node Interactive Call
483 @section Interactive Call
484 @cindex interactive call
486 After the command loop has translated a key sequence into a
487 definition, it invokes that definition using the function
488 @code{command-execute}. If the definition is a function that is a
489 command, @code{command-execute} calls @code{call-interactively}, which
490 reads the arguments and calls the command. You can also call these
493 @defun commandp object
494 Returns @code{t} if @var{object} is suitable for calling interactively;
495 that is, if @var{object} is a command. Otherwise, returns @code{nil}.
497 The interactively callable objects include strings and vectors (treated
498 as keyboard macros), lambda expressions that contain a top-level call to
499 @code{interactive}, compiled function objects made from such lambda
500 expressions, autoload objects that are declared as interactive
501 (non-@code{nil} fourth argument to @code{autoload}), and some of the
504 A symbol is @code{commandp} if its function definition is
507 Keys and keymaps are not commands. Rather, they are used to look up
508 commands (@pxref{Keymaps}).
510 See @code{documentation} in @ref{Accessing Documentation}, for a
511 realistic example of using @code{commandp}.
514 @defun call-interactively command &optional record-flag
515 This function calls the interactively callable function @var{command},
516 reading arguments according to its interactive calling specifications.
517 An error is signaled if @var{command} is not a function or if it cannot
518 be called interactively (i.e., is not a command). Note that keyboard
519 macros (strings and vectors) are not accepted, even though they are
520 considered commands, because they are not functions.
522 @cindex record command history
523 If @var{record-flag} is non-@code{nil}, then this command and its
524 arguments are unconditionally added to the list @code{command-history}.
525 Otherwise, the command is added only if it uses the minibuffer to read
526 an argument. @xref{Command History}.
529 @defun command-execute command &optional record-flag
530 @cindex keyboard macro execution
531 This function executes @var{command} as an editing command. The
532 argument @var{command} must satisfy the @code{commandp} predicate; i.e.,
533 it must be an interactively callable function or a keyboard macro.
535 A string or vector as @var{command} is executed with
536 @code{execute-kbd-macro}. A function is passed to
537 @code{call-interactively}, along with the optional @var{record-flag}.
539 A symbol is handled by using its function definition in its place. A
540 symbol with an @code{autoload} definition counts as a command if it was
541 declared to stand for an interactively callable function. Such a
542 definition is handled by loading the specified library and then
543 rechecking the definition of the symbol.
546 @deffn Command execute-extended-command prefix-argument
547 @cindex read command name
548 This function reads a command name from the minibuffer using
549 @code{completing-read} (@pxref{Completion}). Then it uses
550 @code{command-execute} to call the specified command. Whatever that
551 command returns becomes the value of @code{execute-extended-command}.
553 @cindex execute with prefix argument
554 If the command asks for a prefix argument, it receives the value
555 @var{prefix-argument}. If @code{execute-extended-command} is called
556 interactively, the current raw prefix argument is used for
557 @var{prefix-argument}, and thus passed on to whatever command is run.
559 @c !!! Should this be @kindex?
561 @code{execute-extended-command} is the normal definition of @kbd{M-x},
562 so it uses the string @w{@samp{M-x }} as a prompt. (It would be better
563 to take the prompt from the events used to invoke
564 @code{execute-extended-command}, but that is painful to implement.) A
565 description of the value of the prefix argument, if any, also becomes
570 (execute-extended-command 1)
571 ---------- Buffer: Minibuffer ----------
572 1 M-x forward-word RET
573 ---------- Buffer: Minibuffer ----------
580 This function returns @code{t} if the containing function (the one that
581 called @code{interactive-p}) was called interactively, with the function
582 @code{call-interactively}. (It makes no difference whether
583 @code{call-interactively} was called from Lisp or directly from the
584 editor command loop.) If the containing function was called by Lisp
585 evaluation (or with @code{apply} or @code{funcall}), then it was not
586 called interactively.
588 The most common use of @code{interactive-p} is for deciding whether to
589 print an informative message. As a special exception,
590 @code{interactive-p} returns @code{nil} whenever a keyboard macro is
591 being run. This is to suppress the informative messages and speed
592 execution of the macro.
608 (setq foobar (list (foo) (interactive-p))))
613 ;; @r{Type @kbd{M-x foo}.}
618 ;; @r{Type @kbd{M-x bar}.}
619 ;; @r{This does not print anything.}
629 @node Command Loop Info
630 @comment node-name, next, previous, up
631 @section Information from the Command Loop
633 The editor command loop sets several Lisp variables to keep status
634 records for itself and for commands that are run.
637 This variable records the name of the previous command executed by the
638 command loop (the one before the current command). Normally the value
639 is a symbol with a function definition, but this is not guaranteed.
641 The value is copied from @code{this-command} when a command returns to
642 the command loop, except when the command specifies a prefix argument
643 for the following command.
647 @cindex current command
648 This variable records the name of the command now being executed by
649 the editor command loop. Like @code{last-command}, it is normally a symbol
650 with a function definition.
652 The command loop sets this variable just before running a command, and
653 copies its value into @code{last-command} when the command finishes
654 (unless the command specifies a prefix argument for the following
657 @cindex kill command repetition
658 Some commands set this variable during their execution, as a flag for
659 whatever command runs next. In particular, the functions that kill text
660 set @code{this-command} to @code{kill-region} so that any kill commands
661 immediately following will know to append the killed text to the
665 If you do not want a particular command to be recognized as the previous
666 command in the case where it got an error, you must code that command to
667 prevent this. One way is to set @code{this-command} to @code{t} at the
668 beginning of the command, and set @code{this-command} back to its proper
669 value at the end, like this:
672 (defun foo (args@dots{})
673 (interactive @dots{})
674 (let ((old-this-command this-command))
675 (setq this-command t)
676 @r{@dots{}do the work@dots{}}
677 (setq this-command old-this-command)))
680 @defun this-command-keys
681 This function returns a string or vector containing the key sequence
682 that invoked the present command, plus any previous commands that
683 generated the prefix argument for this command. The value is a string
684 if all those events were characters. @xref{Input Events}.
689 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
695 @defvar last-nonmenu-event
696 This variable holds the last input event read as part of a key
697 sequence, not counting events resulting from mouse menus.
699 One use of this variable is to figure out a good default location to
703 @defvar last-command-event
704 @defvarx last-command-char
705 This variable is set to the last input event that was read by the
706 command loop as part of a command. The principal use of this variable
707 is in @code{self-insert-command}, which uses it to decide which
713 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
719 The value is 5 because that is the @sc{ASCII} code for @kbd{C-e}.
721 The alias @code{last-command-char} exists for compatibility with
726 @defvar last-event-frame
727 This variable records which frame the last input event was directed to.
728 Usually this is the frame that was selected when the event was
729 generated, but if that frame has redirected input focus to another
730 frame, the value is the frame to which the event was redirected.
734 @defvar echo-keystrokes
735 This variable determines how much time should elapse before command
736 characters echo. Its value must be an integer, which specifies the
737 number of seconds to wait before echoing. If the user types a prefix
738 key (such as @kbd{C-x}) and then delays this many seconds before
739 continuing, the prefix key is echoed in the echo area. Any subsequent
740 characters in the same command will be echoed as well.
742 If the value is zero, then command input is not echoed.
746 @section Input Events
750 The Emacs command loop reads a sequence of @dfn{input events} that
751 represent keyboard or mouse activity. The events for keyboard activity
752 are characters or symbols; mouse events are always lists. This section
753 describes the representation and meaning of input events in detail.
756 This function returns non-@code{nil} if @var{event} is an input event.
760 * Keyboard Events:: Ordinary characters--keys with symbols on them.
761 * Function Keys:: Function keys--keys with names, not symbols.
762 * Mouse Events:: Overview of mouse events.
763 * Click Events:: Pushing and releasing a mouse button.
764 * Drag Events:: Moving the mouse before releasing the button.
765 * Button-Down Events:: A button was pushed and not yet released.
766 * Repeat Events:: Double and triple click (or drag, or down).
767 * Motion Events:: Just moving the mouse, not pushing a button.
768 * Focus Events:: Moving the mouse between frames.
769 * Event Examples:: Examples of the lists for mouse events.
770 * Classifying Events:: Finding the modifier keys in an event symbol.
772 * Accessing Events:: Functions to extract info from events.
773 * Strings of Events:: Special considerations for putting
774 keyboard character events in a string.
777 @node Keyboard Events
778 @subsection Keyboard Events
780 There are two kinds of input you can get from the keyboard: ordinary
781 keys, and function keys. Ordinary keys correspond to characters; the
782 events they generate are represented in Lisp as characters. In Emacs
783 versions 18 and earlier, characters were the only events. The event
784 type of a character event is the character itself (an integer);
785 see @ref{Classifying Events}.
787 @cindex modifier bits (of input character)
788 @cindex basic code (of input character)
789 An input character event consists of a @dfn{basic code} between 0 and
790 255, plus any or all of these @dfn{modifier bits}:
794 The 2**23 bit in the character code indicates a character
795 typed with the meta key held down.
798 The 2**22 bit in the character code indicates a non-@sc{ASCII}
801 @sc{ASCII} control characters such as @kbd{C-a} have special basic
802 codes of their own, so Emacs needs no special bit to indicate them.
803 Thus, the code for @kbd{C-a} is just 1.
805 But if you type a control combination not in @sc{ASCII}, such as
806 @kbd{%} with the control key, the numeric value you get is the code
807 for @kbd{%} plus 2**22 (assuming the terminal supports non-@sc{ASCII}
811 The 2**21 bit in the character code indicates an @sc{ASCII} control
812 character typed with the shift key held down.
814 For letters, the basic code indicates upper versus lower case; for
815 digits and punctuation, the shift key selects an entirely different
816 character with a different basic code. In order to keep within
817 the @sc{ASCII} character set whenever possible, Emacs avoids using
818 the 2**21 bit for those characters.
820 However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
821 @kbd{C-a}, so Emacs uses the 2**21 bit in @kbd{C-A} and not in
825 The 2**20 bit in the character code indicates a character
826 typed with the hyper key held down.
829 The 2**19 bit in the character code indicates a character
830 typed with the super key held down.
833 The 2**18 bit in the character code indicates a character typed with
834 the alt key held down. (On some terminals, the key labeled @key{ALT}
835 is actually the meta key.)
838 In the future, Emacs may support a larger range of basic codes. We
839 may also move the modifier bits to larger bit numbers. Therefore, you
840 should avoid mentioning specific bit numbers in your program.
841 Instead, the way to test the modifier bits of a character is with the
842 function @code{event-modifiers} (@pxref{Classifying Events}).
845 @subsection Function Keys
847 @cindex function keys
848 Most keyboards also have @dfn{function keys}---keys that have names or
849 symbols that are not characters. Function keys are represented in Lisp
850 as symbols; the symbol's name is the function key's label, in lower
851 case. For example, pressing a key labeled @key{F1} places the symbol
852 @code{f1} in the input stream.
854 The event type of a function key event is the event symbol itself.
855 @xref{Classifying Events}.
857 Here are a few special cases in the symbol-naming convention for
861 @item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
862 These keys correspond to common @sc{ASCII} control characters that have
863 special keys on most keyboards.
865 In @sc{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the
866 terminal can distinguish between them, Emacs conveys the distinction to
867 Lisp programs by representing the former as the integer 9, and the
868 latter as the symbol @code{tab}.
870 Most of the time, it's not useful to distinguish the two. So normally
871 @code{function-key-map} is set up to map @code{tab} into 9. Thus, a key
872 binding for character code 9 (the character @kbd{C-i}) also applies to
873 @code{tab}. Likewise for the other symbols in this group. The function
874 @code{read-char} likewise converts these events into characters.
876 In @sc{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace}
877 converts into the character code 127 (@key{DEL}), not into code 8
878 (@key{BS}). This is what most users prefer.
880 @item @code{left}, @code{up}, @code{right}, @code{down}
882 @item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
883 Keypad keys (to the right of the regular keyboard).
884 @item @code{kp-0}, @code{kp-1}, @dots{}
885 Keypad keys with digits.
886 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
888 @item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
889 Keypad arrow keys. Emacs normally translates these
890 into the non-keypad keys @code{home}, @code{left}, @dots{}
891 @item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
892 Additional keypad duplicates of keys ordinarily found elsewhere. Emacs
893 normally translates these into the like-named non-keypad keys.
896 You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
897 @key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to
898 represent them is with prefixes in the symbol name:
904 The control modifier.
915 Thus, the symbol for the key @key{F3} with @key{META} held down is
916 @code{M-f3}. When you use more than one prefix, we recommend you
917 write them in alphabetical order; but the order does not matter in
918 arguments to the key-binding lookup and modification functions.
921 @subsection Mouse Events
923 Emacs supports four kinds of mouse events: click events, drag events,
924 button-down events, and motion events. All mouse events are represented
925 as lists. The @sc{car} of the list is the event type; this says which
926 mouse button was involved, and which modifier keys were used with it.
927 The event type can also distinguish double or triple button presses
928 (@pxref{Repeat Events}). The rest of the list elements give position
929 and time information.
931 For key lookup, only the event type matters: two events of the same type
932 necessarily run the same command. The command can access the full
933 values of these events using the @samp{e} interactive code.
934 @xref{Interactive Codes}.
936 A key sequence that starts with a mouse event is read using the keymaps
937 of the buffer in the window that the mouse was in, not the current
938 buffer. This does not imply that clicking in a window selects that
939 window or its buffer---that is entirely under the control of the command
940 binding of the key sequence.
943 @subsection Click Events
945 @cindex mouse click event
947 When the user presses a mouse button and releases it at the same
948 location, that generates a @dfn{click} event. Mouse click events have
953 (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp})
957 Here is what the elements normally mean:
960 @item @var{event-type}
961 This is a symbol that indicates which mouse button was used. It is
962 one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the
963 buttons are numbered left to right.
965 You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-},
966 @samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift
967 and super, just as you would with function keys.
969 This symbol also serves as the event type of the event. Key bindings
970 describe events by their types; thus, if there is a key binding for
971 @code{mouse-1}, that binding would apply to all events whose
972 @var{event-type} is @code{mouse-1}.
975 This is the window in which the click occurred.
977 @item @var{x}, @var{y}
978 These are the pixel-denominated coordinates of the click, relative to
979 the top left corner of @var{window}, which is @code{(0 . 0)}.
981 @item @var{buffer-pos}
982 This is the buffer position of the character clicked on.
984 @item @var{timestamp}
985 This is the time at which the event occurred, in milliseconds. (Since
986 this value wraps around the entire range of Emacs Lisp integers in about
987 five hours, it is useful only for relating the times of nearby events.)
989 @item @var{click-count}
990 This is the number of rapid repeated presses so far of the same mouse
991 button. @xref{Repeat Events}.
994 The meanings of @var{buffer-pos}, @var{x} and @var{y} are somewhat
995 different when the event location is in a special part of the screen,
996 such as the mode line or a scroll bar.
998 If the location is in a scroll bar, then @var{buffer-pos} is the symbol
999 @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}, and the pair
1000 @code{(@var{x} . @var{y})} is replaced with a pair @code{(@var{portion}
1001 . @var{whole})}, where @var{portion} is the distance of the click from
1002 the top or left end of the scroll bar, and @var{whole} is the length of
1003 the entire scroll bar.
1005 If the position is on a mode line or the vertical line separating
1006 @var{window} from its neighbor to the right, then @var{buffer-pos} is
1007 the symbol @code{mode-line} or @code{vertical-line}. For the mode line,
1008 @var{y} does not have meaningful data. For the vertical line, @var{x}
1009 does not have meaningful data.
1011 In one special case, @var{buffer-pos} is a list containing a symbol (one
1012 of the symbols listed above) instead of just the symbol. This happens
1013 after the imaginary prefix keys for the event are inserted into the
1014 input stream. @xref{Key Sequence Input}.
1017 @subsection Drag Events
1019 @cindex mouse drag event
1021 With Emacs, you can have a drag event without even changing your
1022 clothes. A @dfn{drag event} happens every time the user presses a mouse
1023 button and then moves the mouse to a different character position before
1024 releasing the button. Like all mouse events, drag events are
1025 represented in Lisp as lists. The lists record both the starting mouse
1026 position and the final position, like this:
1030 (@var{window1} @var{buffer-pos1} (@var{x1} . @var{y1}) @var{timestamp1})
1031 (@var{window2} @var{buffer-pos2} (@var{x2} . @var{y2}) @var{timestamp2})
1035 For a drag event, the name of the symbol @var{event-type} contains the
1036 prefix @samp{drag-}. The second and third elements of the event give
1037 the starting and ending position of the drag. Aside from that, the data
1038 have the same meanings as in a click event (@pxref{Click Events}). You
1039 can access the second element of any mouse event in the same way, with
1040 no need to distinguish drag events from others.
1042 The @samp{drag-} prefix follows the modifier key prefixes such as
1043 @samp{C-} and @samp{M-}.
1045 If @code{read-key-sequence} receives a drag event that has no key
1046 binding, and the corresponding click event does have a binding, it
1047 changes the drag event into a click event at the drag's starting
1048 position. This means that you don't have to distinguish between click
1049 and drag events unless you want to.
1051 @node Button-Down Events
1052 @subsection Button-Down Events
1053 @cindex button-down event
1055 Click and drag events happen when the user releases a mouse button.
1056 They cannot happen earlier, because there is no way to distinguish a
1057 click from a drag until the button is released.
1059 If you want to take action as soon as a button is pressed, you need to
1060 handle @dfn{button-down} events.@footnote{Button-down is the
1061 conservative antithesis of drag.} These occur as soon as a button is
1062 pressed. They are represented by lists that look exactly like click
1063 events (@pxref{Click Events}), except that the @var{event-type} symbol
1064 name contains the prefix @samp{down-}. The @samp{down-} prefix follows
1065 modifier key prefixes such as @samp{C-} and @samp{M-}.
1067 The function @code{read-key-sequence}, and therefore the Emacs command
1068 loop as well, ignore any button-down events that don't have command
1069 bindings. This means that you need not worry about defining button-down
1070 events unless you want them to do something. The usual reason to define
1071 a button-down event is so that you can track mouse motion (by reading
1072 motion events) until the button is released. @xref{Motion Events}.
1075 @subsection Repeat Events
1076 @cindex repeat events
1077 @cindex double-click events
1078 @cindex triple-click events
1080 If you press the same mouse button more than once in quick succession
1081 without moving the mouse, Emacs generates special @dfn{repeat} mouse
1082 events for the second and subsequent presses.
1084 The most common repeat events are @dfn{double-click} events. Emacs
1085 generates a double-click event when you click a button twice; the event
1086 happens when you release the button (as is normal for all click
1089 The event type of a double-click event contains the prefix
1090 @samp{double-}. Thus, a double click on the second mouse button with
1091 @key{meta} held down comes to the Lisp program as
1092 @code{M-double-mouse-2}. If a double-click event has no binding, the
1093 binding of the corresponding ordinary click event is used to execute
1094 it. Thus, you need not pay attention to the double click feature
1095 unless you really want to.
1097 When the user performs a double click, Emacs generates first an ordinary
1098 click event, and then a double-click event. Therefore, you must design
1099 the command binding of the double click event to assume that the
1100 single-click command has already run. It must produce the desired
1101 results of a double click, starting from the results of a single click.
1103 This is convenient, if the meaning of a double click somehow ``builds
1104 on'' the meaning of a single click---which is recommended user interface
1105 design practice for double clicks.
1107 If you click a button, then press it down again and start moving the
1108 mouse with the button held down, then you get a @dfn{double-drag} event
1109 when you ultimately release the button. Its event type contains
1110 @samp{double-drag} instead of just @samp{drag}. If a double-drag event
1111 has no binding, Emacs looks for an alternate binding as if the event
1112 were an ordinary drag.
1114 Before the double-click or double-drag event, Emacs generates a
1115 @dfn{double-down} event when the user presses the button down for the
1116 second time. Its event type contains @samp{double-down} instead of just
1117 @samp{down}. If a double-down event has no binding, Emacs looks for an
1118 alternate binding as if the event were an ordinary button-down event.
1119 If it finds no binding that way either, the double-down event is
1122 To summarize, when you click a button and then press it again right
1123 away, Emacs generates a down event and a click event for the first
1124 click, a double-down event when you press the button again, and finally
1125 either a double-click or a double-drag event.
1127 If you click a button twice and then press it again, all in quick
1128 succession, Emacs generates a @dfn{triple-down} event, followed by
1129 either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of
1130 these events contain @samp{triple} instead of @samp{double}. If any
1131 triple event has no binding, Emacs uses the binding that it would use
1132 for the corresponding double event.
1134 If you click a button three or more times and then press it again, the
1135 events for the presses beyond the third are all triple events. Emacs
1136 does not have separate event types for quadruple, quintuple, etc.@:
1137 events. However, you can look at the event list to find out precisely
1138 how many times the button was pressed.
1140 @defun event-click-count event
1141 This function returns the number of consecutive button presses that led
1142 up to @var{event}. If @var{event} is a double-down, double-click or
1143 double-drag event, the value is 2. If @var{event} is a triple event,
1144 the value is 3 or greater. If @var{event} is an ordinary mouse event
1145 (not a repeat event), the value is 1.
1148 @defvar double-click-time
1149 To generate repeat events, successive mouse button presses must be at
1150 the same screen position, and the number of milliseconds between
1151 successive button presses must be less than the value of
1152 @code{double-click-time}. Setting @code{double-click-time} to
1153 @code{nil} disables multi-click detection entirely. Setting it to
1154 @code{t} removes the time limit; Emacs then detects multi-clicks by
1159 @subsection Motion Events
1160 @cindex motion event
1161 @cindex mouse motion events
1163 Emacs sometimes generates @dfn{mouse motion} events to describe motion
1164 of the mouse without any button activity. Mouse motion events are
1165 represented by lists that look like this:
1169 (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}))
1172 The second element of the list describes the current position of the
1173 mouse, just as in a click event (@pxref{Click Events}).
1175 The special form @code{track-mouse} enables generation of motion events
1176 within its body. Outside of @code{track-mouse} forms, Emacs does not
1177 generate events for mere motion of the mouse, and these events do not
1180 @defspec track-mouse body@dots{}
1181 This special form executes @var{body}, with generation of mouse motion
1182 events enabled. Typically @var{body} would use @code{read-event}
1183 to read the motion events and modify the display accordingly.
1185 When the user releases the button, that generates a click event.
1186 Typically, @var{body} should return when it sees the click event, and
1191 @subsection Focus Events
1194 Window systems provide general ways for the user to control which window
1195 gets keyboard input. This choice of window is called the @dfn{focus}.
1196 When the user does something to switch between Emacs frames, that
1197 generates a @dfn{focus event}. The normal definition of a focus event,
1198 in the global keymap, is to select a new frame within Emacs, as the user
1199 would expect. @xref{Input Focus}.
1201 Focus events are represented in Lisp as lists that look like this:
1204 (switch-frame @var{new-frame})
1208 where @var{new-frame} is the frame switched to.
1210 Most X window managers are set up so that just moving the mouse into a
1211 window is enough to set the focus there. Emacs appears to do this,
1212 because it changes the cursor to solid in the new frame. However, there
1213 is no need for the Lisp program to know about the focus change until
1214 some other kind of input arrives. So Emacs generates a focus event only
1215 when the user actually types a keyboard key or presses a mouse button in
1216 the new frame; just moving the mouse between frames does not generate a
1219 A focus event in the middle of a key sequence would garble the
1220 sequence. So Emacs never generates a focus event in the middle of a key
1221 sequence. If the user changes focus in the middle of a key
1222 sequence---that is, after a prefix key---then Emacs reorders the events
1223 so that the focus event comes either before or after the multi-event key
1224 sequence, and not within it.
1226 @node Event Examples
1227 @subsection Event Examples
1229 If the user presses and releases the left mouse button over the same
1230 location, that generates a sequence of events like this:
1233 (down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
1234 (mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180))
1237 While holding the control key down, the user might hold down the
1238 second mouse button, and drag the mouse from one line to the next.
1239 That produces two events, as shown here:
1242 (C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
1243 (C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
1244 (#<window 18 on NEWS> 3510 (0 . 28) -729648))
1247 While holding down the meta and shift keys, the user might press the
1248 second mouse button on the window's mode line, and then drag the mouse
1249 into another window. That produces a pair of events like these:
1252 (M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
1253 (M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
1254 (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
1258 @node Classifying Events
1259 @subsection Classifying Events
1262 Every event has an @dfn{event type}, which classifies the event for
1263 key binding purposes. For a keyboard event, the event type equals the
1264 event value; thus, the event type for a character is the character, and
1265 the event type for a function key symbol is the symbol itself. For
1266 events that are lists, the event type is the symbol in the @sc{car} of
1267 the list. Thus, the event type is always a symbol or a character.
1269 Two events of the same type are equivalent where key bindings are
1270 concerned; thus, they always run the same command. That does not
1271 necessarily mean they do the same things, however, as some commands look
1272 at the whole event to decide what to do. For example, some commands use
1273 the location of a mouse event to decide where in the buffer to act.
1275 Sometimes broader classifications of events are useful. For example,
1276 you might want to ask whether an event involved the @key{META} key,
1277 regardless of which other key or mouse button was used.
1279 The functions @code{event-modifiers} and @code{event-basic-type} are
1280 provided to get such information conveniently.
1282 @defun event-modifiers event
1283 This function returns a list of the modifiers that @var{event} has. The
1284 modifiers are symbols; they include @code{shift}, @code{control},
1285 @code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition,
1286 the modifiers list of a mouse event symbol always contains one of
1287 @code{click}, @code{drag}, and @code{down}.
1289 The argument @var{event} may be an entire event object, or just an event
1292 Here are some examples:
1295 (event-modifiers ?a)
1297 (event-modifiers ?\C-a)
1299 (event-modifiers ?\C-%)
1301 (event-modifiers ?\C-\S-a)
1302 @result{} (control shift)
1303 (event-modifiers 'f5)
1305 (event-modifiers 's-f5)
1307 (event-modifiers 'M-S-f5)
1308 @result{} (meta shift)
1309 (event-modifiers 'mouse-1)
1311 (event-modifiers 'down-mouse-1)
1315 The modifiers list for a click event explicitly contains @code{click},
1316 but the event symbol name itself does not contain @samp{click}.
1319 @defun event-basic-type event
1320 This function returns the key or mouse button that @var{event}
1321 describes, with all modifiers removed. For example:
1324 (event-basic-type ?a)
1326 (event-basic-type ?A)
1328 (event-basic-type ?\C-a)
1330 (event-basic-type ?\C-\S-a)
1332 (event-basic-type 'f5)
1334 (event-basic-type 's-f5)
1336 (event-basic-type 'M-S-f5)
1338 (event-basic-type 'down-mouse-1)
1343 @defun mouse-movement-p object
1344 This function returns non-@code{nil} if @var{object} is a mouse movement
1348 @node Accessing Events
1349 @subsection Accessing Events
1351 This section describes convenient functions for accessing the data in
1352 a mouse button or motion event.
1354 These two functions return the starting or ending position of a
1355 mouse-button event. The position is a list of this form:
1358 (@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp})
1361 @defun event-start event
1362 This returns the starting position of @var{event}.
1364 If @var{event} is a click or button-down event, this returns the
1365 location of the event. If @var{event} is a drag event, this returns the
1366 drag's starting position.
1369 @defun event-end event
1370 This returns the ending position of @var{event}.
1372 If @var{event} is a drag event, this returns the position where the user
1373 released the mouse button. If @var{event} is a click or button-down
1374 event, the value is actually the starting position, which is the only
1375 position such events have.
1378 These four functions take a position as described above, and return
1379 various parts of it.
1381 @defun posn-window position
1382 Return the window that @var{position} is in.
1385 @defun posn-point position
1386 Return the buffer position in @var{position}. This is an integer.
1389 @defun posn-x-y position
1390 Return the pixel-based x and y coordinates in @var{position}, as a cons
1391 cell @code{(@var{x} . @var{y})}.
1394 @defun posn-col-row position
1395 Return the row and column (in units of characters) of @var{position}, as
1396 a cons cell @code{(@var{col} . @var{row})}. These are computed from the
1397 @var{x} and @var{y} values actually found in @var{position}.
1400 @defun posn-timestamp position
1401 Return the timestamp in @var{position}.
1404 @defun scroll-bar-event-ratio event
1405 This function returns the fractional vertical position of a scroll bar
1406 event within the scroll bar. The value is a cons cell
1407 @code{(@var{portion} . @var{whole})} containing two integers whose ratio
1408 is the fractional position.
1411 @defun scroll-bar-scale ratio total
1412 This function multiplies (in effect) @var{ratio} by @var{total},
1413 rounding the result to an integer. The argument @var{ratio} is not a
1414 number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
1415 value returned by @code{scroll-bar-event-ratio}.
1417 This function is handy for scaling a position on a scroll bar into a
1418 buffer position. Here's how to do that:
1423 (posn-x-y (event-start event))
1424 (- (point-max) (point-min))))
1427 Recall that scroll bar events have two integers forming ratio in place
1428 of a pair of x and y coordinates.
1431 @node Strings of Events
1432 @subsection Putting Keyboard Events in Strings
1434 In most of the places where strings are used, we conceptualize the
1435 string as containing text characters---the same kind of characters found
1436 in buffers or files. Occasionally Lisp programs use strings that
1437 conceptually contain keyboard characters; for example, they may be key
1438 sequences or keyboard macro definitions. There are special rules for
1439 how to put keyboard characters into a string, because they are not
1440 limited to the range of 0 to 255 as text characters are.
1442 A keyboard character typed using the @key{META} key is called a
1443 @dfn{meta character}. The numeric code for such an event includes the
1444 2**23 bit; it does not even come close to fitting in a string. However,
1445 earlier Emacs versions used a different representation for these
1446 characters, which gave them codes in the range of 128 to 255. That did
1447 fit in a string, and many Lisp programs contain string constants that
1448 use @samp{\M-} to express meta characters, especially as the argument to
1449 @code{define-key} and similar functions.
1451 We provide backward compatibility to run those programs using special
1452 rules for how to put a keyboard character event in a string. Here are
1457 If the keyboard character value is in the range of 0 to 127, it can go
1458 in the string unchanged.
1461 The meta variants of those characters, with codes in the range of 2**23
1462 to 2**23+127, can also go in the string, but you must change their
1463 numeric values. You must set the 2**7 bit instead of the 2**23 bit,
1464 resulting in a value between 128 and 255.
1467 Other keyboard character events cannot fit in a string. This includes
1468 keyboard events in the range of 128 to 255.
1471 Functions such as @code{read-key-sequence} that can construct strings
1472 of keyboard input characters follow these rules. They construct vectors
1473 instead of strings, when the events won't fit in a string.
1475 When you use the read syntax @samp{\M-} in a string, it produces a
1476 code in the range of 128 to 255---the same code that you get if you
1477 modify the corresponding keyboard event to put it in the string. Thus,
1478 meta events in strings work consistently regardless of how they get into
1481 The reason we changed the representation of meta characters as
1482 keyboard events is to make room for basic character codes beyond 127,
1483 and support meta variants of such larger character codes.
1485 New programs can avoid dealing with these special compatibility rules
1486 by using vectors instead of strings for key sequences when there is any
1487 possibility that they might contain meta characters, and by using
1488 @code{listify-key-sequence} to access a string of events.
1490 @defun listify-key-sequence key
1491 This function converts the string or vector @var{key} to a list of
1492 events, which you can put in @code{unread-command-events}. Converting a
1493 vector is simple, but converting a string is tricky because of the
1494 special representation used for meta characters in a string.
1498 @section Reading Input
1500 The editor command loop reads keyboard input using the function
1501 @code{read-key-sequence}, which uses @code{read-event}. These and other
1502 functions for keyboard input are also available for use in Lisp
1503 programs. See also @code{momentary-string-display} in @ref{Temporary
1504 Displays}, and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input},
1505 for functions and variables for controlling terminal input modes and
1506 debugging terminal input.
1508 For higher-level input facilities, see @ref{Minibuffers}.
1511 * Key Sequence Input:: How to read one key sequence.
1512 * Reading One Event:: How to read just one event.
1513 * Quoted Character Input:: Asking the user to specify a character.
1514 * Event Input Misc:: How to reread or throw away input events.
1517 @node Key Sequence Input
1518 @subsection Key Sequence Input
1519 @cindex key sequence input
1521 The command loop reads input a key sequence at a time, by calling
1522 @code{read-key-sequence}. Lisp programs can also call this function;
1523 for example, @code{describe-key} uses it to read the key to describe.
1525 @defun read-key-sequence prompt
1526 @cindex key sequence
1527 This function reads a key sequence and returns it as a string or
1528 vector. It keeps reading events until it has accumulated a full key
1529 sequence; that is, enough to specify a non-prefix command using the
1530 currently active keymaps.
1532 If the events are all characters and all can fit in a string, then
1533 @code{read-key-sequence} returns a string (@pxref{Strings of Events}).
1534 Otherwise, it returns a vector, since a vector can hold all kinds of
1535 events---characters, symbols, and lists. The elements of the string or
1536 vector are the events in the key sequence.
1538 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
1539 typed while reading with this function works like any other character,
1540 and does not set @code{quit-flag}. @xref{Quitting}.
1542 The argument @var{prompt} is either a string to be displayed in the echo
1543 area as a prompt, or @code{nil}, meaning not to display a prompt.
1545 In the example below, the prompt @samp{?} is displayed in the echo area,
1546 and the user types @kbd{C-x C-f}.
1549 (read-key-sequence "?")
1552 ---------- Echo Area ----------
1554 ---------- Echo Area ----------
1561 @defvar num-input-keys
1563 This variable's value is the number of key sequences processed so far in
1564 this Emacs session. This includes key sequences read from the terminal
1565 and key sequences read from keyboard macros being executed.
1568 @cindex upper case key sequence
1569 @cindex downcasing in @code{lookup-key}
1570 If an input character is an upper-case letter and has no key binding,
1571 but its lower-case equivalent has one, then @code{read-key-sequence}
1572 converts the character to lower case. Note that @code{lookup-key} does
1573 not perform case conversion in this way.
1575 The function @code{read-key-sequence} also transforms some mouse events.
1576 It converts unbound drag events into click events, and discards unbound
1577 button-down events entirely. It also reshuffles focus events so that they
1578 never appear in a key sequence with any other events.
1580 When mouse events occur in special parts of a window, such as a mode
1581 line or a scroll bar, the event type shows nothing special---it is the
1582 same symbol that would normally represent that combination of mouse
1583 button and modifier keys. The information about the window part is
1584 kept elsewhere in the event---in the coordinates. But
1585 @code{read-key-sequence} translates this information into imaginary
1586 prefix keys, all of which are symbols: @code{mode-line},
1587 @code{vertical-line}, @code{horizontal-scroll-bar} and
1588 @code{vertical-scroll-bar}.
1590 You can define meanings for mouse clicks in special window parts by
1591 defining key sequences using these imaginary prefix keys.
1593 For example, if you call @code{read-key-sequence} and then click the
1594 mouse on the window's mode line, you get an event like this:
1597 (read-key-sequence "Click on the mode line: ")
1598 @result{} [mode-line
1600 (#<window 6 on NEWS> mode-line
1601 (40 . 63) 5959987))]
1604 @node Reading One Event
1605 @subsection Reading One Event
1607 The lowest level functions for command input are those that read a
1611 This function reads and returns the next event of command input, waiting
1612 if necessary until an event is available. Events can come directly from
1613 the user or from a keyboard macro.
1615 The function @code{read-event} does not display any message to indicate
1616 it is waiting for input; use @code{message} first, if you wish to
1617 display one. If you have not displayed a message, @code{read-event}
1618 prompts by echoing: it displays descriptions of the events that led to
1619 or were read by the current command. @xref{The Echo Area}.
1621 If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
1622 moves the cursor temporarily to the echo area, to the end of any message
1623 displayed there. Otherwise @code{read-event} does not move the cursor.
1625 Here is what happens if you call @code{read-event} and then press the
1626 right-arrow function key:
1637 This function reads and returns a character of command input. It
1638 discards any events that are not characters, until it gets a character.
1640 In the first example, the user types the character @kbd{1} (@sc{ASCII}
1641 code 49). The second example shows a keyboard macro definition that
1642 calls @code{read-char} from the minibuffer using @code{eval-expression}.
1643 @code{read-char} reads the keyboard macro's very next character, which
1644 is @kbd{1}. Then @code{eval-expression} displays its return value in
1654 (symbol-function 'foo)
1655 @result{} "^[^[(read-char)^M1"
1658 (execute-kbd-macro 'foo)
1665 @node Quoted Character Input
1666 @subsection Quoted Character Input
1667 @cindex quoted character input
1669 You can use the function @code{read-quoted-char} to ask the user to
1670 specify a character, and allow the user to specify a control or meta
1671 character conveniently, either literally or as an octal character code.
1672 The command @code{quoted-insert} uses this function.
1674 @defun read-quoted-char &optional prompt
1675 @cindex octal character input
1676 @cindex control characters, reading
1677 @cindex nonprinting characters, reading
1678 This function is like @code{read-char}, except that if the first
1679 character read is an octal digit (0-7), it reads up to two more octal digits
1680 (but stopping if a non-octal digit is found) and returns the
1681 character represented by those digits in octal.
1683 Quitting is suppressed when the first character is read, so that the
1684 user can enter a @kbd{C-g}. @xref{Quitting}.
1686 If @var{prompt} is supplied, it specifies a string for prompting the
1687 user. The prompt string is always displayed in the echo area, followed
1688 by a single @samp{-}.
1690 In the following example, the user types in the octal number 177 (which
1694 (read-quoted-char "What character")
1697 ---------- Echo Area ----------
1698 What character-@kbd{177}
1699 ---------- Echo Area ----------
1707 @node Event Input Misc
1708 @subsection Miscellaneous Event Input Features
1710 This section describes how to ``peek ahead'' at events without using
1711 them up, how to check for pending input, and how to discard pending
1714 @defvar unread-command-events
1716 @cindex peeking at input
1717 This variable holds a list of events waiting to be read as command
1718 input. The events are used in the order they appear in the list, and
1719 removed one by one as they are used.
1721 The variable is needed because in some cases a function reads a event
1722 and then decides not to use it. Storing the event in this variable
1723 causes it to be processed normally, by the command loop or by the
1724 functions to read command input.
1726 @cindex prefix argument unreading
1727 For example, the function that implements numeric prefix arguments reads
1728 any number of digits. When it finds a non-digit event, it must unread
1729 the event so that it can be read normally by the command loop.
1730 Likewise, incremental search uses this feature to unread events with no
1731 special meaning in a search, because these events should exit the search
1732 and then execute normally.
1734 The reliable and easy way to extract events from a key sequence so as to
1735 put them in @code{unread-command-events} is to use
1736 @code{listify-key-sequence} (@pxref{Strings of Events}).
1739 @defvar unread-command-char
1740 This variable holds a character to be read as command input.
1741 A value of -1 means ``empty''.
1743 This variable is mostly obsolete now that you can use
1744 @code{unread-command-events} instead; it exists only to support programs
1745 written for Emacs versions 18 and earlier.
1748 @defun input-pending-p
1749 @cindex waiting for command key input
1750 This function determines whether any command input is currently
1751 available to be read. It returns immediately, with value @code{t} if
1752 there is available input, @code{nil} otherwise. On rare occasions it
1753 may return @code{t} when no input is available.
1756 @defvar last-input-event
1757 This variable records the last terminal input event read, whether
1758 as part of a command or explicitly by a Lisp program.
1760 In the example below, the Lisp program reads the character @kbd{1},
1761 @sc{ASCII} code 49. It becomes the value of @code{last-input-event},
1762 while @kbd{C-e} (from the @kbd{C-x C-e} command used to evaluate this
1763 expression) remains the value of @code{last-command-event}.
1767 (progn (print (read-char))
1768 (print last-command-event)
1776 @vindex last-input-char
1777 The alias @code{last-input-char} exists for compatibility with
1781 @defun discard-input
1783 @cindex discard input
1784 @cindex terminate keyboard macro
1785 This function discards the contents of the terminal input buffer and
1786 cancels any keyboard macro that might be in the process of definition.
1787 It returns @code{nil}.
1789 In the following example, the user may type a number of characters right
1790 after starting the evaluation of the form. After the @code{sleep-for}
1791 finishes sleeping, @code{discard-input} discards any characters typed
1795 (progn (sleep-for 2)
1802 @section Waiting for Elapsed Time or Input
1806 The wait functions are designed to wait for a certain amount of time
1807 to pass or until there is input. For example, you may wish to pause in
1808 the middle of a computation to allow the user time to view the display.
1809 @code{sit-for} pauses and updates the screen, and returns immediately if
1810 input comes in, while @code{sleep-for} pauses without updating the
1813 @defun sit-for seconds &optional millisec nodisp
1814 This function performs redisplay (provided there is no pending input
1815 from the user), then waits @var{seconds} seconds, or until input is
1816 available. The value is @code{t} if @code{sit-for} waited the full
1817 time with no input arriving (see @code{input-pending-p} in @ref{Event
1818 Input Misc}). Otherwise, the value is @code{nil}.
1820 @c Emacs 19 feature ??? maybe not working yet
1821 The optional argument @var{millisec} specifies an additional waiting
1822 period measured in milliseconds. This adds to the period specified by
1823 @var{seconds}. Not all operating systems support waiting periods other
1824 than multiples of a second; on those that do not, you get an error if
1825 you specify nonzero @var{millisec}.
1827 @cindex forcing redisplay
1828 Redisplay is always preempted if input arrives, and does not happen at
1829 all if input is available before it starts. Thus, there is no way to
1830 force screen updating if there is pending input; however, if there is no
1831 input pending, you can force an update with no delay by using
1834 If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
1835 redisplay, but it still returns as soon as input is available (or when
1836 the timeout elapses).
1838 The usual purpose of @code{sit-for} is to give the user time to read
1839 text that you display.
1842 @defun sleep-for seconds &optional millisec
1843 This function simply pauses for @var{seconds} seconds without updating
1844 the display. It pays no attention to available input. It returns
1847 @c Emacs 19 feature ??? maybe not working yet
1848 The optional argument @var{millisec} specifies an additional waiting
1849 period measured in milliseconds. This adds to the period specified by
1850 @var{seconds}. Not all operating systems support waiting periods other
1851 than multiples of a second; on those that do not, you get an error if
1852 you specify nonzero @var{millisec}.
1854 Use @code{sleep-for} when you wish to guarantee a delay.
1857 @xref{Time of Day}, for functions to get the current time.
1864 Typing @kbd{C-g} while a Lisp function is running causes Emacs to
1865 @dfn{quit} whatever it is doing. This means that control returns to the
1866 innermost active command loop.
1868 Typing @kbd{C-g} while the command loop is waiting for keyboard input
1869 does not cause a quit; it acts as an ordinary input character. In the
1870 simplest case, you cannot tell the difference, because @kbd{C-g}
1871 normally runs the command @code{keyboard-quit}, whose effect is to quit.
1872 However, when @kbd{C-g} follows a prefix key, the result is an undefined
1873 key. The effect is to cancel the prefix key as well as any prefix
1876 In the minibuffer, @kbd{C-g} has a different definition: it aborts out
1877 of the minibuffer. This means, in effect, that it exits the minibuffer
1878 and then quits. (Simply quitting would return to the command loop
1879 @emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit
1880 directly when the command reader is reading input is so that its meaning
1881 can be redefined in the minibuffer in this way. @kbd{C-g} following a
1882 prefix key is not redefined in the minibuffer, and it has its normal
1883 effect of canceling the prefix key and prefix argument. This too
1884 would not be possible if @kbd{C-g} always quit directly.
1886 When @kbd{C-g} does directly quit, it does so by setting the variable
1887 @code{quit-flag} to @code{t}. Emacs checks this variable at appropriate
1888 times and quits if it is not @code{nil}. Setting @code{quit-flag}
1889 non-@code{nil} in any way thus causes a quit.
1891 At the level of C code, quitting cannot happen just anywhere; only at the
1892 special places that check @code{quit-flag}. The reason for this is
1893 that quitting at other places might leave an inconsistency in Emacs's
1894 internal state. Because quitting is delayed until a safe place, quitting
1895 cannot make Emacs crash.
1897 Certain functions such as @code{read-key-sequence} or
1898 @code{read-quoted-char} prevent quitting entirely even though they wait
1899 for input. Instead of quitting, @kbd{C-g} serves as the requested
1900 input. In the case of @code{read-key-sequence}, this serves to bring
1901 about the special behavior of @kbd{C-g} in the command loop. In the
1902 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
1903 to quote a @kbd{C-g}.
1905 You can prevent quitting for a portion of a Lisp function by binding
1906 the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
1907 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
1908 usual result of this---a quit---is prevented. Eventually,
1909 @code{inhibit-quit} will become @code{nil} again, such as when its
1910 binding is unwound at the end of a @code{let} form. At that time, if
1911 @code{quit-flag} is still non-@code{nil}, the requested quit happens
1912 immediately. This behavior is ideal when you wish to make sure that
1913 quitting does not happen within a ``critical section'' of the program.
1915 @cindex @code{read-quoted-char} quitting
1916 In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
1917 handled in a special way that does not involve quitting. This is done
1918 by reading the input with @code{inhibit-quit} bound to @code{t}, and
1919 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
1920 becomes @code{nil} again. This excerpt from the definition of
1921 @code{read-quoted-char} shows how this is done; it also shows that
1922 normal quitting is permitted after the first character of input.
1925 (defun read-quoted-char (&optional prompt)
1926 "@dots{}@var{documentation}@dots{}"
1927 (let ((count 0) (code 0) char)
1929 (let ((inhibit-quit (zerop count))
1931 (and prompt (message "%s-" prompt))
1932 (setq char (read-char))
1933 (if inhibit-quit (setq quit-flag nil)))
1939 If this variable is non-@code{nil}, then Emacs quits immediately, unless
1940 @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
1941 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
1944 @defvar inhibit-quit
1945 This variable determines whether Emacs should quit when @code{quit-flag}
1946 is set to a value other than @code{nil}. If @code{inhibit-quit} is
1947 non-@code{nil}, then @code{quit-flag} has no special effect.
1950 @deffn Command keyboard-quit
1951 This function signals the @code{quit} condition with @code{(signal 'quit
1952 nil)}. This is the same thing that quitting does. (See @code{signal}
1956 You can specify a character other than @kbd{C-g} to use for quitting.
1957 See the function @code{set-input-mode} in @ref{Terminal Input}.
1959 @node Prefix Command Arguments
1960 @section Prefix Command Arguments
1961 @cindex prefix argument
1962 @cindex raw prefix argument
1963 @cindex numeric prefix argument
1965 Most Emacs commands can use a @dfn{prefix argument}, a number
1966 specified before the command itself. (Don't confuse prefix arguments
1967 with prefix keys.) The prefix argument is at all times represented by a
1968 value, which may be @code{nil}, meaning there is currently no prefix
1969 argument. Each command may use the prefix argument or ignore it.
1971 There are two representations of the prefix argument: @dfn{raw} and
1972 @dfn{numeric}. The editor command loop uses the raw representation
1973 internally, and so do the Lisp variables that store the information, but
1974 commands can request either representation.
1976 Here are the possible values of a raw prefix argument:
1980 @code{nil}, meaning there is no prefix argument. Its numeric value is
1981 1, but numerous commands make a distinction between @code{nil} and the
1985 An integer, which stands for itself.
1988 A list of one element, which is an integer. This form of prefix
1989 argument results from one or a succession of @kbd{C-u}'s with no
1990 digits. The numeric value is the integer in the list, but some
1991 commands make a distinction between such a list and an integer alone.
1994 The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was
1995 typed, without following digits. The equivalent numeric value is
1996 @minus{}1, but some commands make a distinction between the integer
1997 @minus{}1 and the symbol @code{-}.
2000 We illustrate these possibilities by calling the following function with
2005 (defun display-prefix (arg)
2006 "Display the value of the raw prefix arg."
2013 Here are the results of calling @code{display-prefix} with various
2014 raw prefix arguments:
2017 M-x display-prefix @print{} nil
2019 C-u M-x display-prefix @print{} (4)
2021 C-u C-u M-x display-prefix @print{} (16)
2023 C-u 3 M-x display-prefix @print{} 3
2025 M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
2027 C-u - M-x display-prefix @print{} -
2029 M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
2031 C-u - 7 M-x display-prefix @print{} -7
2033 M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
2036 Emacs uses two variables to store the prefix argument:
2037 @code{prefix-arg} and @code{current-prefix-arg}. Commands such as
2038 @code{universal-argument} that set up prefix arguments for other
2039 commands store them in @code{prefix-arg}. In contrast,
2040 @code{current-prefix-arg} conveys the prefix argument to the current
2041 command, so setting it has no effect on the prefix arguments for future
2044 Normally, commands specify which representation to use for the prefix
2045 argument, either numeric or raw, in the @code{interactive} declaration.
2046 (@xref{Using Interactive}.) Alternatively, functions may look at the
2047 value of the prefix argument directly in the variable
2048 @code{current-prefix-arg}, but this is less clean.
2050 @defun prefix-numeric-value arg
2051 This function returns the numeric meaning of a valid raw prefix argument
2052 value, @var{arg}. The argument may be a symbol, a number, or a list.
2053 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
2054 value @minus{}1 is returned; if it is a number, that number is returned;
2055 if it is a list, the @sc{car} of that list (which should be a number) is
2059 @defvar current-prefix-arg
2060 This variable holds the raw prefix argument for the @emph{current}
2061 command. Commands may examine it directly, but the usual way to access
2062 it is with @code{(interactive "P")}.
2066 The value of this variable is the raw prefix argument for the
2067 @emph{next} editing command. Commands that specify prefix arguments for
2068 the following command work by setting this variable.
2071 Do not call the functions @code{universal-argument},
2072 @code{digit-argument}, or @code{negative-argument} unless you intend to
2073 let the user enter the prefix argument for the @emph{next} command.
2075 @deffn Command universal-argument
2076 This command reads input and specifies a prefix argument for the
2077 following command. Don't call this command yourself unless you know
2081 @deffn Command digit-argument arg
2082 This command adds to the prefix argument for the following command. The
2083 argument @var{arg} is the raw prefix argument as it was before this
2084 command; it is used to compute the updated prefix argument. Don't call
2085 this command yourself unless you know what you are doing.
2088 @deffn Command negative-argument arg
2089 This command adds to the numeric argument for the next command. The
2090 argument @var{arg} is the raw prefix argument as it was before this
2091 command; its value is negated to form the new prefix argument. Don't
2092 call this command yourself unless you know what you are doing.
2095 @node Recursive Editing
2096 @section Recursive Editing
2097 @cindex recursive command loop
2098 @cindex recursive editing level
2099 @cindex command loop, recursive
2101 The Emacs command loop is entered automatically when Emacs starts up.
2102 This top-level invocation of the command loop never exits; it keeps
2103 running as long as Emacs does. Lisp programs can also invoke the
2104 command loop. Since this makes more than one activation of the command
2105 loop, we call it @dfn{recursive editing}. A recursive editing level has
2106 the effect of suspending whatever command invoked it and permitting the
2107 user to do arbitrary editing before resuming that command.
2109 The commands available during recursive editing are the same ones
2110 available in the top-level editing loop and defined in the keymaps.
2111 Only a few special commands exit the recursive editing level; the others
2112 return to the recursive editing level when they finish. (The special
2113 commands for exiting are always available, but they do nothing when
2114 recursive editing is not in progress.)
2116 All command loops, including recursive ones, set up all-purpose error
2117 handlers so that an error in a command run from the command loop will
2120 @cindex minibuffer input
2121 Minibuffer input is a special kind of recursive editing. It has a few
2122 special wrinkles, such as enabling display of the minibuffer and the
2123 minibuffer window, but fewer than you might suppose. Certain keys
2124 behave differently in the minibuffer, but that is only because of the
2125 minibuffer's local map; if you switch windows, you get the usual Emacs
2128 @cindex @code{throw} example
2130 @cindex exit recursive editing
2132 To invoke a recursive editing level, call the function
2133 @code{recursive-edit}. This function contains the command loop; it also
2134 contains a call to @code{catch} with tag @code{exit}, which makes it
2135 possible to exit the recursive editing level by throwing to @code{exit}
2136 (@pxref{Catch and Throw}). If you throw a value other than @code{t},
2137 then @code{recursive-edit} returns normally to the function that called
2138 it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
2139 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
2140 control returns to the command loop one level up. This is called
2141 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
2143 Most applications should not use recursive editing, except as part of
2144 using the minibuffer. Usually it is more convenient for the user if you
2145 change the major mode of the current buffer temporarily to a special
2146 major mode, which should have a command to go back to the previous mode.
2147 (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
2148 give the user different text to edit ``recursively'', create and select
2149 a new buffer in a special mode. In this mode, define a command to
2150 complete the processing and go back to the previous buffer. (The
2151 @kbd{m} command in Rmail does this.)
2153 Recursive edits are useful in debugging. You can insert a call to
2154 @code{debug} into a function definition as a sort of breakpoint, so that
2155 you can look around when the function gets there. @code{debug} invokes
2156 a recursive edit but also provides the other features of the debugger.
2158 Recursive editing levels are also used when you type @kbd{C-r} in
2159 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
2161 @defun recursive-edit
2162 @cindex suspend evaluation
2163 This function invokes the editor command loop. It is called
2164 automatically by the initialization of Emacs, to let the user begin
2165 editing. When called from a Lisp program, it enters a recursive editing
2168 In the following example, the function @code{simple-rec} first
2169 advances point one word, then enters a recursive edit, printing out a
2170 message in the echo area. The user can then do any editing desired, and
2171 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
2174 (defun simple-rec ()
2176 (message "Recursive edit in progress")
2179 @result{} simple-rec
2185 @deffn Command exit-recursive-edit
2186 This function exits from the innermost recursive edit (including
2187 minibuffer input). Its definition is effectively @code{(throw 'exit
2191 @deffn Command abort-recursive-edit
2192 This function aborts the command that requested the innermost recursive
2193 edit (including minibuffer input), by signaling @code{quit}
2194 after exiting the recursive edit. Its definition is effectively
2195 @code{(throw 'exit t)}. @xref{Quitting}.
2198 @deffn Command top-level
2199 This function exits all recursive editing levels; it does not return a
2200 value, as it jumps completely out of any computation directly back to
2201 the main command loop.
2204 @defun recursion-depth
2205 This function returns the current depth of recursive edits. When no
2206 recursive edit is active, it returns 0.
2209 @node Disabling Commands
2210 @section Disabling Commands
2211 @cindex disabled command
2213 @dfn{Disabling a command} marks the command as requiring user
2214 confirmation before it can be executed. Disabling is used for commands
2215 which might be confusing to beginning users, to prevent them from using
2216 the commands by accident.
2219 The low-level mechanism for disabling a command is to put a
2220 non-@code{nil} @code{disabled} property on the Lisp symbol for the
2221 command. These properties are normally set up by the user's
2222 @file{.emacs} file with Lisp expressions such as this:
2225 (put 'upcase-region 'disabled t)
2229 For a few commands, these properties are present by default and may be
2230 removed by the @file{.emacs} file.
2232 If the value of the @code{disabled} property is a string, the message
2233 saying the command is disabled includes that string. For example:
2236 (put 'delete-region 'disabled
2237 "Text deleted this way cannot be yanked back!\n")
2240 @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on
2241 what happens when a disabled command is invoked interactively.
2242 Disabling a command has no effect on calling it as a function from Lisp
2245 @deffn Command enable-command command
2246 Allow @var{command} to be executed without special confirmation from now
2247 on, and (if the user confirms) alter the user's @file{.emacs} file so
2248 that this will apply to future sessions.
2251 @deffn Command disable-command command
2252 Require special confirmation to execute @var{command} from now on, and
2253 (if the user confirms) alter the user's @file{.emacs} file so that this
2254 will apply to future sessions.
2257 @defvar disabled-command-hook
2258 This normal hook is run instead of a disabled command, when the user
2259 invokes the disabled command interactively. The hook functions can use
2260 @code{this-command-keys} to determine what the user typed to run the
2261 command, and thus find the command itself. @xref{Hooks}.
2263 By default, @code{disabled-command-hook} contains a function that asks
2264 the user whether to proceed.
2267 @node Command History
2268 @section Command History
2269 @cindex command history
2270 @cindex complex command
2271 @cindex history of commands
2273 The command loop keeps a history of the complex commands that have
2274 been executed, to make it convenient to repeat these commands. A
2275 @dfn{complex command} is one for which the interactive argument reading
2276 uses the minibuffer. This includes any @kbd{M-x} command, any
2277 @kbd{M-ESC} command, and any command whose @code{interactive}
2278 specification reads an argument from the minibuffer. Explicit use of
2279 the minibuffer during the execution of the command itself does not cause
2280 the command to be considered complex.
2282 @defvar command-history
2283 This variable's value is a list of recent complex commands, each
2284 represented as a form to evaluate. It continues to accumulate all
2285 complex commands for the duration of the editing session, but all but
2286 the first (most recent) thirty elements are deleted when a garbage
2287 collection takes place (@pxref{Garbage Collection}).
2292 @result{} ((switch-to-buffer "chistory.texi")
2293 (describe-key "^X^[")
2294 (visit-tags-table "~/emacs/src/")
2295 (find-tag "repeat-complex-command"))
2300 This history list is actually a special case of minibuffer history
2301 (@pxref{Minibuffer History}), with one special twist: the elements are
2302 expressions rather than strings.
2304 There are a number of commands devoted to the editing and recall of
2305 previous commands. The commands @code{repeat-complex-command}, and
2306 @code{list-command-history} are described in the user manual
2307 (@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the
2308 minibuffer, the history commands used are the same ones available in any
2311 @node Keyboard Macros
2312 @section Keyboard Macros
2313 @cindex keyboard macros
2315 A @dfn{keyboard macro} is a canned sequence of input events that can
2316 be considered a command and made the definition of a key. The Lisp
2317 representation of a keyboard macro is a string or vector containing the
2318 events. Don't confuse keyboard macros with Lisp macros
2321 @defun execute-kbd-macro macro &optional count
2322 This function executes @var{macro} as a sequence of events. If
2323 @var{macro} is a string or vector, then the events in it are executed
2324 exactly as if they had been input by the user. The sequence is
2325 @emph{not} expected to be a single key sequence; normally a keyboard
2326 macro definition consists of several key sequences concatenated.
2328 If @var{macro} is a symbol, then its function definition is used in
2329 place of @var{macro}. If that is another symbol, this process repeats.
2330 Eventually the result should be a string or vector. If the result is
2331 not a symbol, string, or vector, an error is signaled.
2333 The argument @var{count} is a repeat count; @var{macro} is executed that
2334 many times. If @var{count} is omitted or @code{nil}, @var{macro} is
2335 executed once. If it is 0, @var{macro} is executed over and over until it
2336 encounters an error or a failing search.
2339 @defvar last-kbd-macro
2340 This variable is the definition of the most recently defined keyboard
2341 macro. Its value is a string or vector, or @code{nil}.
2344 @defvar executing-macro
2345 This variable contains the string or vector that defines the keyboard
2346 macro that is currently executing. It is @code{nil} if no macro is
2347 currently executing. A command can test this variable to behave
2348 differently when run from an executing macro. Do not set this variable
2352 @defvar defining-kbd-macro
2353 This variable indicates whether a keyboard macro is being defined. A
2354 command can test this variable to behave differently while a macro is
2355 being defined. The commands @code{start-kbd-macro} and
2356 @code{end-kbd-macro} set this variable---do not set it yourself.