Style fixes for floating-point doc.
[bpt/emacs.git] / doc / lispref / commands.texi
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
4 @c Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @node Command Loop
7 @chapter Command Loop
8 @cindex editor command loop
9 @cindex command loop
10
11 When you run Emacs, it enters the @dfn{editor command loop} almost
12 immediately. This loop reads key sequences, executes their definitions,
13 and displays the results. In this chapter, we describe how these things
14 are done, and the subroutines that allow Lisp programs to do them.
15
16 @menu
17 * Command Overview:: How the command loop reads commands.
18 * Defining Commands:: Specifying how a function should read arguments.
19 * Interactive Call:: Calling a command, so that it will read arguments.
20 * Distinguish Interactive:: Making a command distinguish interactive calls.
21 * Command Loop Info:: Variables set by the command loop for you to examine.
22 * Adjusting Point:: Adjustment of point after a command.
23 * Input Events:: What input looks like when you read it.
24 * Reading Input:: How to read input events from the keyboard or mouse.
25 * Special Events:: Events processed immediately and individually.
26 * Waiting:: Waiting for user input or elapsed time.
27 * Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
28 * Prefix Command Arguments:: How the commands to set prefix args work.
29 * Recursive Editing:: Entering a recursive edit,
30 and why you usually shouldn't.
31 * Disabling Commands:: How the command loop handles disabled commands.
32 * Command History:: How the command history is set up, and how accessed.
33 * Keyboard Macros:: How keyboard macros are implemented.
34 @end menu
35
36 @node Command Overview
37 @section Command Loop Overview
38
39 The first thing the command loop must do is read a key sequence,
40 which is a sequence of input events that translates into a command.
41 It does this by calling the function @code{read-key-sequence}. Lisp
42 programs can also call this function (@pxref{Key Sequence Input}).
43 They can also read input at a lower level with @code{read-key} or
44 @code{read-event} (@pxref{Reading One Event}), or discard pending
45 input with @code{discard-input} (@pxref{Event Input Misc}).
46
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}).
53
54 Prior to executing the command, Emacs runs @code{undo-boundary} to
55 create an undo boundary. @xref{Maintaining Undo}.
56
57 To execute a command, Emacs first reads its arguments by calling
58 @code{command-execute} (@pxref{Interactive Call}). For commands
59 written in Lisp, the @code{interactive} specification says how to read
60 the arguments. This may use the prefix argument (@pxref{Prefix
61 Command Arguments}) or may read with prompting in the minibuffer
62 (@pxref{Minibuffers}). For example, the command @code{find-file} has
63 an @code{interactive} specification which says to read a file name
64 using the minibuffer. The function body of @code{find-file} does not
65 use the minibuffer, so if you call @code{find-file} as a function from
66 Lisp code, you must supply the file name string as an ordinary Lisp
67 function argument.
68
69 If the command is a keyboard macro (i.e., a string or vector),
70 Emacs executes it using @code{execute-kbd-macro} (@pxref{Keyboard
71 Macros}).
72
73 @defvar pre-command-hook
74 This normal hook is run by the editor command loop before it executes
75 each command. At that time, @code{this-command} contains the command
76 that is about to run, and @code{last-command} describes the previous
77 command. @xref{Command Loop Info}.
78 @end defvar
79
80 @defvar post-command-hook
81 This normal hook is run by the editor command loop after it executes
82 each command (including commands terminated prematurely by quitting or
83 by errors). At that time, @code{this-command} refers to the command
84 that just ran, and @code{last-command} refers to the command before
85 that.
86
87 This hook is also run when Emacs first enters the command loop (at
88 which point @code{this-command} and @code{last-command} are both
89 @code{nil}).
90 @end defvar
91
92 Quitting is suppressed while running @code{pre-command-hook} and
93 @code{post-command-hook}. If an error happens while executing one of
94 these hooks, it does not terminate execution of the hook; instead
95 the error is silenced and the function in which the error occurred
96 is removed from the hook.
97
98 A request coming into the Emacs server (@pxref{Emacs Server,,,
99 emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard
100 command does.
101
102 @node Defining Commands
103 @section Defining Commands
104 @cindex defining commands
105 @cindex commands, defining
106 @cindex functions, making them interactive
107 @cindex interactive function
108
109 The special form @code{interactive} turns a Lisp function into a
110 command. The @code{interactive} form must be located at top-level in
111 the function body, usually as the first form in the body; this applies
112 to both lambda expressions (@pxref{Lambda Expressions}) and
113 @code{defun} forms (@pxref{Defining Functions}). This form does
114 nothing during the actual execution of the function; its presence
115 serves as a flag, telling the Emacs command loop that the function can
116 be called interactively. The argument of the @code{interactive} form
117 specifies how the arguments for an interactive call should be read.
118
119 @cindex @code{interactive-form} property
120 Alternatively, an @code{interactive} form may be specified in a
121 function symbol's @code{interactive-form} property. A non-@code{nil}
122 value for this property takes precedence over any @code{interactive}
123 form in the function body itself. This feature is seldom used.
124
125 @cindex @code{interactive-only} property
126 Sometimes, a named command is only intended to be called
127 interactively, never directly from Lisp. In that case, give it a
128 non-@code{nil} @code{interactive-only} property. In that case, the
129 byte compiler will print a warning message if the command is called
130 from Lisp.
131
132 @menu
133 * Using Interactive:: General rules for @code{interactive}.
134 * Interactive Codes:: The standard letter-codes for reading arguments
135 in various ways.
136 * Interactive Examples:: Examples of how to read interactive arguments.
137 * Generic Commands:: Select among command alternatives.
138 @end menu
139
140 @node Using Interactive
141 @subsection Using @code{interactive}
142 @cindex arguments, interactive entry
143
144 This section describes how to write the @code{interactive} form that
145 makes a Lisp function an interactively-callable command, and how to
146 examine a command's @code{interactive} form.
147
148 @defspec interactive arg-descriptor
149 This special form declares that a function is a command, and that it
150 may therefore be called interactively (via @kbd{M-x} or by entering a
151 key sequence bound to it). The argument @var{arg-descriptor} declares
152 how to compute the arguments to the command when the command is called
153 interactively.
154
155 A command may be called from Lisp programs like any other function, but
156 then the caller supplies the arguments and @var{arg-descriptor} has no
157 effect.
158
159 @cindex @code{interactive-form}, symbol property
160 The @code{interactive} form must be located at top-level in the
161 function body, or in the function symbol's @code{interactive-form}
162 property (@pxref{Symbol Properties}). It has its effect because the
163 command loop looks for it before calling the function
164 (@pxref{Interactive Call}). Once the function is called, all its body
165 forms are executed; at this time, if the @code{interactive} form
166 occurs within the body, the form simply returns @code{nil} without
167 even evaluating its argument.
168
169 By convention, you should put the @code{interactive} form in the
170 function body, as the first top-level form. If there is an
171 @code{interactive} form in both the @code{interactive-form} symbol
172 property and the function body, the former takes precedence. The
173 @code{interactive-form} symbol property can be used to add an
174 interactive form to an existing function, or change how its arguments
175 are processed interactively, without redefining the function.
176 @end defspec
177
178 There are three possibilities for the argument @var{arg-descriptor}:
179
180 @itemize @bullet
181 @item
182 It may be omitted or @code{nil}; then the command is called with no
183 arguments. This leads quickly to an error if the command requires one
184 or more arguments.
185
186 @item
187 It may be a string; its contents are a sequence of elements separated
188 by newlines, one for each argument@footnote{Some elements actually
189 supply two arguments.}. Each element consists of a code character
190 (@pxref{Interactive Codes}) optionally followed by a prompt (which
191 some code characters use and some ignore). Here is an example:
192
193 @smallexample
194 (interactive "P\nbFrobnicate buffer: ")
195 @end smallexample
196
197 @noindent
198 The code letter @samp{P} sets the command's first argument to the raw
199 command prefix (@pxref{Prefix Command Arguments}). @samp{bFrobnicate
200 buffer: } prompts the user with @samp{Frobnicate buffer: } to enter
201 the name of an existing buffer, which becomes the second and final
202 argument.
203
204 The prompt string can use @samp{%} to include previous argument values
205 (starting with the first argument) in the prompt. This is done using
206 @code{format} (@pxref{Formatting Strings}). For example, here is how
207 you could read the name of an existing buffer followed by a new name to
208 give to that buffer:
209
210 @smallexample
211 @group
212 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
213 @end group
214 @end smallexample
215
216 @cindex @samp{*} in @code{interactive}
217 @cindex read-only buffers in interactive
218 If @samp{*} appears at the beginning of the string, then an error is
219 signaled if the buffer is read-only.
220
221 @cindex @samp{@@} in @code{interactive}
222 If @samp{@@} appears at the beginning of the string, and if the key
223 sequence used to invoke the command includes any mouse events, then
224 the window associated with the first of those events is selected
225 before the command is run.
226
227 @cindex @samp{^} in @code{interactive}
228 @cindex shift-selection, and @code{interactive} spec
229 If @samp{^} appears at the beginning of the string, and if the command
230 was invoked through @dfn{shift-translation}, set the mark and activate
231 the region temporarily, or extend an already active region, before the
232 command is run. If the command was invoked without shift-translation,
233 and the region is temporarily active, deactivate the region before the
234 command is run. Shift-translation is controlled on the user level by
235 @code{shift-select-mode}; see @ref{Shift Selection,,, emacs, The GNU
236 Emacs Manual}.
237
238 You can use @samp{*}, @samp{@@}, and @code{^} together; the order does
239 not matter. Actual reading of arguments is controlled by the rest of
240 the prompt string (starting with the first character that is not
241 @samp{*}, @samp{@@}, or @samp{^}).
242
243 @item
244 It may be a Lisp expression that is not a string; then it should be a
245 form that is evaluated to get a list of arguments to pass to the
246 command. Usually this form will call various functions to read input
247 from the user, most often through the minibuffer (@pxref{Minibuffers})
248 or directly from the keyboard (@pxref{Reading Input}).
249
250 Providing point or the mark as an argument value is also common, but
251 if you do this @emph{and} read input (whether using the minibuffer or
252 not), be sure to get the integer values of point or the mark after
253 reading. The current buffer may be receiving subprocess output; if
254 subprocess output arrives while the command is waiting for input, it
255 could relocate point and the mark.
256
257 Here's an example of what @emph{not} to do:
258
259 @smallexample
260 (interactive
261 (list (region-beginning) (region-end)
262 (read-string "Foo: " nil 'my-history)))
263 @end smallexample
264
265 @noindent
266 Here's how to avoid the problem, by examining point and the mark after
267 reading the keyboard input:
268
269 @smallexample
270 (interactive
271 (let ((string (read-string "Foo: " nil 'my-history)))
272 (list (region-beginning) (region-end) string)))
273 @end smallexample
274
275 @strong{Warning:} the argument values should not include any data
276 types that can't be printed and then read. Some facilities save
277 @code{command-history} in a file to be read in the subsequent
278 sessions; if a command's arguments contain a data type that prints
279 using @samp{#<@dots{}>} syntax, those facilities won't work.
280
281 There are, however, a few exceptions: it is ok to use a limited set of
282 expressions such as @code{(point)}, @code{(mark)},
283 @code{(region-beginning)}, and @code{(region-end)}, because Emacs
284 recognizes them specially and puts the expression (rather than its
285 value) into the command history. To see whether the expression you
286 wrote is one of these exceptions, run the command, then examine
287 @code{(car command-history)}.
288 @end itemize
289
290 @cindex examining the @code{interactive} form
291 @defun interactive-form function
292 This function returns the @code{interactive} form of @var{function}.
293 If @var{function} is an interactively callable function
294 (@pxref{Interactive Call}), the value is the command's
295 @code{interactive} form @code{(interactive @var{spec})}, which
296 specifies how to compute its arguments. Otherwise, the value is
297 @code{nil}. If @var{function} is a symbol, its function definition is
298 used.
299 @end defun
300
301 @node Interactive Codes
302 @subsection Code Characters for @code{interactive}
303 @cindex interactive code description
304 @cindex description for interactive codes
305 @cindex codes, interactive, description of
306 @cindex characters for interactive codes
307
308 The code character descriptions below contain a number of key words,
309 defined here as follows:
310
311 @table @b
312 @item Completion
313 @cindex interactive completion
314 Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name
315 completion because the argument is read using @code{completing-read}
316 (@pxref{Completion}). @kbd{?} displays a list of possible completions.
317
318 @item Existing
319 Require the name of an existing object. An invalid name is not
320 accepted; the commands to exit the minibuffer do not exit if the current
321 input is not valid.
322
323 @item Default
324 @cindex default argument string
325 A default value of some sort is used if the user enters no text in the
326 minibuffer. The default depends on the code character.
327
328 @item No I/O
329 This code letter computes an argument without reading any input.
330 Therefore, it does not use a prompt string, and any prompt string you
331 supply is ignored.
332
333 Even though the code letter doesn't use a prompt string, you must follow
334 it with a newline if it is not the last code character in the string.
335
336 @item Prompt
337 A prompt immediately follows the code character. The prompt ends either
338 with the end of the string or with a newline.
339
340 @item Special
341 This code character is meaningful only at the beginning of the
342 interactive string, and it does not look for a prompt or a newline.
343 It is a single, isolated character.
344 @end table
345
346 @cindex reading interactive arguments
347 Here are the code character descriptions for use with @code{interactive}:
348
349 @table @samp
350 @item *
351 Signal an error if the current buffer is read-only. Special.
352
353 @item @@
354 Select the window mentioned in the first mouse event in the key
355 sequence that invoked this command. Special.
356
357 @item ^
358 If the command was invoked through shift-translation, set the mark and
359 activate the region temporarily, or extend an already active region,
360 before the command is run. If the command was invoked without
361 shift-translation, and the region is temporarily active, deactivate
362 the region before the command is run. Special.
363
364 @item a
365 A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
366 Completion, Prompt.
367
368 @item b
369 The name of an existing buffer. By default, uses the name of the
370 current buffer (@pxref{Buffers}). Existing, Completion, Default,
371 Prompt.
372
373 @item B
374 A buffer name. The buffer need not exist. By default, uses the name of
375 a recently used buffer other than the current buffer. Completion,
376 Default, Prompt.
377
378 @item c
379 A character. The cursor does not move into the echo area. Prompt.
380
381 @item C
382 A command name (i.e., a symbol satisfying @code{commandp}). Existing,
383 Completion, Prompt.
384
385 @item d
386 @cindex position argument
387 The position of point, as an integer (@pxref{Point}). No I/O.
388
389 @item D
390 A directory name. The default is the current default directory of the
391 current buffer, @code{default-directory} (@pxref{File Name Expansion}).
392 Existing, Completion, Default, Prompt.
393
394 @item e
395 The first or next non-keyboard event in the key sequence that invoked
396 the command. More precisely, @samp{e} gets events that are lists, so
397 you can look at the data in the lists. @xref{Input Events}. No I/O.
398
399 You use @samp{e} for mouse events and for special system events
400 (@pxref{Misc Events}). The event list that the command receives
401 depends on the event. @xref{Input Events}, which describes the forms
402 of the list for each event in the corresponding subsections.
403
404 You can use @samp{e} more than once in a single command's interactive
405 specification. If the key sequence that invoked the command has
406 @var{n} events that are lists, the @var{n}th @samp{e} provides the
407 @var{n}th such event. Events that are not lists, such as function keys
408 and @acronym{ASCII} characters, do not count where @samp{e} is concerned.
409
410 @item f
411 A file name of an existing file (@pxref{File Names}). The default
412 directory is @code{default-directory}. Existing, Completion, Default,
413 Prompt.
414
415 @item F
416 A file name. The file need not exist. Completion, Default, Prompt.
417
418 @item G
419 A file name. The file need not exist. If the user enters just a
420 directory name, then the value is just that directory name, with no
421 file name within the directory added. Completion, Default, Prompt.
422
423 @item i
424 An irrelevant argument. This code always supplies @code{nil} as
425 the argument's value. No I/O.
426
427 @item k
428 A key sequence (@pxref{Key Sequences}). This keeps reading events
429 until a command (or undefined command) is found in the current key
430 maps. The key sequence argument is represented as a string or vector.
431 The cursor does not move into the echo area. Prompt.
432
433 If @samp{k} reads a key sequence that ends with a down-event, it also
434 reads and discards the following up-event. You can get access to that
435 up-event with the @samp{U} code character.
436
437 This kind of input is used by commands such as @code{describe-key} and
438 @code{global-set-key}.
439
440 @item K
441 A key sequence, whose definition you intend to change. This works like
442 @samp{k}, except that it suppresses, for the last input event in the key
443 sequence, the conversions that are normally used (when necessary) to
444 convert an undefined key into a defined one.
445
446 @item m
447 @cindex marker argument
448 The position of the mark, as an integer. No I/O.
449
450 @item M
451 Arbitrary text, read in the minibuffer using the current buffer's input
452 method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
453 Emacs Manual}). Prompt.
454
455 @item n
456 A number, read with the minibuffer. If the input is not a number, the
457 user has to try again. @samp{n} never uses the prefix argument.
458 Prompt.
459
460 @item N
461 The numeric prefix argument; but if there is no prefix argument, read
462 a number as with @kbd{n}. The value is always a number. @xref{Prefix
463 Command Arguments}. Prompt.
464
465 @item p
466 @cindex numeric prefix argument usage
467 The numeric prefix argument. (Note that this @samp{p} is lower case.)
468 No I/O.
469
470 @item P
471 @cindex raw prefix argument usage
472 The raw prefix argument. (Note that this @samp{P} is upper case.) No
473 I/O.
474
475 @item r
476 @cindex region argument
477 Point and the mark, as two numeric arguments, smallest first. This is
478 the only code letter that specifies two successive arguments rather than
479 one. No I/O.
480
481 @item s
482 Arbitrary text, read in the minibuffer and returned as a string
483 (@pxref{Text from Minibuffer}). Terminate the input with either
484 @kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of
485 these characters in the input.) Prompt.
486
487 @item S
488 An interned symbol whose name is read in the minibuffer. Terminate
489 the input with either @kbd{C-j} or @key{RET}. Other characters that
490 normally terminate a symbol (e.g., whitespace, parentheses and
491 brackets) do not do so here. Prompt.
492
493 @item U
494 A key sequence or @code{nil}. Can be used after a @samp{k} or
495 @samp{K} argument to get the up-event that was discarded (if any)
496 after @samp{k} or @samp{K} read a down-event. If no up-event has been
497 discarded, @samp{U} provides @code{nil} as the argument. No I/O.
498
499 @item v
500 A variable declared to be a user option (i.e., satisfying the
501 predicate @code{custom-variable-p}). This reads the variable using
502 @code{read-variable}. @xref{Definition of read-variable}. Existing,
503 Completion, Prompt.
504
505 @item x
506 A Lisp object, specified with its read syntax, terminated with a
507 @kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from
508 Minibuffer}. Prompt.
509
510 @item X
511 @cindex evaluated expression argument
512 A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates
513 the form so that its value becomes the argument for the command.
514 Prompt.
515
516 @item z
517 A coding system name (a symbol). If the user enters null input, the
518 argument value is @code{nil}. @xref{Coding Systems}. Completion,
519 Existing, Prompt.
520
521 @item Z
522 A coding system name (a symbol)---but only if this command has a prefix
523 argument. With no prefix argument, @samp{Z} provides @code{nil} as the
524 argument value. Completion, Existing, Prompt.
525 @end table
526
527 @node Interactive Examples
528 @subsection Examples of Using @code{interactive}
529 @cindex examples of using @code{interactive}
530 @cindex @code{interactive}, examples of using
531
532 Here are some examples of @code{interactive}:
533
534 @example
535 @group
536 (defun foo1 () ; @r{@code{foo1} takes no arguments,}
537 (interactive) ; @r{just moves forward two words.}
538 (forward-word 2))
539 @result{} foo1
540 @end group
541
542 @group
543 (defun foo2 (n) ; @r{@code{foo2} takes one argument,}
544 (interactive "^p") ; @r{which is the numeric prefix.}
545 ; @r{under @code{shift-select-mode},}
546 ; @r{will activate or extend region.}
547 (forward-word (* 2 n)))
548 @result{} foo2
549 @end group
550
551 @group
552 (defun foo3 (n) ; @r{@code{foo3} takes one argument,}
553 (interactive "nCount:") ; @r{which is read with the Minibuffer.}
554 (forward-word (* 2 n)))
555 @result{} foo3
556 @end group
557
558 @group
559 (defun three-b (b1 b2 b3)
560 "Select three existing buffers.
561 Put them into three windows, selecting the last one."
562 @end group
563 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
564 (delete-other-windows)
565 (split-window (selected-window) 8)
566 (switch-to-buffer b1)
567 (other-window 1)
568 (split-window (selected-window) 8)
569 (switch-to-buffer b2)
570 (other-window 1)
571 (switch-to-buffer b3))
572 @result{} three-b
573 @group
574 (three-b "*scratch*" "declarations.texi" "*mail*")
575 @result{} nil
576 @end group
577 @end example
578
579 @node Generic Commands
580 @subsection Select among Command Alternatives
581 @cindex generic commands
582 @cindex alternatives, defining
583
584 The macro @code{define-alternatives} can be used to define
585 @dfn{generic commands}. Generic commands are interactive functions
586 whose implementation can be selected among several alternatives, as a
587 matter of user preference.
588
589 @defmac define-alternatives command &rest customizations
590 Define the new command `COMMAND'.
591
592 The argument `COMMAND' should be a symbol.
593
594 When a user runs @kbd{M-x COMMAND @key{RET}} for the first time, Emacs
595 will prompt for which alternative to use and record the selected
596 command as a custom variable.
597
598 Running @kbd{C-u M-x COMMAND @key{RET}} prompts again for an
599 alternative and overwrites the previous choice.
600
601 The variable @code{COMMAND-alternatives} contains an alist
602 (@pxref{Association Lists}) with alternative implementations of
603 `COMMAND'. @code{define-alternatives} does not have any effect until
604 this variable is set.
605
606 If @var{customizations} is non-@var{nil}, it should be composed of
607 alternating @code{defcustom} keywords and values to add to the
608 declaration of @code{COMMAND-alternatives} (typically :group and
609 :version).
610 @end defmac
611
612 @node Interactive Call
613 @section Interactive Call
614 @cindex interactive call
615
616 After the command loop has translated a key sequence into a command,
617 it invokes that command using the function @code{command-execute}. If
618 the command is a function, @code{command-execute} calls
619 @code{call-interactively}, which reads the arguments and calls the
620 command. You can also call these functions yourself.
621
622 Note that the term ``command'', in this context, refers to an
623 interactively callable function (or function-like object), or a
624 keyboard macro. It does not refer to the key sequence used to invoke
625 a command (@pxref{Keymaps}).
626
627 @defun commandp object &optional for-call-interactively
628 This function returns @code{t} if @var{object} is a command.
629 Otherwise, it returns @code{nil}.
630
631 Commands include strings and vectors (which are treated as keyboard
632 macros), lambda expressions that contain a top-level
633 @code{interactive} form (@pxref{Using Interactive}), byte-code
634 function objects made from such lambda expressions, autoload objects
635 that are declared as interactive (non-@code{nil} fourth argument to
636 @code{autoload}), and some primitive functions. Also, a symbol is
637 considered a command if it has a non-@code{nil}
638 @code{interactive-form} property, or if its function definition
639 satisfies @code{commandp}.
640
641 If @var{for-call-interactively} is non-@code{nil}, then
642 @code{commandp} returns @code{t} only for objects that
643 @code{call-interactively} could call---thus, not for keyboard macros.
644
645 See @code{documentation} in @ref{Accessing Documentation}, for a
646 realistic example of using @code{commandp}.
647 @end defun
648
649 @defun call-interactively command &optional record-flag keys
650 This function calls the interactively callable function @var{command},
651 providing arguments according to its interactive calling specifications.
652 It returns whatever @var{command} returns.
653
654 If, for instance, you have a function with the following signature:
655
656 @example
657 (defun foo (begin end)
658 (interactive "r")
659 ...)
660 @end example
661
662 then saying
663
664 @example
665 (call-interactively 'foo)
666 @end example
667
668 will call @code{foo} with the region (@code{point} and @code{mark}) as
669 the arguments.
670
671 An error is signaled if @var{command} is not a function or if it
672 cannot be called interactively (i.e., is not a command). Note that
673 keyboard macros (strings and vectors) are not accepted, even though
674 they are considered commands, because they are not functions. If
675 @var{command} is a symbol, then @code{call-interactively} uses its
676 function definition.
677
678 @cindex record command history
679 If @var{record-flag} is non-@code{nil}, then this command and its
680 arguments are unconditionally added to the list @code{command-history}.
681 Otherwise, the command is added only if it uses the minibuffer to read
682 an argument. @xref{Command History}.
683
684 The argument @var{keys}, if given, should be a vector which specifies
685 the sequence of events to supply if the command inquires which events
686 were used to invoke it. If @var{keys} is omitted or @code{nil}, the
687 default is the return value of @code{this-command-keys-vector}.
688 @xref{Definition of this-command-keys-vector}.
689 @end defun
690
691 @defun command-execute command &optional record-flag keys special
692 @cindex keyboard macro execution
693 This function executes @var{command}. The argument @var{command} must
694 satisfy the @code{commandp} predicate; i.e., it must be an interactively
695 callable function or a keyboard macro.
696
697 A string or vector as @var{command} is executed with
698 @code{execute-kbd-macro}. A function is passed to
699 @code{call-interactively} (see above), along with the
700 @var{record-flag} and @var{keys} arguments.
701
702 If @var{command} is a symbol, its function definition is used in its
703 place. A symbol with an @code{autoload} definition counts as a
704 command if it was declared to stand for an interactively callable
705 function. Such a definition is handled by loading the specified
706 library and then rechecking the definition of the symbol.
707
708 The argument @var{special}, if given, means to ignore the prefix
709 argument and not clear it. This is used for executing special events
710 (@pxref{Special Events}).
711 @end defun
712
713 @deffn Command execute-extended-command prefix-argument
714 @cindex read command name
715 This function reads a command name from the minibuffer using
716 @code{completing-read} (@pxref{Completion}). Then it uses
717 @code{command-execute} to call the specified command. Whatever that
718 command returns becomes the value of @code{execute-extended-command}.
719
720 @cindex execute with prefix argument
721 If the command asks for a prefix argument, it receives the value
722 @var{prefix-argument}. If @code{execute-extended-command} is called
723 interactively, the current raw prefix argument is used for
724 @var{prefix-argument}, and thus passed on to whatever command is run.
725
726 @c !!! Should this be @kindex?
727 @cindex @kbd{M-x}
728 @code{execute-extended-command} is the normal definition of @kbd{M-x},
729 so it uses the string @w{@samp{M-x }} as a prompt. (It would be better
730 to take the prompt from the events used to invoke
731 @code{execute-extended-command}, but that is painful to implement.) A
732 description of the value of the prefix argument, if any, also becomes
733 part of the prompt.
734
735 @example
736 @group
737 (execute-extended-command 3)
738 ---------- Buffer: Minibuffer ----------
739 3 M-x forward-word RET
740 ---------- Buffer: Minibuffer ----------
741 @result{} t
742 @end group
743 @end example
744 @end deffn
745
746 @node Distinguish Interactive
747 @section Distinguish Interactive Calls
748
749 Sometimes a command should display additional visual feedback (such
750 as an informative message in the echo area) for interactive calls
751 only. There are three ways to do this. The recommended way to test
752 whether the function was called using @code{call-interactively} is to
753 give it an optional argument @code{print-message} and use the
754 @code{interactive} spec to make it non-@code{nil} in interactive
755 calls. Here's an example:
756
757 @example
758 (defun foo (&optional print-message)
759 (interactive "p")
760 (when print-message
761 (message "foo")))
762 @end example
763
764 @noindent
765 We use @code{"p"} because the numeric prefix argument is never
766 @code{nil}. Defined in this way, the function does display the
767 message when called from a keyboard macro.
768
769 The above method with the additional argument is usually best,
770 because it allows callers to say ``treat this call as interactive''.
771 But you can also do the job by testing @code{called-interactively-p}.
772
773 @defun called-interactively-p kind
774 This function returns @code{t} when the calling function was called
775 using @code{call-interactively}.
776
777 The argument @var{kind} should be either the symbol @code{interactive}
778 or the symbol @code{any}. If it is @code{interactive}, then
779 @code{called-interactively-p} returns @code{t} only if the call was
780 made directly by the user---e.g., if the user typed a key sequence
781 bound to the calling function, but @emph{not} if the user ran a
782 keyboard macro that called the function (@pxref{Keyboard Macros}). If
783 @var{kind} is @code{any}, @code{called-interactively-p} returns
784 @code{t} for any kind of interactive call, including keyboard macros.
785
786 If in doubt, use @code{any}; the only known proper use of
787 @code{interactive} is if you need to decide whether to display a
788 helpful message while a function is running.
789
790 A function is never considered to be called interactively if it was
791 called via Lisp evaluation (or with @code{apply} or @code{funcall}).
792 @end defun
793
794 @noindent
795 Here is an example of using @code{called-interactively-p}:
796
797 @example
798 @group
799 (defun foo ()
800 (interactive)
801 (when (called-interactively-p 'any)
802 (message "Interactive!")
803 'foo-called-interactively))
804 @end group
805
806 @group
807 ;; @r{Type @kbd{M-x foo}.}
808 @print{} Interactive!
809 @end group
810
811 @group
812 (foo)
813 @result{} nil
814 @end group
815 @end example
816
817 @noindent
818 Here is another example that contrasts direct and indirect calls to
819 @code{called-interactively-p}.
820
821 @example
822 @group
823 (defun bar ()
824 (interactive)
825 (message "%s" (list (foo) (called-interactively-p 'any))))
826 @end group
827
828 @group
829 ;; @r{Type @kbd{M-x bar}.}
830 @print{} (nil t)
831 @end group
832 @end example
833
834 @node Command Loop Info
835 @section Information from the Command Loop
836
837 The editor command loop sets several Lisp variables to keep status
838 records for itself and for commands that are run. With the exception of
839 @code{this-command} and @code{last-command} it's generally a bad idea to
840 change any of these variables in a Lisp program.
841
842 @defvar last-command
843 This variable records the name of the previous command executed by the
844 command loop (the one before the current command). Normally the value
845 is a symbol with a function definition, but this is not guaranteed.
846
847 The value is copied from @code{this-command} when a command returns to
848 the command loop, except when the command has specified a prefix
849 argument for the following command.
850
851 This variable is always local to the current terminal and cannot be
852 buffer-local. @xref{Multiple Terminals}.
853 @end defvar
854
855 @defvar real-last-command
856 This variable is set up by Emacs just like @code{last-command},
857 but never altered by Lisp programs.
858 @end defvar
859
860 @defvar last-repeatable-command
861 This variable stores the most recently executed command that was not
862 part of an input event. This is the command @code{repeat} will try to
863 repeat, @xref{Repeating,,, emacs, The GNU Emacs Manual}.
864 @end defvar
865
866 @defvar this-command
867 @cindex current command
868 This variable records the name of the command now being executed by
869 the editor command loop. Like @code{last-command}, it is normally a symbol
870 with a function definition.
871
872 The command loop sets this variable just before running a command, and
873 copies its value into @code{last-command} when the command finishes
874 (unless the command specified a prefix argument for the following
875 command).
876
877 @cindex kill command repetition
878 Some commands set this variable during their execution, as a flag for
879 whatever command runs next. In particular, the functions for killing text
880 set @code{this-command} to @code{kill-region} so that any kill commands
881 immediately following will know to append the killed text to the
882 previous kill.
883 @end defvar
884
885 If you do not want a particular command to be recognized as the previous
886 command in the case where it got an error, you must code that command to
887 prevent this. One way is to set @code{this-command} to @code{t} at the
888 beginning of the command, and set @code{this-command} back to its proper
889 value at the end, like this:
890
891 @example
892 (defun foo (args@dots{})
893 (interactive @dots{})
894 (let ((old-this-command this-command))
895 (setq this-command t)
896 @r{@dots{}do the work@dots{}}
897 (setq this-command old-this-command)))
898 @end example
899
900 @noindent
901 We do not bind @code{this-command} with @code{let} because that would
902 restore the old value in case of error---a feature of @code{let} which
903 in this case does precisely what we want to avoid.
904
905 @defvar this-original-command
906 This has the same value as @code{this-command} except when command
907 remapping occurs (@pxref{Remapping Commands}). In that case,
908 @code{this-command} gives the command actually run (the result of
909 remapping), and @code{this-original-command} gives the command that
910 was specified to run but remapped into another command.
911 @end defvar
912
913 @defun this-command-keys
914 This function returns a string or vector containing the key sequence
915 that invoked the present command, plus any previous commands that
916 generated the prefix argument for this command. Any events read by the
917 command using @code{read-event} without a timeout get tacked on to the end.
918
919 However, if the command has called @code{read-key-sequence}, it
920 returns the last read key sequence. @xref{Key Sequence Input}. The
921 value is a string if all events in the sequence were characters that
922 fit in a string. @xref{Input Events}.
923
924 @example
925 @group
926 (this-command-keys)
927 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
928 @result{} "^U^X^E"
929 @end group
930 @end example
931 @end defun
932
933 @defun this-command-keys-vector
934 @anchor{Definition of this-command-keys-vector}
935 Like @code{this-command-keys}, except that it always returns the events
936 in a vector, so you don't need to deal with the complexities of storing
937 input events in a string (@pxref{Strings of Events}).
938 @end defun
939
940 @defun clear-this-command-keys &optional keep-record
941 This function empties out the table of events for
942 @code{this-command-keys} to return. Unless @var{keep-record} is
943 non-@code{nil}, it also empties the records that the function
944 @code{recent-keys} (@pxref{Recording Input}) will subsequently return.
945 This is useful after reading a password, to prevent the password from
946 echoing inadvertently as part of the next command in certain cases.
947 @end defun
948
949 @defvar last-nonmenu-event
950 This variable holds the last input event read as part of a key sequence,
951 not counting events resulting from mouse menus.
952
953 One use of this variable is for telling @code{x-popup-menu} where to pop
954 up a menu. It is also used internally by @code{y-or-n-p}
955 (@pxref{Yes-or-No Queries}).
956 @end defvar
957
958 @defvar last-command-event
959 This variable is set to the last input event that was read by the
960 command loop as part of a command. The principal use of this variable
961 is in @code{self-insert-command}, which uses it to decide which
962 character to insert.
963
964 @example
965 @group
966 last-command-event
967 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
968 @result{} 5
969 @end group
970 @end example
971
972 @noindent
973 The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
974 @end defvar
975
976 @defvar last-event-frame
977 This variable records which frame the last input event was directed to.
978 Usually this is the frame that was selected when the event was
979 generated, but if that frame has redirected input focus to another
980 frame, the value is the frame to which the event was redirected.
981 @xref{Input Focus}.
982
983 If the last event came from a keyboard macro, the value is @code{macro}.
984 @end defvar
985
986 @node Adjusting Point
987 @section Adjusting Point After Commands
988 @cindex adjusting point
989 @cindex invisible/intangible text, and point
990 @cindex @code{display} property, and point display
991 @cindex @code{composition} property, and point display
992
993 It is not easy to display a value of point in the middle of a
994 sequence of text that has the @code{display}, @code{composition} or
995 is invisible. Therefore, after a command finishes and returns to the
996 command loop, if point is within such a sequence, the command loop
997 normally moves point to the edge of the sequence.
998
999 A command can inhibit this feature by setting the variable
1000 @code{disable-point-adjustment}:
1001
1002 @defvar disable-point-adjustment
1003 If this variable is non-@code{nil} when a command returns to the
1004 command loop, then the command loop does not check for those text
1005 properties, and does not move point out of sequences that have them.
1006
1007 The command loop sets this variable to @code{nil} before each command,
1008 so if a command sets it, the effect applies only to that command.
1009 @end defvar
1010
1011 @defvar global-disable-point-adjustment
1012 If you set this variable to a non-@code{nil} value, the feature of
1013 moving point out of these sequences is completely turned off.
1014 @end defvar
1015
1016 @node Input Events
1017 @section Input Events
1018 @cindex events
1019 @cindex input events
1020
1021 The Emacs command loop reads a sequence of @dfn{input events} that
1022 represent keyboard or mouse activity, or system events sent to Emacs.
1023 The events for keyboard activity are characters or symbols; other
1024 events are always lists. This section describes the representation
1025 and meaning of input events in detail.
1026
1027 @defun eventp object
1028 This function returns non-@code{nil} if @var{object} is an input event
1029 or event type.
1030
1031 Note that any symbol might be used as an event or an event type.
1032 @code{eventp} cannot distinguish whether a symbol is intended by Lisp
1033 code to be used as an event. Instead, it distinguishes whether the
1034 symbol has actually been used in an event that has been read as input in
1035 the current Emacs session. If a symbol has not yet been so used,
1036 @code{eventp} returns @code{nil}.
1037 @end defun
1038
1039 @menu
1040 * Keyboard Events:: Ordinary characters--keys with symbols on them.
1041 * Function Keys:: Function keys--keys with names, not symbols.
1042 * Mouse Events:: Overview of mouse events.
1043 * Click Events:: Pushing and releasing a mouse button.
1044 * Drag Events:: Moving the mouse before releasing the button.
1045 * Button-Down Events:: A button was pushed and not yet released.
1046 * Repeat Events:: Double and triple click (or drag, or down).
1047 * Motion Events:: Just moving the mouse, not pushing a button.
1048 * Focus Events:: Moving the mouse between frames.
1049 * Misc Events:: Other events the system can generate.
1050 * Event Examples:: Examples of the lists for mouse events.
1051 * Classifying Events:: Finding the modifier keys in an event symbol.
1052 Event types.
1053 * Accessing Mouse:: Functions to extract info from mouse events.
1054 * Accessing Scroll:: Functions to get info from scroll bar events.
1055 * Strings of Events:: Special considerations for putting
1056 keyboard character events in a string.
1057 @end menu
1058
1059 @node Keyboard Events
1060 @subsection Keyboard Events
1061 @cindex keyboard events
1062
1063 There are two kinds of input you can get from the keyboard: ordinary
1064 keys, and function keys. Ordinary keys correspond to characters; the
1065 events they generate are represented in Lisp as characters. The event
1066 type of a character event is the character itself (an integer); see
1067 @ref{Classifying Events}.
1068
1069 @cindex modifier bits (of input character)
1070 @cindex basic code (of input character)
1071 An input character event consists of a @dfn{basic code} between 0 and
1072 524287, plus any or all of these @dfn{modifier bits}:
1073
1074 @table @asis
1075 @item meta
1076 The
1077 @tex
1078 @math{2^{27}}
1079 @end tex
1080 @ifnottex
1081 2**27
1082 @end ifnottex
1083 bit in the character code indicates a character
1084 typed with the meta key held down.
1085
1086 @item control
1087 The
1088 @tex
1089 @math{2^{26}}
1090 @end tex
1091 @ifnottex
1092 2**26
1093 @end ifnottex
1094 bit in the character code indicates a non-@acronym{ASCII}
1095 control character.
1096
1097 @sc{ascii} control characters such as @kbd{C-a} have special basic
1098 codes of their own, so Emacs needs no special bit to indicate them.
1099 Thus, the code for @kbd{C-a} is just 1.
1100
1101 But if you type a control combination not in @acronym{ASCII}, such as
1102 @kbd{%} with the control key, the numeric value you get is the code
1103 for @kbd{%} plus
1104 @tex
1105 @math{2^{26}}
1106 @end tex
1107 @ifnottex
1108 2**26
1109 @end ifnottex
1110 (assuming the terminal supports non-@acronym{ASCII}
1111 control characters).
1112
1113 @item shift
1114 The
1115 @tex
1116 @math{2^{25}}
1117 @end tex
1118 @ifnottex
1119 2**25
1120 @end ifnottex
1121 bit in the character code indicates an @acronym{ASCII} control
1122 character typed with the shift key held down.
1123
1124 For letters, the basic code itself indicates upper versus lower case;
1125 for digits and punctuation, the shift key selects an entirely different
1126 character with a different basic code. In order to keep within the
1127 @acronym{ASCII} character set whenever possible, Emacs avoids using the
1128 @tex
1129 @math{2^{25}}
1130 @end tex
1131 @ifnottex
1132 2**25
1133 @end ifnottex
1134 bit for those characters.
1135
1136 However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
1137 @kbd{C-a}, so Emacs uses the
1138 @tex
1139 @math{2^{25}}
1140 @end tex
1141 @ifnottex
1142 2**25
1143 @end ifnottex
1144 bit in @kbd{C-A} and not in
1145 @kbd{C-a}.
1146
1147 @item hyper
1148 The
1149 @tex
1150 @math{2^{24}}
1151 @end tex
1152 @ifnottex
1153 2**24
1154 @end ifnottex
1155 bit in the character code indicates a character
1156 typed with the hyper key held down.
1157
1158 @item super
1159 The
1160 @tex
1161 @math{2^{23}}
1162 @end tex
1163 @ifnottex
1164 2**23
1165 @end ifnottex
1166 bit in the character code indicates a character
1167 typed with the super key held down.
1168
1169 @item alt
1170 The
1171 @tex
1172 @math{2^{22}}
1173 @end tex
1174 @ifnottex
1175 2**22
1176 @end ifnottex
1177 bit in the character code indicates a character typed with the alt key
1178 held down. (The key labeled @key{Alt} on most keyboards is actually
1179 treated as the meta key, not this.)
1180 @end table
1181
1182 It is best to avoid mentioning specific bit numbers in your program.
1183 To test the modifier bits of a character, use the function
1184 @code{event-modifiers} (@pxref{Classifying Events}). When making key
1185 bindings, you can use the read syntax for characters with modifier bits
1186 (@samp{\C-}, @samp{\M-}, and so on). For making key bindings with
1187 @code{define-key}, you can use lists such as @code{(control hyper ?x)} to
1188 specify the characters (@pxref{Changing Key Bindings}). The function
1189 @code{event-convert-list} converts such a list into an event type
1190 (@pxref{Classifying Events}).
1191
1192 @node Function Keys
1193 @subsection Function Keys
1194
1195 @cindex function keys
1196 Most keyboards also have @dfn{function keys}---keys that have names or
1197 symbols that are not characters. Function keys are represented in
1198 Emacs Lisp as symbols; the symbol's name is the function key's label,
1199 in lower case. For example, pressing a key labeled @key{F1} generates
1200 an input event represented by the symbol @code{f1}.
1201
1202 The event type of a function key event is the event symbol itself.
1203 @xref{Classifying Events}.
1204
1205 Here are a few special cases in the symbol-naming convention for
1206 function keys:
1207
1208 @table @asis
1209 @item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
1210 These keys correspond to common @acronym{ASCII} control characters that have
1211 special keys on most keyboards.
1212
1213 In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the
1214 terminal can distinguish between them, Emacs conveys the distinction to
1215 Lisp programs by representing the former as the integer 9, and the
1216 latter as the symbol @code{tab}.
1217
1218 Most of the time, it's not useful to distinguish the two. So normally
1219 @code{local-function-key-map} (@pxref{Translation Keymaps}) is set up
1220 to map @code{tab} into 9. Thus, a key binding for character code 9
1221 (the character @kbd{C-i}) also applies to @code{tab}. Likewise for
1222 the other symbols in this group. The function @code{read-char}
1223 likewise converts these events into characters.
1224
1225 In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace}
1226 converts into the character code 127 (@key{DEL}), not into code 8
1227 (@key{BS}). This is what most users prefer.
1228
1229 @item @code{left}, @code{up}, @code{right}, @code{down}
1230 Cursor arrow keys
1231 @item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
1232 Keypad keys (to the right of the regular keyboard).
1233 @item @code{kp-0}, @code{kp-1}, @dots{}
1234 Keypad keys with digits.
1235 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
1236 Keypad PF keys.
1237 @item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
1238 Keypad arrow keys. Emacs normally translates these into the
1239 corresponding non-keypad keys @code{home}, @code{left}, @dots{}
1240 @item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
1241 Additional keypad duplicates of keys ordinarily found elsewhere. Emacs
1242 normally translates these into the like-named non-keypad keys.
1243 @end table
1244
1245 You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
1246 @key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to
1247 represent them is with prefixes in the symbol name:
1248
1249 @table @samp
1250 @item A-
1251 The alt modifier.
1252 @item C-
1253 The control modifier.
1254 @item H-
1255 The hyper modifier.
1256 @item M-
1257 The meta modifier.
1258 @item S-
1259 The shift modifier.
1260 @item s-
1261 The super modifier.
1262 @end table
1263
1264 Thus, the symbol for the key @key{F3} with @key{META} held down is
1265 @code{M-f3}. When you use more than one prefix, we recommend you
1266 write them in alphabetical order; but the order does not matter in
1267 arguments to the key-binding lookup and modification functions.
1268
1269 @node Mouse Events
1270 @subsection Mouse Events
1271
1272 Emacs supports four kinds of mouse events: click events, drag events,
1273 button-down events, and motion events. All mouse events are represented
1274 as lists. The @sc{car} of the list is the event type; this says which
1275 mouse button was involved, and which modifier keys were used with it.
1276 The event type can also distinguish double or triple button presses
1277 (@pxref{Repeat Events}). The rest of the list elements give position
1278 and time information.
1279
1280 For key lookup, only the event type matters: two events of the same type
1281 necessarily run the same command. The command can access the full
1282 values of these events using the @samp{e} interactive code.
1283 @xref{Interactive Codes}.
1284
1285 A key sequence that starts with a mouse event is read using the keymaps
1286 of the buffer in the window that the mouse was in, not the current
1287 buffer. This does not imply that clicking in a window selects that
1288 window or its buffer---that is entirely under the control of the command
1289 binding of the key sequence.
1290
1291 @node Click Events
1292 @subsection Click Events
1293 @cindex click event
1294 @cindex mouse click event
1295
1296 When the user presses a mouse button and releases it at the same
1297 location, that generates a @dfn{click} event. All mouse click event
1298 share the same format:
1299
1300 @example
1301 (@var{event-type} @var{position} @var{click-count})
1302 @end example
1303
1304 @table @asis
1305 @item @var{event-type}
1306 This is a symbol that indicates which mouse button was used. It is
1307 one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the
1308 buttons are numbered left to right.
1309
1310 You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-},
1311 @samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift
1312 and super, just as you would with function keys.
1313
1314 This symbol also serves as the event type of the event. Key bindings
1315 describe events by their types; thus, if there is a key binding for
1316 @code{mouse-1}, that binding would apply to all events whose
1317 @var{event-type} is @code{mouse-1}.
1318
1319 @item @var{position}
1320 @cindex mouse position list
1321 This is a @dfn{mouse position list} specifying where the mouse click
1322 occurred; see below for details.
1323
1324 @item @var{click-count}
1325 This is the number of rapid repeated presses so far of the same mouse
1326 button. @xref{Repeat Events}.
1327 @end table
1328
1329 To access the contents of a mouse position list in the
1330 @var{position} slot of a click event, you should typically use the
1331 functions documented in @ref{Accessing Mouse}. The explicit format of
1332 the list depends on where the click occurred. For clicks in the text
1333 area, mode line, header line, or in the fringe or marginal areas, the
1334 mouse position list has the form
1335
1336 @example
1337 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
1338 @var{object} @var{text-pos} (@var{col} . @var{row})
1339 @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
1340 @end example
1341
1342 @noindent
1343 The meanings of these list elements are as follows:
1344
1345 @table @asis
1346 @item @var{window}
1347 The window in which the click occurred.
1348
1349 @item @var{pos-or-area}
1350 The buffer position of the character clicked on in the text area; or,
1351 if the click was outside the text area, the window area where it
1352 occurred. It is one of the symbols @code{mode-line},
1353 @code{header-line}, @code{vertical-line}, @code{left-margin},
1354 @code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
1355
1356 In one special case, @var{pos-or-area} is a list containing a symbol
1357 (one of the symbols listed above) instead of just the symbol. This
1358 happens after the imaginary prefix keys for the event are registered
1359 by Emacs. @xref{Key Sequence Input}.
1360
1361 @item @var{x}, @var{y}
1362 The relative pixel coordinates of the click. For clicks in the text
1363 area of a window, the coordinate origin @code{(0 . 0)} is taken to be
1364 the top left corner of the text area. @xref{Window Sizes}. For
1365 clicks in a mode line or header line, the coordinate origin is the top
1366 left corner of the window itself. For fringes, margins, and the
1367 vertical border, @var{x} does not have meaningful data. For fringes
1368 and margins, @var{y} is relative to the bottom edge of the header
1369 line. In all cases, the @var{x} and @var{y} coordinates increase
1370 rightward and downward respectively.
1371
1372 @item @var{timestamp}
1373 The time at which the event occurred, as an integer number of
1374 milliseconds since a system-dependent initial time.
1375
1376 @item @var{object}
1377 Either @code{nil} if there is no string-type text property at the
1378 click position, or a cons cell of the form (@var{string}
1379 . @var{string-pos}) if there is one:
1380
1381 @table @asis
1382 @item @var{string}
1383 The string which was clicked on, including any properties.
1384
1385 @item @var{string-pos}
1386 The position in the string where the click occurred.
1387 @end table
1388
1389 @item @var{text-pos}
1390 For clicks on a marginal area or on a fringe, this is the buffer
1391 position of the first visible character in the corresponding line in
1392 the window. For other events, it is the current buffer position in
1393 the window.
1394
1395 @item @var{col}, @var{row}
1396 These are the actual column and row coordinate numbers of the glyph
1397 under the @var{x}, @var{y} position. If @var{x} lies beyond the last
1398 column of actual text on its line, @var{col} is reported by adding
1399 fictional extra columns that have the default character width. Row 0
1400 is taken to be the header line if the window has one, or the topmost
1401 row of the text area otherwise. Column 0 is taken to be the leftmost
1402 column of the text area for clicks on a window text area, or the
1403 leftmost mode line or header line column for clicks there. For clicks
1404 on fringes or vertical borders, these have no meaningful data. For
1405 clicks on margins, @var{col} is measured from the left edge of the
1406 margin area and @var{row} is measured from the top of the margin area.
1407
1408 @item @var{image}
1409 This is the image object on which the click occurred. It is either
1410 @code{nil} if there is no image at the position clicked on, or it is
1411 an image object as returned by @code{find-image} if click was in an image.
1412
1413 @item @var{dx}, @var{dy}
1414 These are the pixel coordinates of the click, relative to
1415 the top left corner of @var{object}, which is @code{(0 . 0)}. If
1416 @var{object} is @code{nil}, the coordinates are relative to the top
1417 left corner of the character glyph clicked on.
1418
1419 @item @var{width}, @var{height}
1420 These are the pixel width and height of @var{object} or, if this is
1421 @code{nil}, those of the character glyph clicked on.
1422 @end table
1423
1424 For clicks on a scroll bar, @var{position} has this form:
1425
1426 @example
1427 (@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
1428 @end example
1429
1430 @table @asis
1431 @item @var{window}
1432 The window whose scroll bar was clicked on.
1433
1434 @item @var{area}
1435 This is the symbol @code{vertical-scroll-bar}.
1436
1437 @item @var{portion}
1438 The number of pixels from the top of the scroll bar to the click
1439 position. On some toolkits, including GTK+, Emacs cannot extract this
1440 data, so the value is always @code{0}.
1441
1442 @item @var{whole}
1443 The total length, in pixels, of the scroll bar. On some toolkits,
1444 including GTK+, Emacs cannot extract this data, so the value is always
1445 @code{0}.
1446
1447 @item @var{timestamp}
1448 The time at which the event occurred, in milliseconds. On some
1449 toolkits, including GTK+, Emacs cannot extract this data, so the value
1450 is always @code{0}.
1451
1452 @item @var{part}
1453 The part of the scroll bar on which the click occurred. It is one of
1454 the symbols @code{handle} (the scroll bar handle), @code{above-handle}
1455 (the area above the handle), @code{below-handle} (the area below the
1456 handle), @code{up} (the up arrow at one end of the scroll bar), or
1457 @code{down} (the down arrow at one end of the scroll bar).
1458 @c The `top', `bottom', and `end-scroll' codes don't seem to be used.
1459 @end table
1460
1461
1462 @node Drag Events
1463 @subsection Drag Events
1464 @cindex drag event
1465 @cindex mouse drag event
1466
1467 With Emacs, you can have a drag event without even changing your
1468 clothes. A @dfn{drag event} happens every time the user presses a mouse
1469 button and then moves the mouse to a different character position before
1470 releasing the button. Like all mouse events, drag events are
1471 represented in Lisp as lists. The lists record both the starting mouse
1472 position and the final position, like this:
1473
1474 @example
1475 (@var{event-type}
1476 (@var{window1} START-POSITION)
1477 (@var{window2} END-POSITION))
1478 @end example
1479
1480 For a drag event, the name of the symbol @var{event-type} contains the
1481 prefix @samp{drag-}. For example, dragging the mouse with button 2
1482 held down generates a @code{drag-mouse-2} event. The second and third
1483 elements of the event give the starting and ending position of the
1484 drag, as mouse position lists (@pxref{Click Events}). You can access
1485 the second element of any mouse event in the same way, with no need to
1486 distinguish drag events from others.
1487
1488 The @samp{drag-} prefix follows the modifier key prefixes such as
1489 @samp{C-} and @samp{M-}.
1490
1491 If @code{read-key-sequence} receives a drag event that has no key
1492 binding, and the corresponding click event does have a binding, it
1493 changes the drag event into a click event at the drag's starting
1494 position. This means that you don't have to distinguish between click
1495 and drag events unless you want to.
1496
1497 @node Button-Down Events
1498 @subsection Button-Down Events
1499 @cindex button-down event
1500
1501 Click and drag events happen when the user releases a mouse button.
1502 They cannot happen earlier, because there is no way to distinguish a
1503 click from a drag until the button is released.
1504
1505 If you want to take action as soon as a button is pressed, you need to
1506 handle @dfn{button-down} events.@footnote{Button-down is the
1507 conservative antithesis of drag.} These occur as soon as a button is
1508 pressed. They are represented by lists that look exactly like click
1509 events (@pxref{Click Events}), except that the @var{event-type} symbol
1510 name contains the prefix @samp{down-}. The @samp{down-} prefix follows
1511 modifier key prefixes such as @samp{C-} and @samp{M-}.
1512
1513 The function @code{read-key-sequence} ignores any button-down events
1514 that don't have command bindings; therefore, the Emacs command loop
1515 ignores them too. This means that you need not worry about defining
1516 button-down events unless you want them to do something. The usual
1517 reason to define a button-down event is so that you can track mouse
1518 motion (by reading motion events) until the button is released.
1519 @xref{Motion Events}.
1520
1521 @node Repeat Events
1522 @subsection Repeat Events
1523 @cindex repeat events
1524 @cindex double-click events
1525 @cindex triple-click events
1526 @cindex mouse events, repeated
1527
1528 If you press the same mouse button more than once in quick succession
1529 without moving the mouse, Emacs generates special @dfn{repeat} mouse
1530 events for the second and subsequent presses.
1531
1532 The most common repeat events are @dfn{double-click} events. Emacs
1533 generates a double-click event when you click a button twice; the event
1534 happens when you release the button (as is normal for all click
1535 events).
1536
1537 The event type of a double-click event contains the prefix
1538 @samp{double-}. Thus, a double click on the second mouse button with
1539 @key{meta} held down comes to the Lisp program as
1540 @code{M-double-mouse-2}. If a double-click event has no binding, the
1541 binding of the corresponding ordinary click event is used to execute
1542 it. Thus, you need not pay attention to the double click feature
1543 unless you really want to.
1544
1545 When the user performs a double click, Emacs generates first an ordinary
1546 click event, and then a double-click event. Therefore, you must design
1547 the command binding of the double click event to assume that the
1548 single-click command has already run. It must produce the desired
1549 results of a double click, starting from the results of a single click.
1550
1551 This is convenient, if the meaning of a double click somehow ``builds
1552 on'' the meaning of a single click---which is recommended user interface
1553 design practice for double clicks.
1554
1555 If you click a button, then press it down again and start moving the
1556 mouse with the button held down, then you get a @dfn{double-drag} event
1557 when you ultimately release the button. Its event type contains
1558 @samp{double-drag} instead of just @samp{drag}. If a double-drag event
1559 has no binding, Emacs looks for an alternate binding as if the event
1560 were an ordinary drag.
1561
1562 Before the double-click or double-drag event, Emacs generates a
1563 @dfn{double-down} event when the user presses the button down for the
1564 second time. Its event type contains @samp{double-down} instead of just
1565 @samp{down}. If a double-down event has no binding, Emacs looks for an
1566 alternate binding as if the event were an ordinary button-down event.
1567 If it finds no binding that way either, the double-down event is
1568 ignored.
1569
1570 To summarize, when you click a button and then press it again right
1571 away, Emacs generates a down event and a click event for the first
1572 click, a double-down event when you press the button again, and finally
1573 either a double-click or a double-drag event.
1574
1575 If you click a button twice and then press it again, all in quick
1576 succession, Emacs generates a @dfn{triple-down} event, followed by
1577 either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of
1578 these events contain @samp{triple} instead of @samp{double}. If any
1579 triple event has no binding, Emacs uses the binding that it would use
1580 for the corresponding double event.
1581
1582 If you click a button three or more times and then press it again, the
1583 events for the presses beyond the third are all triple events. Emacs
1584 does not have separate event types for quadruple, quintuple, etc.@:
1585 events. However, you can look at the event list to find out precisely
1586 how many times the button was pressed.
1587
1588 @defun event-click-count event
1589 This function returns the number of consecutive button presses that led
1590 up to @var{event}. If @var{event} is a double-down, double-click or
1591 double-drag event, the value is 2. If @var{event} is a triple event,
1592 the value is 3 or greater. If @var{event} is an ordinary mouse event
1593 (not a repeat event), the value is 1.
1594 @end defun
1595
1596 @defopt double-click-fuzz
1597 To generate repeat events, successive mouse button presses must be at
1598 approximately the same screen position. The value of
1599 @code{double-click-fuzz} specifies the maximum number of pixels the
1600 mouse may be moved (horizontally or vertically) between two successive
1601 clicks to make a double-click.
1602
1603 This variable is also the threshold for motion of the mouse to count
1604 as a drag.
1605 @end defopt
1606
1607 @defopt double-click-time
1608 To generate repeat events, the number of milliseconds between
1609 successive button presses must be less than the value of
1610 @code{double-click-time}. Setting @code{double-click-time} to
1611 @code{nil} disables multi-click detection entirely. Setting it to
1612 @code{t} removes the time limit; Emacs then detects multi-clicks by
1613 position only.
1614 @end defopt
1615
1616 @node Motion Events
1617 @subsection Motion Events
1618 @cindex motion event
1619 @cindex mouse motion events
1620
1621 Emacs sometimes generates @dfn{mouse motion} events to describe motion
1622 of the mouse without any button activity. Mouse motion events are
1623 represented by lists that look like this:
1624
1625 @example
1626 (mouse-movement POSITION)
1627 @end example
1628
1629 @noindent
1630 @var{position} is a mouse position list (@pxref{Click Events}),
1631 specifying the current position of the mouse cursor.
1632
1633 The special form @code{track-mouse} enables generation of motion
1634 events within its body. Outside of @code{track-mouse} forms, Emacs
1635 does not generate events for mere motion of the mouse, and these
1636 events do not appear. @xref{Mouse Tracking}.
1637
1638 @node Focus Events
1639 @subsection Focus Events
1640 @cindex focus event
1641
1642 Window systems provide general ways for the user to control which window
1643 gets keyboard input. This choice of window is called the @dfn{focus}.
1644 When the user does something to switch between Emacs frames, that
1645 generates a @dfn{focus event}. The normal definition of a focus event,
1646 in the global keymap, is to select a new frame within Emacs, as the user
1647 would expect. @xref{Input Focus}.
1648
1649 Focus events are represented in Lisp as lists that look like this:
1650
1651 @example
1652 (switch-frame @var{new-frame})
1653 @end example
1654
1655 @noindent
1656 where @var{new-frame} is the frame switched to.
1657
1658 Some X window managers are set up so that just moving the mouse into a
1659 window is enough to set the focus there. Usually, there is no need
1660 for a Lisp program to know about the focus change until some other
1661 kind of input arrives. Emacs generates a focus event only when the
1662 user actually types a keyboard key or presses a mouse button in the
1663 new frame; just moving the mouse between frames does not generate a
1664 focus event.
1665
1666 A focus event in the middle of a key sequence would garble the
1667 sequence. So Emacs never generates a focus event in the middle of a key
1668 sequence. If the user changes focus in the middle of a key
1669 sequence---that is, after a prefix key---then Emacs reorders the events
1670 so that the focus event comes either before or after the multi-event key
1671 sequence, and not within it.
1672
1673 @node Misc Events
1674 @subsection Miscellaneous System Events
1675
1676 A few other event types represent occurrences within the system.
1677
1678 @table @code
1679 @cindex @code{delete-frame} event
1680 @item (delete-frame (@var{frame}))
1681 This kind of event indicates that the user gave the window manager
1682 a command to delete a particular window, which happens to be an Emacs frame.
1683
1684 The standard definition of the @code{delete-frame} event is to delete @var{frame}.
1685
1686 @cindex @code{iconify-frame} event
1687 @item (iconify-frame (@var{frame}))
1688 This kind of event indicates that the user iconified @var{frame} using
1689 the window manager. Its standard definition is @code{ignore}; since the
1690 frame has already been iconified, Emacs has no work to do. The purpose
1691 of this event type is so that you can keep track of such events if you
1692 want to.
1693
1694 @cindex @code{make-frame-visible} event
1695 @item (make-frame-visible (@var{frame}))
1696 This kind of event indicates that the user deiconified @var{frame} using
1697 the window manager. Its standard definition is @code{ignore}; since the
1698 frame has already been made visible, Emacs has no work to do.
1699
1700 @cindex @code{wheel-up} event
1701 @cindex @code{wheel-down} event
1702 @item (wheel-up @var{position})
1703 @itemx (wheel-down @var{position})
1704 These kinds of event are generated by moving a mouse wheel. The
1705 @var{position} element is a mouse position list (@pxref{Click
1706 Events}), specifying the position of the mouse cursor when the event
1707 occurred.
1708
1709 @vindex mouse-wheel-up-event
1710 @vindex mouse-wheel-down-event
1711 This kind of event is generated only on some kinds of systems. On some
1712 systems, @code{mouse-4} and @code{mouse-5} are used instead. For
1713 portable code, use the variables @code{mouse-wheel-up-event} and
1714 @code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine
1715 what event types to expect for the mouse wheel.
1716
1717 @cindex @code{drag-n-drop} event
1718 @item (drag-n-drop @var{position} @var{files})
1719 This kind of event is generated when a group of files is
1720 selected in an application outside of Emacs, and then dragged and
1721 dropped onto an Emacs frame.
1722
1723 The element @var{position} is a list describing the position of the
1724 event, in the same format as used in a mouse-click event (@pxref{Click
1725 Events}), and @var{files} is the list of file names that were dragged
1726 and dropped. The usual way to handle this event is by visiting these
1727 files.
1728
1729 This kind of event is generated, at present, only on some kinds of
1730 systems.
1731
1732 @cindex @code{help-echo} event
1733 @item help-echo
1734 This kind of event is generated when a mouse pointer moves onto a
1735 portion of buffer text which has a @code{help-echo} text property.
1736 The generated event has this form:
1737
1738 @example
1739 (help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos})
1740 @end example
1741
1742 @noindent
1743 The precise meaning of the event parameters and the way these
1744 parameters are used to display the help-echo text are described in
1745 @ref{Text help-echo}.
1746
1747 @cindex @code{sigusr1} event
1748 @cindex @code{sigusr2} event
1749 @cindex user signals
1750 @item sigusr1
1751 @itemx sigusr2
1752 These events are generated when the Emacs process receives
1753 the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no
1754 additional data because signals do not carry additional information.
1755 They can be useful for debugging (@pxref{Error Debugging}).
1756
1757 To catch a user signal, bind the corresponding event to an interactive
1758 command in the @code{special-event-map} (@pxref{Active Keymaps}).
1759 The command is called with no arguments, and the specific signal event is
1760 available in @code{last-input-event}. For example:
1761
1762 @smallexample
1763 (defun sigusr-handler ()
1764 (interactive)
1765 (message "Caught signal %S" last-input-event))
1766
1767 (define-key special-event-map [sigusr1] 'sigusr-handler)
1768 @end smallexample
1769
1770 To test the signal handler, you can make Emacs send a signal to itself:
1771
1772 @smallexample
1773 (signal-process (emacs-pid) 'sigusr1)
1774 @end smallexample
1775
1776 @cindex @code{language-change} event
1777 @item language-change
1778 This kind of event is generated on MS-Windows when the input language
1779 has changed. This typically means that the keyboard keys will send to
1780 Emacs characters from a different language. The generated event has
1781 this form:
1782
1783 @smallexample
1784 (language-change @var{frame} @var{codepage} @var{language-id})
1785 @end smallexample
1786
1787 @noindent
1788 Here @var{frame} is the frame which was current when the input
1789 language changed; @var{codepage} is the new codepage number; and
1790 @var{language-id} is the numerical ID of the new input language. The
1791 coding-system (@pxref{Coding Systems}) that corresponds to
1792 @var{codepage} is @code{cp@var{codepage}} or
1793 @code{windows-@var{codepage}}. To convert @var{language-id} to a
1794 string (e.g., to use it for various language-dependent features, such
1795 as @code{set-language-environment}), use the
1796 @code{w32-get-locale-info} function, like this:
1797
1798 @smallexample
1799 ;; Get the abbreviated language name, such as "ENU" for English
1800 (w32-get-locale-info language-id)
1801 ;; Get the full English name of the language,
1802 ;; such as "English (United States)"
1803 (w32-get-locale-info language-id 4097)
1804 ;; Get the full localized name of the language
1805 (w32-get-locale-info language-id t)
1806 @end smallexample
1807 @end table
1808
1809 If one of these events arrives in the middle of a key sequence---that
1810 is, after a prefix key---then Emacs reorders the events so that this
1811 event comes either before or after the multi-event key sequence, not
1812 within it.
1813
1814 @node Event Examples
1815 @subsection Event Examples
1816
1817 If the user presses and releases the left mouse button over the same
1818 location, that generates a sequence of events like this:
1819
1820 @smallexample
1821 (down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
1822 (mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180))
1823 @end smallexample
1824
1825 While holding the control key down, the user might hold down the
1826 second mouse button, and drag the mouse from one line to the next.
1827 That produces two events, as shown here:
1828
1829 @smallexample
1830 (C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
1831 (C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
1832 (#<window 18 on NEWS> 3510 (0 . 28) -729648))
1833 @end smallexample
1834
1835 While holding down the meta and shift keys, the user might press the
1836 second mouse button on the window's mode line, and then drag the mouse
1837 into another window. That produces a pair of events like these:
1838
1839 @smallexample
1840 (M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
1841 (M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
1842 (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
1843 -453816))
1844 @end smallexample
1845
1846 To handle a SIGUSR1 signal, define an interactive function, and
1847 bind it to the @code{signal usr1} event sequence:
1848
1849 @smallexample
1850 (defun usr1-handler ()
1851 (interactive)
1852 (message "Got USR1 signal"))
1853 (global-set-key [signal usr1] 'usr1-handler)
1854 @end smallexample
1855
1856 @node Classifying Events
1857 @subsection Classifying Events
1858 @cindex event type
1859
1860 Every event has an @dfn{event type}, which classifies the event for
1861 key binding purposes. For a keyboard event, the event type equals the
1862 event value; thus, the event type for a character is the character, and
1863 the event type for a function key symbol is the symbol itself. For
1864 events that are lists, the event type is the symbol in the @sc{car} of
1865 the list. Thus, the event type is always a symbol or a character.
1866
1867 Two events of the same type are equivalent where key bindings are
1868 concerned; thus, they always run the same command. That does not
1869 necessarily mean they do the same things, however, as some commands look
1870 at the whole event to decide what to do. For example, some commands use
1871 the location of a mouse event to decide where in the buffer to act.
1872
1873 Sometimes broader classifications of events are useful. For example,
1874 you might want to ask whether an event involved the @key{META} key,
1875 regardless of which other key or mouse button was used.
1876
1877 The functions @code{event-modifiers} and @code{event-basic-type} are
1878 provided to get such information conveniently.
1879
1880 @defun event-modifiers event
1881 This function returns a list of the modifiers that @var{event} has. The
1882 modifiers are symbols; they include @code{shift}, @code{control},
1883 @code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition,
1884 the modifiers list of a mouse event symbol always contains one of
1885 @code{click}, @code{drag}, and @code{down}. For double or triple
1886 events, it also contains @code{double} or @code{triple}.
1887
1888 The argument @var{event} may be an entire event object, or just an
1889 event type. If @var{event} is a symbol that has never been used in an
1890 event that has been read as input in the current Emacs session, then
1891 @code{event-modifiers} can return @code{nil}, even when @var{event}
1892 actually has modifiers.
1893
1894 Here are some examples:
1895
1896 @example
1897 (event-modifiers ?a)
1898 @result{} nil
1899 (event-modifiers ?A)
1900 @result{} (shift)
1901 (event-modifiers ?\C-a)
1902 @result{} (control)
1903 (event-modifiers ?\C-%)
1904 @result{} (control)
1905 (event-modifiers ?\C-\S-a)
1906 @result{} (control shift)
1907 (event-modifiers 'f5)
1908 @result{} nil
1909 (event-modifiers 's-f5)
1910 @result{} (super)
1911 (event-modifiers 'M-S-f5)
1912 @result{} (meta shift)
1913 (event-modifiers 'mouse-1)
1914 @result{} (click)
1915 (event-modifiers 'down-mouse-1)
1916 @result{} (down)
1917 @end example
1918
1919 The modifiers list for a click event explicitly contains @code{click},
1920 but the event symbol name itself does not contain @samp{click}.
1921 @end defun
1922
1923 @defun event-basic-type event
1924 This function returns the key or mouse button that @var{event}
1925 describes, with all modifiers removed. The @var{event} argument is as
1926 in @code{event-modifiers}. For example:
1927
1928 @example
1929 (event-basic-type ?a)
1930 @result{} 97
1931 (event-basic-type ?A)
1932 @result{} 97
1933 (event-basic-type ?\C-a)
1934 @result{} 97
1935 (event-basic-type ?\C-\S-a)
1936 @result{} 97
1937 (event-basic-type 'f5)
1938 @result{} f5
1939 (event-basic-type 's-f5)
1940 @result{} f5
1941 (event-basic-type 'M-S-f5)
1942 @result{} f5
1943 (event-basic-type 'down-mouse-1)
1944 @result{} mouse-1
1945 @end example
1946 @end defun
1947
1948 @defun mouse-movement-p object
1949 This function returns non-@code{nil} if @var{object} is a mouse movement
1950 event.
1951 @end defun
1952
1953 @defun event-convert-list list
1954 This function converts a list of modifier names and a basic event type
1955 to an event type which specifies all of them. The basic event type
1956 must be the last element of the list. For example,
1957
1958 @example
1959 (event-convert-list '(control ?a))
1960 @result{} 1
1961 (event-convert-list '(control meta ?a))
1962 @result{} -134217727
1963 (event-convert-list '(control super f1))
1964 @result{} C-s-f1
1965 @end example
1966 @end defun
1967
1968 @node Accessing Mouse
1969 @subsection Accessing Mouse Events
1970 @cindex mouse events, data in
1971 @cindex keyboard events, data in
1972
1973 This section describes convenient functions for accessing the data in
1974 a mouse button or motion event. Keyboard event data can be accessed
1975 using the same functions, but data elements that aren't applicable to
1976 keyboard events are zero or @code{nil}.
1977
1978 The following two functions return a mouse position list
1979 (@pxref{Click Events}), specifying the position of a mouse event.
1980
1981 @defun event-start event
1982 This returns the starting position of @var{event}.
1983
1984 If @var{event} is a click or button-down event, this returns the
1985 location of the event. If @var{event} is a drag event, this returns the
1986 drag's starting position.
1987 @end defun
1988
1989 @defun event-end event
1990 This returns the ending position of @var{event}.
1991
1992 If @var{event} is a drag event, this returns the position where the user
1993 released the mouse button. If @var{event} is a click or button-down
1994 event, the value is actually the starting position, which is the only
1995 position such events have.
1996 @end defun
1997
1998 @defun posnp object
1999 This function returns non-@code{nil} if @var{object} is a mouse
2000 position list, in either of the formats documented in @ref{Click
2001 Events}); and @code{nil} otherwise.
2002 @end defun
2003
2004 @cindex mouse position list, accessing
2005 These functions take a mouse position list as argument, and return
2006 various parts of it:
2007
2008 @defun posn-window position
2009 Return the window that @var{position} is in.
2010 @end defun
2011
2012 @defun posn-area position
2013 Return the window area recorded in @var{position}. It returns @code{nil}
2014 when the event occurred in the text area of the window; otherwise, it
2015 is a symbol identifying the area in which the event occurred.
2016 @end defun
2017
2018 @defun posn-point position
2019 Return the buffer position in @var{position}. When the event occurred
2020 in the text area of the window, in a marginal area, or on a fringe,
2021 this is an integer specifying a buffer position. Otherwise, the value
2022 is undefined.
2023 @end defun
2024
2025 @defun posn-x-y position
2026 Return the pixel-based x and y coordinates in @var{position}, as a
2027 cons cell @code{(@var{x} . @var{y})}. These coordinates are relative
2028 to the window given by @code{posn-window}.
2029
2030 This example shows how to convert the window-relative coordinates in
2031 the text area of a window into frame-relative coordinates:
2032
2033 @example
2034 (defun frame-relative-coordinates (position)
2035 "Return frame-relative coordinates from POSITION.
2036 POSITION is assumed to lie in a window text area."
2037 (let* ((x-y (posn-x-y position))
2038 (window (posn-window position))
2039 (edges (window-inside-pixel-edges window)))
2040 (cons (+ (car x-y) (car edges))
2041 (+ (cdr x-y) (cadr edges)))))
2042 @end example
2043 @end defun
2044
2045 @defun posn-col-row position
2046 This function returns a cons cell @code{(@var{col} . @var{row})},
2047 containing the estimated column and row corresponding to buffer
2048 position @var{position}. The return value is given in units of the
2049 frame's default character width and height, as computed from the
2050 @var{x} and @var{y} values corresponding to @var{position}. (So, if
2051 the actual characters have non-default sizes, the actual row and
2052 column may differ from these computed values.)
2053
2054 Note that @var{row} is counted from the top of the text area. If the
2055 window possesses a header line (@pxref{Header Lines}), it is
2056 @emph{not} counted as the first line.
2057 @end defun
2058
2059 @defun posn-actual-col-row position
2060 Return the actual row and column in @var{position}, as a cons cell
2061 @code{(@var{col} . @var{row})}. The values are the actual row and
2062 column numbers in the window. @xref{Click Events}, for details. It
2063 returns @code{nil} if @var{position} does not include actual positions
2064 values.
2065 @end defun
2066
2067 @defun posn-string position
2068 Return the string object in @var{position}, either @code{nil}, or a
2069 cons cell @code{(@var{string} . @var{string-pos})}.
2070 @end defun
2071
2072 @defun posn-image position
2073 Return the image object in @var{position}, either @code{nil}, or an
2074 image @code{(image ...)}.
2075 @end defun
2076
2077 @defun posn-object position
2078 Return the image or string object in @var{position}, either
2079 @code{nil}, an image @code{(image ...)}, or a cons cell
2080 @code{(@var{string} . @var{string-pos})}.
2081 @end defun
2082
2083 @defun posn-object-x-y position
2084 Return the pixel-based x and y coordinates relative to the upper left
2085 corner of the object in @var{position} as a cons cell @code{(@var{dx}
2086 . @var{dy})}. If the @var{position} is a buffer position, return the
2087 relative position in the character at that position.
2088 @end defun
2089
2090 @defun posn-object-width-height position
2091 Return the pixel width and height of the object in @var{position} as a
2092 cons cell @code{(@var{width} . @var{height})}. If the @var{position}
2093 is a buffer position, return the size of the character at that position.
2094 @end defun
2095
2096 @cindex timestamp of a mouse event
2097 @defun posn-timestamp position
2098 Return the timestamp in @var{position}. This is the time at which the
2099 event occurred, in milliseconds.
2100 @end defun
2101
2102 These functions compute a position list given particular buffer
2103 position or screen position. You can access the data in this position
2104 list with the functions described above.
2105
2106 @defun posn-at-point &optional pos window
2107 This function returns a position list for position @var{pos} in
2108 @var{window}. @var{pos} defaults to point in @var{window};
2109 @var{window} defaults to the selected window.
2110
2111 @code{posn-at-point} returns @code{nil} if @var{pos} is not visible in
2112 @var{window}.
2113 @end defun
2114
2115 @defun posn-at-x-y x y &optional frame-or-window whole
2116 This function returns position information corresponding to pixel
2117 coordinates @var{x} and @var{y} in a specified frame or window,
2118 @var{frame-or-window}, which defaults to the selected window.
2119 The coordinates @var{x} and @var{y} are relative to the
2120 frame or window used.
2121 If @var{whole} is @code{nil}, the coordinates are relative
2122 to the window text area, otherwise they are relative to
2123 the entire window area including scroll bars, margins and fringes.
2124 @end defun
2125
2126 @node Accessing Scroll
2127 @subsection Accessing Scroll Bar Events
2128 @cindex scroll bar events, data in
2129
2130 These functions are useful for decoding scroll bar events.
2131
2132 @defun scroll-bar-event-ratio event
2133 This function returns the fractional vertical position of a scroll bar
2134 event within the scroll bar. The value is a cons cell
2135 @code{(@var{portion} . @var{whole})} containing two integers whose ratio
2136 is the fractional position.
2137 @end defun
2138
2139 @defun scroll-bar-scale ratio total
2140 This function multiplies (in effect) @var{ratio} by @var{total},
2141 rounding the result to an integer. The argument @var{ratio} is not a
2142 number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
2143 value returned by @code{scroll-bar-event-ratio}.
2144
2145 This function is handy for scaling a position on a scroll bar into a
2146 buffer position. Here's how to do that:
2147
2148 @example
2149 (+ (point-min)
2150 (scroll-bar-scale
2151 (posn-x-y (event-start event))
2152 (- (point-max) (point-min))))
2153 @end example
2154
2155 Recall that scroll bar events have two integers forming a ratio, in place
2156 of a pair of x and y coordinates.
2157 @end defun
2158
2159 @node Strings of Events
2160 @subsection Putting Keyboard Events in Strings
2161 @cindex keyboard events in strings
2162 @cindex strings with keyboard events
2163
2164 In most of the places where strings are used, we conceptualize the
2165 string as containing text characters---the same kind of characters found
2166 in buffers or files. Occasionally Lisp programs use strings that
2167 conceptually contain keyboard characters; for example, they may be key
2168 sequences or keyboard macro definitions. However, storing keyboard
2169 characters in a string is a complex matter, for reasons of historical
2170 compatibility, and it is not always possible.
2171
2172 We recommend that new programs avoid dealing with these complexities
2173 by not storing keyboard events in strings. Here is how to do that:
2174
2175 @itemize @bullet
2176 @item
2177 Use vectors instead of strings for key sequences, when you plan to use
2178 them for anything other than as arguments to @code{lookup-key} and
2179 @code{define-key}. For example, you can use
2180 @code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
2181 @code{this-command-keys-vector} instead of @code{this-command-keys}.
2182
2183 @item
2184 Use vectors to write key sequence constants containing meta characters,
2185 even when passing them directly to @code{define-key}.
2186
2187 @item
2188 When you have to look at the contents of a key sequence that might be a
2189 string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
2190 first, to convert it to a list.
2191 @end itemize
2192
2193 The complexities stem from the modifier bits that keyboard input
2194 characters can include. Aside from the Meta modifier, none of these
2195 modifier bits can be included in a string, and the Meta modifier is
2196 allowed only in special cases.
2197
2198 The earliest GNU Emacs versions represented meta characters as codes
2199 in the range of 128 to 255. At that time, the basic character codes
2200 ranged from 0 to 127, so all keyboard character codes did fit in a
2201 string. Many Lisp programs used @samp{\M-} in string constants to stand
2202 for meta characters, especially in arguments to @code{define-key} and
2203 similar functions, and key sequences and sequences of events were always
2204 represented as strings.
2205
2206 When we added support for larger basic character codes beyond 127, and
2207 additional modifier bits, we had to change the representation of meta
2208 characters. Now the flag that represents the Meta modifier in a
2209 character is
2210 @tex
2211 @math{2^{27}}
2212 @end tex
2213 @ifnottex
2214 2**27
2215 @end ifnottex
2216 and such numbers cannot be included in a string.
2217
2218 To support programs with @samp{\M-} in string constants, there are
2219 special rules for including certain meta characters in a string.
2220 Here are the rules for interpreting a string as a sequence of input
2221 characters:
2222
2223 @itemize @bullet
2224 @item
2225 If the keyboard character value is in the range of 0 to 127, it can go
2226 in the string unchanged.
2227
2228 @item
2229 The meta variants of those characters, with codes in the range of
2230 @tex
2231 @math{2^{27}}
2232 @end tex
2233 @ifnottex
2234 2**27
2235 @end ifnottex
2236 to
2237 @tex
2238 @math{2^{27} + 127},
2239 @end tex
2240 @ifnottex
2241 2**27+127,
2242 @end ifnottex
2243 can also go in the string, but you must change their
2244 numeric values. You must set the
2245 @tex
2246 @math{2^{7}}
2247 @end tex
2248 @ifnottex
2249 2**7
2250 @end ifnottex
2251 bit instead of the
2252 @tex
2253 @math{2^{27}}
2254 @end tex
2255 @ifnottex
2256 2**27
2257 @end ifnottex
2258 bit, resulting in a value between 128 and 255. Only a unibyte string
2259 can include these codes.
2260
2261 @item
2262 Non-@acronym{ASCII} characters above 256 can be included in a multibyte string.
2263
2264 @item
2265 Other keyboard character events cannot fit in a string. This includes
2266 keyboard events in the range of 128 to 255.
2267 @end itemize
2268
2269 Functions such as @code{read-key-sequence} that construct strings of
2270 keyboard input characters follow these rules: they construct vectors
2271 instead of strings, when the events won't fit in a string.
2272
2273 When you use the read syntax @samp{\M-} in a string, it produces a
2274 code in the range of 128 to 255---the same code that you get if you
2275 modify the corresponding keyboard event to put it in the string. Thus,
2276 meta events in strings work consistently regardless of how they get into
2277 the strings.
2278
2279 However, most programs would do well to avoid these issues by
2280 following the recommendations at the beginning of this section.
2281
2282 @node Reading Input
2283 @section Reading Input
2284 @cindex read input
2285 @cindex keyboard input
2286
2287 The editor command loop reads key sequences using the function
2288 @code{read-key-sequence}, which uses @code{read-event}. These and other
2289 functions for event input are also available for use in Lisp programs.
2290 See also @code{momentary-string-display} in @ref{Temporary Displays},
2291 and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
2292 functions and variables for controlling terminal input modes and
2293 debugging terminal input.
2294
2295 For higher-level input facilities, see @ref{Minibuffers}.
2296
2297 @menu
2298 * Key Sequence Input:: How to read one key sequence.
2299 * Reading One Event:: How to read just one event.
2300 * Event Mod:: How Emacs modifies events as they are read.
2301 * Invoking the Input Method:: How reading an event uses the input method.
2302 * Quoted Character Input:: Asking the user to specify a character.
2303 * Event Input Misc:: How to reread or throw away input events.
2304 @end menu
2305
2306 @node Key Sequence Input
2307 @subsection Key Sequence Input
2308 @cindex key sequence input
2309
2310 The command loop reads input a key sequence at a time, by calling
2311 @code{read-key-sequence}. Lisp programs can also call this function;
2312 for example, @code{describe-key} uses it to read the key to describe.
2313
2314 @defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
2315 This function reads a key sequence and returns it as a string or
2316 vector. It keeps reading events until it has accumulated a complete key
2317 sequence; that is, enough to specify a non-prefix command using the
2318 currently active keymaps. (Remember that a key sequence that starts
2319 with a mouse event is read using the keymaps of the buffer in the
2320 window that the mouse was in, not the current buffer.)
2321
2322 If the events are all characters and all can fit in a string, then
2323 @code{read-key-sequence} returns a string (@pxref{Strings of Events}).
2324 Otherwise, it returns a vector, since a vector can hold all kinds of
2325 events---characters, symbols, and lists. The elements of the string or
2326 vector are the events in the key sequence.
2327
2328 Reading a key sequence includes translating the events in various
2329 ways. @xref{Translation Keymaps}.
2330
2331 The argument @var{prompt} is either a string to be displayed in the
2332 echo area as a prompt, or @code{nil}, meaning not to display a prompt.
2333 The argument @var{continue-echo}, if non-@code{nil}, means to echo
2334 this key as a continuation of the previous key.
2335
2336 Normally any upper case event is converted to lower case if the
2337 original event is undefined and the lower case equivalent is defined.
2338 The argument @var{dont-downcase-last}, if non-@code{nil}, means do not
2339 convert the last event to lower case. This is appropriate for reading
2340 a key sequence to be defined.
2341
2342 The argument @var{switch-frame-ok}, if non-@code{nil}, means that this
2343 function should process a @code{switch-frame} event if the user
2344 switches frames before typing anything. If the user switches frames
2345 in the middle of a key sequence, or at the start of the sequence but
2346 @var{switch-frame-ok} is @code{nil}, then the event will be put off
2347 until after the current key sequence.
2348
2349 The argument @var{command-loop}, if non-@code{nil}, means that this
2350 key sequence is being read by something that will read commands one
2351 after another. It should be @code{nil} if the caller will read just
2352 one key sequence.
2353
2354 In the following example, Emacs displays the prompt @samp{?} in the
2355 echo area, and then the user types @kbd{C-x C-f}.
2356
2357 @example
2358 (read-key-sequence "?")
2359
2360 @group
2361 ---------- Echo Area ----------
2362 ?@kbd{C-x C-f}
2363 ---------- Echo Area ----------
2364
2365 @result{} "^X^F"
2366 @end group
2367 @end example
2368
2369 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
2370 typed while reading with this function works like any other character,
2371 and does not set @code{quit-flag}. @xref{Quitting}.
2372 @end defun
2373
2374 @defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop
2375 This is like @code{read-key-sequence} except that it always
2376 returns the key sequence as a vector, never as a string.
2377 @xref{Strings of Events}.
2378 @end defun
2379
2380 @cindex upper case key sequence
2381 @cindex downcasing in @code{lookup-key}
2382 @cindex shift-translation
2383 If an input character is upper-case (or has the shift modifier) and
2384 has no key binding, but its lower-case equivalent has one, then
2385 @code{read-key-sequence} converts the character to lower case. Note
2386 that @code{lookup-key} does not perform case conversion in this way.
2387
2388 @vindex this-command-keys-shift-translated
2389 When reading input results in such a @dfn{shift-translation}, Emacs
2390 sets the variable @code{this-command-keys-shift-translated} to a
2391 non-@code{nil} value. Lisp programs can examine this variable if they
2392 need to modify their behavior when invoked by shift-translated keys.
2393 For example, the function @code{handle-shift-selection} examines the
2394 value of this variable to determine how to activate or deactivate the
2395 region (@pxref{The Mark, handle-shift-selection}).
2396
2397 The function @code{read-key-sequence} also transforms some mouse events.
2398 It converts unbound drag events into click events, and discards unbound
2399 button-down events entirely. It also reshuffles focus events and
2400 miscellaneous window events so that they never appear in a key sequence
2401 with any other events.
2402
2403 @cindex @code{header-line} prefix key
2404 @cindex @code{mode-line} prefix key
2405 @cindex @code{vertical-line} prefix key
2406 @cindex @code{horizontal-scroll-bar} prefix key
2407 @cindex @code{vertical-scroll-bar} prefix key
2408 @cindex @code{menu-bar} prefix key
2409 @cindex mouse events, in special parts of frame
2410 When mouse events occur in special parts of a window, such as a mode
2411 line or a scroll bar, the event type shows nothing special---it is the
2412 same symbol that would normally represent that combination of mouse
2413 button and modifier keys. The information about the window part is kept
2414 elsewhere in the event---in the coordinates. But
2415 @code{read-key-sequence} translates this information into imaginary
2416 ``prefix keys'', all of which are symbols: @code{header-line},
2417 @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
2418 @code{vertical-line}, and @code{vertical-scroll-bar}. You can define
2419 meanings for mouse clicks in special window parts by defining key
2420 sequences using these imaginary prefix keys.
2421
2422 For example, if you call @code{read-key-sequence} and then click the
2423 mouse on the window's mode line, you get two events, like this:
2424
2425 @example
2426 (read-key-sequence "Click on the mode line: ")
2427 @result{} [mode-line
2428 (mouse-1
2429 (#<window 6 on NEWS> mode-line
2430 (40 . 63) 5959987))]
2431 @end example
2432
2433 @defvar num-input-keys
2434 This variable's value is the number of key sequences processed so far in
2435 this Emacs session. This includes key sequences read from the terminal
2436 and key sequences read from keyboard macros being executed.
2437 @end defvar
2438
2439 @node Reading One Event
2440 @subsection Reading One Event
2441 @cindex reading a single event
2442 @cindex event, reading only one
2443
2444 The lowest level functions for command input are @code{read-event},
2445 @code{read-char}, and @code{read-char-exclusive}.
2446
2447 @defun read-event &optional prompt inherit-input-method seconds
2448 This function reads and returns the next event of command input,
2449 waiting if necessary until an event is available.
2450
2451 The returned event may come directly from the user, or from a keyboard
2452 macro. It is not decoded by the keyboard's input coding system
2453 (@pxref{Terminal I/O Encoding}).
2454
2455 If the optional argument @var{prompt} is non-@code{nil}, it should be a
2456 string to display in the echo area as a prompt. Otherwise,
2457 @code{read-event} does not display any message to indicate it is waiting
2458 for input; instead, it prompts by echoing: it displays descriptions of
2459 the events that led to or were read by the current command. @xref{The
2460 Echo Area}.
2461
2462 If @var{inherit-input-method} is non-@code{nil}, then the current input
2463 method (if any) is employed to make it possible to enter a
2464 non-@acronym{ASCII} character. Otherwise, input method handling is disabled
2465 for reading this event.
2466
2467 If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
2468 moves the cursor temporarily to the echo area, to the end of any message
2469 displayed there. Otherwise @code{read-event} does not move the cursor.
2470
2471 If @var{seconds} is non-@code{nil}, it should be a number specifying
2472 the maximum time to wait for input, in seconds. If no input arrives
2473 within that time, @code{read-event} stops waiting and returns
2474 @code{nil}. A floating point @var{seconds} means to wait
2475 for a fractional number of seconds. Some systems support only a whole
2476 number of seconds; on these systems, @var{seconds} is rounded down.
2477 If @var{seconds} is @code{nil}, @code{read-event} waits as long as
2478 necessary for input to arrive.
2479
2480 If @var{seconds} is @code{nil}, Emacs is considered idle while waiting
2481 for user input to arrive. Idle timers---those created with
2482 @code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this
2483 period. However, if @var{seconds} is non-@code{nil}, the state of
2484 idleness remains unchanged. If Emacs is non-idle when
2485 @code{read-event} is called, it remains non-idle throughout the
2486 operation of @code{read-event}; if Emacs is idle (which can happen if
2487 the call happens inside an idle timer), it remains idle.
2488
2489 If @code{read-event} gets an event that is defined as a help character,
2490 then in some cases @code{read-event} processes the event directly without
2491 returning. @xref{Help Functions}. Certain other events, called
2492 @dfn{special events}, are also processed directly within
2493 @code{read-event} (@pxref{Special Events}).
2494
2495 Here is what happens if you call @code{read-event} and then press the
2496 right-arrow function key:
2497
2498 @example
2499 @group
2500 (read-event)
2501 @result{} right
2502 @end group
2503 @end example
2504 @end defun
2505
2506 @defun read-char &optional prompt inherit-input-method seconds
2507 This function reads and returns a character of command input. If the
2508 user generates an event which is not a character (i.e., a mouse click or
2509 function key event), @code{read-char} signals an error. The arguments
2510 work as in @code{read-event}.
2511
2512 In the first example, the user types the character @kbd{1} (@acronym{ASCII}
2513 code 49). The second example shows a keyboard macro definition that
2514 calls @code{read-char} from the minibuffer using @code{eval-expression}.
2515 @code{read-char} reads the keyboard macro's very next character, which
2516 is @kbd{1}. Then @code{eval-expression} displays its return value in
2517 the echo area.
2518
2519 @example
2520 @group
2521 (read-char)
2522 @result{} 49
2523 @end group
2524
2525 @group
2526 ;; @r{We assume here you use @kbd{M-:} to evaluate this.}
2527 (symbol-function 'foo)
2528 @result{} "^[:(read-char)^M1"
2529 @end group
2530 @group
2531 (execute-kbd-macro 'foo)
2532 @print{} 49
2533 @result{} nil
2534 @end group
2535 @end example
2536 @end defun
2537
2538 @defun read-char-exclusive &optional prompt inherit-input-method seconds
2539 This function reads and returns a character of command input. If the
2540 user generates an event which is not a character,
2541 @code{read-char-exclusive} ignores it and reads another event, until it
2542 gets a character. The arguments work as in @code{read-event}.
2543 @end defun
2544
2545 None of the above functions suppress quitting.
2546
2547 @defvar num-nonmacro-input-events
2548 This variable holds the total number of input events received so far
2549 from the terminal---not counting those generated by keyboard macros.
2550 @end defvar
2551
2552 We emphasize that, unlike @code{read-key-sequence}, the functions
2553 @code{read-event}, @code{read-char}, and @code{read-char-exclusive} do
2554 not perform the translations described in @ref{Translation Keymaps}.
2555 If you wish to read a single key taking these translations into
2556 account, use the function @code{read-key}:
2557
2558 @defun read-key &optional prompt
2559 This function reads a single key. It is ``intermediate'' between
2560 @code{read-key-sequence} and @code{read-event}. Unlike the former, it
2561 reads a single key, not a key sequence. Unlike the latter, it does
2562 not return a raw event, but decodes and translates the user input
2563 according to @code{input-decode-map}, @code{local-function-key-map},
2564 and @code{key-translation-map} (@pxref{Translation Keymaps}).
2565
2566 The argument @var{prompt} is either a string to be displayed in the
2567 echo area as a prompt, or @code{nil}, meaning not to display a prompt.
2568 @end defun
2569
2570 @defun read-char-choice prompt chars &optional inhibit-quit
2571 This function uses @code{read-key} to read and return a single
2572 character. It ignores any input that is not a member of @var{chars},
2573 a list of accepted characters. Optionally, it will also ignore
2574 keyboard-quit events while it is waiting for valid input. If you bind
2575 @code{help-form} (@pxref{Help Functions}) to a non-@code{nil} value
2576 while calling @code{read-char-choice}, then pressing @code{help-char}
2577 causes it to evaluate @code{help-form} and display the result. It
2578 then continues to wait for a valid input character, or keyboard-quit.
2579 @end defun
2580
2581 @node Event Mod
2582 @subsection Modifying and Translating Input Events
2583
2584 Emacs modifies every event it reads according to
2585 @code{extra-keyboard-modifiers}, then translates it through
2586 @code{keyboard-translate-table} (if applicable), before returning it
2587 from @code{read-event}.
2588
2589 @defvar extra-keyboard-modifiers
2590 This variable lets Lisp programs ``press'' the modifier keys on the
2591 keyboard. The value is a character. Only the modifiers of the
2592 character matter. Each time the user types a keyboard key, it is
2593 altered as if those modifier keys were held down. For instance, if
2594 you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all
2595 keyboard input characters typed during the scope of the binding will
2596 have the control and meta modifiers applied to them. The character
2597 @code{?\C-@@}, equivalent to the integer 0, does not count as a control
2598 character for this purpose, but as a character with no modifiers.
2599 Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
2600 modification.
2601
2602 When using a window system, the program can ``press'' any of the
2603 modifier keys in this way. Otherwise, only the @key{CTL} and @key{META}
2604 keys can be virtually pressed.
2605
2606 Note that this variable applies only to events that really come from
2607 the keyboard, and has no effect on mouse events or any other events.
2608 @end defvar
2609
2610 @defvar keyboard-translate-table
2611 This terminal-local variable is the translate table for keyboard
2612 characters. It lets you reshuffle the keys on the keyboard without
2613 changing any command bindings. Its value is normally a char-table, or
2614 else @code{nil}. (It can also be a string or vector, but this is
2615 considered obsolete.)
2616
2617 If @code{keyboard-translate-table} is a char-table
2618 (@pxref{Char-Tables}), then each character read from the keyboard is
2619 looked up in this char-table. If the value found there is
2620 non-@code{nil}, then it is used instead of the actual input character.
2621
2622 Note that this translation is the first thing that happens to a
2623 character after it is read from the terminal. Record-keeping features
2624 such as @code{recent-keys} and dribble files record the characters after
2625 translation.
2626
2627 Note also that this translation is done before the characters are
2628 supplied to input methods (@pxref{Input Methods}). Use
2629 @code{translation-table-for-input} (@pxref{Translation of Characters}),
2630 if you want to translate characters after input methods operate.
2631 @end defvar
2632
2633 @defun keyboard-translate from to
2634 This function modifies @code{keyboard-translate-table} to translate
2635 character code @var{from} into character code @var{to}. It creates
2636 the keyboard translate table if necessary.
2637 @end defun
2638
2639 Here's an example of using the @code{keyboard-translate-table} to
2640 make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste
2641 operations:
2642
2643 @example
2644 (keyboard-translate ?\C-x 'control-x)
2645 (keyboard-translate ?\C-c 'control-c)
2646 (keyboard-translate ?\C-v 'control-v)
2647 (global-set-key [control-x] 'kill-region)
2648 (global-set-key [control-c] 'kill-ring-save)
2649 (global-set-key [control-v] 'yank)
2650 @end example
2651
2652 @noindent
2653 On a graphical terminal that supports extended @acronym{ASCII} input,
2654 you can still get the standard Emacs meanings of one of those
2655 characters by typing it with the shift key. That makes it a different
2656 character as far as keyboard translation is concerned, but it has the
2657 same usual meaning.
2658
2659 @xref{Translation Keymaps}, for mechanisms that translate event sequences
2660 at the level of @code{read-key-sequence}.
2661
2662 @node Invoking the Input Method
2663 @subsection Invoking the Input Method
2664
2665 The event-reading functions invoke the current input method, if any
2666 (@pxref{Input Methods}). If the value of @code{input-method-function}
2667 is non-@code{nil}, it should be a function; when @code{read-event} reads
2668 a printing character (including @key{SPC}) with no modifier bits, it
2669 calls that function, passing the character as an argument.
2670
2671 @defvar input-method-function
2672 If this is non-@code{nil}, its value specifies the current input method
2673 function.
2674
2675 @strong{Warning:} don't bind this variable with @code{let}. It is often
2676 buffer-local, and if you bind it around reading input (which is exactly
2677 when you @emph{would} bind it), switching buffers asynchronously while
2678 Emacs is waiting will cause the value to be restored in the wrong
2679 buffer.
2680 @end defvar
2681
2682 The input method function should return a list of events which should
2683 be used as input. (If the list is @code{nil}, that means there is no
2684 input, so @code{read-event} waits for another event.) These events are
2685 processed before the events in @code{unread-command-events}
2686 (@pxref{Event Input Misc}). Events
2687 returned by the input method function are not passed to the input method
2688 function again, even if they are printing characters with no modifier
2689 bits.
2690
2691 If the input method function calls @code{read-event} or
2692 @code{read-key-sequence}, it should bind @code{input-method-function} to
2693 @code{nil} first, to prevent recursion.
2694
2695 The input method function is not called when reading the second and
2696 subsequent events of a key sequence. Thus, these characters are not
2697 subject to input method processing. The input method function should
2698 test the values of @code{overriding-local-map} and
2699 @code{overriding-terminal-local-map}; if either of these variables is
2700 non-@code{nil}, the input method should put its argument into a list and
2701 return that list with no further processing.
2702
2703 @node Quoted Character Input
2704 @subsection Quoted Character Input
2705 @cindex quoted character input
2706
2707 You can use the function @code{read-quoted-char} to ask the user to
2708 specify a character, and allow the user to specify a control or meta
2709 character conveniently, either literally or as an octal character code.
2710 The command @code{quoted-insert} uses this function.
2711
2712 @defun read-quoted-char &optional prompt
2713 @cindex octal character input
2714 @cindex control characters, reading
2715 @cindex nonprinting characters, reading
2716 This function is like @code{read-char}, except that if the first
2717 character read is an octal digit (0--7), it reads any number of octal
2718 digits (but stopping if a non-octal digit is found), and returns the
2719 character represented by that numeric character code. If the
2720 character that terminates the sequence of octal digits is @key{RET},
2721 it is discarded. Any other terminating character is used as input
2722 after this function returns.
2723
2724 Quitting is suppressed when the first character is read, so that the
2725 user can enter a @kbd{C-g}. @xref{Quitting}.
2726
2727 If @var{prompt} is supplied, it specifies a string for prompting the
2728 user. The prompt string is always displayed in the echo area, followed
2729 by a single @samp{-}.
2730
2731 In the following example, the user types in the octal number 177 (which
2732 is 127 in decimal).
2733
2734 @example
2735 (read-quoted-char "What character")
2736
2737 @group
2738 ---------- Echo Area ----------
2739 What character @kbd{1 7 7}-
2740 ---------- Echo Area ----------
2741
2742 @result{} 127
2743 @end group
2744 @end example
2745 @end defun
2746
2747 @need 2000
2748 @node Event Input Misc
2749 @subsection Miscellaneous Event Input Features
2750
2751 This section describes how to ``peek ahead'' at events without using
2752 them up, how to check for pending input, and how to discard pending
2753 input. See also the function @code{read-passwd} (@pxref{Reading a
2754 Password}).
2755
2756 @defvar unread-command-events
2757 @cindex next input
2758 @cindex peeking at input
2759 This variable holds a list of events waiting to be read as command
2760 input. The events are used in the order they appear in the list, and
2761 removed one by one as they are used.
2762
2763 The variable is needed because in some cases a function reads an event
2764 and then decides not to use it. Storing the event in this variable
2765 causes it to be processed normally, by the command loop or by the
2766 functions to read command input.
2767
2768 @cindex prefix argument unreading
2769 For example, the function that implements numeric prefix arguments reads
2770 any number of digits. When it finds a non-digit event, it must unread
2771 the event so that it can be read normally by the command loop.
2772 Likewise, incremental search uses this feature to unread events with no
2773 special meaning in a search, because these events should exit the search
2774 and then execute normally.
2775
2776 The reliable and easy way to extract events from a key sequence so as
2777 to put them in @code{unread-command-events} is to use
2778 @code{listify-key-sequence} (see below).
2779
2780 Normally you add events to the front of this list, so that the events
2781 most recently unread will be reread first.
2782
2783 Events read from this list are not normally added to the current
2784 command's key sequence (as returned by, e.g., @code{this-command-keys}),
2785 as the events will already have been added once as they were read for
2786 the first time. An element of the form @code{(@code{t} . @var{event})}
2787 forces @var{event} to be added to the current command's key sequence.
2788 @end defvar
2789
2790 @defun listify-key-sequence key
2791 This function converts the string or vector @var{key} to a list of
2792 individual events, which you can put in @code{unread-command-events}.
2793 @end defun
2794
2795 @defun input-pending-p &optional check-timers
2796 @cindex waiting for command key input
2797 This function determines whether any command input is currently
2798 available to be read. It returns immediately, with value @code{t} if
2799 there is available input, @code{nil} otherwise. On rare occasions it
2800 may return @code{t} when no input is available.
2801
2802 If the optional argument @var{check-timers} is non-@code{nil}, then if
2803 no input is available, Emacs runs any timers which are ready.
2804 @xref{Timers}.
2805 @end defun
2806
2807 @defvar last-input-event
2808 This variable records the last terminal input event read, whether
2809 as part of a command or explicitly by a Lisp program.
2810
2811 In the example below, the Lisp program reads the character @kbd{1},
2812 @acronym{ASCII} code 49. It becomes the value of @code{last-input-event},
2813 while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
2814 this expression) remains the value of @code{last-command-event}.
2815
2816 @example
2817 @group
2818 (progn (print (read-char))
2819 (print last-command-event)
2820 last-input-event)
2821 @print{} 49
2822 @print{} 5
2823 @result{} 49
2824 @end group
2825 @end example
2826 @end defvar
2827
2828 @defmac while-no-input body@dots{}
2829 This construct runs the @var{body} forms and returns the value of the
2830 last one---but only if no input arrives. If any input arrives during
2831 the execution of the @var{body} forms, it aborts them (working much
2832 like a quit). The @code{while-no-input} form returns @code{nil} if
2833 aborted by a real quit, and returns @code{t} if aborted by arrival of
2834 other input.
2835
2836 If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil},
2837 arrival of input during those parts won't cause an abort until
2838 the end of that part.
2839
2840 If you want to be able to distinguish all possible values computed
2841 by @var{body} from both kinds of abort conditions, write the code
2842 like this:
2843
2844 @example
2845 (while-no-input
2846 (list
2847 (progn . @var{body})))
2848 @end example
2849 @end defmac
2850
2851 @defun discard-input
2852 @cindex flushing input
2853 @cindex discarding input
2854 @cindex keyboard macro, terminating
2855 This function discards the contents of the terminal input buffer and
2856 cancels any keyboard macro that might be in the process of definition.
2857 It returns @code{nil}.
2858
2859 In the following example, the user may type a number of characters right
2860 after starting the evaluation of the form. After the @code{sleep-for}
2861 finishes sleeping, @code{discard-input} discards any characters typed
2862 during the sleep.
2863
2864 @example
2865 (progn (sleep-for 2)
2866 (discard-input))
2867 @result{} nil
2868 @end example
2869 @end defun
2870
2871 @node Special Events
2872 @section Special Events
2873
2874 @cindex special events
2875 Certain @dfn{special events} are handled at a very low level---as soon
2876 as they are read. The @code{read-event} function processes these
2877 events itself, and never returns them. Instead, it keeps waiting for
2878 the first event that is not special and returns that one.
2879
2880 Special events do not echo, they are never grouped into key
2881 sequences, and they never appear in the value of
2882 @code{last-command-event} or @code{(this-command-keys)}. They do not
2883 discard a numeric argument, they cannot be unread with
2884 @code{unread-command-events}, they may not appear in a keyboard macro,
2885 and they are not recorded in a keyboard macro while you are defining
2886 one.
2887
2888 Special events do, however, appear in @code{last-input-event}
2889 immediately after they are read, and this is the way for the event's
2890 definition to find the actual event.
2891
2892 The events types @code{iconify-frame}, @code{make-frame-visible},
2893 @code{delete-frame}, @code{drag-n-drop}, @code{language-change}, and
2894 user signals like @code{sigusr1} are normally handled in this way.
2895 The keymap which defines how to handle special events---and which
2896 events are special---is in the variable @code{special-event-map}
2897 (@pxref{Active Keymaps}).
2898
2899 @node Waiting
2900 @section Waiting for Elapsed Time or Input
2901 @cindex waiting
2902
2903 The wait functions are designed to wait for a certain amount of time
2904 to pass or until there is input. For example, you may wish to pause in
2905 the middle of a computation to allow the user time to view the display.
2906 @code{sit-for} pauses and updates the screen, and returns immediately if
2907 input comes in, while @code{sleep-for} pauses without updating the
2908 screen.
2909
2910 @defun sit-for seconds &optional nodisp
2911 This function performs redisplay (provided there is no pending input
2912 from the user), then waits @var{seconds} seconds, or until input is
2913 available. The usual purpose of @code{sit-for} is to give the user
2914 time to read text that you display. The value is @code{t} if
2915 @code{sit-for} waited the full time with no input arriving
2916 (@pxref{Event Input Misc}). Otherwise, the value is @code{nil}.
2917
2918 The argument @var{seconds} need not be an integer. If it is floating
2919 point, @code{sit-for} waits for a fractional number of seconds.
2920 Some systems support only a whole number of seconds; on these systems,
2921 @var{seconds} is rounded down.
2922
2923 The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)},
2924 i.e., it requests a redisplay, without any delay, if there is no pending input.
2925 @xref{Forcing Redisplay}.
2926
2927 If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
2928 redisplay, but it still returns as soon as input is available (or when
2929 the timeout elapses).
2930
2931 In batch mode (@pxref{Batch Mode}), @code{sit-for} cannot be
2932 interrupted, even by input from the standard input descriptor. It is
2933 thus equivalent to @code{sleep-for}, which is described below.
2934
2935 It is also possible to call @code{sit-for} with three arguments,
2936 as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})},
2937 but that is considered obsolete.
2938 @end defun
2939
2940 @defun sleep-for seconds &optional millisec
2941 This function simply pauses for @var{seconds} seconds without updating
2942 the display. It pays no attention to available input. It returns
2943 @code{nil}.
2944
2945 The argument @var{seconds} need not be an integer. If it is floating
2946 point, @code{sleep-for} waits for a fractional number of seconds.
2947 Some systems support only a whole number of seconds; on these systems,
2948 @var{seconds} is rounded down.
2949
2950 The optional argument @var{millisec} specifies an additional waiting
2951 period measured in milliseconds. This adds to the period specified by
2952 @var{seconds}. If the system doesn't support waiting fractions of a
2953 second, you get an error if you specify nonzero @var{millisec}.
2954
2955 Use @code{sleep-for} when you wish to guarantee a delay.
2956 @end defun
2957
2958 @xref{Time of Day}, for functions to get the current time.
2959
2960 @node Quitting
2961 @section Quitting
2962 @cindex @kbd{C-g}
2963 @cindex quitting
2964 @cindex interrupt Lisp functions
2965
2966 Typing @kbd{C-g} while a Lisp function is running causes Emacs to
2967 @dfn{quit} whatever it is doing. This means that control returns to the
2968 innermost active command loop.
2969
2970 Typing @kbd{C-g} while the command loop is waiting for keyboard input
2971 does not cause a quit; it acts as an ordinary input character. In the
2972 simplest case, you cannot tell the difference, because @kbd{C-g}
2973 normally runs the command @code{keyboard-quit}, whose effect is to quit.
2974 However, when @kbd{C-g} follows a prefix key, they combine to form an
2975 undefined key. The effect is to cancel the prefix key as well as any
2976 prefix argument.
2977
2978 In the minibuffer, @kbd{C-g} has a different definition: it aborts out
2979 of the minibuffer. This means, in effect, that it exits the minibuffer
2980 and then quits. (Simply quitting would return to the command loop
2981 @emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit
2982 directly when the command reader is reading input is so that its meaning
2983 can be redefined in the minibuffer in this way. @kbd{C-g} following a
2984 prefix key is not redefined in the minibuffer, and it has its normal
2985 effect of canceling the prefix key and prefix argument. This too
2986 would not be possible if @kbd{C-g} always quit directly.
2987
2988 When @kbd{C-g} does directly quit, it does so by setting the variable
2989 @code{quit-flag} to @code{t}. Emacs checks this variable at appropriate
2990 times and quits if it is not @code{nil}. Setting @code{quit-flag}
2991 non-@code{nil} in any way thus causes a quit.
2992
2993 At the level of C code, quitting cannot happen just anywhere; only at the
2994 special places that check @code{quit-flag}. The reason for this is
2995 that quitting at other places might leave an inconsistency in Emacs's
2996 internal state. Because quitting is delayed until a safe place, quitting
2997 cannot make Emacs crash.
2998
2999 Certain functions such as @code{read-key-sequence} or
3000 @code{read-quoted-char} prevent quitting entirely even though they wait
3001 for input. Instead of quitting, @kbd{C-g} serves as the requested
3002 input. In the case of @code{read-key-sequence}, this serves to bring
3003 about the special behavior of @kbd{C-g} in the command loop. In the
3004 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
3005 to quote a @kbd{C-g}.
3006
3007 @cindex preventing quitting
3008 You can prevent quitting for a portion of a Lisp function by binding
3009 the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
3010 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
3011 usual result of this---a quit---is prevented. Eventually,
3012 @code{inhibit-quit} will become @code{nil} again, such as when its
3013 binding is unwound at the end of a @code{let} form. At that time, if
3014 @code{quit-flag} is still non-@code{nil}, the requested quit happens
3015 immediately. This behavior is ideal when you wish to make sure that
3016 quitting does not happen within a ``critical section'' of the program.
3017
3018 @cindex @code{read-quoted-char} quitting
3019 In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
3020 handled in a special way that does not involve quitting. This is done
3021 by reading the input with @code{inhibit-quit} bound to @code{t}, and
3022 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
3023 becomes @code{nil} again. This excerpt from the definition of
3024 @code{read-quoted-char} shows how this is done; it also shows that
3025 normal quitting is permitted after the first character of input.
3026
3027 @example
3028 (defun read-quoted-char (&optional prompt)
3029 "@dots{}@var{documentation}@dots{}"
3030 (let ((message-log-max nil) done (first t) (code 0) char)
3031 (while (not done)
3032 (let ((inhibit-quit first)
3033 @dots{})
3034 (and prompt (message "%s-" prompt))
3035 (setq char (read-event))
3036 (if inhibit-quit (setq quit-flag nil)))
3037 @r{@dots{}set the variable @code{code}@dots{}})
3038 code))
3039 @end example
3040
3041 @defvar quit-flag
3042 If this variable is non-@code{nil}, then Emacs quits immediately, unless
3043 @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
3044 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
3045 @end defvar
3046
3047 @defvar inhibit-quit
3048 This variable determines whether Emacs should quit when @code{quit-flag}
3049 is set to a value other than @code{nil}. If @code{inhibit-quit} is
3050 non-@code{nil}, then @code{quit-flag} has no special effect.
3051 @end defvar
3052
3053 @defmac with-local-quit body@dots{}
3054 This macro executes @var{body} forms in sequence, but allows quitting, at
3055 least locally, within @var{body} even if @code{inhibit-quit} was
3056 non-@code{nil} outside this construct. It returns the value of the
3057 last form in @var{body}, unless exited by quitting, in which case
3058 it returns @code{nil}.
3059
3060 If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit},
3061 it only executes the @var{body}, and setting @code{quit-flag} causes
3062 a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so
3063 that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag}
3064 triggers a special kind of local quit. This ends the execution of
3065 @var{body} and exits the @code{with-local-quit} body with
3066 @code{quit-flag} still non-@code{nil}, so that another (ordinary) quit
3067 will happen as soon as that is allowed. If @code{quit-flag} is
3068 already non-@code{nil} at the beginning of @var{body}, the local quit
3069 happens immediately and the body doesn't execute at all.
3070
3071 This macro is mainly useful in functions that can be called from
3072 timers, process filters, process sentinels, @code{pre-command-hook},
3073 @code{post-command-hook}, and other places where @code{inhibit-quit} is
3074 normally bound to @code{t}.
3075 @end defmac
3076
3077 @deffn Command keyboard-quit
3078 This function signals the @code{quit} condition with @code{(signal 'quit
3079 nil)}. This is the same thing that quitting does. (See @code{signal}
3080 in @ref{Errors}.)
3081 @end deffn
3082
3083 You can specify a character other than @kbd{C-g} to use for quitting.
3084 See the function @code{set-input-mode} in @ref{Input Modes}.
3085
3086 @node Prefix Command Arguments
3087 @section Prefix Command Arguments
3088 @cindex prefix argument
3089 @cindex raw prefix argument
3090 @cindex numeric prefix argument
3091
3092 Most Emacs commands can use a @dfn{prefix argument}, a number
3093 specified before the command itself. (Don't confuse prefix arguments
3094 with prefix keys.) The prefix argument is at all times represented by a
3095 value, which may be @code{nil}, meaning there is currently no prefix
3096 argument. Each command may use the prefix argument or ignore it.
3097
3098 There are two representations of the prefix argument: @dfn{raw} and
3099 @dfn{numeric}. The editor command loop uses the raw representation
3100 internally, and so do the Lisp variables that store the information, but
3101 commands can request either representation.
3102
3103 Here are the possible values of a raw prefix argument:
3104
3105 @itemize @bullet
3106 @item
3107 @code{nil}, meaning there is no prefix argument. Its numeric value is
3108 1, but numerous commands make a distinction between @code{nil} and the
3109 integer 1.
3110
3111 @item
3112 An integer, which stands for itself.
3113
3114 @item
3115 A list of one element, which is an integer. This form of prefix
3116 argument results from one or a succession of @kbd{C-u}s with no
3117 digits. The numeric value is the integer in the list, but some
3118 commands make a distinction between such a list and an integer alone.
3119
3120 @item
3121 The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was
3122 typed, without following digits. The equivalent numeric value is
3123 @minus{}1, but some commands make a distinction between the integer
3124 @minus{}1 and the symbol @code{-}.
3125 @end itemize
3126
3127 We illustrate these possibilities by calling the following function with
3128 various prefixes:
3129
3130 @example
3131 @group
3132 (defun display-prefix (arg)
3133 "Display the value of the raw prefix arg."
3134 (interactive "P")
3135 (message "%s" arg))
3136 @end group
3137 @end example
3138
3139 @noindent
3140 Here are the results of calling @code{display-prefix} with various
3141 raw prefix arguments:
3142
3143 @example
3144 M-x display-prefix @print{} nil
3145
3146 C-u M-x display-prefix @print{} (4)
3147
3148 C-u C-u M-x display-prefix @print{} (16)
3149
3150 C-u 3 M-x display-prefix @print{} 3
3151
3152 M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
3153
3154 C-u - M-x display-prefix @print{} -
3155
3156 M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
3157
3158 C-u - 7 M-x display-prefix @print{} -7
3159
3160 M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
3161 @end example
3162
3163 Emacs uses two variables to store the prefix argument:
3164 @code{prefix-arg} and @code{current-prefix-arg}. Commands such as
3165 @code{universal-argument} that set up prefix arguments for other
3166 commands store them in @code{prefix-arg}. In contrast,
3167 @code{current-prefix-arg} conveys the prefix argument to the current
3168 command, so setting it has no effect on the prefix arguments for future
3169 commands.
3170
3171 Normally, commands specify which representation to use for the prefix
3172 argument, either numeric or raw, in the @code{interactive} specification.
3173 (@xref{Using Interactive}.) Alternatively, functions may look at the
3174 value of the prefix argument directly in the variable
3175 @code{current-prefix-arg}, but this is less clean.
3176
3177 @defun prefix-numeric-value arg
3178 This function returns the numeric meaning of a valid raw prefix argument
3179 value, @var{arg}. The argument may be a symbol, a number, or a list.
3180 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
3181 value @minus{}1 is returned; if it is a number, that number is returned;
3182 if it is a list, the @sc{car} of that list (which should be a number) is
3183 returned.
3184 @end defun
3185
3186 @defvar current-prefix-arg
3187 This variable holds the raw prefix argument for the @emph{current}
3188 command. Commands may examine it directly, but the usual method for
3189 accessing it is with @code{(interactive "P")}.
3190 @end defvar
3191
3192 @defvar prefix-arg
3193 The value of this variable is the raw prefix argument for the
3194 @emph{next} editing command. Commands such as @code{universal-argument}
3195 that specify prefix arguments for the following command work by setting
3196 this variable.
3197 @end defvar
3198
3199 @defvar last-prefix-arg
3200 The raw prefix argument value used by the previous command.
3201 @end defvar
3202
3203 The following commands exist to set up prefix arguments for the
3204 following command. Do not call them for any other reason.
3205
3206 @deffn Command universal-argument
3207 This command reads input and specifies a prefix argument for the
3208 following command. Don't call this command yourself unless you know
3209 what you are doing.
3210 @end deffn
3211
3212 @deffn Command digit-argument arg
3213 This command adds to the prefix argument for the following command. The
3214 argument @var{arg} is the raw prefix argument as it was before this
3215 command; it is used to compute the updated prefix argument. Don't call
3216 this command yourself unless you know what you are doing.
3217 @end deffn
3218
3219 @deffn Command negative-argument arg
3220 This command adds to the numeric argument for the next command. The
3221 argument @var{arg} is the raw prefix argument as it was before this
3222 command; its value is negated to form the new prefix argument. Don't
3223 call this command yourself unless you know what you are doing.
3224 @end deffn
3225
3226 @node Recursive Editing
3227 @section Recursive Editing
3228 @cindex recursive command loop
3229 @cindex recursive editing level
3230 @cindex command loop, recursive
3231
3232 The Emacs command loop is entered automatically when Emacs starts up.
3233 This top-level invocation of the command loop never exits; it keeps
3234 running as long as Emacs does. Lisp programs can also invoke the
3235 command loop. Since this makes more than one activation of the command
3236 loop, we call it @dfn{recursive editing}. A recursive editing level has
3237 the effect of suspending whatever command invoked it and permitting the
3238 user to do arbitrary editing before resuming that command.
3239
3240 The commands available during recursive editing are the same ones
3241 available in the top-level editing loop and defined in the keymaps.
3242 Only a few special commands exit the recursive editing level; the others
3243 return to the recursive editing level when they finish. (The special
3244 commands for exiting are always available, but they do nothing when
3245 recursive editing is not in progress.)
3246
3247 All command loops, including recursive ones, set up all-purpose error
3248 handlers so that an error in a command run from the command loop will
3249 not exit the loop.
3250
3251 @cindex minibuffer input
3252 Minibuffer input is a special kind of recursive editing. It has a few
3253 special wrinkles, such as enabling display of the minibuffer and the
3254 minibuffer window, but fewer than you might suppose. Certain keys
3255 behave differently in the minibuffer, but that is only because of the
3256 minibuffer's local map; if you switch windows, you get the usual Emacs
3257 commands.
3258
3259 @cindex @code{throw} example
3260 @kindex exit
3261 @cindex exit recursive editing
3262 @cindex aborting
3263 To invoke a recursive editing level, call the function
3264 @code{recursive-edit}. This function contains the command loop; it also
3265 contains a call to @code{catch} with tag @code{exit}, which makes it
3266 possible to exit the recursive editing level by throwing to @code{exit}
3267 (@pxref{Catch and Throw}). If you throw a value other than @code{t},
3268 then @code{recursive-edit} returns normally to the function that called
3269 it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
3270 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
3271 control returns to the command loop one level up. This is called
3272 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
3273
3274 Most applications should not use recursive editing, except as part of
3275 using the minibuffer. Usually it is more convenient for the user if you
3276 change the major mode of the current buffer temporarily to a special
3277 major mode, which should have a command to go back to the previous mode.
3278 (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
3279 give the user different text to edit ``recursively'', create and select
3280 a new buffer in a special mode. In this mode, define a command to
3281 complete the processing and go back to the previous buffer. (The
3282 @kbd{m} command in Rmail does this.)
3283
3284 Recursive edits are useful in debugging. You can insert a call to
3285 @code{debug} into a function definition as a sort of breakpoint, so that
3286 you can look around when the function gets there. @code{debug} invokes
3287 a recursive edit but also provides the other features of the debugger.
3288
3289 Recursive editing levels are also used when you type @kbd{C-r} in
3290 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
3291
3292 @deffn Command recursive-edit
3293 @cindex suspend evaluation
3294 This function invokes the editor command loop. It is called
3295 automatically by the initialization of Emacs, to let the user begin
3296 editing. When called from a Lisp program, it enters a recursive editing
3297 level.
3298
3299 If the current buffer is not the same as the selected window's buffer,
3300 @code{recursive-edit} saves and restores the current buffer. Otherwise,
3301 if you switch buffers, the buffer you switched to is current after
3302 @code{recursive-edit} returns.
3303
3304 In the following example, the function @code{simple-rec} first
3305 advances point one word, then enters a recursive edit, printing out a
3306 message in the echo area. The user can then do any editing desired, and
3307 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
3308
3309 @example
3310 (defun simple-rec ()
3311 (forward-word 1)
3312 (message "Recursive edit in progress")
3313 (recursive-edit)
3314 (forward-word 1))
3315 @result{} simple-rec
3316 (simple-rec)
3317 @result{} nil
3318 @end example
3319 @end deffn
3320
3321 @deffn Command exit-recursive-edit
3322 This function exits from the innermost recursive edit (including
3323 minibuffer input). Its definition is effectively @code{(throw 'exit
3324 nil)}.
3325 @end deffn
3326
3327 @deffn Command abort-recursive-edit
3328 This function aborts the command that requested the innermost recursive
3329 edit (including minibuffer input), by signaling @code{quit}
3330 after exiting the recursive edit. Its definition is effectively
3331 @code{(throw 'exit t)}. @xref{Quitting}.
3332 @end deffn
3333
3334 @deffn Command top-level
3335 This function exits all recursive editing levels; it does not return a
3336 value, as it jumps completely out of any computation directly back to
3337 the main command loop.
3338 @end deffn
3339
3340 @defun recursion-depth
3341 This function returns the current depth of recursive edits. When no
3342 recursive edit is active, it returns 0.
3343 @end defun
3344
3345 @node Disabling Commands
3346 @section Disabling Commands
3347 @cindex disabled command
3348
3349 @dfn{Disabling a command} marks the command as requiring user
3350 confirmation before it can be executed. Disabling is used for commands
3351 which might be confusing to beginning users, to prevent them from using
3352 the commands by accident.
3353
3354 @kindex disabled
3355 The low-level mechanism for disabling a command is to put a
3356 non-@code{nil} @code{disabled} property on the Lisp symbol for the
3357 command. These properties are normally set up by the user's
3358 init file (@pxref{Init File}) with Lisp expressions such as this:
3359
3360 @example
3361 (put 'upcase-region 'disabled t)
3362 @end example
3363
3364 @noindent
3365 For a few commands, these properties are present by default (you can
3366 remove them in your init file if you wish).
3367
3368 If the value of the @code{disabled} property is a string, the message
3369 saying the command is disabled includes that string. For example:
3370
3371 @example
3372 (put 'delete-region 'disabled
3373 "Text deleted this way cannot be yanked back!\n")
3374 @end example
3375
3376 @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on
3377 what happens when a disabled command is invoked interactively.
3378 Disabling a command has no effect on calling it as a function from Lisp
3379 programs.
3380
3381 @deffn Command enable-command command
3382 Allow @var{command} (a symbol) to be executed without special
3383 confirmation from now on, and alter the user's init file (@pxref{Init
3384 File}) so that this will apply to future sessions.
3385 @end deffn
3386
3387 @deffn Command disable-command command
3388 Require special confirmation to execute @var{command} from now on, and
3389 alter the user's init file so that this will apply to future sessions.
3390 @end deffn
3391
3392 @defvar disabled-command-function
3393 The value of this variable should be a function. When the user
3394 invokes a disabled command interactively, this function is called
3395 instead of the disabled command. It can use @code{this-command-keys}
3396 to determine what the user typed to run the command, and thus find the
3397 command itself.
3398
3399 The value may also be @code{nil}. Then all commands work normally,
3400 even disabled ones.
3401
3402 By default, the value is a function that asks the user whether to
3403 proceed.
3404 @end defvar
3405
3406 @node Command History
3407 @section Command History
3408 @cindex command history
3409 @cindex complex command
3410 @cindex history of commands
3411
3412 The command loop keeps a history of the complex commands that have
3413 been executed, to make it convenient to repeat these commands. A
3414 @dfn{complex command} is one for which the interactive argument reading
3415 uses the minibuffer. This includes any @kbd{M-x} command, any
3416 @kbd{M-:} command, and any command whose @code{interactive}
3417 specification reads an argument from the minibuffer. Explicit use of
3418 the minibuffer during the execution of the command itself does not cause
3419 the command to be considered complex.
3420
3421 @defvar command-history
3422 This variable's value is a list of recent complex commands, each
3423 represented as a form to evaluate. It continues to accumulate all
3424 complex commands for the duration of the editing session, but when it
3425 reaches the maximum size (@pxref{Minibuffer History}), the oldest
3426 elements are deleted as new ones are added.
3427
3428 @example
3429 @group
3430 command-history
3431 @result{} ((switch-to-buffer "chistory.texi")
3432 (describe-key "^X^[")
3433 (visit-tags-table "~/emacs/src/")
3434 (find-tag "repeat-complex-command"))
3435 @end group
3436 @end example
3437 @end defvar
3438
3439 This history list is actually a special case of minibuffer history
3440 (@pxref{Minibuffer History}), with one special twist: the elements are
3441 expressions rather than strings.
3442
3443 There are a number of commands devoted to the editing and recall of
3444 previous commands. The commands @code{repeat-complex-command}, and
3445 @code{list-command-history} are described in the user manual
3446 (@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the
3447 minibuffer, the usual minibuffer history commands are available.
3448
3449 @node Keyboard Macros
3450 @section Keyboard Macros
3451 @cindex keyboard macros
3452
3453 A @dfn{keyboard macro} is a canned sequence of input events that can
3454 be considered a command and made the definition of a key. The Lisp
3455 representation of a keyboard macro is a string or vector containing the
3456 events. Don't confuse keyboard macros with Lisp macros
3457 (@pxref{Macros}).
3458
3459 @defun execute-kbd-macro kbdmacro &optional count loopfunc
3460 This function executes @var{kbdmacro} as a sequence of events. If
3461 @var{kbdmacro} is a string or vector, then the events in it are executed
3462 exactly as if they had been input by the user. The sequence is
3463 @emph{not} expected to be a single key sequence; normally a keyboard
3464 macro definition consists of several key sequences concatenated.
3465
3466 If @var{kbdmacro} is a symbol, then its function definition is used in
3467 place of @var{kbdmacro}. If that is another symbol, this process repeats.
3468 Eventually the result should be a string or vector. If the result is
3469 not a symbol, string, or vector, an error is signaled.
3470
3471 The argument @var{count} is a repeat count; @var{kbdmacro} is executed that
3472 many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is
3473 executed once. If it is 0, @var{kbdmacro} is executed over and over until it
3474 encounters an error or a failing search.
3475
3476 If @var{loopfunc} is non-@code{nil}, it is a function that is called,
3477 without arguments, prior to each iteration of the macro. If
3478 @var{loopfunc} returns @code{nil}, then this stops execution of the macro.
3479
3480 @xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
3481 @end defun
3482
3483 @defvar executing-kbd-macro
3484 This variable contains the string or vector that defines the keyboard
3485 macro that is currently executing. It is @code{nil} if no macro is
3486 currently executing. A command can test this variable so as to behave
3487 differently when run from an executing macro. Do not set this variable
3488 yourself.
3489 @end defvar
3490
3491 @defvar defining-kbd-macro
3492 This variable is non-@code{nil} if and only if a keyboard macro is
3493 being defined. A command can test this variable so as to behave
3494 differently while a macro is being defined. The value is
3495 @code{append} while appending to the definition of an existing macro.
3496 The commands @code{start-kbd-macro}, @code{kmacro-start-macro} and
3497 @code{end-kbd-macro} set this variable---do not set it yourself.
3498
3499 The variable is always local to the current terminal and cannot be
3500 buffer-local. @xref{Multiple Terminals}.
3501 @end defvar
3502
3503 @defvar last-kbd-macro
3504 This variable is the definition of the most recently defined keyboard
3505 macro. Its value is a string or vector, or @code{nil}.
3506
3507 The variable is always local to the current terminal and cannot be
3508 buffer-local. @xref{Multiple Terminals}.
3509 @end defvar
3510
3511 @defvar kbd-macro-termination-hook
3512 This normal hook is run when a keyboard macro terminates, regardless
3513 of what caused it to terminate (reaching the macro end or an error
3514 which ended the macro prematurely).
3515 @end defvar