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