2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/commands.info
6 @node Command Loop, Keymaps, Minibuffers, Top
8 @cindex editor command loop
11 When you run XEmacs, it enters the @dfn{editor command loop} almost
12 immediately. This loop reads events, executes their definitions,
13 and displays the results. In this chapter, we describe how these things
14 are done, and the subroutines that allow Lisp programs to do them.
17 * Command Overview:: How the command loop reads commands.
18 * Defining Commands:: Specifying how a function should read arguments.
19 * Interactive Call:: Calling a command, so that it will read arguments.
20 * Command Loop Info:: Variables set by the command loop for you to examine.
21 * Events:: What input looks like when you read it.
22 * Reading Input:: How to read input events from the keyboard or mouse.
23 * Waiting:: Waiting for user input or elapsed time.
24 * Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
25 * Prefix Command Arguments:: How the commands to set prefix args work.
26 * Recursive Editing:: Entering a recursive edit,
27 and why you usually shouldn't.
28 * Disabling Commands:: How the command loop handles disabled commands.
29 * Command History:: How the command history is set up, and how accessed.
30 * Keyboard Macros:: How keyboard macros are implemented.
33 @node Command Overview
34 @section Command Loop Overview
36 The command loop in XEmacs is a standard event loop, reading events
37 one at a time with @code{next-event} and handling them with
38 @code{dispatch-event}. An event is typically a single user action, such
39 as a keypress, mouse movement, or menu selection; but they can also be
40 notifications from the window system, informing XEmacs that (for
41 example) part of its window was just uncovered and needs to be redrawn.
42 @xref{Events}. Pending events are held in a first-in, first-out list
43 called the @dfn{event queue}: events are read from the head of the list,
44 and newly arriving events are added to the tail. In this way, events
45 are always processed in the order in which they arrive.
47 @code{dispatch-event} does most of the work of handling user actions.
48 The first thing it must do is put the events together into a key
49 sequence, which is a sequence of events that translates into a command.
50 It does this by consulting the active keymaps, which specify what the
51 valid key sequences are and how to translate them into commands.
52 @xref{Key Lookup}, for information on how this is done. The result of
53 the translation should be a keyboard macro or an interactively callable
54 function. If the key is @kbd{M-x}, then it reads the name of another
55 command, which it then calls. This is done by the command
56 @code{execute-extended-command} (@pxref{Interactive Call}).
58 To execute a command requires first reading the arguments for it.
59 This is done by calling @code{command-execute} (@pxref{Interactive
60 Call}). For commands written in Lisp, the @code{interactive}
61 specification says how to read the arguments. This may use the prefix
62 argument (@pxref{Prefix Command Arguments}) or may read with prompting
63 in the minibuffer (@pxref{Minibuffers}). For example, the command
64 @code{find-file} has an @code{interactive} specification which says to
65 read a file name using the minibuffer. The command's function body does
66 not use the minibuffer; if you call this command from Lisp code as a
67 function, you must supply the file name string as an ordinary Lisp
70 If the command is a string or vector (i.e., a keyboard macro) then
71 @code{execute-kbd-macro} is used to execute it. You can call this
72 function yourself (@pxref{Keyboard Macros}).
74 To terminate the execution of a running command, type @kbd{C-g}. This
75 character causes @dfn{quitting} (@pxref{Quitting}).
77 @defvar pre-command-hook
78 The editor command loop runs this normal hook before each command. At
79 that time, @code{this-command} contains the command that is about to
80 run, and @code{last-command} describes the previous command.
84 @defvar post-command-hook
85 The editor command loop runs this normal hook after each command. (In
86 FSF Emacs, it is also run when the command loop is entered, or
87 reentered after an error or quit.) At that time,
88 @code{this-command} describes the command that just ran, and
89 @code{last-command} describes the command before that. @xref{Hooks}.
92 Quitting is suppressed while running @code{pre-command-hook} and
93 @code{post-command-hook}. If an error happens while executing one of
94 these hooks, it terminates execution of the hook, but that is all it
97 @node Defining Commands
98 @section Defining Commands
99 @cindex defining commands
100 @cindex commands, defining
101 @cindex functions, making them interactive
102 @cindex interactive function
104 A Lisp function becomes a command when its body contains, at top
105 level, a form that calls the special form @code{interactive}. This
106 form does nothing when actually executed, but its presence serves as a
107 flag to indicate that interactive calling is permitted. Its argument
108 controls the reading of arguments for an interactive call.
111 * Using Interactive:: General rules for @code{interactive}.
112 * Interactive Codes:: The standard letter-codes for reading arguments
114 * Interactive Examples:: Examples of how to read interactive arguments.
117 @node Using Interactive
118 @subsection Using @code{interactive}
120 This section describes how to write the @code{interactive} form that
121 makes a Lisp function an interactively-callable command.
123 @defspec interactive arg-descriptor
124 @cindex argument descriptors
125 This special form declares that the function in which it appears is a
126 command, and that it may therefore be called interactively (via
127 @kbd{M-x} or by entering a key sequence bound to it). The argument
128 @var{arg-descriptor} declares how to compute the arguments to the
129 command when the command is called interactively.
131 A command may be called from Lisp programs like any other function, but
132 then the caller supplies the arguments and @var{arg-descriptor} has no
135 The @code{interactive} form has its effect because the command loop
136 (actually, its subroutine @code{call-interactively}) scans through the
137 function definition looking for it, before calling the function. Once
138 the function is called, all its body forms including the
139 @code{interactive} form are executed, but at this time
140 @code{interactive} simply returns @code{nil} without even evaluating its
144 There are three possibilities for the argument @var{arg-descriptor}:
148 It may be omitted or @code{nil}; then the command is called with no
149 arguments. This leads quickly to an error if the command requires one
153 It may be a Lisp expression that is not a string; then it should be a
154 form that is evaluated to get a list of arguments to pass to the
156 @cindex argument evaluation form
158 If this expression reads keyboard input (this includes using the
159 minibuffer), keep in mind that the integer value of point or the mark
160 before reading input may be incorrect after reading input. This is
161 because the current buffer may be receiving subprocess output;
162 if subprocess output arrives while the command is waiting for input,
163 it could relocate point and the mark.
165 Here's an example of what @emph{not} to do:
169 (list (region-beginning) (region-end)
170 (read-string "Foo: " nil 'my-history)))
174 Here's how to avoid the problem, by examining point and the mark only
175 after reading the keyboard input:
179 (let ((string (read-string "Foo: " nil 'my-history)))
180 (list (region-beginning) (region-end) string)))
184 @cindex argument prompt
185 It may be a string; then its contents should consist of a code character
186 followed by a prompt (which some code characters use and some ignore).
187 The prompt ends either with the end of the string or with a newline.
188 Here is a simple example:
191 (interactive "bFrobnicate buffer: ")
195 The code letter @samp{b} says to read the name of an existing buffer,
196 with completion. The buffer name is the sole argument passed to the
197 command. The rest of the string is a prompt.
199 If there is a newline character in the string, it terminates the prompt.
200 If the string does not end there, then the rest of the string should
201 contain another code character and prompt, specifying another argument.
202 You can specify any number of arguments in this way.
205 The prompt string can use @samp{%} to include previous argument values
206 (starting with the first argument) in the prompt. This is done using
207 @code{format} (@pxref{Formatting Strings}). For example, here is how
208 you could read the name of an existing buffer followed by a new name to
213 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
217 @cindex @samp{*} in interactive
218 @cindex read-only buffers in interactive
219 If the first character in the string is @samp{*}, then an error is
220 signaled if the buffer is read-only.
222 @cindex @samp{@@} in interactive
224 If the first character in the string is @samp{@@}, and if the key
225 sequence used to invoke the command includes any mouse events, then
226 the window associated with the first of those events is selected
227 before the command is run.
229 @cindex @samp{_} in interactive
231 If the first character in the string is @samp{_}, then this command will
232 not cause the region to be deactivated when it completes; that is,
233 @code{zmacs-region-stays} will be set to @code{t} when the command exits
236 You can use @samp{*}, @samp{@@}, and @samp{_} together; the order does
237 not matter. Actual reading of arguments is controlled by the rest of
238 the prompt string (starting with the first character that is not
239 @samp{*}, @samp{@@}, or @samp{_}).
242 @defun function-interactive function
243 This function retrieves the interactive specification of @var{function},
244 which may be any funcallable object. The specification will be returned
245 as the list of the symbol @code{interactive} and the specs. If
246 @var{function} is not interactive, @code{nil} will be returned.
249 @node Interactive Codes
250 @subsection Code Characters for @code{interactive}
251 @cindex interactive code description
252 @cindex description for interactive codes
253 @cindex codes, interactive, description of
254 @cindex characters for interactive codes
256 The code character descriptions below contain a number of key words,
257 defined here as follows:
261 @cindex interactive completion
262 Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name
263 completion because the argument is read using @code{completing-read}
264 (@pxref{Completion}). @kbd{?} displays a list of possible completions.
267 Require the name of an existing object. An invalid name is not
268 accepted; the commands to exit the minibuffer do not exit if the current
272 @cindex default argument string
273 A default value of some sort is used if the user enters no text in the
274 minibuffer. The default depends on the code character.
277 This code letter computes an argument without reading any input.
278 Therefore, it does not use a prompt string, and any prompt string you
281 Even though the code letter doesn't use a prompt string, you must follow
282 it with a newline if it is not the last code character in the string.
285 A prompt immediately follows the code character. The prompt ends either
286 with the end of the string or with a newline.
289 This code character is meaningful only at the beginning of the
290 interactive string, and it does not look for a prompt or a newline.
291 It is a single, isolated character.
294 @cindex reading interactive arguments
295 Here are the code character descriptions for use with @code{interactive}:
299 Signal an error if the current buffer is read-only. Special.
302 Select the window mentioned in the first mouse event in the key
303 sequence that invoked this command. Special.
306 Do not cause the region to be deactivated when this command completes.
310 A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
314 The name of an existing buffer. By default, uses the name of the
315 current buffer (@pxref{Buffers}). Existing, Completion, Default,
319 A buffer name. The buffer need not exist. By default, uses the name of
320 a recently used buffer other than the current buffer. Completion,
324 A character. The cursor does not move into the echo area. Prompt.
327 A command name (i.e., a symbol satisfying @code{commandp}). Existing,
331 @cindex position argument
332 The position of point, as an integer (@pxref{Point}). No I/O.
335 A directory name. The default is the current default directory of the
336 current buffer, @code{default-directory} (@pxref{System Environment}).
337 Existing, Completion, Default, Prompt.
340 The last mouse-button or misc-user event in the key sequence that
341 invoked the command. No I/O.
343 You can use @samp{e} more than once in a single command's interactive
344 specification. If the key sequence that invoked the command has @var{n}
345 mouse-button or misc-user events, the @var{n}th @samp{e} provides the
346 @var{n}th such event.
349 A file name of an existing file (@pxref{File Names}). The default
350 directory is @code{default-directory}. Existing, Completion, Default,
354 A file name. The file need not exist. Completion, Default, Prompt.
357 A key sequence (@pxref{Keymap Terminology}). This keeps reading events
358 until a command (or undefined command) is found in the current key
359 maps. The key sequence argument is represented as a vector of events.
360 The cursor does not move into the echo area. Prompt.
362 This kind of input is used by commands such as @code{describe-key} and
363 @code{global-set-key}.
366 A key sequence, whose definition you intend to change. This works like
367 @samp{k}, except that it suppresses, for the last input event in the key
368 sequence, the conversions that are normally used (when necessary) to
369 convert an undefined key into a defined one.
372 @cindex marker argument
373 The position of the mark, as an integer. No I/O.
376 A number read with the minibuffer. If the input is not a number, the
377 user is asked to try again. The prefix argument, if any, is not used.
381 @cindex raw prefix argument usage
382 The raw prefix argument. If the prefix argument is @code{nil}, then
383 read a number as with @kbd{n}. Requires a number. @xref{Prefix Command
387 @cindex numeric prefix argument usage
388 The numeric prefix argument. (Note that this @samp{p} is lower case.)
392 The raw prefix argument. (Note that this @samp{P} is upper case.) No
396 @cindex region argument
397 Point and the mark, as two numeric arguments, smallest first. This is
398 the only code letter that specifies two successive arguments rather than
402 Arbitrary text, read in the minibuffer and returned as a string
403 (@pxref{Text from Minibuffer}). Terminate the input with either
404 @key{LFD} or @key{RET}. (@kbd{C-q} may be used to include either of
405 these characters in the input.) Prompt.
408 An interned symbol whose name is read in the minibuffer. Any whitespace
409 character terminates the input. (Use @kbd{C-q} to include whitespace in
410 the string.) Other characters that normally terminate a symbol (e.g.,
411 parentheses and brackets) do not do so here. Prompt.
414 A variable declared to be a user option (i.e., satisfying the predicate
415 @code{user-variable-p}). @xref{High-Level Completion}. Existing,
419 A Lisp object, specified with its read syntax, terminated with a
420 @key{LFD} or @key{RET}. The object is not evaluated. @xref{Object from
424 @cindex evaluated expression argument
425 A Lisp form is read as with @kbd{x}, but then evaluated so that its
426 value becomes the argument for the command. Prompt.
429 @node Interactive Examples
430 @subsection Examples of Using @code{interactive}
431 @cindex examples of using @code{interactive}
432 @cindex @code{interactive}, examples of using
434 Here are some examples of @code{interactive}:
438 (defun foo1 () ; @r{@code{foo1} takes no arguments,}
439 (interactive) ; @r{just moves forward two words.}
445 (defun foo2 (n) ; @r{@code{foo2} takes one argument,}
446 (interactive "p") ; @r{which is the numeric prefix.}
447 (forward-word (* 2 n)))
452 (defun foo3 (n) ; @r{@code{foo3} takes one argument,}
453 (interactive "nCount:") ; @r{which is read with the Minibuffer.}
454 (forward-word (* 2 n)))
459 (defun three-b (b1 b2 b3)
460 "Select three existing buffers.
461 Put them into three windows, selecting the last one."
463 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
464 (delete-other-windows)
465 (split-window (selected-window) 8)
466 (switch-to-buffer b1)
468 (split-window (selected-window) 8)
469 (switch-to-buffer b2)
471 (switch-to-buffer b3))
474 (three-b "*scratch*" "declarations.texi" "*mail*")
479 @node Interactive Call
480 @section Interactive Call
481 @cindex interactive call
483 After the command loop has translated a key sequence into a
484 definition, it invokes that definition using the function
485 @code{command-execute}. If the definition is a function that is a
486 command, @code{command-execute} calls @code{call-interactively}, which
487 reads the arguments and calls the command. You can also call these
490 @defun commandp object
491 Returns @code{t} if @var{object} is suitable for calling interactively;
492 that is, if @var{object} is a command. Otherwise, returns @code{nil}.
494 The interactively callable objects include strings and vectors (treated
495 as keyboard macros), lambda expressions that contain a top-level call to
496 @code{interactive}, compiled-function objects made from such lambda
497 expressions, autoload objects that are declared as interactive
498 (non-@code{nil} fourth argument to @code{autoload}), and some of the
501 A symbol is @code{commandp} if its function definition is
504 Keys and keymaps are not commands. Rather, they are used to look up
505 commands (@pxref{Keymaps}).
507 See @code{documentation} in @ref{Accessing Documentation}, for a
508 realistic example of using @code{commandp}.
511 @defun call-interactively command &optional record-flag
512 This function calls the interactively callable function @var{command},
513 reading arguments according to its interactive calling specifications.
514 An error is signaled if @var{command} is not a function or if it cannot
515 be called interactively (i.e., is not a command). Note that keyboard
516 macros (strings and vectors) are not accepted, even though they are
517 considered commands, because they are not functions.
520 If @var{record-flag} is the symbol @code{lambda}, the interactive
521 calling arguments for @code{command} are read and returned as a list,
522 but the function is not called on them.
524 @cindex record command history
525 If @var{record-flag} is @code{t}, then this command and its arguments
526 are unconditionally added to the list @code{command-history}.
527 Otherwise, the command is added only if it uses the minibuffer to read
528 an argument. @xref{Command History}.
531 @defun command-execute command &optional record-flag
532 @cindex keyboard macro execution
533 This function executes @var{command} as an editing command. The
534 argument @var{command} must satisfy the @code{commandp} predicate; i.e.,
535 it must be an interactively callable function or a keyboard macro.
537 A string or vector as @var{command} is executed with
538 @code{execute-kbd-macro}. A function is passed to
539 @code{call-interactively}, along with the optional @var{record-flag}.
541 A symbol is handled by using its function definition in its place. A
542 symbol with an @code{autoload} definition counts as a command if it was
543 declared to stand for an interactively callable function. Such a
544 definition is handled by loading the specified library and then
545 rechecking the definition of the symbol.
548 @deffn Command execute-extended-command prefix-argument
549 @cindex read command name
550 This function reads a command name from the minibuffer using
551 @code{completing-read} (@pxref{Completion}). Then it uses
552 @code{command-execute} to call the specified command. Whatever that
553 command returns becomes the value of @code{execute-extended-command}.
555 @cindex execute with prefix argument
556 If the command asks for a prefix argument, it receives the value
557 @var{prefix-argument}. If @code{execute-extended-command} is called
558 interactively, the current raw prefix argument is used for
559 @var{prefix-argument}, and thus passed on to whatever command is run.
561 @c !!! Should this be @kindex?
563 @code{execute-extended-command} is the normal definition of @kbd{M-x},
564 so it uses the string @w{@samp{M-x }} as a prompt. (It would be better
565 to take the prompt from the events used to invoke
566 @code{execute-extended-command}, but that is painful to implement.) A
567 description of the value of the prefix argument, if any, also becomes
572 (execute-extended-command 1)
573 ---------- Buffer: Minibuffer ----------
574 1 M-x forward-word RET
575 ---------- Buffer: Minibuffer ----------
582 This function returns @code{t} if the containing function (the one that
583 called @code{interactive-p}) was called interactively, with the function
584 @code{call-interactively}. (It makes no difference whether
585 @code{call-interactively} was called from Lisp or directly from the
586 editor command loop.) If the containing function was called by Lisp
587 evaluation (or with @code{apply} or @code{funcall}), then it was not
588 called interactively.
590 The most common use of @code{interactive-p} is for deciding whether to
591 print an informative message. As a special exception,
592 @code{interactive-p} returns @code{nil} whenever a keyboard macro is
593 being run. This is to suppress the informative messages and speed
594 execution of the macro.
610 (setq foobar (list (foo) (interactive-p))))
615 ;; @r{Type @kbd{M-x foo}.}
620 ;; @r{Type @kbd{M-x bar}.}
621 ;; @r{This does not print anything.}
631 @node Command Loop Info
632 @section Information from the Command Loop
634 The editor command loop sets several Lisp variables to keep status
635 records for itself and for commands that are run.
638 This variable records the name of the previous command executed by the
639 command loop (the one before the current command). Normally the value
640 is a symbol with a function definition, but this is not guaranteed.
642 The value is copied from @code{this-command} when a command returns to
643 the command loop, except when the command specifies a prefix argument
644 for the following command.
648 @cindex current command
649 This variable records the name of the command now being executed by
650 the editor command loop. Like @code{last-command}, it is normally a symbol
651 with a function definition.
653 The command loop sets this variable just before running a command, and
654 copies its value into @code{last-command} when the command finishes
655 (unless the command specifies a prefix argument for the following
658 @cindex kill command repetition
659 Some commands set this variable during their execution, as a flag for
660 whatever command runs next. In particular, the functions for killing text
661 set @code{this-command} to @code{kill-region} so that any kill commands
662 immediately following will know to append the killed text to the
666 If you do not want a particular command to be recognized as the previous
667 command in the case where it got an error, you must code that command to
668 prevent this. One way is to set @code{this-command} to @code{t} at the
669 beginning of the command, and set @code{this-command} back to its proper
670 value at the end, like this:
673 (defun foo (args@dots{})
674 (interactive @dots{})
675 (let ((old-this-command this-command))
676 (setq this-command t)
677 @r{@dots{}do the work@dots{}}
678 (setq this-command old-this-command)))
681 @defun this-command-keys
682 This function returns a vector containing the key and mouse events that
683 invoked the present command, plus any previous commands that generated
684 the prefix argument for this command. (Note: this is not the same as in
685 FSF Emacs, which can return a string.) @xref{Events}.
687 This function copies the vector and the events; it is safe to keep and
693 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
694 @result{} [#<keypress-event control-U> #<keypress-event control-X> #<keypress-event control-E>]
699 @ignore Not in XEmacs
700 @defvar last-nonmenu-event
701 This variable holds the last input event read as part of a key
702 sequence, not counting events resulting from mouse menus.
704 One use of this variable is to figure out a good default location to
709 @defvar last-command-event
710 This variable is set to the last input event that was read by the
711 command loop as part of a command. The principal use of this variable
712 is in @code{self-insert-command}, which uses it to decide which
715 This variable is off limits: you may not set its value or modify the
716 event that is its value, as it is destructively modified by
717 @code{read-key-sequence}. If you want to keep a pointer to this value,
718 you must use @code{copy-event}.
720 Note that this variable is an alias for @code{last-command-char} in
726 ;; @r{Now type @kbd{C-u C-x C-e}.}
727 @result{} #<keypress-event control-E>
732 @defvar last-command-char
734 If the value of @code{last-command-event} is a keyboard event, then this
735 is the nearest character equivalent to it (or @code{nil} if there is no
736 character equivalent). @code{last-command-char} is the character that
737 @code{self-insert-command} will insert in the buffer. Remember that
738 there is @emph{not} a one-to-one mapping between keyboard events and
739 XEmacs characters: many keyboard events have no corresponding character,
740 and when the Mule feature is available, most characters can not be input
741 on standard keyboards, except possibly with help from an input method.
742 So writing code that examines this variable to determine what key has
743 been typed is bad practice, unless you are certain that it will be one
744 of a small set of characters.
746 This variable exists for compatibility with Emacs version 18.
751 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
758 @defvar current-mouse-event
759 This variable holds the mouse-button event which invoked this command,
760 or @code{nil}. This is what @code{(interactive "e")} returns.
763 @defvar echo-keystrokes
764 This variable determines how much time should elapse before command
765 characters echo. Its value must be an integer, which specifies the
766 number of seconds to wait before echoing. If the user types a prefix
767 key (say @kbd{C-x}) and then delays this many seconds before continuing,
768 the key @kbd{C-x} is echoed in the echo area. Any subsequent characters
769 in the same command will be echoed as well.
771 If the value is zero, then command input is not echoed.
779 The XEmacs command loop reads a sequence of @dfn{events} that
780 represent keyboard or mouse activity. Unlike in Emacs 18 and in FSF
781 Emacs, events are a primitive Lisp type that must be manipulated
782 using their own accessor and settor primitives. This section describes
783 the representation and meaning of input events in detail.
785 A key sequence that starts with a mouse event is read using the keymaps
786 of the buffer in the window that the mouse was in, not the current
787 buffer. This does not imply that clicking in a window selects that
788 window or its buffer---that is entirely under the control of the command
789 binding of the key sequence.
791 For information about how exactly the XEmacs command loop works,
792 @xref{Reading Input}.
795 This function returns non-@code{nil} if @var{event} is an input event.
799 * Event Types:: Events come in different types.
800 * Event Contents:: What the contents of each event type are.
801 * Event Predicates:: Querying whether an event is of a
803 * Accessing Mouse Event Positions::
804 Determining where a mouse event occurred,
806 * Accessing Other Event Info:: Accessing non-positional event info.
807 * Working With Events:: Creating, copying, and destroying events.
808 * Converting Events:: Converting between events, keys, and
813 @subsection Event Types
815 Events represent keyboard or mouse activity or status changes of various
816 sorts, such as process input being available or a timeout being triggered.
817 The different event types are as follows:
820 @item key-press event
821 A key was pressed. Note that modifier keys such as ``control'', ``shift'',
822 and ``alt'' do not generate events; instead, they are tracked internally
823 by XEmacs, and non-modifier key presses generate events that specify both
824 the key pressed and the modifiers that were held down at the time.
826 @item button-press event
827 @itemx button-release event
828 A button was pressed or released. Along with the button that was pressed
829 or released, button events specify the modifier keys that were held down
830 at the time and the position of the pointer at the time.
833 The pointer was moved. Along with the position of the pointer, these events
834 also specify the modifier keys that were held down at the time.
836 @item misc-user event
837 A menu item was selected, the scrollbar was used, or a drag or a drop occurred.
840 Input is available on a process.
843 A timeout has triggered.
846 Some window-system-specific action (such as a frame being resized or
847 a portion of a frame needing to be redrawn) has occurred. The contents
848 of this event are not accessible at the E-Lisp level, but
849 @code{dispatch-event} knows what to do with an event of this type.
852 This is a special kind of event specifying that a particular function
853 needs to be called when this event is dispatched. An event of this type
854 is sometimes placed in the event queue when a magic event is processed.
855 This kind of event should generally just be passed off to
856 @code{dispatch-event}. @xref{Dispatching an Event}.
860 @subsection Contents of the Different Types of Events
862 Every event, no matter what type it is, contains a timestamp (which is
863 typically an offset in milliseconds from when the X server was started)
864 indicating when the event occurred. In addition, many events contain
865 a @dfn{channel}, which specifies which frame the event occurred on,
866 and/or a value indicating which modifier keys (shift, control, etc.)
867 were held down at the time of the event.
869 The contents of each event are as follows:
872 @item key-press event
877 Which key was pressed. This is an integer (in the printing @sc{ASCII}
878 range: >32 and <127) or a symbol such as @code{left} or @code{right}.
879 Note that many physical keys are actually treated as two separate keys,
880 depending on whether the shift key is pressed; for example, the ``a''
881 key is treated as either ``a'' or ``A'' depending on the state of the
882 shift key, and the ``1'' key is similarly treated as either ``1'' or
883 ``!'' on most keyboards. In such cases, the shift key does not show up
884 in the modifier list. For other keys, such as @code{backspace}, the
885 shift key shows up as a regular modifier.
887 Which modifier keys were pressed. As mentioned above, the shift key
888 is not treated as a modifier for many keys and will not show up in this list
892 @item button-press event
893 @itemx button-release event
898 What button went down or up. Buttons are numbered starting at 1.
900 Which modifier keys were pressed. The special business mentioned above
901 for the shift key does @emph{not} apply to mouse events.
904 The position of the pointer (in pixels) at the time of the event.
907 @item pointer-motion event
913 The position of the pointer (in pixels) after it moved.
915 Which modifier keys were pressed. The special business mentioned above
916 for the shift key does @emph{not} apply to mouse events.
919 @item misc-user event
923 The E-Lisp function to call for this event. This is normally either
924 @code{eval} or @code{call-interactively}.
926 The object to pass to the function. This is normally the callback that
927 was specified in the menu description.
929 What button went down or up. Buttons are numbered starting at 1.
931 Which modifier keys were pressed. The special business mentioned above
932 for the shift key does @emph{not} apply to mouse events.
935 The position of the pointer (in pixels) at the time of the event.
942 The Emacs ``process'' object in question.
949 The E-Lisp function to call for this timeout. It is called with one
952 Some Lisp object associated with this timeout, to make it easier to tell
953 them apart. The function and object for this event were specified when
961 (The rest of the information in this event is not user-accessible.)
967 An E-Lisp function to call when this event is dispatched.
969 The object to pass to the function. The function and object are set
970 when the event is created.
974 @defun event-type event
975 Return the type of @var{event}.
977 This will be a symbol; one of
983 A mouse button was pressed.
985 A mouse button was released.
989 Some other user action happened; typically, this is
990 a menu selection, scrollbar action, or drag and drop action.
992 Input is available from a subprocess.
994 A timeout has expired.
996 This causes a specified action to occur when dispatched.
998 Some window-system-specific event has occurred.
1002 @node Event Predicates
1003 @subsection Event Predicates
1005 The following predicates return whether an object is an event of a
1008 @defun key-press-event-p object
1009 This is true if @var{object} is a key-press event.
1012 @defun button-event-p object object
1013 This is true if @var{object} is a mouse button-press or button-release
1017 @defun button-press-event-p object
1018 This is true if @var{object} is a mouse button-press event.
1021 @defun button-release-event-p object
1022 This is true if @var{object} is a mouse button-release event.
1025 @defun motion-event-p object
1026 This is true if @var{object} is a mouse motion event.
1029 @defun mouse-event-p object
1030 This is true if @var{object} is a mouse button-press, button-release
1034 @defun eval-event-p object
1035 This is true if @var{object} is an eval event.
1038 @defun misc-user-event-p object
1039 This is true if @var{object} is a misc-user event.
1042 @defun process-event-p object
1043 This is true if @var{object} is a process event.
1046 @defun timeout-event-p object
1047 This is true if @var{object} is a timeout event.
1050 @defun event-live-p object
1051 This is true if @var{object} is any event that has not been deallocated.
1054 @node Accessing Mouse Event Positions
1055 @subsection Accessing the Position of a Mouse Event
1057 Unlike other events, mouse events (i.e. motion, button-press,
1058 button-release, and drag or drop type misc-user events) occur in a
1059 particular location on the screen. Many primitives are provided for
1060 determining exactly where the event occurred and what is under that
1064 * Frame-Level Event Position Info::
1065 * Window-Level Event Position Info::
1066 * Event Text Position Info::
1067 * Event Glyph Position Info::
1068 * Event Toolbar Position Info::
1069 * Other Event Position Info::
1072 @node Frame-Level Event Position Info
1073 @subsubsection Frame-Level Event Position Info
1075 The following functions return frame-level information about where
1076 a mouse event occurred.
1078 @defun event-frame event
1079 This function returns the ``channel'' or frame that the given mouse
1080 motion, button press, button release, or misc-user event occurred in.
1081 This will be @code{nil} for non-mouse events.
1084 @defun event-x-pixel event
1085 This function returns the X position in pixels of the given mouse event.
1086 The value returned is relative to the frame the event occurred in.
1087 This will signal an error if the event is not a mouse event.
1090 @defun event-y-pixel event
1091 This function returns the Y position in pixels of the given mouse event.
1092 The value returned is relative to the frame the event occurred in.
1093 This will signal an error if the event is not a mouse event.
1096 @node Window-Level Event Position Info
1097 @subsubsection Window-Level Event Position Info
1099 The following functions return window-level information about where
1100 a mouse event occurred.
1102 @defun event-window event
1103 Given a mouse motion, button press, button release, or misc-user event, compute and
1104 return the window on which that event occurred. This may be @code{nil}
1105 if the event occurred in the border or over a toolbar. The modeline is
1106 considered to be within the window it describes.
1109 @defun event-buffer event
1110 Given a mouse motion, button press, button release, or misc-user event, compute and
1111 return the buffer of the window on which that event occurred. This may
1112 be @code{nil} if the event occurred in the border or over a toolbar.
1113 The modeline is considered to be within the window it describes. This is
1114 equivalent to calling @code{event-window} and then calling
1115 @code{window-buffer} on the result if it is a window.
1118 @defun event-window-x-pixel event
1119 This function returns the X position in pixels of the given mouse event.
1120 The value returned is relative to the window the event occurred in.
1121 This will signal an error if the event is not a mouse-motion, button-press,
1122 button-release, or misc-user event.
1125 @defun event-window-y-pixel event
1126 This function returns the Y position in pixels of the given mouse event.
1127 The value returned is relative to the window the event occurred in.
1128 This will signal an error if the event is not a mouse-motion, button-press,
1129 button-release, or misc-user event.
1132 @node Event Text Position Info
1133 @subsubsection Event Text Position Info
1135 The following functions return information about the text (including the
1136 modeline) that a mouse event occurred over or near.
1138 @defun event-over-text-area-p event
1139 Given a mouse-motion, button-press, button-release, or misc-user event, this
1140 function returns @code{t} if the event is over the text area of a
1141 window. Otherwise, @code{nil} is returned. The modeline is not
1142 considered to be part of the text area.
1145 @defun event-over-modeline-p event
1146 Given a mouse-motion, button-press, button-release, or misc-user event, this
1147 function returns @code{t} if the event is over the modeline of a window.
1148 Otherwise, @code{nil} is returned.
1151 @defun event-x event
1152 This function returns the X position of the given mouse-motion,
1153 button-press, button-release, or misc-user event in characters. This is relative
1154 to the window the event occurred over.
1157 @defun event-y event
1158 This function returns the Y position of the given mouse-motion,
1159 button-press, button-release, or misc-user event in characters. This is relative
1160 to the window the event occurred over.
1163 @defun event-point event
1164 This function returns the character position of the given mouse-motion,
1165 button-press, button-release, or misc-user event. If the event did not occur over
1166 a window, or did not occur over text, then this returns @code{nil}.
1167 Otherwise, it returns an index into the buffer visible in the event's
1171 @defun event-closest-point event
1172 This function returns the character position of the given mouse-motion,
1173 button-press, button-release, or misc-user event. If the event did not occur over
1174 a window or over text, it returns the closest point to the location of
1175 the event. If the Y pixel position overlaps a window and the X pixel
1176 position is to the left of that window, the closest point is the
1177 beginning of the line containing the Y position. If the Y pixel
1178 position overlaps a window and the X pixel position is to the right of
1179 that window, the closest point is the end of the line containing the Y
1180 position. If the Y pixel position is above a window, 0 is returned. If
1181 it is below a window, the value of @code{(window-end)} is returned.
1184 @node Event Glyph Position Info
1185 @subsubsection Event Glyph Position Info
1187 The following functions return information about the glyph (if any) that
1188 a mouse event occurred over.
1190 @defun event-over-glyph-p event
1191 Given a mouse-motion, button-press, button-release, or misc-user event, this
1192 function returns @code{t} if the event is over a glyph. Otherwise,
1193 @code{nil} is returned.
1196 @defun event-glyph-extent event
1197 If the given mouse-motion, button-press, button-release, or misc-user event happened
1198 on top of a glyph, this returns its extent; else @code{nil} is returned.
1201 @defun event-glyph-x-pixel event
1202 Given a mouse-motion, button-press, button-release, or misc-user event over a
1203 glyph, this function returns the X position of the pointer relative to
1204 the upper left of the glyph. If the event is not over a glyph, it returns
1208 @defun event-glyph-y-pixel event
1209 Given a mouse-motion, button-press, button-release, or misc-user event over a
1210 glyph, this function returns the Y position of the pointer relative to
1211 the upper left of the glyph. If the event is not over a glyph, it returns
1215 @node Event Toolbar Position Info
1216 @subsubsection Event Toolbar Position Info
1218 @defun event-over-toolbar-p event
1219 Given a mouse-motion, button-press, button-release, or misc-user event, this
1220 function returns @code{t} if the event is over a toolbar. Otherwise,
1221 @code{nil} is returned.
1224 @defun event-toolbar-button event
1225 If the given mouse-motion, button-press, button-release, or misc-user event
1226 happened on top of a toolbar button, this function returns the button.
1227 Otherwise, @code{nil} is returned.
1230 @node Other Event Position Info
1231 @subsubsection Other Event Position Info
1233 @defun event-over-border-p event
1234 Given a mouse-motion, button-press, button-release, or misc-user event, this
1235 function returns @code{t} if the event is over an internal toolbar.
1236 Otherwise, @code{nil} is returned.
1239 @node Accessing Other Event Info
1240 @subsection Accessing the Other Contents of Events
1242 The following functions allow access to the contents of events other than
1243 the position info described in the previous section.
1245 @defun event-timestamp event
1246 This function returns the timestamp of the given event object.
1249 @defun event-device event
1250 This function returns the device that the given event occurred on.
1253 @defun event-key event
1254 This function returns the Keysym of the given key-press event.
1255 This will be the @sc{ASCII} code of a printing character, or a symbol.
1258 @defun event-button event
1259 This function returns the button-number of the given button-press or
1260 button-release event.
1263 @defun event-modifiers event
1264 This function returns a list of symbols, the names of the modifier keys
1265 which were down when the given mouse or keyboard event was produced.
1268 @defun event-modifier-bits event
1269 This function returns a number representing the modifier keys which were down
1270 when the given mouse or keyboard event was produced.
1273 @defun event-function event
1274 This function returns the callback function of the given timeout, misc-user,
1278 @defun event-object event
1279 This function returns the callback function argument of the given timeout,
1280 misc-user, or eval event.
1283 @defun event-process event
1284 This function returns the process of the given process event.
1287 @node Working With Events
1288 @subsection Working With Events
1290 XEmacs provides primitives for creating, copying, and destroying event
1291 objects. Many functions that return events take an event object as an
1292 argument and fill in the fields of this event; or they make accept
1293 either an event object or @code{nil}, creating the event object first in
1296 @defun make-event &optional type plist
1297 This function creates a new event structure. If no arguments are
1298 specified, the created event will be empty. To specify the event type,
1299 use the @var{type} argument. The allowed types are @code{empty},
1300 @code{key-press}, @code{button-press}, @code{button-release},
1301 @code{motion}, or @code{misc-user}.
1303 @var{plist} is a property list, the properties being compatible to those
1304 returned by @code{event-properties}. For events other than
1305 @code{empty}, it is mandatory to specify certain properties. For
1306 @code{empty} events, @var{plist} must be @code{nil}. The list is
1307 @dfn{canonicalized}, which means that if a property keyword is present
1308 more than once, only the first instance is taken into account.
1309 Specifying an unknown or illegal property signals an error.
1311 The following properties are allowed:
1314 @item @code{channel}
1315 The event channel. This is a frame or a console. For mouse events (of
1316 type @code{button-press}, @code{button-release} and @code{motion}), this
1317 must be a frame. For key-press events, it must be a console. If
1318 channel is unspecified by @var{plist}, it will be set to the selected
1319 frame or selected console, as appropriate.
1322 The event key. This is either a symbol or a character. It is allowed
1323 (and required) only for key-press events.
1326 The event button. This an integer, either 1, 2 or 3. It is allowed
1327 only for button-press and button-release events.
1329 @item @code{modifiers}
1330 The event modifiers. This is a list of modifier symbols. It is allowed
1331 for key-press, button-press, button-release and motion events.
1334 The event X coordinate. This is an integer. It is relative to the
1335 channel's root window, and is allowed for button-press, button-release
1339 The event Y coordinate. This is an integer. It is relative to the
1340 channel's root window, and is allowed for button-press, button-release
1341 and motion events. This means that, for instance, to access the
1342 toolbar, the @code{y} property will have to be negative.
1344 @item @code{timestamp}
1345 The event timestamp, a non-negative integer. Allowed for all types of
1349 @emph{WARNING}: the event object returned by this function may be a
1350 reused one; see the function @code{deallocate-event}.
1352 The events created by @code{make-event} can be used as non-interactive
1353 arguments to the functions with an @code{(interactive "e")}
1356 Here are some basic examples of usage:
1360 ;; @r{Create an empty event.}
1362 @result{} #<empty-event>
1366 ;; @r{Try creating a key-press event.}
1367 (make-event 'key-press)
1368 @error{} Undefined key for keypress event
1372 ;; @r{Creating a key-press event, try 2}
1373 (make-event 'key-press '(key home))
1374 @result{} #<keypress-event home>
1378 ;; @r{Create a key-press event of dubious fame.}
1379 (make-event 'key-press '(key escape modifiers (meta alt control shift)))
1380 @result{} #<keypress-event control-meta-alt-shift-escape>
1384 ;; @r{Create a M-button1 event at coordinates defined by variables}
1385 ;; @r{@var{x} and @var{y}.}
1386 (make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y))
1387 @result{} #<buttondown-event meta-button1>
1391 ;; @r{Create a similar button-release event.}
1392 (make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x))
1393 @result{} #<buttonup-event meta-button1up>
1397 ;; @r{Create a mouse-motion event.}
1398 (make-event 'motion '(x 20 y 30))
1399 @result{} #<motion-event 20, 30>
1401 (event-properties (make-event 'motion '(x 20 y 30)))
1402 @result{} (channel #<x-frame "emacs" 0x8e2> x 20 y 30
1403 modifiers nil timestamp 0)
1407 In conjunction with @code{event-properties}, you can use
1408 @code{make-event} to create modified copies of existing events. For
1409 instance, the following code will return an @code{equal} copy of
1413 (make-event (event-type @var{event})
1414 (event-properties @var{event}))
1417 Note, however, that you cannot use @code{make-event} as the generic
1418 replacement for @code{copy-event}, because it does not allow creating
1419 all of the event types.
1421 To create a modified copy of an event, you can use the canonicalization
1422 feature of @var{plist}. The following example creates a copy of
1423 @var{event}, but with @code{modifiers} reset to @code{nil}.
1426 (make-event (event-type @var{event})
1427 (append '(modifiers nil)
1428 (event-properties @var{event})))
1432 @defun copy-event event1 &optional event2
1433 This function makes a copy of the given event object. If a second
1434 argument is given, the first event is copied into the second and the
1435 second is returned. If the second argument is not supplied (or is
1436 @code{nil}) then a new event will be made.
1439 @defun deallocate-event event
1440 This function allows the given event structure to be reused. You
1441 @strong{MUST NOT} use this event object after calling this function with
1442 it. You will lose. It is not necessary to call this function, as event
1443 objects are garbage-collected like all other objects; however, it may be
1444 more efficient to explicitly deallocate events when you are sure that
1448 @node Converting Events
1449 @subsection Converting Events
1451 XEmacs provides some auxiliary functions for converting between events
1452 and other ways of representing keys. These are useful when working with
1453 @sc{ASCII} strings and with keymaps.
1455 @defun character-to-event ch &optional event device
1456 This function converts a numeric @sc{ASCII} value to an event structure,
1457 replete with modifier bits. @var{ch} is the character to convert, and
1458 @var{event} is the event object to fill in. This function contains
1459 knowledge about what the codes ``mean'' -- for example, the number 9 is
1460 converted to the character @key{Tab}, not the distinct character
1463 Note that @var{ch} does not have to be a numeric value, but can be a
1464 symbol such as @code{clear} or a list such as @code{(control
1467 If @code{event} is not @code{nil}, it is modified; otherwise, a
1468 new event object is created. In both cases, the event is returned.
1470 Optional third arg @var{device} is the device to store in the event;
1471 this also affects whether the high bit is interpreted as a meta key. A
1472 value of @code{nil} means use the selected device but always treat the
1475 Beware that @code{character-to-event} and @code{event-to-character} are
1476 not strictly inverse functions, since events contain much more
1477 information than the @sc{ASCII} character set can encode.
1480 @defun event-to-character event &optional allow-extra-modifiers allow-meta allow-non-ascii
1481 This function returns the closest @sc{ASCII} approximation to
1482 @var{event}. If the event isn't a keypress, this returns @code{nil}.
1484 If @var{allow-extra-modifiers} is non-@code{nil}, then this is lenient
1485 in its translation; it will ignore modifier keys other than
1486 @key{control} and @key{meta}, and will ignore the @key{shift} modifier
1487 on those characters which have no shifted @sc{ASCII} equivalent
1488 (@key{Control-Shift-A} for example, will be mapped to the same
1489 @sc{ASCII} code as @key{Control-A}).
1491 If @var{allow-meta} is non-@code{nil}, then the @key{Meta} modifier will
1492 be represented by turning on the high bit of the byte returned;
1493 otherwise, @code{nil} will be returned for events containing the
1494 @key{Meta} modifier.
1496 If @var{allow-non-ascii} is non-@code{nil}, then characters which are
1497 present in the prevailing character set (@pxref{Keymaps, variable
1498 @code{character-set-property}}) will be returned as their code in that
1499 character set, instead of the return value being restricted to
1502 Note that specifying both @var{allow-meta} and @var{allow-non-ascii} is
1503 ambiguous, as both use the high bit; @key{M-x} and @key{oslash} will be
1507 @defun events-to-keys events &optional no-mice
1508 Given a vector of event objects, this function returns a vector of key
1509 descriptors, or a string (if they all fit in the @sc{ASCII} range).
1510 Optional arg @var{no-mice} means that button events are not allowed.
1514 @section Reading Input
1516 The editor command loop reads keyboard input using the function
1517 @code{next-event} and constructs key sequences out of the events using
1518 @code{dispatch-event}. Lisp programs can also use the function
1519 @code{read-key-sequence}, which reads input a key sequence at a time.
1520 See also @code{momentary-string-display} in @ref{Temporary Displays},
1521 and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
1522 functions and variables for controlling terminal input modes and
1523 debugging terminal input.
1525 For higher-level input facilities, see @ref{Minibuffers}.
1528 * Key Sequence Input:: How to read one key sequence.
1529 * Reading One Event:: How to read just one event.
1530 * Dispatching an Event:: What to do with an event once it has been read.
1531 * Quoted Character Input:: Asking the user to specify a character.
1532 * Peeking and Discarding:: How to reread or throw away input events.
1535 @node Key Sequence Input
1536 @subsection Key Sequence Input
1537 @cindex key sequence input
1539 Lisp programs can read input a key sequence at a time by calling
1540 @code{read-key-sequence}; for example, @code{describe-key} uses it to
1541 read the key to describe.
1543 @defun read-key-sequence prompt
1544 @cindex key sequence
1545 This function reads a sequence of keystrokes or mouse clicks and returns
1546 it as a vector of events. It keeps reading events until it has
1547 accumulated a full key sequence; that is, enough to specify a non-prefix
1548 command using the currently active keymaps.
1550 The vector and the event objects it contains are freshly created, and
1551 will not be side-effected by subsequent calls to this function.
1553 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
1554 typed while reading with this function works like any other character,
1555 and does not set @code{quit-flag}. @xref{Quitting}.
1557 The argument @var{prompt} is either a string to be displayed in the echo
1558 area as a prompt, or @code{nil}, meaning not to display a prompt.
1561 If the user selects a menu item while we are prompting for a key
1562 sequence, the returned value will be a vector of a single menu-selection
1563 event (a misc-user event). An error will be signalled if you pass this
1564 value to @code{lookup-key} or a related function.
1566 In the example below, the prompt @samp{?} is displayed in the echo area,
1567 and the user types @kbd{C-x C-f}.
1570 (read-key-sequence "?")
1573 ---------- Echo Area ----------
1575 ---------- Echo Area ----------
1577 @result{} [#<keypress-event control-X> #<keypress-event control-F>]
1582 @ignore @c Not in XEmacs
1583 @defvar num-input-keys
1585 This variable's value is the number of key sequences processed so far in
1586 this XEmacs session. This includes key sequences read from the terminal
1587 and key sequences read from keyboard macros being executed.
1591 @cindex upper case key sequence
1592 @cindex downcasing in @code{lookup-key}
1593 If an input character is an upper-case letter and has no key binding,
1594 but its lower-case equivalent has one, then @code{read-key-sequence}
1595 converts the character to lower case. Note that @code{lookup-key} does
1596 not perform case conversion in this way.
1598 @node Reading One Event
1599 @subsection Reading One Event
1601 The lowest level functions for command input are those which read a
1602 single event. These functions often make a distinction between
1603 @dfn{command events}, which are user actions (keystrokes and mouse
1604 actions), and other events, which serve as communication between
1605 XEmacs and the window system.
1607 @defun next-event &optional event prompt
1608 This function reads and returns the next available event from the window
1609 system or terminal driver, waiting if necessary until an event is
1610 available. Pass this object to @code{dispatch-event} to handle it. If
1611 an event object is supplied, it is filled in and returned; otherwise a
1612 new event object will be created.
1614 Events can come directly from the user, from a keyboard macro, or from
1615 @code{unread-command-events}.
1617 In most cases, the function @code{next-command-event} is more
1621 @defun next-command-event &optional event
1622 This function returns the next available ``user'' event from the window
1623 system or terminal driver. Pass this object to @code{dispatch-event} to
1624 handle it. If an event object is supplied, it is filled in and
1625 returned, otherwise a new event object will be created.
1627 The event returned will be a keyboard, mouse press, or mouse release
1628 event. If there are non-command events available (mouse motion,
1629 sub-process output, etc) then these will be executed (with
1630 @code{dispatch-event}) and discarded. This function is provided as a
1631 convenience; it is equivalent to the Lisp code
1637 (not (or (key-press-event-p event)
1638 (button-press-event-p event)
1639 (button-release-event-p event)
1640 (menu-event-p event))))
1641 (dispatch-event event))
1645 Here is what happens if you call @code{next-command-event} and then
1646 press the right-arrow function key:
1650 (next-command-event)
1651 @result{} #<keypress-event right>
1657 This function reads and returns a character of command input. If a
1658 mouse click is detected, an error is signalled. The character typed is
1659 returned as an @sc{ASCII} value. This function is retained for
1660 compatibility with Emacs 18, and is most likely the wrong thing for you
1661 to be using: consider using @code{next-command-event} instead.
1664 @defun enqueue-eval-event function object
1665 This function adds an eval event to the back of the queue. The
1666 eval event will be the next event read after all pending events.
1669 @node Dispatching an Event
1670 @subsection Dispatching an Event
1671 @cindex dispatching an event
1673 @defun dispatch-event event
1674 Given an event object returned by @code{next-event}, this function
1675 executes it. This is the basic function that makes XEmacs respond to
1676 user input; it also deals with notifications from the window system
1677 (such as Expose events).
1680 @node Quoted Character Input
1681 @subsection Quoted Character Input
1682 @cindex quoted character input
1684 You can use the function @code{read-quoted-char} to ask the user to
1685 specify a character, and allow the user to specify a control or meta
1686 character conveniently, either literally or as an octal character code.
1687 The command @code{quoted-insert} uses this function.
1689 @defun read-quoted-char &optional prompt
1690 @cindex octal character input
1691 @cindex control characters, reading
1692 @cindex nonprinting characters, reading
1693 This function is like @code{read-char}, except that if the first
1694 character read is an octal digit (0-7), it reads up to two more octal digits
1695 (but stopping if a non-octal digit is found) and returns the
1696 character represented by those digits in octal.
1698 Quitting is suppressed when the first character is read, so that the
1699 user can enter a @kbd{C-g}. @xref{Quitting}.
1701 If @var{prompt} is supplied, it specifies a string for prompting the
1702 user. The prompt string is always displayed in the echo area, followed
1703 by a single @samp{-}.
1705 In the following example, the user types in the octal number 177 (which
1709 (read-quoted-char "What character")
1712 ---------- Echo Area ----------
1713 What character-@kbd{177}
1714 ---------- Echo Area ----------
1722 @node Peeking and Discarding
1723 @subsection Miscellaneous Event Input Features
1725 This section describes how to ``peek ahead'' at events without using
1726 them up, how to check for pending input, and how to discard pending
1729 See also the variables @code{last-command-event} and @code{last-command-char}
1730 (@ref{Command Loop Info}).
1732 @defvar unread-command-events
1734 @cindex peeking at input
1735 This variable holds a list of events waiting to be read as command
1736 input. The events are used in the order they appear in the list, and
1737 removed one by one as they are used.
1739 The variable is needed because in some cases a function reads a event
1740 and then decides not to use it. Storing the event in this variable
1741 causes it to be processed normally, by the command loop or by the
1742 functions to read command input.
1744 @cindex prefix argument unreading
1745 For example, the function that implements numeric prefix arguments reads
1746 any number of digits. When it finds a non-digit event, it must unread
1747 the event so that it can be read normally by the command loop.
1748 Likewise, incremental search uses this feature to unread events with no
1749 special meaning in a search, because these events should exit the search
1750 and then execute normally.
1752 @ignore FSF Emacs stuff
1753 The reliable and easy way to extract events from a key sequence so as to
1754 put them in @code{unread-command-events} is to use
1755 @code{listify-key-sequence} (@pxref{Strings of Events}).
1759 @defvar unread-command-event
1760 This variable holds a single event to be read as command input.
1762 This variable is mostly obsolete now that you can use
1763 @code{unread-command-events} instead; it exists only to support programs
1764 written for versions of XEmacs prior to 19.12.
1767 @defun input-pending-p
1768 @cindex waiting for command key input
1769 This function determines whether any command input is currently
1770 available to be read. It returns immediately, with value @code{t} if
1771 there is available input, @code{nil} otherwise. On rare occasions it
1772 may return @code{t} when no input is available.
1775 @defvar last-input-event
1776 This variable is set to the last keyboard or mouse button event received.
1778 This variable is off limits: you may not set its value or modify the
1779 event that is its value, as it is destructively modified by
1780 @code{read-key-sequence}. If you want to keep a pointer to this value,
1781 you must use @code{copy-event}.
1783 Note that this variable is an alias for @code{last-input-char} in
1786 In the example below, a character is read (the character @kbd{1}). It
1787 becomes the value of @code{last-input-event}, while @kbd{C-e} (from the
1788 @kbd{C-x C-e} command used to evaluate this expression) remains the
1789 value of @code{last-command-event}.
1793 (progn (print (next-command-event))
1794 (print last-command-event)
1796 @print{} #<keypress-event 1>
1797 @print{} #<keypress-event control-E>
1798 @result{} #<keypress-event 1>
1804 @defvar last-input-char
1805 If the value of @code{last-input-event} is a keyboard event, then this
1806 is the nearest @sc{ASCII} equivalent to it. Remember that there is
1807 @emph{not} a 1:1 mapping between keyboard events and @sc{ASCII}
1808 characters: the set of keyboard events is much larger, so writing code
1809 that examines this variable to determine what key has been typed is bad
1810 practice, unless you are certain that it will be one of a small set of
1813 This function exists for compatibility with Emacs version 18.
1816 @defun discard-input
1818 @cindex discard input
1819 @cindex terminate keyboard macro
1820 This function discards the contents of the terminal input buffer and
1821 cancels any keyboard macro that might be in the process of definition.
1822 It returns @code{nil}.
1824 In the following example, the user may type a number of characters right
1825 after starting the evaluation of the form. After the @code{sleep-for}
1826 finishes sleeping, @code{discard-input} discards any characters typed
1830 (progn (sleep-for 2)
1837 @section Waiting for Elapsed Time or Input
1841 The wait functions are designed to wait for a certain amount of time
1842 to pass or until there is input. For example, you may wish to pause in
1843 the middle of a computation to allow the user time to view the display.
1844 @code{sit-for} pauses and updates the screen, and returns immediately if
1845 input comes in, while @code{sleep-for} pauses without updating the
1848 Note that in FSF Emacs, the commands @code{sit-for} and @code{sleep-for}
1849 take two arguments to specify the time (one integer and one float
1850 value), instead of a single argument that can be either an integer or a
1853 @defun sit-for seconds &optional nodisp
1854 This function performs redisplay (provided there is no pending input
1855 from the user), then waits @var{seconds} seconds, or until input is
1856 available. The result is @code{t} if @code{sit-for} waited the full
1857 time with no input arriving (see @code{input-pending-p} in @ref{Peeking
1858 and Discarding}). Otherwise, the value is @code{nil}.
1860 The argument @var{seconds} need not be an integer. If it is a floating
1861 point number, @code{sit-for} waits for a fractional number of seconds.
1862 @ignore FSF Emacs stuff
1863 Some systems support only a whole number of seconds; on these systems,
1864 @var{seconds} is rounded down.
1866 The optional argument @var{millisec} specifies an additional waiting
1867 period measured in milliseconds. This adds to the period specified by
1868 @var{seconds}. If the system doesn't support waiting fractions of a
1869 second, you get an error if you specify nonzero @var{millisec}.
1872 @cindex forcing redisplay
1873 Redisplay is normally preempted if input arrives, and does not happen at
1874 all if input is available before it starts. (You can force screen
1875 updating in such a case by using @code{force-redisplay}. @xref{Refresh
1876 Screen}.) If there is no input pending, you can force an update with no
1877 delay by using @code{(sit-for 0)}.
1879 If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
1880 redisplay, but it still returns as soon as input is available (or when
1881 the timeout elapses).
1884 Iconifying or deiconifying a frame makes @code{sit-for} return, because
1885 that generates an event. @xref{Misc Events}.
1888 The usual purpose of @code{sit-for} is to give the user time to read
1889 text that you display.
1892 @defun sleep-for seconds
1893 This function simply pauses for @var{seconds} seconds without updating
1894 the display. This function pays no attention to available input. It
1897 The argument @var{seconds} need not be an integer. If it is a floating
1898 point number, @code{sleep-for} waits for a fractional number of seconds.
1899 @ignore FSF Emacs stuff
1900 Some systems support only a whole number of seconds; on these systems,
1901 @var{seconds} is rounded down.
1903 The optional argument @var{millisec} specifies an additional waiting
1904 period measured in milliseconds. This adds to the period specified by
1905 @var{seconds}. If the system doesn't support waiting fractions of a
1906 second, you get an error if you specify nonzero @var{millisec}.
1909 Use @code{sleep-for} when you wish to guarantee a delay.
1912 @xref{Time of Day}, for functions to get the current time.
1919 Typing @kbd{C-g} while a Lisp function is running causes XEmacs to
1920 @dfn{quit} whatever it is doing. This means that control returns to the
1921 innermost active command loop.
1923 Typing @kbd{C-g} while the command loop is waiting for keyboard input
1924 does not cause a quit; it acts as an ordinary input character. In the
1925 simplest case, you cannot tell the difference, because @kbd{C-g}
1926 normally runs the command @code{keyboard-quit}, whose effect is to quit.
1927 However, when @kbd{C-g} follows a prefix key, the result is an undefined
1928 key. The effect is to cancel the prefix key as well as any prefix
1931 In the minibuffer, @kbd{C-g} has a different definition: it aborts out
1932 of the minibuffer. This means, in effect, that it exits the minibuffer
1933 and then quits. (Simply quitting would return to the command loop
1934 @emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit
1935 directly when the command reader is reading input is so that its meaning
1936 can be redefined in the minibuffer in this way. @kbd{C-g} following a
1937 prefix key is not redefined in the minibuffer, and it has its normal
1938 effect of canceling the prefix key and prefix argument. This too
1939 would not be possible if @kbd{C-g} always quit directly.
1941 When @kbd{C-g} does directly quit, it does so by setting the variable
1942 @code{quit-flag} to @code{t}. XEmacs checks this variable at appropriate
1943 times and quits if it is not @code{nil}. Setting @code{quit-flag}
1944 non-@code{nil} in any way thus causes a quit.
1946 At the level of C code, quitting cannot happen just anywhere; only at the
1947 special places that check @code{quit-flag}. The reason for this is
1948 that quitting at other places might leave an inconsistency in XEmacs's
1949 internal state. Because quitting is delayed until a safe place, quitting
1950 cannot make XEmacs crash.
1952 Certain functions such as @code{read-key-sequence} or
1953 @code{read-quoted-char} prevent quitting entirely even though they wait
1954 for input. Instead of quitting, @kbd{C-g} serves as the requested
1955 input. In the case of @code{read-key-sequence}, this serves to bring
1956 about the special behavior of @kbd{C-g} in the command loop. In the
1957 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
1958 to quote a @kbd{C-g}.
1960 You can prevent quitting for a portion of a Lisp function by binding
1961 the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
1962 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
1963 usual result of this---a quit---is prevented. Eventually,
1964 @code{inhibit-quit} will become @code{nil} again, such as when its
1965 binding is unwound at the end of a @code{let} form. At that time, if
1966 @code{quit-flag} is still non-@code{nil}, the requested quit happens
1967 immediately. This behavior is ideal when you wish to make sure that
1968 quitting does not happen within a ``critical section'' of the program.
1970 @cindex @code{read-quoted-char} quitting
1971 In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
1972 handled in a special way that does not involve quitting. This is done
1973 by reading the input with @code{inhibit-quit} bound to @code{t}, and
1974 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
1975 becomes @code{nil} again. This excerpt from the definition of
1976 @code{read-quoted-char} shows how this is done; it also shows that
1977 normal quitting is permitted after the first character of input.
1980 (defun read-quoted-char (&optional prompt)
1981 "@dots{}@var{documentation}@dots{}"
1982 (let ((count 0) (code 0) char)
1984 (let ((inhibit-quit (zerop count))
1986 (and prompt (message "%s-" prompt))
1987 (setq char (read-char))
1988 (if inhibit-quit (setq quit-flag nil)))
1994 If this variable is non-@code{nil}, then XEmacs quits immediately, unless
1995 @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
1996 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
1999 @defvar inhibit-quit
2000 This variable determines whether XEmacs should quit when @code{quit-flag}
2001 is set to a value other than @code{nil}. If @code{inhibit-quit} is
2002 non-@code{nil}, then @code{quit-flag} has no special effect.
2005 @deffn Command keyboard-quit
2006 This function signals the @code{quit} condition with @code{(signal 'quit
2007 nil)}. This is the same thing that quitting does. (See @code{signal}
2011 You can specify a character other than @kbd{C-g} to use for quitting.
2012 See the function @code{set-input-mode} in @ref{Terminal Input}.
2014 @node Prefix Command Arguments
2015 @section Prefix Command Arguments
2016 @cindex prefix argument
2017 @cindex raw prefix argument
2018 @cindex numeric prefix argument
2020 Most XEmacs commands can use a @dfn{prefix argument}, a number
2021 specified before the command itself. (Don't confuse prefix arguments
2022 with prefix keys.) The prefix argument is at all times represented by a
2023 value, which may be @code{nil}, meaning there is currently no prefix
2024 argument. Each command may use the prefix argument or ignore it.
2026 There are two representations of the prefix argument: @dfn{raw} and
2027 @dfn{numeric}. The editor command loop uses the raw representation
2028 internally, and so do the Lisp variables that store the information, but
2029 commands can request either representation.
2031 Here are the possible values of a raw prefix argument:
2035 @code{nil}, meaning there is no prefix argument. Its numeric value is
2036 1, but numerous commands make a distinction between @code{nil} and the
2040 An integer, which stands for itself.
2043 A list of one element, which is an integer. This form of prefix
2044 argument results from one or a succession of @kbd{C-u}'s with no
2045 digits. The numeric value is the integer in the list, but some
2046 commands make a distinction between such a list and an integer alone.
2049 The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was
2050 typed, without following digits. The equivalent numeric value is
2051 @minus{}1, but some commands make a distinction between the integer
2052 @minus{}1 and the symbol @code{-}.
2055 We illustrate these possibilities by calling the following function with
2060 (defun display-prefix (arg)
2061 "Display the value of the raw prefix arg."
2068 Here are the results of calling @code{display-prefix} with various
2069 raw prefix arguments:
2072 M-x display-prefix @print{} nil
2074 C-u M-x display-prefix @print{} (4)
2076 C-u C-u M-x display-prefix @print{} (16)
2078 C-u 3 M-x display-prefix @print{} 3
2080 M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
2082 C-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
2084 C-u - M-x display-prefix @print{} -
2086 M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
2088 C-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
2090 C-u - 7 M-x display-prefix @print{} -7
2092 M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
2094 C-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
2097 XEmacs uses two variables to store the prefix argument:
2098 @code{prefix-arg} and @code{current-prefix-arg}. Commands such as
2099 @code{universal-argument} that set up prefix arguments for other
2100 commands store them in @code{prefix-arg}. In contrast,
2101 @code{current-prefix-arg} conveys the prefix argument to the current
2102 command, so setting it has no effect on the prefix arguments for future
2105 Normally, commands specify which representation to use for the prefix
2106 argument, either numeric or raw, in the @code{interactive} declaration.
2107 (@xref{Using Interactive}.) Alternatively, functions may look at the
2108 value of the prefix argument directly in the variable
2109 @code{current-prefix-arg}, but this is less clean.
2111 @defun prefix-numeric-value arg
2112 This function returns the numeric meaning of a valid raw prefix argument
2113 value, @var{arg}. The argument may be a symbol, a number, or a list.
2114 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
2115 value @minus{}1 is returned; if it is a number, that number is returned;
2116 if it is a list, the @sc{car} of that list (which should be a number) is
2120 @defvar current-prefix-arg
2121 This variable holds the raw prefix argument for the @emph{current}
2122 command. Commands may examine it directly, but the usual way to access
2123 it is with @code{(interactive "P")}.
2127 The value of this variable is the raw prefix argument for the
2128 @emph{next} editing command. Commands that specify prefix arguments for
2129 the following command work by setting this variable.
2132 Do not call the functions @code{universal-argument},
2133 @code{digit-argument}, or @code{negative-argument} unless you intend to
2134 let the user enter the prefix argument for the @emph{next} command.
2136 @deffn Command universal-argument
2137 This command reads input and specifies a prefix argument for the
2138 following command. Don't call this command yourself unless you know
2142 @deffn Command digit-argument arg
2143 This command adds to the prefix argument for the following command. The
2144 argument @var{arg} is the raw prefix argument as it was before this
2145 command; it is used to compute the updated prefix argument. Don't call
2146 this command yourself unless you know what you are doing.
2149 @deffn Command negative-argument arg
2150 This command adds to the numeric argument for the next command. The
2151 argument @var{arg} is the raw prefix argument as it was before this
2152 command; its value is negated to form the new prefix argument. Don't
2153 call this command yourself unless you know what you are doing.
2156 @node Recursive Editing
2157 @section Recursive Editing
2158 @cindex recursive command loop
2159 @cindex recursive editing level
2160 @cindex command loop, recursive
2162 The XEmacs command loop is entered automatically when XEmacs starts up.
2163 This top-level invocation of the command loop never exits; it keeps
2164 running as long as XEmacs does. Lisp programs can also invoke the
2165 command loop. Since this makes more than one activation of the command
2166 loop, we call it @dfn{recursive editing}. A recursive editing level has
2167 the effect of suspending whatever command invoked it and permitting the
2168 user to do arbitrary editing before resuming that command.
2170 The commands available during recursive editing are the same ones
2171 available in the top-level editing loop and defined in the keymaps.
2172 Only a few special commands exit the recursive editing level; the others
2173 return to the recursive editing level when they finish. (The special
2174 commands for exiting are always available, but they do nothing when
2175 recursive editing is not in progress.)
2177 All command loops, including recursive ones, set up all-purpose error
2178 handlers so that an error in a command run from the command loop will
2181 @cindex minibuffer input
2182 Minibuffer input is a special kind of recursive editing. It has a few
2183 special wrinkles, such as enabling display of the minibuffer and the
2184 minibuffer window, but fewer than you might suppose. Certain keys
2185 behave differently in the minibuffer, but that is only because of the
2186 minibuffer's local map; if you switch windows, you get the usual XEmacs
2189 @cindex @code{throw} example
2191 @cindex exit recursive editing
2193 To invoke a recursive editing level, call the function
2194 @code{recursive-edit}. This function contains the command loop; it also
2195 contains a call to @code{catch} with tag @code{exit}, which makes it
2196 possible to exit the recursive editing level by throwing to @code{exit}
2197 (@pxref{Catch and Throw}). If you throw a value other than @code{t},
2198 then @code{recursive-edit} returns normally to the function that called
2199 it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
2200 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
2201 control returns to the command loop one level up. This is called
2202 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
2204 Most applications should not use recursive editing, except as part of
2205 using the minibuffer. Usually it is more convenient for the user if you
2206 change the major mode of the current buffer temporarily to a special
2207 major mode, which should have a command to go back to the previous mode.
2208 (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
2209 give the user different text to edit ``recursively'', create and select
2210 a new buffer in a special mode. In this mode, define a command to
2211 complete the processing and go back to the previous buffer. (The
2212 @kbd{m} command in Rmail does this.)
2214 Recursive edits are useful in debugging. You can insert a call to
2215 @code{debug} into a function definition as a sort of breakpoint, so that
2216 you can look around when the function gets there. @code{debug} invokes
2217 a recursive edit but also provides the other features of the debugger.
2219 Recursive editing levels are also used when you type @kbd{C-r} in
2220 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
2222 @defun recursive-edit
2223 @cindex suspend evaluation
2224 This function invokes the editor command loop. It is called
2225 automatically by the initialization of XEmacs, to let the user begin
2226 editing. When called from a Lisp program, it enters a recursive editing
2229 In the following example, the function @code{simple-rec} first
2230 advances point one word, then enters a recursive edit, printing out a
2231 message in the echo area. The user can then do any editing desired, and
2232 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
2235 (defun simple-rec ()
2237 (message "Recursive edit in progress")
2240 @result{} simple-rec
2246 @deffn Command exit-recursive-edit
2247 This function exits from the innermost recursive edit (including
2248 minibuffer input). Its definition is effectively @code{(throw 'exit
2252 @deffn Command abort-recursive-edit
2253 This function aborts the command that requested the innermost recursive
2254 edit (including minibuffer input), by signaling @code{quit}
2255 after exiting the recursive edit. Its definition is effectively
2256 @code{(throw 'exit t)}. @xref{Quitting}.
2259 @deffn Command top-level
2260 This function exits all recursive editing levels; it does not return a
2261 value, as it jumps completely out of any computation directly back to
2262 the main command loop.
2265 @defun recursion-depth
2266 This function returns the current depth of recursive edits. When no
2267 recursive edit is active, it returns 0.
2270 @node Disabling Commands
2271 @section Disabling Commands
2272 @cindex disabled command
2274 @dfn{Disabling a command} marks the command as requiring user
2275 confirmation before it can be executed. Disabling is used for commands
2276 which might be confusing to beginning users, to prevent them from using
2277 the commands by accident.
2280 The low-level mechanism for disabling a command is to put a
2281 non-@code{nil} @code{disabled} property on the Lisp symbol for the
2282 command. These properties are normally set up by the user's
2283 @file{.emacs} file with Lisp expressions such as this:
2286 (put 'upcase-region 'disabled t)
2290 For a few commands, these properties are present by default and may be
2291 removed by the @file{.emacs} file.
2293 If the value of the @code{disabled} property is a string, the message
2294 saying the command is disabled includes that string. For example:
2297 (put 'delete-region 'disabled
2298 "Text deleted this way cannot be yanked back!\n")
2301 @xref{Disabling,,, xemacs, The XEmacs User's Manual}, for the details on
2302 what happens when a disabled command is invoked interactively.
2303 Disabling a command has no effect on calling it as a function from Lisp
2306 @deffn Command enable-command command
2307 Allow @var{command} to be executed without special confirmation from now
2308 on, and (if the user confirms) alter the user's @file{.emacs} file so
2309 that this will apply to future sessions.
2312 @deffn Command disable-command command
2313 Require special confirmation to execute @var{command} from now on, and
2314 (if the user confirms) alter the user's @file{.emacs} file so that this
2315 will apply to future sessions.
2318 @defvar disabled-command-hook
2319 This normal hook is run instead of a disabled command, when the user
2320 invokes the disabled command interactively. The hook functions can use
2321 @code{this-command-keys} to determine what the user typed to run the
2322 command, and thus find the command itself. @xref{Hooks}.
2324 By default, @code{disabled-command-hook} contains a function that asks
2325 the user whether to proceed.
2328 @node Command History
2329 @section Command History
2330 @cindex command history
2331 @cindex complex command
2332 @cindex history of commands
2334 The command loop keeps a history of the complex commands that have
2335 been executed, to make it convenient to repeat these commands. A
2336 @dfn{complex command} is one for which the interactive argument reading
2337 uses the minibuffer. This includes any @kbd{M-x} command, any
2338 @kbd{M-:} command, and any command whose @code{interactive}
2339 specification reads an argument from the minibuffer. Explicit use of
2340 the minibuffer during the execution of the command itself does not cause
2341 the command to be considered complex.
2343 @defvar command-history
2344 This variable's value is a list of recent complex commands, each
2345 represented as a form to evaluate. It continues to accumulate all
2346 complex commands for the duration of the editing session, but all but
2347 the first (most recent) thirty elements are deleted when a garbage
2348 collection takes place (@pxref{Garbage Collection}).
2353 @result{} ((switch-to-buffer "chistory.texi")
2354 (describe-key "^X^[")
2355 (visit-tags-table "~/emacs/src/")
2356 (find-tag "repeat-complex-command"))
2361 This history list is actually a special case of minibuffer history
2362 (@pxref{Minibuffer History}), with one special twist: the elements are
2363 expressions rather than strings.
2365 There are a number of commands devoted to the editing and recall of
2366 previous commands. The commands @code{repeat-complex-command}, and
2367 @code{list-command-history} are described in the user manual
2368 (@pxref{Repetition,,, xemacs, The XEmacs User's Manual}). Within the
2369 minibuffer, the history commands used are the same ones available in any
2372 @node Keyboard Macros
2373 @section Keyboard Macros
2374 @cindex keyboard macros
2376 A @dfn{keyboard macro} is a canned sequence of input events that can
2377 be considered a command and made the definition of a key. The Lisp
2378 representation of a keyboard macro is a string or vector containing the
2379 events. Don't confuse keyboard macros with Lisp macros
2382 @defun execute-kbd-macro macro &optional count
2383 This function executes @var{macro} as a sequence of events. If
2384 @var{macro} is a string or vector, then the events in it are executed
2385 exactly as if they had been input by the user. The sequence is
2386 @emph{not} expected to be a single key sequence; normally a keyboard
2387 macro definition consists of several key sequences concatenated.
2389 If @var{macro} is a symbol, then its function definition is used in
2390 place of @var{macro}. If that is another symbol, this process repeats.
2391 Eventually the result should be a string or vector. If the result is
2392 not a symbol, string, or vector, an error is signaled.
2394 The argument @var{count} is a repeat count; @var{macro} is executed that
2395 many times. If @var{count} is omitted or @code{nil}, @var{macro} is
2396 executed once. If it is 0, @var{macro} is executed over and over until it
2397 encounters an error or a failing search.
2400 @defvar executing-macro
2401 This variable contains the string or vector that defines the keyboard
2402 macro that is currently executing. It is @code{nil} if no macro is
2403 currently executing. A command can test this variable to behave
2404 differently when run from an executing macro. Do not set this variable
2408 @defvar defining-kbd-macro
2409 This variable indicates whether a keyboard macro is being defined. A
2410 command can test this variable to behave differently while a macro is
2411 being defined. The commands @code{start-kbd-macro} and
2412 @code{end-kbd-macro} set this variable---do not set it yourself.
2415 @defvar last-kbd-macro
2416 This variable is the definition of the most recently defined keyboard
2417 macro. Its value is a string or vector, or @code{nil}.
2420 @c Broke paragraph to prevent overfull hbox. --rjc 15mar92
2421 The commands are described in the user's manual (@pxref{Keyboard
2422 Macros,,, xemacs, The XEmacs User's Manual}).