(emacs-version): Check for `gtk' feature before `x-toolkit' feature.
[emacs.git] / lispref / commands.texi
blob5a38179996f243169d5bf8ee668cc0d1ab3ad85d
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
4 @c   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
8 @chapter Command Loop
9 @cindex editor command loop
10 @cindex 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.
17 @menu
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.
34 @end menu
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
64 function argument.
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{Hooks}.
78 @end defvar
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} describes the command that just ran, and
85 @code{last-command} describes the command before that.  @xref{Hooks}.
86 @end defvar
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
95 command does.
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.
110 @menu
111 * Using Interactive::     General rules for @code{interactive}.
112 * Interactive Codes::     The standard letter-codes for reading arguments
113                              in various ways.
114 * Interactive Examples::  Examples of how to read interactive arguments.
115 @end menu
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 commands'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
134 effect.
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
142 argument.
143 @end defspec
145 There are three possibilities for the argument @var{arg-descriptor}:
147 @itemize @bullet
148 @item
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
151 or more arguments.
153 @item
154 It may be a Lisp expression that is not a string; then it should be a
155 form that is evaluated to get a list of arguments to pass to the
156 command.
157 @cindex argument evaluation form
159 If this expression reads keyboard input (this includes using the
160 minibuffer), keep in mind that the integer value of point or the mark
161 before reading input may be incorrect after reading input.  This is
162 because the current buffer may be receiving subprocess output;
163 if subprocess output arrives while the command is waiting for input,
164 it could relocate point and the mark.
166 Here's an example of what @emph{not} to do:
168 @smallexample
169 (interactive
170  (list (region-beginning) (region-end)
171        (read-string "Foo: " nil 'my-history)))
172 @end smallexample
174 @noindent
175 Here's how to avoid the problem, by examining point and the mark only
176 after reading the keyboard input:
178 @smallexample
179 (interactive
180  (let ((string (read-string "Foo: " nil 'my-history)))
181    (list (region-beginning) (region-end) string)))
182 @end smallexample
184 @item
185 @cindex argument prompt
186 It may be a string; then its contents should consist of a code character
187 followed by a prompt (which some code characters use and some ignore).
188 The prompt ends either with the end of the string or with a newline.
189 Here is a simple example:
191 @smallexample
192 (interactive "bFrobnicate buffer: ")
193 @end smallexample
195 @noindent
196 The code letter @samp{b} says to read the name of an existing buffer,
197 with completion.  The buffer name is the sole argument passed to the
198 command.  The rest of the string is a prompt.
200 If there is a newline character in the string, it terminates the prompt.
201 If the string does not end there, then the rest of the string should
202 contain another code character and prompt, specifying another argument.
203 You can specify any number of arguments in this way.
205 @c Emacs 19 feature
206 The prompt string can use @samp{%} to include previous argument values
207 (starting with the first argument) in the prompt.  This is done using
208 @code{format} (@pxref{Formatting Strings}).  For example, here is how
209 you could read the name of an existing buffer followed by a new name to
210 give to that buffer:
212 @smallexample
213 @group
214 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
215 @end group
216 @end smallexample
218 @cindex @samp{*} in @code{interactive}
219 @cindex read-only buffers in interactive
220 If the first character in the string is @samp{*}, then an error is
221 signaled if the buffer is read-only.
223 @cindex @samp{@@} in @code{interactive}
224 @c Emacs 19 feature
225 If the first character in the string is @samp{@@}, and if the key
226 sequence used to invoke the command includes any mouse events, then
227 the window associated with the first of those events is selected
228 before the command is run.
230 You can use @samp{*} and @samp{@@} together; the order does not matter.
231 Actual reading of arguments is controlled by the rest of the prompt
232 string (starting with the first character that is not @samp{*} or
233 @samp{@@}).
234 @end itemize
236 @cindex examining the @code{interactive} form
237 @defun interactive-form function
238 This function returns the @code{interactive} form of @var{function}.  If
239 @var{function} is a command (@pxref{Interactive Call}), the value is a
240 list of the form @code{(interactive @var{spec})}, where @var{spec} is
241 the descriptor specification used by the command's @code{interactive}
242 form to compute the function's arguments.  If @var{function} is not a
243 command, @code{interactive-form} returns @code{nil}.
244 @end defun
246 @node Interactive Codes
247 @comment  node-name,  next,  previous,  up
248 @subsection Code Characters for @code{interactive}
249 @cindex interactive code description
250 @cindex description for interactive codes
251 @cindex codes, interactive, description of
252 @cindex characters for interactive codes
254   The code character descriptions below contain a number of key words,
255 defined here as follows:
257 @table @b
258 @item Completion
259 @cindex interactive completion
260 Provide completion.  @key{TAB}, @key{SPC}, and @key{RET} perform name
261 completion because the argument is read using @code{completing-read}
262 (@pxref{Completion}).  @kbd{?} displays a list of possible completions.
264 @item Existing
265 Require the name of an existing object.  An invalid name is not
266 accepted; the commands to exit the minibuffer do not exit if the current
267 input is not valid.
269 @item Default
270 @cindex default argument string
271 A default value of some sort is used if the user enters no text in the
272 minibuffer.  The default depends on the code character.
274 @item No I/O
275 This code letter computes an argument without reading any input.
276 Therefore, it does not use a prompt string, and any prompt string you
277 supply is ignored.
279 Even though the code letter doesn't use a prompt string, you must follow
280 it with a newline if it is not the last code character in the string.
282 @item Prompt
283 A prompt immediately follows the code character.  The prompt ends either
284 with the end of the string or with a newline.
286 @item Special
287 This code character is meaningful only at the beginning of the
288 interactive string, and it does not look for a prompt or a newline.
289 It is a single, isolated character.
290 @end table
292 @cindex reading interactive arguments
293   Here are the code character descriptions for use with @code{interactive}:
295 @table @samp
296 @item *
297 Signal an error if the current buffer is read-only.  Special.
299 @item @@
300 Select the window mentioned in the first mouse event in the key
301 sequence that invoked this command.  Special.
303 @item a
304 A function name (i.e., a symbol satisfying @code{fboundp}).  Existing,
305 Completion, Prompt.
307 @item b
308 The name of an existing buffer.  By default, uses the name of the
309 current buffer (@pxref{Buffers}).  Existing, Completion, Default,
310 Prompt.
312 @item B
313 A buffer name.  The buffer need not exist.  By default, uses the name of
314 a recently used buffer other than the current buffer.  Completion,
315 Default, Prompt.
317 @item c
318 A character.  The cursor does not move into the echo area.  Prompt.
320 @item C
321 A command name (i.e., a symbol satisfying @code{commandp}).  Existing,
322 Completion, Prompt.
324 @item d
325 @cindex position argument
326 The position of point, as an integer (@pxref{Point}).  No I/O.
328 @item D
329 A directory name.  The default is the current default directory of the
330 current buffer, @code{default-directory} (@pxref{File Name Expansion}).
331 Existing, Completion, Default, Prompt.
333 @item e
334 The first or next mouse event in the key sequence that invoked the command.
335 More precisely, @samp{e} gets events that are lists, so you can look at
336 the data in the lists.  @xref{Input Events}.  No I/O.
338 You can use @samp{e} more than once in a single command's interactive
339 specification.  If the key sequence that invoked the command has
340 @var{n} events that are lists, the @var{n}th @samp{e} provides the
341 @var{n}th such event.  Events that are not lists, such as function keys
342 and @acronym{ASCII} characters, do not count where @samp{e} is concerned.
344 @item f
345 A file name of an existing file (@pxref{File Names}).  The default
346 directory is @code{default-directory}.  Existing, Completion, Default,
347 Prompt.
349 @item F
350 A file name.  The file need not exist.  Completion, Default, Prompt.
352 @item i
353 An irrelevant argument.  This code always supplies @code{nil} as
354 the argument's value.  No I/O.
356 @item k
357 A key sequence (@pxref{Keymap Terminology}).  This keeps reading events
358 until a command (or undefined command) is found in the current key
359 maps.  The key sequence argument is represented as a string or vector.
360 The cursor does not move into the echo area.  Prompt.
362 This kind of input is used by commands such as @code{describe-key} and
363 @code{global-set-key}.
365 @item K
366 A key sequence, whose definition you intend to change.  This works like
367 @samp{k}, except that it suppresses, for the last input event in the key
368 sequence, the conversions that are normally used (when necessary) to
369 convert an undefined key into a defined one.
371 @item m
372 @cindex marker argument
373 The position of the mark, as an integer.  No I/O.
375 @item M
376 Arbitrary text, read in the minibuffer using the current buffer's input
377 method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
378 Emacs Manual}).  Prompt.
380 @item n
381 A number read with the minibuffer.  If the input is not a number, the
382 user is asked to try again.  The prefix argument, if any, is not used.
383 Prompt.
385 @item N
386 @cindex raw prefix argument usage
387 The numeric prefix argument; but if there is no prefix argument, read a
388 number as with @kbd{n}.  Requires a number.  @xref{Prefix Command
389 Arguments}.  Prompt.
391 @item p
392 @cindex numeric prefix argument usage
393 The numeric prefix argument.  (Note that this @samp{p} is lower case.)
394 No I/O.
396 @item P
397 The raw prefix argument.  (Note that this @samp{P} is upper case.)  No
398 I/O.
400 @item r
401 @cindex region argument
402 Point and the mark, as two numeric arguments, smallest first.  This is
403 the only code letter that specifies two successive arguments rather than
404 one.  No I/O.
406 @item s
407 Arbitrary text, read in the minibuffer and returned as a string
408 (@pxref{Text from Minibuffer}).  Terminate the input with either
409 @kbd{C-j} or @key{RET}.  (@kbd{C-q} may be used to include either of
410 these characters in the input.)  Prompt.
412 @item S
413 An interned symbol whose name is read in the minibuffer.  Any whitespace
414 character terminates the input.  (Use @kbd{C-q} to include whitespace in
415 the string.)  Other characters that normally terminate a symbol (e.g.,
416 parentheses and brackets) do not do so here.  Prompt.
418 @item v
419 A variable declared to be a user option (i.e., satisfying the predicate
420 @code{user-variable-p}).  @xref{High-Level Completion}.  Existing,
421 Completion, Prompt.
423 @item x
424 A Lisp object, specified with its read syntax, terminated with a
425 @kbd{C-j} or @key{RET}.  The object is not evaluated.  @xref{Object from
426 Minibuffer}.  Prompt.
428 @item X
429 @cindex evaluated expression argument
430 A Lisp form is read as with @kbd{x}, but then evaluated so that its
431 value becomes the argument for the command.  Prompt.
433 @item z
434 A coding system name (a symbol).  If the user enters null input, the
435 argument value is @code{nil}.  @xref{Coding Systems}.  Completion,
436 Existing, Prompt.
438 @item Z
439 A coding system name (a symbol)---but only if this command has a prefix
440 argument.  With no prefix argument, @samp{Z} provides @code{nil} as the
441 argument value.  Completion, Existing, Prompt.
442 @end table
444 @node Interactive Examples
445 @comment  node-name,  next,  previous,  up
446 @subsection Examples of Using @code{interactive}
447 @cindex examples of using @code{interactive}
448 @cindex @code{interactive}, examples of using
450   Here are some examples of @code{interactive}:
452 @example
453 @group
454 (defun foo1 ()              ; @r{@code{foo1} takes no arguments,}
455     (interactive)           ;   @r{just moves forward two words.}
456     (forward-word 2))
457      @result{} foo1
458 @end group
460 @group
461 (defun foo2 (n)             ; @r{@code{foo2} takes one argument,}
462     (interactive "p")       ;   @r{which is the numeric prefix.}
463     (forward-word (* 2 n)))
464      @result{} foo2
465 @end group
467 @group
468 (defun foo3 (n)             ; @r{@code{foo3} takes one argument,}
469     (interactive "nCount:") ;   @r{which is read with the Minibuffer.}
470     (forward-word (* 2 n)))
471      @result{} foo3
472 @end group
474 @group
475 (defun three-b (b1 b2 b3)
476   "Select three existing buffers.
477 Put them into three windows, selecting the last one."
478 @end group
479     (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
480     (delete-other-windows)
481     (split-window (selected-window) 8)
482     (switch-to-buffer b1)
483     (other-window 1)
484     (split-window (selected-window) 8)
485     (switch-to-buffer b2)
486     (other-window 1)
487     (switch-to-buffer b3))
488      @result{} three-b
489 @group
490 (three-b "*scratch*" "declarations.texi" "*mail*")
491      @result{} nil
492 @end group
493 @end example
495 @node Interactive Call
496 @section Interactive Call
497 @cindex interactive call
499   After the command loop has translated a key sequence into a command it
500 invokes that command using the function @code{command-execute}.  If the
501 command is a function, @code{command-execute} calls
502 @code{call-interactively}, which reads the arguments and calls the
503 command.  You can also call these functions yourself.
505 @defun commandp object &optional for-call-interactively
506 Returns @code{t} if @var{object} is suitable for calling interactively;
507 that is, if @var{object} is a command.  Otherwise, returns @code{nil}.
509 The interactively callable objects include strings and vectors (treated
510 as keyboard macros), lambda expressions that contain a top-level call to
511 @code{interactive}, byte-code function objects made from such lambda
512 expressions, autoload objects that are declared as interactive
513 (non-@code{nil} fourth argument to @code{autoload}), and some of the
514 primitive functions.
516 A symbol satisfies @code{commandp} if its function definition
517 satisfies @code{commandp}.  Keys and keymaps are not commands.
518 Rather, they are used to look up commands (@pxref{Keymaps}).
520 If @var{for-call-interactively} is non-@code{nil}, then
521 @code{commandp} returns @code{t} only for objects that
522 @code{call-interactively} could call---thus, not for keyboard macros.
524 See @code{documentation} in @ref{Accessing Documentation}, for a
525 realistic example of using @code{commandp}.
526 @end defun
528 @defun call-interactively command &optional record-flag keys
529 This function calls the interactively callable function @var{command},
530 reading arguments according to its interactive calling specifications.
531 An error is signaled if @var{command} is not a function or if it cannot
532 be called interactively (i.e., is not a command).  Note that keyboard
533 macros (strings and vectors) are not accepted, even though they are
534 considered commands, because they are not functions.
536 @cindex record command history
537 If @var{record-flag} is non-@code{nil}, then this command and its
538 arguments are unconditionally added to the list @code{command-history}.
539 Otherwise, the command is added only if it uses the minibuffer to read
540 an argument.  @xref{Command History}.
542 The argument @var{keys}, if given, specifies the sequence of events to
543 supply if the command inquires which events were used to invoke it.
544 @end defun
546 @defun command-execute command &optional record-flag keys special
547 @cindex keyboard macro execution
548 This function executes @var{command}.  The argument @var{command} must
549 satisfy the @code{commandp} predicate; i.e., it must be an interactively
550 callable function or a keyboard macro.
552 A string or vector as @var{command} is executed with
553 @code{execute-kbd-macro}.  A function is passed to
554 @code{call-interactively}, along with the optional @var{record-flag}.
556 A symbol is handled by using its function definition in its place.  A
557 symbol with an @code{autoload} definition counts as a command if it was
558 declared to stand for an interactively callable function.  Such a
559 definition is handled by loading the specified library and then
560 rechecking the definition of the symbol.
562 The argument @var{keys}, if given, specifies the sequence of events to
563 supply if the command inquires which events were used to invoke it.
565 The argument @var{special}, if given, means to ignore the prefix
566 argument and not clear it.  This is used for executing special events
567 (@pxref{Special Events}).
568 @end defun
570 @deffn Command execute-extended-command prefix-argument
571 @cindex read command name
572 This function reads a command name from the minibuffer using
573 @code{completing-read} (@pxref{Completion}).  Then it uses
574 @code{command-execute} to call the specified command.  Whatever that
575 command returns becomes the value of @code{execute-extended-command}.
577 @cindex execute with prefix argument
578 If the command asks for a prefix argument, it receives the value
579 @var{prefix-argument}.  If @code{execute-extended-command} is called
580 interactively, the current raw prefix argument is used for
581 @var{prefix-argument}, and thus passed on to whatever command is run.
583 @c !!! Should this be @kindex?
584 @cindex @kbd{M-x}
585 @code{execute-extended-command} is the normal definition of @kbd{M-x},
586 so it uses the string @w{@samp{M-x }} as a prompt.  (It would be better
587 to take the prompt from the events used to invoke
588 @code{execute-extended-command}, but that is painful to implement.)  A
589 description of the value of the prefix argument, if any, also becomes
590 part of the prompt.
592 @example
593 @group
594 (execute-extended-command 1)
595 ---------- Buffer: Minibuffer ----------
596 1 M-x forward-word RET
597 ---------- Buffer: Minibuffer ----------
598      @result{} t
599 @end group
600 @end example
601 @end deffn
603 @defun interactive-p
604 This function returns @code{t} if the containing function (the one whose
605 code includes the call to @code{interactive-p}) was called
606 interactively, with the function @code{call-interactively}.  (It makes
607 no difference whether @code{call-interactively} was called from Lisp or
608 directly from the editor command loop.)  If the containing function was
609 called by Lisp evaluation (or with @code{apply} or @code{funcall}), then
610 it was not called interactively.
611 @end defun
613   The most common use of @code{interactive-p} is for deciding whether to
614 print an informative message.  As a special exception,
615 @code{interactive-p} returns @code{nil} whenever a keyboard macro is
616 being run.  This is to suppress the informative messages and speed
617 execution of the macro.
619   For example:
621 @example
622 @group
623 (defun foo ()
624   (interactive)
625   (when (interactive-p)
626     (message "foo")))
627      @result{} foo
628 @end group
630 @group
631 (defun bar ()
632   (interactive)
633   (setq foobar (list (foo) (interactive-p))))
634      @result{} bar
635 @end group
637 @group
638 ;; @r{Type @kbd{M-x foo}.}
639      @print{} foo
640 @end group
642 @group
643 ;; @r{Type @kbd{M-x bar}.}
644 ;; @r{This does not print anything.}
645 @end group
647 @group
648 foobar
649      @result{} (nil t)
650 @end group
651 @end example
653   The other way to do this sort of job is to make the command take an
654 argument @code{print-message} which should be non-@code{nil} in an
655 interactive call, and use the @code{interactive} spec to make sure it is
656 non-@code{nil}.  Here's how:
658 @example
659 (defun foo (&optional print-message)
660   (interactive "p")
661   (when print-message
662     (message "foo")))
663 @end example
665 @noindent
666 Defined in this way, the function does display the message when
667 called from a keyboard macro.
669   The numeric prefix argument, provided by @samp{p}, is never @code{nil}.
671 @node Command Loop Info
672 @comment  node-name,  next,  previous,  up
673 @section Information from the Command Loop
675 The editor command loop sets several Lisp variables to keep status
676 records for itself and for commands that are run.
678 @defvar last-command
679 This variable records the name of the previous command executed by the
680 command loop (the one before the current command).  Normally the value
681 is a symbol with a function definition, but this is not guaranteed.
683 The value is copied from @code{this-command} when a command returns to
684 the command loop, except when the command has specified a prefix
685 argument for the following command.
687 This variable is always local to the current terminal and cannot be
688 buffer-local.  @xref{Multiple Displays}.
689 @end defvar
691 @defvar real-last-command
692 This variable is set up by Emacs just like @code{last-command},
693 but never altered by Lisp programs.
694 @end defvar
696 @defvar this-command
697 @cindex current command
698 This variable records the name of the command now being executed by
699 the editor command loop.  Like @code{last-command}, it is normally a symbol
700 with a function definition.
702 The command loop sets this variable just before running a command, and
703 copies its value into @code{last-command} when the command finishes
704 (unless the command specified a prefix argument for the following
705 command).
707 @cindex kill command repetition
708 Some commands set this variable during their execution, as a flag for
709 whatever command runs next.  In particular, the functions for killing text
710 set @code{this-command} to @code{kill-region} so that any kill commands
711 immediately following will know to append the killed text to the
712 previous kill.
713 @end defvar
715 If you do not want a particular command to be recognized as the previous
716 command in the case where it got an error, you must code that command to
717 prevent this.  One way is to set @code{this-command} to @code{t} at the
718 beginning of the command, and set @code{this-command} back to its proper
719 value at the end, like this:
721 @example
722 (defun foo (args@dots{})
723   (interactive @dots{})
724   (let ((old-this-command this-command))
725     (setq this-command t)
726     @r{@dots{}do the work@dots{}}
727     (setq this-command old-this-command)))
728 @end example
730 @noindent
731 We do not bind @code{this-command} with @code{let} because that would
732 restore the old value in case of error---a feature of @code{let} which
733 in this case does precisely what we want to avoid.
735 @defvar this-original-command
736 This has the same value as @code{this-command} except when command
737 remapping occurs (@pxref{Remapping Commands}).  In that case,
738 @code{this-command} gives the command actually run (the result of
739 remapping), and @code{this-original-command} gives the command that
740 was specified to run but remapped into another command.
741 @end defvar
743 @defun this-command-keys
744 This function returns a string or vector containing the key sequence
745 that invoked the present command, plus any previous commands that
746 generated the prefix argument for this command.  The value is a string
747 if all those events were characters.  @xref{Input Events}.
749 @example
750 @group
751 (this-command-keys)
752 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
753      @result{} "^U^X^E"
754 @end group
755 @end example
756 @end defun
758 @defun this-command-keys-vector
759 Like @code{this-command-keys}, except that it always returns the events
760 in a vector, so you don't need to deal with the complexities of storing
761 input events in a string (@pxref{Strings of Events}).
762 @end defun
764 @tindex clear-this-command-keys
765 @defun clear-this-command-keys
766 This function empties out the table of events for
767 @code{this-command-keys} to return, and also empties the records that
768 the function @code{recent-keys} (@pxref{Recording Input}) will
769 subsequently return.  This is useful after reading a password, to
770 prevent the password from echoing inadvertently as part of the next
771 command in certain cases.
772 @end defun
774 @defvar last-nonmenu-event
775 This variable holds the last input event read as part of a key sequence,
776 not counting events resulting from mouse menus.
778 One use of this variable is for telling @code{x-popup-menu} where to pop
779 up a menu.  It is also used internally by @code{y-or-n-p}
780 (@pxref{Yes-or-No Queries}).
781 @end defvar
783 @defvar last-command-event
784 @defvarx last-command-char
785 This variable is set to the last input event that was read by the
786 command loop as part of a command.  The principal use of this variable
787 is in @code{self-insert-command}, which uses it to decide which
788 character to insert.
790 @example
791 @group
792 last-command-event
793 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
794      @result{} 5
795 @end group
796 @end example
798 @noindent
799 The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
801 The alias @code{last-command-char} exists for compatibility with
802 Emacs version 18.
803 @end defvar
805 @c Emacs 19 feature
806 @defvar last-event-frame
807 This variable records which frame the last input event was directed to.
808 Usually this is the frame that was selected when the event was
809 generated, but if that frame has redirected input focus to another
810 frame, the value is the frame to which the event was redirected.
811 @xref{Input Focus}.
812 @end defvar
814 @node Adjusting Point
815 @section Adjusting Point After Commands
817   It is not easy to display a value of point in the middle of a sequence
818 of text that has the @code{display} or @code{composition} property.  So
819 after a command finishes and returns to the command loop, if point is
820 within such a sequence, the command loop normally moves point to the
821 edge of the sequence.
823   A command can inhibit this feature by setting the variable
824 @code{disable-point-adjustment}:
826 @defvar disable-point-adjustment
827 @tindex disable-point-adjustment
828 If this variable is non-@code{nil} when a command returns to the command
829 loop, then the command loop does not check for text properties such as
830 @code{display} and @code{composition}, and does not move point out of
831 sequences that have these properties.
833 The command loop sets this variable to @code{nil} before each command,
834 so if a command sets it, the effect applies only to that command.
835 @end defvar
837 @defvar global-disable-point-adjustment
838 @tindex global-disable-point-adjustment
839 If you set this variable to a non-@code{nil} value, the feature of
840 moving point out of these sequences is completely turned off.
841 @end defvar
843 @node Input Events
844 @section Input Events
845 @cindex events
846 @cindex input events
848 The Emacs command loop reads a sequence of @dfn{input events} that
849 represent keyboard or mouse activity.  The events for keyboard activity
850 are characters or symbols; mouse events are always lists.  This section
851 describes the representation and meaning of input events in detail.
853 @defun eventp object
854 This function returns non-@code{nil} if @var{object} is an input event
855 or event type.
857 Note that any symbol might be used as an event or an event type.
858 @code{eventp} cannot distinguish whether a symbol is intended by Lisp
859 code to be used as an event.  Instead, it distinguishes whether the
860 symbol has actually been used in an event that has been read as input in
861 the current Emacs session.  If a symbol has not yet been so used,
862 @code{eventp} returns @code{nil}.
863 @end defun
865 @menu
866 * Keyboard Events::             Ordinary characters--keys with symbols on them.
867 * Function Keys::               Function keys--keys with names, not symbols.
868 * Mouse Events::                Overview of mouse events.
869 * Click Events::                Pushing and releasing a mouse button.
870 * Drag Events::                 Moving the mouse before releasing the button.
871 * Button-Down Events::          A button was pushed and not yet released.
872 * Repeat Events::               Double and triple click (or drag, or down).
873 * Motion Events::               Just moving the mouse, not pushing a button.
874 * Focus Events::                Moving the mouse between frames.
875 * Misc Events::                 Other events window systems can generate.
876 * Event Examples::              Examples of the lists for mouse events.
877 * Classifying Events::          Finding the modifier keys in an event symbol.
878                                 Event types.
879 * Accessing Events::            Functions to extract info from events.
880 * Strings of Events::           Special considerations for putting
881                                   keyboard character events in a string.
882 @end menu
884 @node Keyboard Events
885 @subsection Keyboard Events
887 There are two kinds of input you can get from the keyboard: ordinary
888 keys, and function keys.  Ordinary keys correspond to characters; the
889 events they generate are represented in Lisp as characters.  The event
890 type of a character event is the character itself (an integer); see
891 @ref{Classifying Events}.
893 @cindex modifier bits (of input character)
894 @cindex basic code (of input character)
895 An input character event consists of a @dfn{basic code} between 0 and
896 524287, plus any or all of these @dfn{modifier bits}:
898 @table @asis
899 @item meta
901 @tex
902 @math{2^{27}}
903 @end tex
904 @ifnottex
905 2**27
906 @end ifnottex
907 bit in the character code indicates a character
908 typed with the meta key held down.
910 @item control
912 @tex
913 @math{2^{26}}
914 @end tex
915 @ifnottex
916 2**26
917 @end ifnottex
918 bit in the character code indicates a non-@acronym{ASCII}
919 control character.
921 @sc{ascii} control characters such as @kbd{C-a} have special basic
922 codes of their own, so Emacs needs no special bit to indicate them.
923 Thus, the code for @kbd{C-a} is just 1.
925 But if you type a control combination not in @acronym{ASCII}, such as
926 @kbd{%} with the control key, the numeric value you get is the code
927 for @kbd{%} plus
928 @tex
929 @math{2^{26}}
930 @end tex
931 @ifnottex
932 2**26
933 @end ifnottex
934 (assuming the terminal supports non-@acronym{ASCII}
935 control characters).
937 @item shift
939 @tex
940 @math{2^{25}}
941 @end tex
942 @ifnottex
943 2**25
944 @end ifnottex
945 bit in the character code indicates an @acronym{ASCII} control
946 character typed with the shift key held down.
948 For letters, the basic code itself indicates upper versus lower case;
949 for digits and punctuation, the shift key selects an entirely different
950 character with a different basic code.  In order to keep within the
951 @acronym{ASCII} character set whenever possible, Emacs avoids using the
952 @tex
953 @math{2^{25}}
954 @end tex
955 @ifnottex
956 2**25
957 @end ifnottex
958 bit for those characters.
960 However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
961 @kbd{C-a}, so Emacs uses the
962 @tex
963 @math{2^{25}}
964 @end tex
965 @ifnottex
966 2**25
967 @end ifnottex
968 bit in @kbd{C-A} and not in
969 @kbd{C-a}.
971 @item hyper
973 @tex
974 @math{2^{24}}
975 @end tex
976 @ifnottex
977 2**24
978 @end ifnottex
979 bit in the character code indicates a character
980 typed with the hyper key held down.
982 @item super
984 @tex
985 @math{2^{23}}
986 @end tex
987 @ifnottex
988 2**23
989 @end ifnottex
990 bit in the character code indicates a character
991 typed with the super key held down.
993 @item alt
995 @tex
996 @math{2^{22}}
997 @end tex
998 @ifnottex
999 2**22
1000 @end ifnottex
1001 bit in the character code indicates a character typed with
1002 the alt key held down.  (On some terminals, the key labeled @key{ALT}
1003 is actually the meta key.)
1004 @end table
1006   It is best to avoid mentioning specific bit numbers in your program.
1007 To test the modifier bits of a character, use the function
1008 @code{event-modifiers} (@pxref{Classifying Events}).  When making key
1009 bindings, you can use the read syntax for characters with modifier bits
1010 (@samp{\C-}, @samp{\M-}, and so on).  For making key bindings with
1011 @code{define-key}, you can use lists such as @code{(control hyper ?x)} to
1012 specify the characters (@pxref{Changing Key Bindings}).  The function
1013 @code{event-convert-list} converts such a list into an event type
1014 (@pxref{Classifying Events}).
1016 @node Function Keys
1017 @subsection Function Keys
1019 @cindex function keys
1020 Most keyboards also have @dfn{function keys}---keys that have names or
1021 symbols that are not characters.  Function keys are represented in Emacs
1022 Lisp as symbols; the symbol's name is the function key's label, in lower
1023 case.  For example, pressing a key labeled @key{F1} places the symbol
1024 @code{f1} in the input stream.
1026 The event type of a function key event is the event symbol itself.
1027 @xref{Classifying Events}.
1029 Here are a few special cases in the symbol-naming convention for
1030 function keys:
1032 @table @asis
1033 @item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
1034 These keys correspond to common @acronym{ASCII} control characters that have
1035 special keys on most keyboards.
1037 In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character.  If the
1038 terminal can distinguish between them, Emacs conveys the distinction to
1039 Lisp programs by representing the former as the integer 9, and the
1040 latter as the symbol @code{tab}.
1042 Most of the time, it's not useful to distinguish the two.  So normally
1043 @code{function-key-map} (@pxref{Translating Input}) is set up to map
1044 @code{tab} into 9.  Thus, a key binding for character code 9 (the
1045 character @kbd{C-i}) also applies to @code{tab}.  Likewise for the other
1046 symbols in this group.  The function @code{read-char} likewise converts
1047 these events into characters.
1049 In @acronym{ASCII}, @key{BS} is really @kbd{C-h}.  But @code{backspace}
1050 converts into the character code 127 (@key{DEL}), not into code 8
1051 (@key{BS}).  This is what most users prefer.
1053 @item @code{left}, @code{up}, @code{right}, @code{down}
1054 Cursor arrow keys
1055 @item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
1056 Keypad keys (to the right of the regular keyboard).
1057 @item @code{kp-0}, @code{kp-1}, @dots{}
1058 Keypad keys with digits.
1059 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
1060 Keypad PF keys.
1061 @item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
1062 Keypad arrow keys.  Emacs normally translates these into the
1063 corresponding non-keypad keys @code{home}, @code{left}, @dots{}
1064 @item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
1065 Additional keypad duplicates of keys ordinarily found elsewhere.  Emacs
1066 normally translates these into the like-named non-keypad keys.
1067 @end table
1069 You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
1070 @key{META}, @key{SHIFT}, and @key{SUPER} with function keys.  The way to
1071 represent them is with prefixes in the symbol name:
1073 @table @samp
1074 @item A-
1075 The alt modifier.
1076 @item C-
1077 The control modifier.
1078 @item H-
1079 The hyper modifier.
1080 @item M-
1081 The meta modifier.
1082 @item S-
1083 The shift modifier.
1084 @item s-
1085 The super modifier.
1086 @end table
1088 Thus, the symbol for the key @key{F3} with @key{META} held down is
1089 @code{M-f3}.  When you use more than one prefix, we recommend you
1090 write them in alphabetical order; but the order does not matter in
1091 arguments to the key-binding lookup and modification functions.
1093 @node Mouse Events
1094 @subsection Mouse Events
1096 Emacs supports four kinds of mouse events: click events, drag events,
1097 button-down events, and motion events.  All mouse events are represented
1098 as lists.  The @sc{car} of the list is the event type; this says which
1099 mouse button was involved, and which modifier keys were used with it.
1100 The event type can also distinguish double or triple button presses
1101 (@pxref{Repeat Events}).  The rest of the list elements give position
1102 and time information.
1104 For key lookup, only the event type matters: two events of the same type
1105 necessarily run the same command.  The command can access the full
1106 values of these events using the @samp{e} interactive code.
1107 @xref{Interactive Codes}.
1109 A key sequence that starts with a mouse event is read using the keymaps
1110 of the buffer in the window that the mouse was in, not the current
1111 buffer.  This does not imply that clicking in a window selects that
1112 window or its buffer---that is entirely under the control of the command
1113 binding of the key sequence.
1115 @node Click Events
1116 @subsection Click Events
1117 @cindex click event
1118 @cindex mouse click event
1120 When the user presses a mouse button and releases it at the same
1121 location, that generates a @dfn{click} event.  All mouse click event
1122 share the same format:
1124 @example
1125 (@var{event-type} @var{position} @var{click-count})
1126 @end example
1128 @table @asis
1129 @item @var{event-type}
1130 This is a symbol that indicates which mouse button was used.  It is
1131 one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the
1132 buttons are numbered left to right.
1134 You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-},
1135 @samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift
1136 and super, just as you would with function keys.
1138 This symbol also serves as the event type of the event.  Key bindings
1139 describe events by their types; thus, if there is a key binding for
1140 @code{mouse-1}, that binding would apply to all events whose
1141 @var{event-type} is @code{mouse-1}.
1143 @item @var{position}
1144 This is the position where the mouse click occurred.  The actual
1145 format of @var{position} depends on what part of a window was clicked
1146 on.  The various formats are described below.
1148 @item @var{click-count}
1149 This is the number of rapid repeated presses so far of the same mouse
1150 button.  @xref{Repeat Events}.
1151 @end table
1153 For mouse click events in the text area, mode line, header line, or in
1154 the marginal areas, @var{position} has this form:
1156 @example
1157 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
1158  @var{object} @var{text-pos} (@var{col} . @var{row}) 
1159  @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
1160 @end example
1162 @table @asis
1163 @item @var{window}
1164 This is the window in which the click occurred.
1166 @item @var{pos-or-area}
1167 This is the buffer position of the character clicked on in the text
1168 area, or if clicked outside the text area, it is the window area in
1169 which the click occurred.  It is one of the symbols @code{mode-line},
1170 @code{header-line}, @code{vertical-line}, @code{left-margin},
1171 @code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
1173 @item @var{x}, @var{y}
1174 These are the pixel-denominated coordinates of the click, relative to
1175 the top left corner of @var{window}, which is @code{(0 . 0)}.
1176 For the mode or header line, @var{y} does not have meaningful data.
1177 For the vertical line, @var{x} does not have meaningful data.
1179 @item @var{timestamp}
1180 This is the time at which the event occurred, in milliseconds.
1182 @item @var{object}
1183 This is the object on which the click occurred.  It is either
1184 @code{nil} if there is no string property, or it has the form
1185 (@var{string} . @var{string-pos}) when there is a string-type text
1186 property at the click position.
1188 @item @var{string}
1189 This is the string on which the click occurred, including any
1190 properties.
1192 @item @var{string-pos}
1193 This is the position in the string on which the click occurred,
1194 relevant if properties at the click need to be looked up.
1196 @item @var{text-pos}
1197 For clicks on a marginal area or on a fringe, this is the buffer
1198 position of the first visible character in the corresponding line in
1199 the window.  For other events, it is the current buffer position in
1200 the window.
1202 @item @var{col}, @var{row}
1203 These are the actual coordinates of the glyph under the @var{x},
1204 @var{y} position, possibly padded with default character width
1205 glyphs if @var{x} is beyond the last glyph on the line.
1207 @item @var{image}
1208 This is the image object on which the click occurred.  It is either
1209 @code{nil} if there is no image at the position clicked on, or it is
1210 an image object as returned by @code{find-image} if click was in an image.
1212 @item @var{dx}, @var{dy}
1213 These are the pixel-denominated coordinates of the click, relative to
1214 the top left corner of @var{object}, which is @code{(0 . 0)}.  If
1215 @var{object} is @code{nil}, the coordinates are relative to the top
1216 left corner of the character glyph clicked on.
1217 @end table
1219 For mouse clicks on a scroll-bar, @var{position} has this form:
1221 @example
1222 (@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
1223 @end example
1225 @table @asis
1226 @item @var{window}
1227 This is the window whose scroll-bar was clicked on.
1229 @item @var{area}
1230 This is the scroll bar where the click occurred.  It is one of the
1231 symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.
1233 @item @var{portion}
1234 This is the distance of the click from the top or left end of
1235 the scroll bar.
1237 @item @var{whole}
1238 This is the length of the entire scroll bar.
1240 @item @var{timestamp}
1241 This is the time at which the event occurred, in milliseconds.
1243 @item @var{part}
1244 This is the part of the scroll-bar which was clicked on.  It is one
1245 of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
1246 @code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
1247 @end table
1249 In one special case, @var{buffer-pos} is a list containing a symbol (one
1250 of the symbols listed above) instead of just the symbol.  This happens
1251 after the imaginary prefix keys for the event are inserted into the
1252 input stream.  @xref{Key Sequence Input}.
1254 @node Drag Events
1255 @subsection Drag Events
1256 @cindex drag event
1257 @cindex mouse drag event
1259 With Emacs, you can have a drag event without even changing your
1260 clothes.  A @dfn{drag event} happens every time the user presses a mouse
1261 button and then moves the mouse to a different character position before
1262 releasing the button.  Like all mouse events, drag events are
1263 represented in Lisp as lists.  The lists record both the starting mouse
1264 position and the final position, like this:
1266 @example
1267 (@var{event-type}
1268  (@var{window1} @var{buffer-pos1} (@var{x1} . @var{y1}) @var{timestamp1})
1269  (@var{window2} @var{buffer-pos2} (@var{x2} . @var{y2}) @var{timestamp2})
1270  @var{click-count})
1271 @end example
1273 For a drag event, the name of the symbol @var{event-type} contains the
1274 prefix @samp{drag-}.  For example, dragging the mouse with button 2 held
1275 down generates a @code{drag-mouse-2} event.  The second and third
1276 elements of the event give the starting and ending position of the drag.
1277 Aside from that, the data have the same meanings as in a click event
1278 (@pxref{Click Events}).  You can access the second element of any mouse
1279 event in the same way, with no need to distinguish drag events from
1280 others.
1282 The @samp{drag-} prefix follows the modifier key prefixes such as
1283 @samp{C-} and @samp{M-}.
1285 If @code{read-key-sequence} receives a drag event that has no key
1286 binding, and the corresponding click event does have a binding, it
1287 changes the drag event into a click event at the drag's starting
1288 position.  This means that you don't have to distinguish between click
1289 and drag events unless you want to.
1291 @node Button-Down Events
1292 @subsection Button-Down Events
1293 @cindex button-down event
1295 Click and drag events happen when the user releases a mouse button.
1296 They cannot happen earlier, because there is no way to distinguish a
1297 click from a drag until the button is released.
1299 If you want to take action as soon as a button is pressed, you need to
1300 handle @dfn{button-down} events.@footnote{Button-down is the
1301 conservative antithesis of drag.}  These occur as soon as a button is
1302 pressed.  They are represented by lists that look exactly like click
1303 events (@pxref{Click Events}), except that the @var{event-type} symbol
1304 name contains the prefix @samp{down-}.  The @samp{down-} prefix follows
1305 modifier key prefixes such as @samp{C-} and @samp{M-}.
1307 The function @code{read-key-sequence} ignores any button-down events
1308 that don't have command bindings; therefore, the Emacs command loop
1309 ignores them too.  This means that you need not worry about defining
1310 button-down events unless you want them to do something.  The usual
1311 reason to define a button-down event is so that you can track mouse
1312 motion (by reading motion events) until the button is released.
1313 @xref{Motion Events}.
1315 @node Repeat Events
1316 @subsection Repeat Events
1317 @cindex repeat events
1318 @cindex double-click events
1319 @cindex triple-click events
1320 @cindex mouse events, repeated
1322 If you press the same mouse button more than once in quick succession
1323 without moving the mouse, Emacs generates special @dfn{repeat} mouse
1324 events for the second and subsequent presses.
1326 The most common repeat events are @dfn{double-click} events.  Emacs
1327 generates a double-click event when you click a button twice; the event
1328 happens when you release the button (as is normal for all click
1329 events).
1331 The event type of a double-click event contains the prefix
1332 @samp{double-}.  Thus, a double click on the second mouse button with
1333 @key{meta} held down comes to the Lisp program as
1334 @code{M-double-mouse-2}.  If a double-click event has no binding, the
1335 binding of the corresponding ordinary click event is used to execute
1336 it.  Thus, you need not pay attention to the double click feature
1337 unless you really want to.
1339 When the user performs a double click, Emacs generates first an ordinary
1340 click event, and then a double-click event.  Therefore, you must design
1341 the command binding of the double click event to assume that the
1342 single-click command has already run.  It must produce the desired
1343 results of a double click, starting from the results of a single click.
1345 This is convenient, if the meaning of a double click somehow ``builds
1346 on'' the meaning of a single click---which is recommended user interface
1347 design practice for double clicks.
1349 If you click a button, then press it down again and start moving the
1350 mouse with the button held down, then you get a @dfn{double-drag} event
1351 when you ultimately release the button.  Its event type contains
1352 @samp{double-drag} instead of just @samp{drag}.  If a double-drag event
1353 has no binding, Emacs looks for an alternate binding as if the event
1354 were an ordinary drag.
1356 Before the double-click or double-drag event, Emacs generates a
1357 @dfn{double-down} event when the user presses the button down for the
1358 second time.  Its event type contains @samp{double-down} instead of just
1359 @samp{down}.  If a double-down event has no binding, Emacs looks for an
1360 alternate binding as if the event were an ordinary button-down event.
1361 If it finds no binding that way either, the double-down event is
1362 ignored.
1364 To summarize, when you click a button and then press it again right
1365 away, Emacs generates a down event and a click event for the first
1366 click, a double-down event when you press the button again, and finally
1367 either a double-click or a double-drag event.
1369 If you click a button twice and then press it again, all in quick
1370 succession, Emacs generates a @dfn{triple-down} event, followed by
1371 either a @dfn{triple-click} or a @dfn{triple-drag}.  The event types of
1372 these events contain @samp{triple} instead of @samp{double}.  If any
1373 triple event has no binding, Emacs uses the binding that it would use
1374 for the corresponding double event.
1376 If you click a button three or more times and then press it again, the
1377 events for the presses beyond the third are all triple events.  Emacs
1378 does not have separate event types for quadruple, quintuple, etc.@:
1379 events.  However, you can look at the event list to find out precisely
1380 how many times the button was pressed.
1382 @defun event-click-count event
1383 This function returns the number of consecutive button presses that led
1384 up to @var{event}.  If @var{event} is a double-down, double-click or
1385 double-drag event, the value is 2.  If @var{event} is a triple event,
1386 the value is 3 or greater.  If @var{event} is an ordinary mouse event
1387 (not a repeat event), the value is 1.
1388 @end defun
1390 @defvar double-click-fuzz
1391 To generate repeat events, successive mouse button presses must be at
1392 approximately the same screen position.  The value of
1393 @code{double-click-fuzz} specifies the maximum number of pixels the
1394 mouse may be moved between two successive clicks to make a
1395 double-click.
1396 @end defvar
1398 @defvar double-click-time
1399 To generate repeat events, the number of milliseconds between
1400 successive button presses must be less than the value of
1401 @code{double-click-time}.  Setting @code{double-click-time} to
1402 @code{nil} disables multi-click detection entirely.  Setting it to
1403 @code{t} removes the time limit; Emacs then detects multi-clicks by
1404 position only.
1405 @end defvar
1407 @node Motion Events
1408 @subsection Motion Events
1409 @cindex motion event
1410 @cindex mouse motion events
1412 Emacs sometimes generates @dfn{mouse motion} events to describe motion
1413 of the mouse without any button activity.  Mouse motion events are
1414 represented by lists that look like this:
1416 @example
1417 (mouse-movement (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}))
1418 @end example
1420 The second element of the list describes the current position of the
1421 mouse, just as in a click event (@pxref{Click Events}).
1423 The special form @code{track-mouse} enables generation of motion events
1424 within its body.  Outside of @code{track-mouse} forms, Emacs does not
1425 generate events for mere motion of the mouse, and these events do not
1426 appear.  @xref{Mouse Tracking}.
1428 @node Focus Events
1429 @subsection Focus Events
1430 @cindex focus event
1432 Window systems provide general ways for the user to control which window
1433 gets keyboard input.  This choice of window is called the @dfn{focus}.
1434 When the user does something to switch between Emacs frames, that
1435 generates a @dfn{focus event}.  The normal definition of a focus event,
1436 in the global keymap, is to select a new frame within Emacs, as the user
1437 would expect.  @xref{Input Focus}.
1439 Focus events are represented in Lisp as lists that look like this:
1441 @example
1442 (switch-frame @var{new-frame})
1443 @end example
1445 @noindent
1446 where @var{new-frame} is the frame switched to.
1448 Most X window managers are set up so that just moving the mouse into a
1449 window is enough to set the focus there.  Emacs appears to do this,
1450 because it changes the cursor to solid in the new frame.  However, there
1451 is no need for the Lisp program to know about the focus change until
1452 some other kind of input arrives.  So Emacs generates a focus event only
1453 when the user actually types a keyboard key or presses a mouse button in
1454 the new frame; just moving the mouse between frames does not generate a
1455 focus event.
1457 A focus event in the middle of a key sequence would garble the
1458 sequence.  So Emacs never generates a focus event in the middle of a key
1459 sequence.  If the user changes focus in the middle of a key
1460 sequence---that is, after a prefix key---then Emacs reorders the events
1461 so that the focus event comes either before or after the multi-event key
1462 sequence, and not within it.
1464 @node Misc Events
1465 @subsection Miscellaneous Window System Events
1467 A few other event types represent occurrences within the window system.
1469 @table @code
1470 @cindex @code{delete-frame} event
1471 @item (delete-frame (@var{frame}))
1472 This kind of event indicates that the user gave the window manager
1473 a command to delete a particular window, which happens to be an Emacs frame.
1475 The standard definition of the @code{delete-frame} event is to delete @var{frame}.
1477 @cindex @code{iconify-frame} event
1478 @item (iconify-frame (@var{frame}))
1479 This kind of event indicates that the user iconified @var{frame} using
1480 the window manager.  Its standard definition is @code{ignore}; since the
1481 frame has already been iconified, Emacs has no work to do.  The purpose
1482 of this event type is so that you can keep track of such events if you
1483 want to.
1485 @cindex @code{make-frame-visible} event
1486 @item (make-frame-visible (@var{frame}))
1487 This kind of event indicates that the user deiconified @var{frame} using
1488 the window manager.  Its standard definition is @code{ignore}; since the
1489 frame has already been made visible, Emacs has no work to do.
1491 @cindex @code{mouse-wheel} event
1492 @item (mouse-wheel @var{position} @var{delta})
1493 This kind of event is generated by moving a wheel on a mouse (such as
1494 the MS Intellimouse).  Its effect is typically a kind of scroll or zoom.
1496 The element @var{delta} describes the amount and direction of the wheel
1497 rotation.  Its absolute value is the number of increments by which the
1498 wheel was rotated.  A negative @var{delta} indicates that the wheel was
1499 rotated backwards, towards the user, and a positive @var{delta}
1500 indicates that the wheel was rotated forward, away from the user.
1502 The element @var{position} is a list describing the position of the
1503 event, in the same format as used in a mouse-click event.
1505 This kind of event is generated only on some kinds of systems.
1507 @cindex @code{drag-n-drop} event
1508 @item (drag-n-drop @var{position} @var{files})
1509 This kind of event is generated when a group of files is
1510 selected in an application outside of Emacs, and then dragged and
1511 dropped onto an Emacs frame.
1513 The element @var{position} is a list describing the position of the
1514 event, in the same format as used in a mouse-click event, and
1515 @var{files} is the list of file names that were dragged and dropped.
1516 The usual way to handle this event is by visiting these files.
1518 This kind of event is generated, at present, only on some kinds of
1519 systems.
1520 @end table
1522   If one of these events arrives in the middle of a key sequence---that
1523 is, after a prefix key---then Emacs reorders the events so that this
1524 event comes either before or after the multi-event key sequence, not
1525 within it.
1527 @node Event Examples
1528 @subsection Event Examples
1530 If the user presses and releases the left mouse button over the same
1531 location, that generates a sequence of events like this:
1533 @smallexample
1534 (down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
1535 (mouse-1      (#<window 18 on NEWS> 2613 (0 . 38) -864180))
1536 @end smallexample
1538 While holding the control key down, the user might hold down the
1539 second mouse button, and drag the mouse from one line to the next.
1540 That produces two events, as shown here:
1542 @smallexample
1543 (C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
1544 (C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
1545                 (#<window 18 on NEWS> 3510 (0 . 28) -729648))
1546 @end smallexample
1548 While holding down the meta and shift keys, the user might press the
1549 second mouse button on the window's mode line, and then drag the mouse
1550 into another window.  That produces a pair of events like these:
1552 @smallexample
1553 (M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
1554 (M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
1555                   (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
1556                    -453816))
1557 @end smallexample
1559 @node Classifying Events
1560 @subsection Classifying Events
1561 @cindex event type
1563   Every event has an @dfn{event type}, which classifies the event for
1564 key binding purposes.  For a keyboard event, the event type equals the
1565 event value; thus, the event type for a character is the character, and
1566 the event type for a function key symbol is the symbol itself.  For
1567 events that are lists, the event type is the symbol in the @sc{car} of
1568 the list.  Thus, the event type is always a symbol or a character.
1570   Two events of the same type are equivalent where key bindings are
1571 concerned; thus, they always run the same command.  That does not
1572 necessarily mean they do the same things, however, as some commands look
1573 at the whole event to decide what to do.  For example, some commands use
1574 the location of a mouse event to decide where in the buffer to act.
1576   Sometimes broader classifications of events are useful.  For example,
1577 you might want to ask whether an event involved the @key{META} key,
1578 regardless of which other key or mouse button was used.
1580   The functions @code{event-modifiers} and @code{event-basic-type} are
1581 provided to get such information conveniently.
1583 @defun event-modifiers event
1584 This function returns a list of the modifiers that @var{event} has.  The
1585 modifiers are symbols; they include @code{shift}, @code{control},
1586 @code{meta}, @code{alt}, @code{hyper} and @code{super}.  In addition,
1587 the modifiers list of a mouse event symbol always contains one of
1588 @code{click}, @code{drag}, and @code{down}.
1590 The argument @var{event} may be an entire event object, or just an event
1591 type.
1593 Here are some examples:
1595 @example
1596 (event-modifiers ?a)
1597      @result{} nil
1598 (event-modifiers ?\C-a)
1599      @result{} (control)
1600 (event-modifiers ?\C-%)
1601      @result{} (control)
1602 (event-modifiers ?\C-\S-a)
1603      @result{} (control shift)
1604 (event-modifiers 'f5)
1605      @result{} nil
1606 (event-modifiers 's-f5)
1607      @result{} (super)
1608 (event-modifiers 'M-S-f5)
1609      @result{} (meta shift)
1610 (event-modifiers 'mouse-1)
1611      @result{} (click)
1612 (event-modifiers 'down-mouse-1)
1613      @result{} (down)
1614 @end example
1616 The modifiers list for a click event explicitly contains @code{click},
1617 but the event symbol name itself does not contain @samp{click}.
1618 @end defun
1620 @defun event-basic-type event
1621 This function returns the key or mouse button that @var{event}
1622 describes, with all modifiers removed.  For example:
1624 @example
1625 (event-basic-type ?a)
1626      @result{} 97
1627 (event-basic-type ?A)
1628      @result{} 97
1629 (event-basic-type ?\C-a)
1630      @result{} 97
1631 (event-basic-type ?\C-\S-a)
1632      @result{} 97
1633 (event-basic-type 'f5)
1634      @result{} f5
1635 (event-basic-type 's-f5)
1636      @result{} f5
1637 (event-basic-type 'M-S-f5)
1638      @result{} f5
1639 (event-basic-type 'down-mouse-1)
1640      @result{} mouse-1
1641 @end example
1642 @end defun
1644 @defun mouse-movement-p object
1645 This function returns non-@code{nil} if @var{object} is a mouse movement
1646 event.
1647 @end defun
1649 @defun event-convert-list list
1650 This function converts a list of modifier names and a basic event type
1651 to an event type which specifies all of them.  For example,
1653 @example
1654 (event-convert-list '(control ?a))
1655      @result{} 1
1656 (event-convert-list '(control meta ?a))
1657      @result{} -134217727
1658 (event-convert-list '(control super f1))
1659      @result{} C-s-f1
1660 @end example
1661 @end defun
1663 @node Accessing Events
1664 @subsection Accessing Events
1665 @cindex mouse events, accessing the data
1666 @cindex accessing data of mouse events
1668   This section describes convenient functions for accessing the data in
1669 a mouse button or motion event.
1671   These two functions return the starting or ending position of a
1672 mouse-button event, as a list of this form:
1674 @example
1675 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
1676  @var{object} @var{text-pos} (@var{col} . @var{row})
1677  @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
1678 @end example
1680 @defun event-start event
1681 This returns the starting position of @var{event}.
1683 If @var{event} is a click or button-down event, this returns the
1684 location of the event.  If @var{event} is a drag event, this returns the
1685 drag's starting position.
1686 @end defun
1688 @defun event-end event
1689 This returns the ending position of @var{event}.
1691 If @var{event} is a drag event, this returns the position where the user
1692 released the mouse button.  If @var{event} is a click or button-down
1693 event, the value is actually the starting position, which is the only
1694 position such events have.
1695 @end defun
1697 @cindex mouse position list, accessing
1698   These seven functions take a position list as described above, and
1699 return various parts of it.
1701 @defun posn-window position
1702 Return the window that @var{position} is in.
1703 @end defun
1705 @defun posn-area position
1706 Return the window area recorded in @var{position}.  It returns @code{nil}
1707 when the event occurred in the text area of the window; otherwise, it
1708 is a symbol identifying the area in which the the event occurred.
1709 @end defun
1711 @defun posn-point position
1712 Return the buffer position in @var{position}.  When the event occurred
1713 in the text area of the window, in a marginal area, or on a fringe,
1714 this is an integer specifying a buffer position.  Otherwise, the value
1715 is undefined.
1716 @end defun
1718 @defun posn-x-y position
1719 Return the pixel-based x and y coordinates in @var{position}, as a cons
1720 cell @code{(@var{x} . @var{y})}.
1721 @end defun
1723 @defun posn-col-row position
1724 Return the row and column (in units of frame default characters) of
1725 @var{position}, as a cons cell @code{(@var{col} . @var{row})}.  These
1726 are computed from the @var{x} and @var{y} values actually found in
1727 @var{position}.
1728 @end defun
1730 @defun posn-actual-col-row position
1731 Return the actual row and column in @var{position}, as a cons cell
1732 @code{(@var{col} . @var{row})}.  The values are the actual row number
1733 in the window, and the actual character number in that row.  Return
1734 @code{nil} if @var{position} does not include the actual positions; in that
1735 case, @code{posn-col-row} can be used to get approximate values.
1736 @end defun
1738 @defun posn-string position
1739 Return the string object in @var{position}, either @code{nil}, or a
1740 cons cell @code{(@var{string} . @var{string-pos})}.
1741 @end defun
1743 @defun posn-image position
1744 Return the image object in @var{position}, either @code{nil}, or an
1745 image @code{(image ...)}.
1746 @end defun
1748 @defun posn-object position
1749 Return the image or string object in @var{position}, either
1750 @code{nil}, an image @code{(image ...)}, or a cons cell
1751 @code{(@var{string} . @var{string-pos})}.
1752 @end defun
1754 @defun posn-object-x-y position
1755 Return the pixel-based x and y coordinates relative to the upper left
1756 corner of the object in @var{position} as a cons cell @code{(@var{dx}
1757 . @var{dy})}.  If the @var{position} is a buffer position, return the
1758 relative position in the character at that position.
1759 @end defun
1761 @defun posn-object-width-height position
1762 Return the pixel width and height of the object in @var{position} as a
1763 cons cell @code{(@var{width} . @var{height})}.  If the @var{position}
1764 is a buffer position, return the size of the character at that position.
1765 @end defun
1767 @cindex mouse event, timestamp
1768 @cindex timestamp of a mouse event
1769 @defun posn-timestamp
1770 Return the timestamp in @var{position}.  This is the time at which the
1771 event occurred, in milliseconds.
1772 @end defun
1774   These functions are useful for decoding scroll bar events.
1776 @defun scroll-bar-event-ratio event
1777 This function returns the fractional vertical position of a scroll bar
1778 event within the scroll bar.  The value is a cons cell
1779 @code{(@var{portion} . @var{whole})} containing two integers whose ratio
1780 is the fractional position.
1781 @end defun
1783 @defun scroll-bar-scale ratio total
1784 This function multiplies (in effect) @var{ratio} by @var{total},
1785 rounding the result to an integer.  The argument @var{ratio} is not a
1786 number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
1787 value returned by @code{scroll-bar-event-ratio}.
1789 This function is handy for scaling a position on a scroll bar into a
1790 buffer position.  Here's how to do that:
1792 @example
1793 (+ (point-min)
1794    (scroll-bar-scale
1795       (posn-x-y (event-start event))
1796       (- (point-max) (point-min))))
1797 @end example
1799 Recall that scroll bar events have two integers forming a ratio, in place
1800 of a pair of x and y coordinates.
1801 @end defun
1803 @node Strings of Events
1804 @subsection Putting Keyboard Events in Strings
1805 @cindex keyboard events in strings
1806 @cindex strings with keyboard events
1808   In most of the places where strings are used, we conceptualize the
1809 string as containing text characters---the same kind of characters found
1810 in buffers or files.  Occasionally Lisp programs use strings that
1811 conceptually contain keyboard characters; for example, they may be key
1812 sequences or keyboard macro definitions.  However, storing keyboard
1813 characters in a string is a complex matter, for reasons of historical
1814 compatibility, and it is not always possible.
1816   We recommend that new programs avoid dealing with these complexities
1817 by not storing keyboard events in strings.  Here is how to do that:
1819 @itemize @bullet
1820 @item
1821 Use vectors instead of strings for key sequences, when you plan to use
1822 them for anything other than as arguments to @code{lookup-key} and
1823 @code{define-key}.  For example, you can use
1824 @code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
1825 @code{this-command-keys-vector} instead of @code{this-command-keys}.
1827 @item
1828 Use vectors to write key sequence constants containing meta characters,
1829 even when passing them directly to @code{define-key}.
1831 @item
1832 When you have to look at the contents of a key sequence that might be a
1833 string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
1834 first, to convert it to a list.
1835 @end itemize
1837   The complexities stem from the modifier bits that keyboard input
1838 characters can include.  Aside from the Meta modifier, none of these
1839 modifier bits can be included in a string, and the Meta modifier is
1840 allowed only in special cases.
1842   The earliest GNU Emacs versions represented meta characters as codes
1843 in the range of 128 to 255.  At that time, the basic character codes
1844 ranged from 0 to 127, so all keyboard character codes did fit in a
1845 string.  Many Lisp programs used @samp{\M-} in string constants to stand
1846 for meta characters, especially in arguments to @code{define-key} and
1847 similar functions, and key sequences and sequences of events were always
1848 represented as strings.
1850   When we added support for larger basic character codes beyond 127, and
1851 additional modifier bits, we had to change the representation of meta
1852 characters.  Now the flag that represents the Meta modifier in a
1853 character is
1854 @tex
1855 @math{2^{27}}
1856 @end tex
1857 @ifnottex
1858 2**27
1859 @end ifnottex
1860 and such numbers cannot be included in a string.
1862   To support programs with @samp{\M-} in string constants, there are
1863 special rules for including certain meta characters in a string.
1864 Here are the rules for interpreting a string as a sequence of input
1865 characters:
1867 @itemize @bullet
1868 @item
1869 If the keyboard character value is in the range of 0 to 127, it can go
1870 in the string unchanged.
1872 @item
1873 The meta variants of those characters, with codes in the range of
1874 @tex
1875 @math{2^{27}}
1876 @end tex
1877 @ifnottex
1878 2**27
1879 @end ifnottex
1881 @tex
1882 @math{2^{27} + 127},
1883 @end tex
1884 @ifnottex
1885 2**27+127,
1886 @end ifnottex
1887 can also go in the string, but you must change their
1888 numeric values.  You must set the
1889 @tex
1890 @math{2^{7}}
1891 @end tex
1892 @ifnottex
1893 2**7
1894 @end ifnottex
1895 bit instead of the
1896 @tex
1897 @math{2^{27}}
1898 @end tex
1899 @ifnottex
1900 2**27
1901 @end ifnottex
1902 bit, resulting in a value between 128 and 255.  Only a unibyte string
1903 can include these codes.
1905 @item
1906 Non-@acronym{ASCII} characters above 256 can be included in a multibyte string.
1908 @item
1909 Other keyboard character events cannot fit in a string.  This includes
1910 keyboard events in the range of 128 to 255.
1911 @end itemize
1913   Functions such as @code{read-key-sequence} that construct strings of
1914 keyboard input characters follow these rules: they construct vectors
1915 instead of strings, when the events won't fit in a string.
1917   When you use the read syntax @samp{\M-} in a string, it produces a
1918 code in the range of 128 to 255---the same code that you get if you
1919 modify the corresponding keyboard event to put it in the string.  Thus,
1920 meta events in strings work consistently regardless of how they get into
1921 the strings.
1923   However, most programs would do well to avoid these issues by
1924 following the recommendations at the beginning of this section.
1926 @node Reading Input
1927 @section Reading Input
1929   The editor command loop reads key sequences using the function
1930 @code{read-key-sequence}, which uses @code{read-event}.  These and other
1931 functions for event input are also available for use in Lisp programs.
1932 See also @code{momentary-string-display} in @ref{Temporary Displays},
1933 and @code{sit-for} in @ref{Waiting}.  @xref{Terminal Input}, for
1934 functions and variables for controlling terminal input modes and
1935 debugging terminal input.  @xref{Translating Input}, for features you
1936 can use for translating or modifying input events while reading them.
1938   For higher-level input facilities, see @ref{Minibuffers}.
1940 @menu
1941 * Key Sequence Input::          How to read one key sequence.
1942 * Reading One Event::           How to read just one event.
1943 * Invoking the Input Method::   How reading an event uses the input method.
1944 * Quoted Character Input::      Asking the user to specify a character.
1945 * Event Input Misc::            How to reread or throw away input events.
1946 @end menu
1948 @node Key Sequence Input
1949 @subsection Key Sequence Input
1950 @cindex key sequence input
1952   The command loop reads input a key sequence at a time, by calling
1953 @code{read-key-sequence}.  Lisp programs can also call this function;
1954 for example, @code{describe-key} uses it to read the key to describe.
1956 @defun read-key-sequence prompt
1957 @cindex key sequence
1958 This function reads a key sequence and returns it as a string or
1959 vector.  It keeps reading events until it has accumulated a complete key
1960 sequence; that is, enough to specify a non-prefix command using the
1961 currently active keymaps.
1963 If the events are all characters and all can fit in a string, then
1964 @code{read-key-sequence} returns a string (@pxref{Strings of Events}).
1965 Otherwise, it returns a vector, since a vector can hold all kinds of
1966 events---characters, symbols, and lists.  The elements of the string or
1967 vector are the events in the key sequence.
1969 The argument @var{prompt} is either a string to be displayed in the echo
1970 area as a prompt, or @code{nil}, meaning not to display a prompt.
1972 In the example below, the prompt @samp{?} is displayed in the echo area,
1973 and the user types @kbd{C-x C-f}.
1975 @example
1976 (read-key-sequence "?")
1978 @group
1979 ---------- Echo Area ----------
1980 ?@kbd{C-x C-f}
1981 ---------- Echo Area ----------
1983      @result{} "^X^F"
1984 @end group
1985 @end example
1987 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
1988 typed while reading with this function works like any other character,
1989 and does not set @code{quit-flag}.  @xref{Quitting}.
1990 @end defun
1992 @defun read-key-sequence-vector prompt
1993 This is like @code{read-key-sequence} except that it always
1994 returns the key sequence as a vector, never as a string.
1995 @xref{Strings of Events}.
1996 @end defun
1998 @cindex upper case key sequence
1999 @cindex downcasing in @code{lookup-key}
2000 If an input character is an upper-case letter and has no key binding,
2001 but its lower-case equivalent has one, then @code{read-key-sequence}
2002 converts the character to lower case.  Note that @code{lookup-key} does
2003 not perform case conversion in this way.
2005 The function @code{read-key-sequence} also transforms some mouse events.
2006 It converts unbound drag events into click events, and discards unbound
2007 button-down events entirely.  It also reshuffles focus events and
2008 miscellaneous window events so that they never appear in a key sequence
2009 with any other events.
2011 @cindex @code{header-line} prefix key
2012 @cindex @code{mode-line} prefix key
2013 @cindex @code{vertical-line} prefix key
2014 @cindex @code{horizontal-scroll-bar} prefix key
2015 @cindex @code{vertical-scroll-bar} prefix key
2016 @cindex @code{menu-bar} prefix key
2017 @cindex mouse events, in special parts of frame
2018 When mouse events occur in special parts of a window, such as a mode
2019 line or a scroll bar, the event type shows nothing special---it is the
2020 same symbol that would normally represent that combination of mouse
2021 button and modifier keys.  The information about the window part is kept
2022 elsewhere in the event---in the coordinates.  But
2023 @code{read-key-sequence} translates this information into imaginary
2024 ``prefix keys'', all of which are symbols: @code{header-line},
2025 @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
2026 @code{vertical-line}, and @code{vertical-scroll-bar}.  You can define
2027 meanings for mouse clicks in special window parts by defining key
2028 sequences using these imaginary prefix keys.
2030 For example, if you call @code{read-key-sequence} and then click the
2031 mouse on the window's mode line, you get two events, like this:
2033 @example
2034 (read-key-sequence "Click on the mode line: ")
2035      @result{} [mode-line
2036          (mouse-1
2037           (#<window 6 on NEWS> mode-line
2038            (40 . 63) 5959987))]
2039 @end example
2041 @defvar num-input-keys
2042 @c Emacs 19 feature
2043 This variable's value is the number of key sequences processed so far in
2044 this Emacs session.  This includes key sequences read from the terminal
2045 and key sequences read from keyboard macros being executed.
2046 @end defvar
2048 @defvar num-nonmacro-input-events
2049 This variable holds the total number of input events received so far
2050 from the terminal---not counting those generated by keyboard macros.
2051 @end defvar
2053 @node Reading One Event
2054 @subsection Reading One Event
2055 @cindex reading a single event
2056 @cindex event, reading only one
2058   The lowest level functions for command input are those that read a
2059 single event.
2061 @defun read-event &optional prompt inherit-input-method
2062 This function reads and returns the next event of command input, waiting
2063 if necessary until an event is available.  Events can come directly from
2064 the user or from a keyboard macro.
2066 If the optional argument @var{prompt} is non-@code{nil}, it should be a
2067 string to display in the echo area as a prompt.  Otherwise,
2068 @code{read-event} does not display any message to indicate it is waiting
2069 for input; instead, it prompts by echoing: it displays descriptions of
2070 the events that led to or were read by the current command.  @xref{The
2071 Echo Area}.
2073 If @var{inherit-input-method} is non-@code{nil}, then the current input
2074 method (if any) is employed to make it possible to enter a
2075 non-@acronym{ASCII} character.  Otherwise, input method handling is disabled
2076 for reading this event.
2078 If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
2079 moves the cursor temporarily to the echo area, to the end of any message
2080 displayed there.  Otherwise @code{read-event} does not move the cursor.
2082 If @code{read-event} gets an event that is defined as a help character, in
2083 some cases @code{read-event} processes the event directly without
2084 returning.  @xref{Help Functions}.  Certain other events, called
2085 @dfn{special events}, are also processed directly within
2086 @code{read-event} (@pxref{Special Events}).
2088 Here is what happens if you call @code{read-event} and then press the
2089 right-arrow function key:
2091 @example
2092 @group
2093 (read-event)
2094      @result{} right
2095 @end group
2096 @end example
2097 @end defun
2099 @defun read-char &optional prompt inherit-input-method
2100 This function reads and returns a character of command input.  If the
2101 user generates an event which is not a character (i.e. a mouse click or
2102 function key event), @code{read-char} signals an error.  The arguments
2103 work as in @code{read-event}.
2105 In the first example, the user types the character @kbd{1} (@acronym{ASCII}
2106 code 49).  The second example shows a keyboard macro definition that
2107 calls @code{read-char} from the minibuffer using @code{eval-expression}.
2108 @code{read-char} reads the keyboard macro's very next character, which
2109 is @kbd{1}.  Then @code{eval-expression} displays its return value in
2110 the echo area.
2112 @example
2113 @group
2114 (read-char)
2115      @result{} 49
2116 @end group
2118 @group
2119 ;; @r{We assume here you use @kbd{M-:} to evaluate this.}
2120 (symbol-function 'foo)
2121      @result{} "^[:(read-char)^M1"
2122 @end group
2123 @group
2124 (execute-kbd-macro 'foo)
2125      @print{} 49
2126      @result{} nil
2127 @end group
2128 @end example
2129 @end defun
2131 @defun read-char-exclusive &optional prompt inherit-input-method
2132 This function reads and returns a character of command input.  If the
2133 user generates an event which is not a character,
2134 @code{read-char-exclusive} ignores it and reads another event, until it
2135 gets a character.  The arguments work as in @code{read-event}.
2136 @end defun
2138 @node Invoking the Input Method
2139 @subsection Invoking the Input Method
2141   The event-reading functions invoke the current input method, if any
2142 (@pxref{Input Methods}).  If the value of @code{input-method-function}
2143 is non-@code{nil}, it should be a function; when @code{read-event} reads
2144 a printing character (including @key{SPC}) with no modifier bits, it
2145 calls that function, passing the character as an argument.
2147 @defvar input-method-function
2148 If this is non-@code{nil}, its value specifies the current input method
2149 function.
2151 @strong{Warning:} don't bind this variable with @code{let}.  It is often
2152 buffer-local, and if you bind it around reading input (which is exactly
2153 when you @emph{would} bind it), switching buffers asynchronously while
2154 Emacs is waiting will cause the value to be restored in the wrong
2155 buffer.
2156 @end defvar
2158   The input method function should return a list of events which should
2159 be used as input.  (If the list is @code{nil}, that means there is no
2160 input, so @code{read-event} waits for another event.)  These events are
2161 processed before the events in @code{unread-command-events}
2162 (@pxref{Event Input Misc}).  Events
2163 returned by the input method function are not passed to the input method
2164 function again, even if they are printing characters with no modifier
2165 bits.
2167   If the input method function calls @code{read-event} or
2168 @code{read-key-sequence}, it should bind @code{input-method-function} to
2169 @code{nil} first, to prevent recursion.
2171   The input method function is not called when reading the second and
2172 subsequent events of a key sequence.  Thus, these characters are not
2173 subject to input method processing.  The input method function should
2174 test the values of @code{overriding-local-map} and
2175 @code{overriding-terminal-local-map}; if either of these variables is
2176 non-@code{nil}, the input method should put its argument into a list and
2177 return that list with no further processing.
2179 @node Quoted Character Input
2180 @subsection Quoted Character Input
2181 @cindex quoted character input
2183   You can use the function @code{read-quoted-char} to ask the user to
2184 specify a character, and allow the user to specify a control or meta
2185 character conveniently, either literally or as an octal character code.
2186 The command @code{quoted-insert} uses this function.
2188 @defun read-quoted-char &optional prompt
2189 @cindex octal character input
2190 @cindex control characters, reading
2191 @cindex nonprinting characters, reading
2192 This function is like @code{read-char}, except that if the first
2193 character read is an octal digit (0-7), it reads any number of octal
2194 digits (but stopping if a non-octal digit is found), and returns the
2195 character represented by that numeric character code.
2197 Quitting is suppressed when the first character is read, so that the
2198 user can enter a @kbd{C-g}.  @xref{Quitting}.
2200 If @var{prompt} is supplied, it specifies a string for prompting the
2201 user.  The prompt string is always displayed in the echo area, followed
2202 by a single @samp{-}.
2204 In the following example, the user types in the octal number 177 (which
2205 is 127 in decimal).
2207 @example
2208 (read-quoted-char "What character")
2210 @group
2211 ---------- Echo Area ----------
2212 What character-@kbd{177}
2213 ---------- Echo Area ----------
2215      @result{} 127
2216 @end group
2217 @end example
2218 @end defun
2220 @need 2000
2221 @node Event Input Misc
2222 @subsection Miscellaneous Event Input Features
2224 This section describes how to ``peek ahead'' at events without using
2225 them up, how to check for pending input, and how to discard pending
2226 input.  See also the function @code{read-passwd} (@pxref{Reading a
2227 Password}).
2229 @defvar unread-command-events
2230 @cindex next input
2231 @cindex peeking at input
2232 This variable holds a list of events waiting to be read as command
2233 input.  The events are used in the order they appear in the list, and
2234 removed one by one as they are used.
2236 The variable is needed because in some cases a function reads an event
2237 and then decides not to use it.  Storing the event in this variable
2238 causes it to be processed normally, by the command loop or by the
2239 functions to read command input.
2241 @cindex prefix argument unreading
2242 For example, the function that implements numeric prefix arguments reads
2243 any number of digits.  When it finds a non-digit event, it must unread
2244 the event so that it can be read normally by the command loop.
2245 Likewise, incremental search uses this feature to unread events with no
2246 special meaning in a search, because these events should exit the search
2247 and then execute normally.
2249 The reliable and easy way to extract events from a key sequence so as to
2250 put them in @code{unread-command-events} is to use
2251 @code{listify-key-sequence} (@pxref{Strings of Events}).
2253 Normally you add events to the front of this list, so that the events
2254 most recently unread will be reread first.
2255 @end defvar
2257 @defun listify-key-sequence key
2258 This function converts the string or vector @var{key} to a list of
2259 individual events, which you can put in @code{unread-command-events}.
2260 @end defun
2262 @defvar unread-command-char
2263 This variable holds a character to be read as command input.
2264 A value of -1 means ``empty''.
2266 This variable is mostly obsolete now that you can use
2267 @code{unread-command-events} instead; it exists only to support programs
2268 written for Emacs versions 18 and earlier.
2269 @end defvar
2271 @defun input-pending-p
2272 @cindex waiting for command key input
2273 This function determines whether any command input is currently
2274 available to be read.  It returns immediately, with value @code{t} if
2275 there is available input, @code{nil} otherwise.  On rare occasions it
2276 may return @code{t} when no input is available.
2277 @end defun
2279 @defvar last-input-event
2280 @defvarx last-input-char
2281 This variable records the last terminal input event read, whether
2282 as part of a command or explicitly by a Lisp program.
2284 In the example below, the Lisp program reads the character @kbd{1},
2285 @acronym{ASCII} code 49.  It becomes the value of @code{last-input-event},
2286 while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
2287 this expression) remains the value of @code{last-command-event}.
2289 @example
2290 @group
2291 (progn (print (read-char))
2292        (print last-command-event)
2293        last-input-event)
2294      @print{} 49
2295      @print{} 5
2296      @result{} 49
2297 @end group
2298 @end example
2300 The alias @code{last-input-char} exists for compatibility with
2301 Emacs version 18.
2302 @end defvar
2304 @defun discard-input
2305 @cindex flush input
2306 @cindex discard input
2307 @cindex terminate keyboard macro
2308 This function discards the contents of the terminal input buffer and
2309 cancels any keyboard macro that might be in the process of definition.
2310 It returns @code{nil}.
2312 In the following example, the user may type a number of characters right
2313 after starting the evaluation of the form.  After the @code{sleep-for}
2314 finishes sleeping, @code{discard-input} discards any characters typed
2315 during the sleep.
2317 @example
2318 (progn (sleep-for 2)
2319        (discard-input))
2320      @result{} nil
2321 @end example
2322 @end defun
2324 @node Special Events
2325 @section Special Events
2327 @cindex special events
2328 Special events are handled at a very low level---as soon as they are
2329 read.  The @code{read-event} function processes these events itself, and
2330 never returns them.
2332 Events that are handled in this way do not echo, they are never grouped
2333 into key sequences, and they never appear in the value of
2334 @code{last-command-event} or @code{(this-command-keys)}.  They do not
2335 discard a numeric argument, they cannot be unread with
2336 @code{unread-command-events}, they may not appear in a keyboard macro,
2337 and they are not recorded in a keyboard macro while you are defining
2338 one.
2340 These events do, however, appear in @code{last-input-event} immediately
2341 after they are read, and this is the way for the event's definition to
2342 find the actual event.
2344 The events types @code{iconify-frame}, @code{make-frame-visible} and
2345 @code{delete-frame} are normally handled in this way.  The keymap which
2346 defines how to handle special events---and which events are special---is
2347 in the variable @code{special-event-map} (@pxref{Active Keymaps}).
2349 @node Waiting
2350 @section Waiting for Elapsed Time or Input
2351 @cindex pausing
2352 @cindex waiting
2354   The wait functions are designed to wait for a certain amount of time
2355 to pass or until there is input.  For example, you may wish to pause in
2356 the middle of a computation to allow the user time to view the display.
2357 @code{sit-for} pauses and updates the screen, and returns immediately if
2358 input comes in, while @code{sleep-for} pauses without updating the
2359 screen.
2361 @defun sit-for seconds &optional nodisp
2362 This function performs redisplay (provided there is no pending input
2363 from the user), then waits @var{seconds} seconds, or until input is
2364 available.  The value is @code{t} if @code{sit-for} waited the full
2365 time with no input arriving (see @code{input-pending-p} in @ref{Event
2366 Input Misc}).  Otherwise, the value is @code{nil}.
2368 The argument @var{seconds} need not be an integer.  If it is a floating
2369 point number, @code{sit-for} waits for a fractional number of seconds.
2370 Some systems support only a whole number of seconds; on these systems,
2371 @var{seconds} is rounded down.
2373 The expression @code{(sit-for 0)} is a convenient way to request a
2374 redisplay, without any delay.  @xref{Forcing Redisplay}.
2376 If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
2377 redisplay, but it still returns as soon as input is available (or when
2378 the timeout elapses).
2380 Iconifying or deiconifying a frame makes @code{sit-for} return, because
2381 that generates an event.  @xref{Misc Events}.
2383 The usual purpose of @code{sit-for} is to give the user time to read
2384 text that you display.
2386 It is also possible to call @code{sit-for} with three arguments,
2387 as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})},
2388 but that is considered obsolete.
2389 @end defun
2391 @defun sleep-for seconds &optional millisec
2392 This function simply pauses for @var{seconds} seconds without updating
2393 the display.  It pays no attention to available input.  It returns
2394 @code{nil}.
2396 The argument @var{seconds} need not be an integer.  If it is a floating
2397 point number, @code{sleep-for} waits for a fractional number of seconds.
2398 Some systems support only a whole number of seconds; on these systems,
2399 @var{seconds} is rounded down.
2401 The optional argument @var{millisec} specifies an additional waiting
2402 period measured in milliseconds.  This adds to the period specified by
2403 @var{seconds}.  If the system doesn't support waiting fractions of a
2404 second, you get an error if you specify nonzero @var{millisec}.
2406 Use @code{sleep-for} when you wish to guarantee a delay.
2407 @end defun
2409   @xref{Time of Day}, for functions to get the current time.
2411 @node Quitting
2412 @section Quitting
2413 @cindex @kbd{C-g}
2414 @cindex quitting
2415 @cindex interrupt Lisp functions
2417   Typing @kbd{C-g} while a Lisp function is running causes Emacs to
2418 @dfn{quit} whatever it is doing.  This means that control returns to the
2419 innermost active command loop.
2421   Typing @kbd{C-g} while the command loop is waiting for keyboard input
2422 does not cause a quit; it acts as an ordinary input character.  In the
2423 simplest case, you cannot tell the difference, because @kbd{C-g}
2424 normally runs the command @code{keyboard-quit}, whose effect is to quit.
2425 However, when @kbd{C-g} follows a prefix key, they combine to form an
2426 undefined key.  The effect is to cancel the prefix key as well as any
2427 prefix argument.
2429   In the minibuffer, @kbd{C-g} has a different definition: it aborts out
2430 of the minibuffer.  This means, in effect, that it exits the minibuffer
2431 and then quits.  (Simply quitting would return to the command loop
2432 @emph{within} the minibuffer.)  The reason why @kbd{C-g} does not quit
2433 directly when the command reader is reading input is so that its meaning
2434 can be redefined in the minibuffer in this way.  @kbd{C-g} following a
2435 prefix key is not redefined in the minibuffer, and it has its normal
2436 effect of canceling the prefix key and prefix argument.  This too
2437 would not be possible if @kbd{C-g} always quit directly.
2439   When @kbd{C-g} does directly quit, it does so by setting the variable
2440 @code{quit-flag} to @code{t}.  Emacs checks this variable at appropriate
2441 times and quits if it is not @code{nil}.  Setting @code{quit-flag}
2442 non-@code{nil} in any way thus causes a quit.
2444   At the level of C code, quitting cannot happen just anywhere; only at the
2445 special places that check @code{quit-flag}.  The reason for this is
2446 that quitting at other places might leave an inconsistency in Emacs's
2447 internal state.  Because quitting is delayed until a safe place, quitting
2448 cannot make Emacs crash.
2450   Certain functions such as @code{read-key-sequence} or
2451 @code{read-quoted-char} prevent quitting entirely even though they wait
2452 for input.  Instead of quitting, @kbd{C-g} serves as the requested
2453 input.  In the case of @code{read-key-sequence}, this serves to bring
2454 about the special behavior of @kbd{C-g} in the command loop.  In the
2455 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
2456 to quote a @kbd{C-g}.
2458 @cindex prevent quitting
2459   You can prevent quitting for a portion of a Lisp function by binding
2460 the variable @code{inhibit-quit} to a non-@code{nil} value.  Then,
2461 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
2462 usual result of this---a quit---is prevented.  Eventually,
2463 @code{inhibit-quit} will become @code{nil} again, such as when its
2464 binding is unwound at the end of a @code{let} form.  At that time, if
2465 @code{quit-flag} is still non-@code{nil}, the requested quit happens
2466 immediately.  This behavior is ideal when you wish to make sure that
2467 quitting does not happen within a ``critical section'' of the program.
2469 @cindex @code{read-quoted-char} quitting
2470   In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
2471 handled in a special way that does not involve quitting.  This is done
2472 by reading the input with @code{inhibit-quit} bound to @code{t}, and
2473 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
2474 becomes @code{nil} again.  This excerpt from the definition of
2475 @code{read-quoted-char} shows how this is done; it also shows that
2476 normal quitting is permitted after the first character of input.
2478 @example
2479 (defun read-quoted-char (&optional prompt)
2480   "@dots{}@var{documentation}@dots{}"
2481   (let ((message-log-max nil) done (first t) (code 0) char)
2482     (while (not done)
2483       (let ((inhibit-quit first)
2484             @dots{})
2485         (and prompt (message "%s-" prompt))
2486         (setq char (read-event))
2487         (if inhibit-quit (setq quit-flag nil)))
2488       @r{@dots{}set the variable @code{code}@dots{}})
2489     code))
2490 @end example
2492 @defvar quit-flag
2493 If this variable is non-@code{nil}, then Emacs quits immediately, unless
2494 @code{inhibit-quit} is non-@code{nil}.  Typing @kbd{C-g} ordinarily sets
2495 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
2496 @end defvar
2498 @defvar inhibit-quit
2499 This variable determines whether Emacs should quit when @code{quit-flag}
2500 is set to a value other than @code{nil}.  If @code{inhibit-quit} is
2501 non-@code{nil}, then @code{quit-flag} has no special effect.
2502 @end defvar
2504 @deffn Command keyboard-quit
2505 This function signals the @code{quit} condition with @code{(signal 'quit
2506 nil)}.  This is the same thing that quitting does.  (See @code{signal}
2507 in @ref{Errors}.)
2508 @end deffn
2510   You can specify a character other than @kbd{C-g} to use for quitting.
2511 See the function @code{set-input-mode} in @ref{Terminal Input}.
2513 @node Prefix Command Arguments
2514 @section Prefix Command Arguments
2515 @cindex prefix argument
2516 @cindex raw prefix argument
2517 @cindex numeric prefix argument
2519   Most Emacs commands can use a @dfn{prefix argument}, a number
2520 specified before the command itself.  (Don't confuse prefix arguments
2521 with prefix keys.)  The prefix argument is at all times represented by a
2522 value, which may be @code{nil}, meaning there is currently no prefix
2523 argument.  Each command may use the prefix argument or ignore it.
2525   There are two representations of the prefix argument: @dfn{raw} and
2526 @dfn{numeric}.  The editor command loop uses the raw representation
2527 internally, and so do the Lisp variables that store the information, but
2528 commands can request either representation.
2530   Here are the possible values of a raw prefix argument:
2532 @itemize @bullet
2533 @item
2534 @code{nil}, meaning there is no prefix argument.  Its numeric value is
2535 1, but numerous commands make a distinction between @code{nil} and the
2536 integer 1.
2538 @item
2539 An integer, which stands for itself.
2541 @item
2542 A list of one element, which is an integer.  This form of prefix
2543 argument results from one or a succession of @kbd{C-u}'s with no
2544 digits.  The numeric value is the integer in the list, but some
2545 commands make a distinction between such a list and an integer alone.
2547 @item
2548 The symbol @code{-}.  This indicates that @kbd{M--} or @kbd{C-u -} was
2549 typed, without following digits.  The equivalent numeric value is
2550 @minus{}1, but some commands make a distinction between the integer
2551 @minus{}1 and the symbol @code{-}.
2552 @end itemize
2554 We illustrate these possibilities by calling the following function with
2555 various prefixes:
2557 @example
2558 @group
2559 (defun display-prefix (arg)
2560   "Display the value of the raw prefix arg."
2561   (interactive "P")
2562   (message "%s" arg))
2563 @end group
2564 @end example
2566 @noindent
2567 Here are the results of calling @code{display-prefix} with various
2568 raw prefix arguments:
2570 @example
2571         M-x display-prefix  @print{} nil
2573 C-u     M-x display-prefix  @print{} (4)
2575 C-u C-u M-x display-prefix  @print{} (16)
2577 C-u 3   M-x display-prefix  @print{} 3
2579 M-3     M-x display-prefix  @print{} 3      ; @r{(Same as @code{C-u 3}.)}
2581 C-u -   M-x display-prefix  @print{} -
2583 M--     M-x display-prefix  @print{} -      ; @r{(Same as @code{C-u -}.)}
2585 C-u - 7 M-x display-prefix  @print{} -7
2587 M-- 7   M-x display-prefix  @print{} -7     ; @r{(Same as @code{C-u -7}.)}
2588 @end example
2590   Emacs uses two variables to store the prefix argument:
2591 @code{prefix-arg} and @code{current-prefix-arg}.  Commands such as
2592 @code{universal-argument} that set up prefix arguments for other
2593 commands store them in @code{prefix-arg}.  In contrast,
2594 @code{current-prefix-arg} conveys the prefix argument to the current
2595 command, so setting it has no effect on the prefix arguments for future
2596 commands.
2598   Normally, commands specify which representation to use for the prefix
2599 argument, either numeric or raw, in the @code{interactive} declaration.
2600 (@xref{Using Interactive}.)  Alternatively, functions may look at the
2601 value of the prefix argument directly in the variable
2602 @code{current-prefix-arg}, but this is less clean.
2604 @defun prefix-numeric-value arg
2605 This function returns the numeric meaning of a valid raw prefix argument
2606 value, @var{arg}.  The argument may be a symbol, a number, or a list.
2607 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
2608 value @minus{}1 is returned; if it is a number, that number is returned;
2609 if it is a list, the @sc{car} of that list (which should be a number) is
2610 returned.
2611 @end defun
2613 @defvar current-prefix-arg
2614 This variable holds the raw prefix argument for the @emph{current}
2615 command.  Commands may examine it directly, but the usual method for
2616 accessing it is with @code{(interactive "P")}.
2617 @end defvar
2619 @defvar prefix-arg
2620 The value of this variable is the raw prefix argument for the
2621 @emph{next} editing command.  Commands such as @code{universal-argument}
2622 that specify prefix arguments for the following command work by setting
2623 this variable.
2624 @end defvar
2626 @defvar last-prefix-arg
2627 The raw prefix argument value used by the previous command.
2628 @end defvar
2630   The following commands exist to set up prefix arguments for the
2631 following command.  Do not call them for any other reason.
2633 @deffn Command universal-argument
2634 This command reads input and specifies a prefix argument for the
2635 following command.  Don't call this command yourself unless you know
2636 what you are doing.
2637 @end deffn
2639 @deffn Command digit-argument arg
2640 This command adds to the prefix argument for the following command.  The
2641 argument @var{arg} is the raw prefix argument as it was before this
2642 command; it is used to compute the updated prefix argument.  Don't call
2643 this command yourself unless you know what you are doing.
2644 @end deffn
2646 @deffn Command negative-argument arg
2647 This command adds to the numeric argument for the next command.  The
2648 argument @var{arg} is the raw prefix argument as it was before this
2649 command; its value is negated to form the new prefix argument.  Don't
2650 call this command yourself unless you know what you are doing.
2651 @end deffn
2653 @node Recursive Editing
2654 @section Recursive Editing
2655 @cindex recursive command loop
2656 @cindex recursive editing level
2657 @cindex command loop, recursive
2659   The Emacs command loop is entered automatically when Emacs starts up.
2660 This top-level invocation of the command loop never exits; it keeps
2661 running as long as Emacs does.  Lisp programs can also invoke the
2662 command loop.  Since this makes more than one activation of the command
2663 loop, we call it @dfn{recursive editing}.  A recursive editing level has
2664 the effect of suspending whatever command invoked it and permitting the
2665 user to do arbitrary editing before resuming that command.
2667   The commands available during recursive editing are the same ones
2668 available in the top-level editing loop and defined in the keymaps.
2669 Only a few special commands exit the recursive editing level; the others
2670 return to the recursive editing level when they finish.  (The special
2671 commands for exiting are always available, but they do nothing when
2672 recursive editing is not in progress.)
2674   All command loops, including recursive ones, set up all-purpose error
2675 handlers so that an error in a command run from the command loop will
2676 not exit the loop.
2678 @cindex minibuffer input
2679   Minibuffer input is a special kind of recursive editing.  It has a few
2680 special wrinkles, such as enabling display of the minibuffer and the
2681 minibuffer window, but fewer than you might suppose.  Certain keys
2682 behave differently in the minibuffer, but that is only because of the
2683 minibuffer's local map; if you switch windows, you get the usual Emacs
2684 commands.
2686 @cindex @code{throw} example
2687 @kindex exit
2688 @cindex exit recursive editing
2689 @cindex aborting
2690   To invoke a recursive editing level, call the function
2691 @code{recursive-edit}.  This function contains the command loop; it also
2692 contains a call to @code{catch} with tag @code{exit}, which makes it
2693 possible to exit the recursive editing level by throwing to @code{exit}
2694 (@pxref{Catch and Throw}).  If you throw a value other than @code{t},
2695 then @code{recursive-edit} returns normally to the function that called
2696 it.  The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
2697 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
2698 control returns to the command loop one level up.  This is called
2699 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
2701   Most applications should not use recursive editing, except as part of
2702 using the minibuffer.  Usually it is more convenient for the user if you
2703 change the major mode of the current buffer temporarily to a special
2704 major mode, which should have a command to go back to the previous mode.
2705 (The @kbd{e} command in Rmail uses this technique.)  Or, if you wish to
2706 give the user different text to edit ``recursively'', create and select
2707 a new buffer in a special mode.  In this mode, define a command to
2708 complete the processing and go back to the previous buffer.  (The
2709 @kbd{m} command in Rmail does this.)
2711   Recursive edits are useful in debugging.  You can insert a call to
2712 @code{debug} into a function definition as a sort of breakpoint, so that
2713 you can look around when the function gets there.  @code{debug} invokes
2714 a recursive edit but also provides the other features of the debugger.
2716   Recursive editing levels are also used when you type @kbd{C-r} in
2717 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
2719 @defun recursive-edit
2720 @cindex suspend evaluation
2721 This function invokes the editor command loop.  It is called
2722 automatically by the initialization of Emacs, to let the user begin
2723 editing.  When called from a Lisp program, it enters a recursive editing
2724 level.
2726   In the following example, the function @code{simple-rec} first
2727 advances point one word, then enters a recursive edit, printing out a
2728 message in the echo area.  The user can then do any editing desired, and
2729 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
2731 @example
2732 (defun simple-rec ()
2733   (forward-word 1)
2734   (message "Recursive edit in progress")
2735   (recursive-edit)
2736   (forward-word 1))
2737      @result{} simple-rec
2738 (simple-rec)
2739      @result{} nil
2740 @end example
2741 @end defun
2743 @deffn Command exit-recursive-edit
2744 This function exits from the innermost recursive edit (including
2745 minibuffer input).  Its definition is effectively @code{(throw 'exit
2746 nil)}.
2747 @end deffn
2749 @deffn Command abort-recursive-edit
2750 This function aborts the command that requested the innermost recursive
2751 edit (including minibuffer input), by signaling @code{quit}
2752 after exiting the recursive edit.  Its definition is effectively
2753 @code{(throw 'exit t)}.  @xref{Quitting}.
2754 @end deffn
2756 @deffn Command top-level
2757 This function exits all recursive editing levels; it does not return a
2758 value, as it jumps completely out of any computation directly back to
2759 the main command loop.
2760 @end deffn
2762 @defun recursion-depth
2763 This function returns the current depth of recursive edits.  When no
2764 recursive edit is active, it returns 0.
2765 @end defun
2767 @node Disabling Commands
2768 @section Disabling Commands
2769 @cindex disabled command
2771   @dfn{Disabling a command} marks the command as requiring user
2772 confirmation before it can be executed.  Disabling is used for commands
2773 which might be confusing to beginning users, to prevent them from using
2774 the commands by accident.
2776 @kindex disabled
2777   The low-level mechanism for disabling a command is to put a
2778 non-@code{nil} @code{disabled} property on the Lisp symbol for the
2779 command.  These properties are normally set up by the user's
2780 init file (@pxref{Init File}) with Lisp expressions such as this:
2782 @example
2783 (put 'upcase-region 'disabled t)
2784 @end example
2786 @noindent
2787 For a few commands, these properties are present by default (you can
2788 remove them in your init file if you wish).
2790   If the value of the @code{disabled} property is a string, the message
2791 saying the command is disabled includes that string.  For example:
2793 @example
2794 (put 'delete-region 'disabled
2795      "Text deleted this way cannot be yanked back!\n")
2796 @end example
2798   @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on
2799 what happens when a disabled command is invoked interactively.
2800 Disabling a command has no effect on calling it as a function from Lisp
2801 programs.
2803 @deffn Command enable-command command
2804 Allow @var{command} to be executed without special confirmation from now
2805 on, and (if the user confirms) alter the user's init file (@pxref{Init
2806 File}) so that this will apply to future sessions.
2807 @end deffn
2809 @deffn Command disable-command command
2810 Require special confirmation to execute @var{command} from now on, and
2811 (if the user confirms) alter the user's init file so that this
2812 will apply to future sessions.
2813 @end deffn
2815 @defvar disabled-command-hook
2816 When the user invokes a disabled command interactively, this normal hook
2817 is run instead of the disabled command.  The hook functions can use
2818 @code{this-command-keys} to determine what the user typed to run the
2819 command, and thus find the command itself.  @xref{Hooks}.
2821 By default, @code{disabled-command-hook} contains a function that asks
2822 the user whether to proceed.
2823 @end defvar
2825 @node Command History
2826 @section Command History
2827 @cindex command history
2828 @cindex complex command
2829 @cindex history of commands
2831   The command loop keeps a history of the complex commands that have
2832 been executed, to make it convenient to repeat these commands.  A
2833 @dfn{complex command} is one for which the interactive argument reading
2834 uses the minibuffer.  This includes any @kbd{M-x} command, any
2835 @kbd{M-:} command, and any command whose @code{interactive}
2836 specification reads an argument from the minibuffer.  Explicit use of
2837 the minibuffer during the execution of the command itself does not cause
2838 the command to be considered complex.
2840 @defvar command-history
2841 This variable's value is a list of recent complex commands, each
2842 represented as a form to evaluate.  It continues to accumulate all
2843 complex commands for the duration of the editing session, but when it
2844 reaches the maximum size (@pxref{Minibuffer History}), the oldest
2845 elements are deleted as new ones are added.
2847 @example
2848 @group
2849 command-history
2850 @result{} ((switch-to-buffer "chistory.texi")
2851     (describe-key "^X^[")
2852     (visit-tags-table "~/emacs/src/")
2853     (find-tag "repeat-complex-command"))
2854 @end group
2855 @end example
2856 @end defvar
2858   This history list is actually a special case of minibuffer history
2859 (@pxref{Minibuffer History}), with one special twist: the elements are
2860 expressions rather than strings.
2862   There are a number of commands devoted to the editing and recall of
2863 previous commands.  The commands @code{repeat-complex-command}, and
2864 @code{list-command-history} are described in the user manual
2865 (@pxref{Repetition,,, emacs, The GNU Emacs Manual}).  Within the
2866 minibuffer, the usual minibuffer history commands are available.
2868 @node Keyboard Macros
2869 @section Keyboard Macros
2870 @cindex keyboard macros
2872   A @dfn{keyboard macro} is a canned sequence of input events that can
2873 be considered a command and made the definition of a key.  The Lisp
2874 representation of a keyboard macro is a string or vector containing the
2875 events.  Don't confuse keyboard macros with Lisp macros
2876 (@pxref{Macros}).
2878 @defun execute-kbd-macro kbdmacro &optional count
2879 This function executes @var{kbdmacro} as a sequence of events.  If
2880 @var{kbdmacro} is a string or vector, then the events in it are executed
2881 exactly as if they had been input by the user.  The sequence is
2882 @emph{not} expected to be a single key sequence; normally a keyboard
2883 macro definition consists of several key sequences concatenated.
2885 If @var{kbdmacro} is a symbol, then its function definition is used in
2886 place of @var{kbdmacro}.  If that is another symbol, this process repeats.
2887 Eventually the result should be a string or vector.  If the result is
2888 not a symbol, string, or vector, an error is signaled.
2890 The argument @var{count} is a repeat count; @var{kbdmacro} is executed that
2891 many times.  If @var{count} is omitted or @code{nil}, @var{kbdmacro} is
2892 executed once.  If it is 0, @var{kbdmacro} is executed over and over until it
2893 encounters an error or a failing search.
2895 @xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
2896 @end defun
2898 @defvar executing-macro
2899 This variable contains the string or vector that defines the keyboard
2900 macro that is currently executing.  It is @code{nil} if no macro is
2901 currently executing.  A command can test this variable so as to behave
2902 differently when run from an executing macro.  Do not set this variable
2903 yourself.
2904 @end defvar
2906 @defvar defining-kbd-macro
2907 This variable indicates whether a keyboard macro is being defined.  A
2908 command can test this variable so as to behave differently while a macro
2909 is being defined.  The commands @code{start-kbd-macro} and
2910 @code{end-kbd-macro} set this variable---do not set it yourself.
2912 The variable is always local to the current terminal and cannot be
2913 buffer-local.  @xref{Multiple Displays}.
2914 @end defvar
2916 @defvar last-kbd-macro
2917 This variable is the definition of the most recently defined keyboard
2918 macro.  Its value is a string or vector, or @code{nil}.
2920 The variable is always local to the current terminal and cannot be
2921 buffer-local.  @xref{Multiple Displays}.
2922 @end defvar
2924 @defvar kbd-macro-termination-hook
2925 This normal hook (@pxref{Standard Hooks}) is run when a keyboard
2926 macro terminates, regardless of what caused it to terminate (reaching
2927 the macro end or an error which ended the macro prematurely).
2928 @end defvar
2930 @ignore
2931    arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1
2932 @end ignore