2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/commands.info
8 @node Command Loop, Keymaps, Minibuffers, Top
10 @cindex editor command loop
13 When you run SXEmacs, it enters the @dfn{editor command loop} almost
14 immediately. This loop reads events, executes their definitions,
15 and displays the results. In this chapter, we describe how these things
16 are done, and the subroutines that allow Lisp programs to do them.
19 * Command Overview:: How the command loop reads commands.
20 * Defining Commands:: Specifying how a function should read arguments.
21 * Interactive Call:: Calling a command, so that it will read arguments.
22 * Command Loop Info:: Variables set by the command loop for you to examine.
23 * Events:: What input looks like when you read it.
24 * Reading Input:: How to read input events from the keyboard or mouse.
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.
36 @node Command Overview
37 @section Command Loop Overview
39 The command loop in SXEmacs is a standard event loop, reading events
40 one at a time with @code{next-event} and handling them with
41 @code{dispatch-event}. An event is typically a single user action, such
42 as a keypress, mouse movement, or menu selection; but they can also be
43 notifications from the window system, informing SXEmacs that (for
44 example) part of its window was just uncovered and needs to be redrawn.
45 @xref{Events}. Pending events are held in a first-in, first-out list
46 called the @dfn{event queue}: events are read from the head of the list,
47 and newly arriving events are added to the tail. In this way, events
48 are always processed in the order in which they arrive.
50 @code{dispatch-event} does most of the work of handling user actions.
51 The first thing it must do is put the events together into a key
52 sequence, which is a sequence of events that translates into a command.
53 It does this by consulting the active keymaps, which specify what the
54 valid key sequences are and how to translate them into commands.
55 @xref{Key Lookup}, for information on how this is done. The result of
56 the translation should be a keyboard macro or an interactively callable
57 function. If the key is @kbd{M-x}, then it reads the name of another
58 command, which it then calls. This is done by the command
59 @code{execute-extended-command} (@pxref{Interactive Call}).
61 To execute a command requires first reading the arguments for it.
62 This is done by calling @code{command-execute} (@pxref{Interactive
63 Call}). For commands written in Lisp, the @code{interactive}
64 specification says how to read the arguments. This may use the prefix
65 argument (@pxref{Prefix Command Arguments}) or may read with prompting
66 in the minibuffer (@pxref{Minibuffers}).
68 For example, the command @code{find-file} has an @code{interactive}
69 specification which says to read a file name using the minibuffer. The
70 command's function body does not use the minibuffer; if you call this
71 command from Lisp code as a function, you must supply the file name
72 string as an ordinary Lisp function argument.
74 If the command is a string or vector (i.e., a keyboard macro) then
75 @code{execute-kbd-macro} is used to execute it. You can call this
76 function yourself (@pxref{Keyboard Macros}).
78 To terminate the execution of a running command, type @kbd{C-g}. This
79 character causes @dfn{quitting} (@pxref{Quitting}).
81 @defvar pre-command-hook
82 The editor command loop runs this normal hook before each command. At
83 that time, @code{this-command} contains the command that is about to
84 run, and @code{last-command} describes the previous command.
88 @defvar post-command-hook
89 The editor command loop runs this normal hook after each command. (In
90 FSF Emacs, it is also run when the command loop is entered, or
91 reentered after an error or quit.) At that time,
92 @code{this-command} describes the command that just ran, and
93 @code{last-command} describes the command before that. @xref{Hooks}.
96 Quitting is suppressed while running @code{pre-command-hook} and
97 @code{post-command-hook}. If an error happens while executing one of
98 these hooks, it terminates execution of the hook, but that is all it
102 @node Defining Commands
103 @section Defining Commands
104 @cindex defining commands
105 @cindex commands, defining
106 @cindex functions, making them interactive
107 @cindex interactive function
109 A Lisp function becomes a command when its body contains, at top
110 level, a form that calls the special form @code{interactive}. This
111 form does nothing when actually executed, but its presence serves as a
112 flag to indicate that interactive calling is permitted. Its argument
113 controls the reading of arguments for an interactive call.
116 * Using Interactive:: General rules for @code{interactive}.
117 * Interactive Codes:: The standard letter-codes for reading arguments
119 * Interactive Examples:: Examples of how to read interactive arguments.
123 @node Using Interactive
124 @subsection Using @code{interactive}
126 This section describes how to write the @code{interactive} form that
127 makes a Lisp function an interactively-callable command.
129 @defspec interactive arg-descriptor
130 @cindex argument descriptors
131 This special form declares that the function in which it appears is a
132 command, and that it may therefore be called interactively (via
133 @kbd{M-x} or by entering a key sequence bound to it). The argument
134 @var{arg-descriptor} declares how to compute the arguments to the
135 command when the command is called interactively.
137 A command may be called from Lisp programs like any other function, but
138 then the caller supplies the arguments and @var{arg-descriptor} has no
141 The @code{interactive} form has its effect because the command loop
142 (actually, its subroutine @code{call-interactively}) scans through the
143 function definition looking for it, before calling the function. Once
144 the function is called, all its body forms including the
145 @code{interactive} form are executed, but at this time
146 @code{interactive} simply returns @code{nil} without even evaluating its
150 There are three possibilities for the argument @var{arg-descriptor}:
154 It may be omitted or @code{nil}; then the command is called with no
155 arguments. This leads quickly to an error if the command requires one
159 It may be a Lisp expression that is not a string; then it should be a
160 form that is evaluated to get a list of arguments to pass to the
162 @cindex argument evaluation form
164 If this expression reads keyboard input (this includes using the
165 minibuffer), keep in mind that the integer value of point or the mark
166 before reading input may be incorrect after reading input. This is
167 because the current buffer may be receiving subprocess output;
168 if subprocess output arrives while the command is waiting for input,
169 it could relocate point and the mark.
171 Here's an example of what @emph{not} to do:
175 (list (region-beginning) (region-end)
176 (read-string "Foo: " nil 'my-history)))
180 Here's how to avoid the problem, by examining point and the mark only
181 after reading the keyboard input:
185 (let ((string (read-string "Foo: " nil 'my-history)))
186 (list (region-beginning) (region-end) string)))
190 @cindex argument prompt
191 It may be a string; then its contents should consist of a code character
192 followed by a prompt (which some code characters use and some ignore).
193 The prompt ends either with the end of the string or with a newline.
194 Here is a simple example:
197 (interactive "bFrobnicate buffer: ")
201 The code letter @samp{b} says to read the name of an existing buffer,
202 with completion. The buffer name is the sole argument passed to the
203 command. The rest of the string is a prompt.
205 If there is a newline character in the string, it terminates the prompt.
206 If the string does not end there, then the rest of the string should
207 contain another code character and prompt, specifying another argument.
208 You can specify any number of arguments in this way.
211 The prompt string can use @samp{%} to include previous argument values
212 (starting with the first argument) in the prompt. This is done using
213 @code{format} (@pxref{Formatting Strings}). For example, here is how
214 you could read the name of an existing buffer followed by a new name to
219 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
223 @cindex @samp{*} in interactive
224 @cindex read-only buffers in interactive
225 If the first character in the string is @samp{*}, then an error is
226 signaled if the buffer is read-only.
228 @cindex @samp{@@} in interactive
230 If the first character in the string is @samp{@@}, and if the key
231 sequence used to invoke the command includes any mouse events, then
232 the window associated with the first of those events is selected
233 before the command is run.
235 @cindex @samp{_} in interactive
237 If the first character in the string is @samp{_}, then this command will
238 not cause the region to be deactivated when it completes; that is,
239 @code{zmacs-region-stays} will be set to @code{t} when the command exits
242 You can use @samp{*}, @samp{@@}, and @samp{_} together; the order does
243 not matter. Actual reading of arguments is controlled by the rest of
244 the prompt string (starting with the first character that is not
245 @samp{*}, @samp{@@}, or @samp{_}).
248 @defun function-interactive function
249 This function retrieves the interactive specification of @var{function},
250 which may be any funcallable object. The specification will be returned
251 as the list of the symbol @code{interactive} and the specs. If
252 @var{function} is not interactive, @code{nil} will be returned.
255 @node Interactive Codes
256 @subsection Code Characters for @code{interactive}
257 @cindex interactive code description
258 @cindex description for interactive codes
259 @cindex codes, interactive, description of
260 @cindex characters for interactive codes
262 The code character descriptions below contain a number of key words,
263 defined here as follows:
267 @cindex interactive completion
268 Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name
269 completion because the argument is read using @code{completing-read}
270 (@pxref{Completion}). @kbd{?} displays a list of possible completions.
273 Require the name of an existing object. An invalid name is not
274 accepted; the commands to exit the minibuffer do not exit if the current
278 @cindex default argument string
279 A default value of some sort is used if the user enters no text in the
280 minibuffer. The default depends on the code character.
283 This code letter computes an argument without reading any input.
284 Therefore, it does not use a prompt string, and any prompt string you
287 Even though the code letter doesn't use a prompt string, you must follow
288 it with a newline if it is not the last code character in the string.
291 A prompt immediately follows the code character. The prompt ends either
292 with the end of the string or with a newline.
295 This code character is meaningful only at the beginning of the
296 interactive string, and it does not look for a prompt or a newline.
297 It is a single, isolated character.
300 @cindex reading interactive arguments
301 Here are the code character descriptions for use with @code{interactive}:
305 Signal an error if the current buffer is read-only. Special.
308 Select the window mentioned in the first mouse event in the key
309 sequence that invoked this command. Special.
312 Do not cause the region to be deactivated when this command completes.
316 A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
320 The name of an existing buffer. By default, uses the name of the
321 current buffer (@pxref{Buffers}). Existing, Completion, Default,
325 A buffer name. The buffer need not exist. By default, uses the name of
326 a recently used buffer other than the current buffer. Completion,
330 A character. The cursor does not move into the echo area. Prompt.
333 A command name (i.e., a symbol satisfying @code{commandp}). Existing,
337 @cindex position argument
338 The position of point, as an integer (@pxref{Point}). No I/O.
341 A directory name. The default is the current default directory of the
342 current buffer, @code{default-directory} (@pxref{System Environment}).
343 Existing, Completion, Default, Prompt.
346 The last mouse-button or misc-user event in the key sequence that
347 invoked the command. No I/O.
349 You can use @samp{e} more than once in a single command's interactive
350 specification. If the key sequence that invoked the command has @var{n}
351 mouse-button or misc-user events, the @var{n}th @samp{e} provides the
352 @var{n}th such event.
355 A file name of an existing file (@pxref{File Names}). The default
356 directory is @code{default-directory}. Existing, Completion, Default,
360 A file name. The file need not exist. Completion, Default, Prompt.
363 A key sequence (@pxref{Keymap Terminology}). This keeps reading events
364 until a command (or undefined command) is found in the current key
365 maps. The key sequence argument is represented as a vector of events.
366 The cursor does not move into the echo area. Prompt.
368 This kind of input is used by commands such as @code{describe-key} and
369 @code{global-set-key}.
372 A key sequence, whose definition you intend to change. This works like
373 @samp{k}, except that it suppresses, for the last input event in the key
374 sequence, the conversions that are normally used (when necessary) to
375 convert an undefined key into a defined one.
378 @cindex marker argument
379 The position of the mark, as an integer. No I/O.
382 A number read with the minibuffer. If the input is not a number, the
383 user is asked to try again. The prefix argument, if any, is not used.
387 @cindex raw prefix argument usage
388 The raw prefix argument. If the prefix argument is @code{nil}, then
389 read a number as with @kbd{n}. Requires a number. @xref{Prefix Command
393 @cindex numeric prefix argument usage
394 The numeric prefix argument. (Note that this @samp{p} is lower case.)
398 The raw prefix argument. (Note that this @samp{P} is upper case.) No
402 @cindex region argument
403 Point and the mark, as two numeric arguments, smallest first. This is
404 the only code letter that specifies two successive arguments rather than
408 Arbitrary text, read in the minibuffer and returned as a string
409 (@pxref{Text from Minibuffer}). Terminate the input with either
410 @key{LFD} or @key{RET}. (@kbd{C-q} may be used to include either of
411 these characters in the input.) Prompt.
414 An interned symbol whose name is read in the minibuffer. Any whitespace
415 character terminates the input. (Use @kbd{C-q} to include whitespace in
416 the string.) Other characters that normally terminate a symbol (e.g.,
417 parentheses and brackets) do not do so here. Prompt.
420 A variable declared to be a user option (i.e., satisfying the predicate
421 @code{user-variable-p}). @xref{High-Level Completion}. Existing,
425 A Lisp object, specified with its read syntax, terminated with a
426 @key{LFD} or @key{RET}. The object is not evaluated. @xref{Object from
430 @cindex evaluated expression argument
431 A Lisp form is read as with @kbd{x}, but then evaluated so that its
432 value becomes the argument for the command. Prompt.
435 @node Interactive Examples
436 @subsection Examples of Using @code{interactive}
437 @cindex examples of using @code{interactive}
438 @cindex @code{interactive}, examples of using
440 Here are some examples of @code{interactive}:
444 (defun foo1 () ; @r{@code{foo1} takes no arguments,}
445 (interactive) ; @r{just moves forward two words.}
451 (defun foo2 (n) ; @r{@code{foo2} takes one argument,}
452 (interactive "p") ; @r{which is the numeric prefix.}
453 (forward-word (* 2 n)))
458 (defun foo3 (n) ; @r{@code{foo3} takes one argument,}
459 (interactive "nCount:") ; @r{which is read with the Minibuffer.}
460 (forward-word (* 2 n)))
465 (defun three-b (b1 b2 b3)
466 "Select three existing buffers.
467 Put them into three windows, selecting the last one."
469 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
470 (delete-other-windows)
471 (split-window (selected-window) 8)
472 (switch-to-buffer b1)
474 (split-window (selected-window) 8)
475 (switch-to-buffer b2)
477 (switch-to-buffer b3))
480 (three-b "*scratch*" "declarations.texi" "*mail*")
486 @node Interactive Call
487 @section Interactive Call
488 @cindex interactive call
490 After the command loop has translated a key sequence into a
491 definition, it invokes that definition using the function
492 @code{command-execute}. If the definition is a function that is a
493 command, @code{command-execute} calls @code{call-interactively}, which
494 reads the arguments and calls the command. You can also call these
497 @defun commandp function
498 Returns @code{t} if @var{function} is suitable for calling
499 interactively; that is, if @var{function} is a command. Otherwise,
502 The interactively callable objects include strings and vectors (treated
503 as keyboard macros), lambda expressions that contain a top-level call to
504 @code{interactive}, compiled-function objects made from such lambda
505 expressions, autoload objects that are declared as interactive
506 (non-@code{nil} fourth argument to @code{autoload}), and some of the
509 A symbol is @code{commandp} if its function definition is
512 Keys and keymaps are not commands. Rather, they are used to look up
513 commands (@pxref{Keymaps}).
515 See @code{documentation} in @ref{Accessing Documentation}, for a
516 realistic example of using @code{commandp}.
519 @defun call-interactively command &optional record-flag keys
520 This function calls the interactively callable function @var{command},
521 reading arguments according to its interactive calling specifications.
522 An error is signaled if @var{command} is not a function or if it cannot
523 be called interactively (i.e., is not a command). Note that keyboard
524 macros (strings and vectors) are not accepted, even though they are
525 considered commands, because they are not functions.
528 If @var{record-flag} is the symbol @code{lambda}, the interactive
529 calling arguments for @var{command} are read and returned as a list,
530 but the function is not called on them.
532 @cindex record command history
533 If @var{record-flag} is @code{t}, then this command and its arguments
534 are unconditionally added to the list @code{command-history}.
535 Otherwise, the command is added only if it uses the minibuffer to read
536 an argument. @xref{Command History}.
539 @defun command-execute command &optional record-flag keys
540 @cindex keyboard macro execution
541 This function executes @var{command} as an editing command. The
542 argument @var{command} must satisfy the @code{commandp} predicate; i.e.,
543 it must be an interactively callable function or a keyboard macro.
545 A string or vector as @var{command} is executed with
546 @code{execute-kbd-macro}. A function is passed to
547 @code{call-interactively}, along with the optional @var{record-flag}.
549 A symbol is handled by using its function definition in its place. A
550 symbol with an @code{autoload} definition counts as a command if it was
551 declared to stand for an interactively callable function. Such a
552 definition is handled by loading the specified library and then
553 rechecking the definition of the symbol.
556 @deffn Command execute-extended-command prefix-argument
557 @cindex read command name
558 This function reads a command name from the minibuffer using
559 @code{completing-read} (@pxref{Completion}). Then it uses
560 @code{command-execute} to call the specified command. Whatever that
561 command returns becomes the value of @code{execute-extended-command}.
563 @cindex execute with prefix argument
564 If the command asks for a prefix argument, it receives the value
565 @var{prefix-argument}. If @code{execute-extended-command} is called
566 interactively, the current raw prefix argument is used for
567 @var{prefix-argument}, and thus passed on to whatever command is run.
569 @c !!! Should this be @kindex?
571 @code{execute-extended-command} is the normal definition of @kbd{M-x},
572 so it uses the string @w{@samp{M-x }} as a prompt. (It would be better
573 to take the prompt from the events used to invoke
574 @code{execute-extended-command}, but that is painful to implement.) A
575 description of the value of the prefix argument, if any, also becomes
580 (execute-extended-command 1)
581 ---------- Buffer: Minibuffer ----------
582 1 M-x forward-word RET
583 ---------- Buffer: Minibuffer ----------
590 This function returns @code{t} if the containing function (the one that
591 called @code{interactive-p}) was called interactively, with the function
592 @code{call-interactively}. (It makes no difference whether
593 @code{call-interactively} was called from Lisp or directly from the
594 editor command loop.) If the containing function was called by Lisp
595 evaluation (or with @code{apply} or @code{funcall}), then it was not
596 called interactively.
598 The most common use of @code{interactive-p} is for deciding whether to
599 print an informative message. As a special exception,
600 @code{interactive-p} returns @code{nil} whenever a keyboard macro is
601 being run. This is to suppress the informative messages and speed up
602 the execution of the macro.
618 (setq foobar (list (foo) (interactive-p))))
623 ;; @r{Type @kbd{M-x foo}.}
628 ;; @r{Type @kbd{M-x bar}.}
629 ;; @r{This does not print anything.}
640 @node Command Loop Info
641 @section Information from the Command Loop
643 The editor command loop sets several Lisp variables to keep status
644 records for itself and for commands that are run.
647 This variable records the name of the previous command executed by the
648 command loop (the one before the current command). Normally the value
649 is a symbol with a function definition, but this is not guaranteed.
651 The value is copied from @code{this-command} when a command returns to
652 the command loop, except when the command specifies a prefix argument
653 for the following command.
657 @cindex current command
658 This variable records the name of the command now being executed by
659 the editor command loop. Like @code{last-command}, it is normally a symbol
660 with a function definition.
662 The command loop sets this variable just before running a command, and
663 copies its value into @code{last-command} when the command finishes
664 (unless the command specifies a prefix argument for the following
667 @cindex kill command repetition
668 Some commands set this variable during their execution, as a flag for
669 whatever command runs next. In particular, the functions for killing text
670 set @code{this-command} to @code{kill-region} so that any kill commands
671 immediately following will know to append the killed text to the
675 If you do not want a particular command to be recognized as the previous
676 command in the case where it got an error, you must code that command to
677 prevent this. One way is to set @code{this-command} to @code{t} at the
678 beginning of the command, and set @code{this-command} back to its proper
679 value at the end, like this:
682 (defun foo (args@dots{})
683 (interactive @dots{})
684 (let ((old-this-command this-command))
685 (setq this-command t)
686 @r{@dots{}do the work@dots{}}
687 (setq this-command old-this-command)))
690 @defun this-command-keys
691 This function returns a vector containing the key and mouse events that
692 invoked the present command, plus any previous commands that generated
693 the prefix argument for this command.
695 Note: this is not the same as in FSF Emacs, which can return a string.
698 This function copies the vector and the events; it is safe to keep and
704 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
705 @result{} [#<keypress-event control-U> #<keypress-event control-X> #<keypress-event control-E>]
710 @ignore Not in SXEmacs
711 @defvar last-nonmenu-event
712 This variable holds the last input event read as part of a key
713 sequence, not counting events resulting from mouse menus.
715 One use of this variable is to figure out a good default location to
720 @defvar last-command-event
721 This variable is set to the last input event that was read by the
722 command loop as part of a command. The principal use of this variable
723 is in @code{self-insert-command}, which uses it to decide which
726 This variable is off limits: you may not set its value or modify the
727 event that is its value, as it is destructively modified by
728 @code{read-key-sequence}. If you want to keep a pointer to this value,
729 you must use @code{copy-event}.
731 Note: This variable is an alias for @code{last-command-char} in FSF
737 ;; @r{Now type @kbd{C-u C-x C-e}.}
738 @result{} #<keypress-event control-E>
743 @defvar last-command-char
744 If the value of @code{last-command-event} is a keyboard event, then this
745 is the nearest character equivalent to it (or @code{nil} if there is no
746 character equivalent). @code{last-command-char} is the character that
747 @code{self-insert-command} will insert in the buffer.
749 Remember that there is @emph{not} a one-to-one mapping between keyboard
750 events and SXEmacs characters: many keyboard events have no
751 corresponding character, and when the Mule feature is available, most
752 characters can not be input on standard keyboards, except possibly with
753 help from an input method.
755 So writing code that examines this variable to determine what key has
756 been typed is bad practice, unless you are certain that it will be one
757 of a small set of characters.
759 This variable exists for compatibility with Emacs version 18.
764 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
771 @defvar current-mouse-event
772 This variable holds the mouse-button event which invoked this command,
773 or @code{nil}. This is what @code{(interactive "e")} returns.
776 @defvar echo-keystrokes
777 This variable determines how much time should elapse before command
778 characters echo. Its value must be an integer, which specifies the
779 number of seconds to wait before echoing. If the user types a prefix
780 key (say @kbd{C-x}) and then delays this many seconds before continuing,
781 the key @kbd{C-x} is echoed in the echo area. Any subsequent characters
782 in the same command will be echoed as well.
784 If the value is zero, then command input is not echoed.
793 The SXEmacs command loop reads a sequence of @dfn{events} that
794 represent keyboard or mouse activity.
796 Unlike in Emacs 18 and in FSF Emacs, events are a primitive Lisp type
797 that must be manipulated using their own accessor and settor primitives.
798 This section describes the representation and meaning of input events in
801 A key sequence that starts with a mouse event is read using the keymaps
802 of the buffer in the window that the mouse was in, not the current
803 buffer. This does not imply that clicking in a window selects that
804 window or its buffer---that is entirely under the control of the command
805 binding of the key sequence.
807 For information about how exactly the SXEmacs command loop works,
808 @xref{Reading Input}.
811 This function returns non-@code{nil} if @var{object} is an input event.
815 * Event Types:: Events come in different types.
816 * Event Contents:: What the contents of each event type are.
817 * Event Predicates:: Querying whether an event is of a
819 * Accessing Mouse Event Positions::
820 Determining where a mouse event occurred,
822 * Accessing Other Event Info:: Accessing non-positional event info.
823 * Working With Events:: Creating, copying, and destroying events.
824 * Converting Events:: Converting between events, keys, and
830 @subsection Event Types
832 Events represent keyboard or mouse activity or status changes of various
833 sorts, such as process input being available or a timeout being triggered.
834 The different event types are as follows:
837 @item key-press event
840 Note: Modifier keys such as ``control'', ``shift'', and ``alt'' do not
841 generate events; instead, they are tracked internally by SXEmacs, and
842 non-modifier key presses generate events that specify both the key
843 pressed and the modifiers that were held down at the time.
845 @item button-press event
846 @itemx button-release event
847 A button was pressed or released. Along with the button that was pressed
848 or released, button events specify the modifier keys that were held down
849 at the time and the position of the pointer at the time.
852 The pointer was moved. Along with the position of the pointer, these
853 events also specify the modifier keys that were held down at the time.
855 @item misc-user event
856 A menu item was selected, the scrollbar was used, or a drag or a drop
860 Input is available on a process.
863 A timeout has triggered.
866 Some window-system-specific action (such as a frame being resized or
867 a portion of a frame needing to be redrawn) has occurred. The contents
868 of this event are not accessible at the elisp level, but
869 @code{dispatch-event} knows what to do with an event of this type.
872 This is a special kind of event specifying that a particular function
873 needs to be called when this event is dispatched. An event of this type
874 is sometimes placed in the event queue when a magic event is processed.
875 This kind of event should generally just be passed off to
876 @code{dispatch-event}. @xref{Dispatching an Event}.
881 @subsection Contents of the Different Types of Events
883 Every event, no matter what type it is, contains a timestamp (which is
884 typically an offset in milliseconds from when the X server was started)
885 indicating when the event occurred. In addition, many events contain
886 a @dfn{channel}, which specifies which frame the event occurred on,
887 and/or a value indicating which modifier keys (shift, control, etc.)
888 were held down at the time of the event.
890 The contents of each event are as follows:
893 @item key-press event
898 Which key was pressed. This is an integer (in the printing @sc{ascii}
899 range: >32 and <127) or a symbol such as @code{left} or @code{right}.
901 Note: Many physical keys are actually treated as two separate keys,
902 depending on whether the shift key is pressed; for example, the ``a''
903 key is treated as either ``a'' or ``A'' depending on the state of the
904 shift key, and the ``1'' key is similarly treated as either ``1'' or
905 ``!'' on most keyboards.
907 In such cases, the shift key does not show up in the modifier list. For
908 other keys, such as @code{backspace}, the shift key shows up as a
911 Which modifier keys were pressed. As mentioned above, the shift key
912 is not treated as a modifier for many keys and will not show up in this
916 @item button-press event
917 @itemx button-release event
922 What button went down or up. Buttons are numbered starting at 1.
924 Which modifier keys were pressed. The special business mentioned
925 above for the shift key does @emph{not} apply to mouse events.
928 The position of the pointer (in pixels) at the time of the event.
931 @item pointer-motion event
937 The position of the pointer (in pixels) after it moved.
939 Which modifier keys were pressed. The special business mentioned above
940 for the shift key does @emph{not} apply to mouse events.
943 @item misc-user event
947 The elisp function to call for this event. This is normally either
948 @code{eval} or @code{call-interactively}.
950 The object to pass to the function. This is normally the callback that
951 was specified in the menu description.
953 What button went down or up. Buttons are numbered starting at 1.
955 Which modifier keys were pressed. The special business mentioned above
956 for the shift key does @emph{not} apply to mouse events.
959 The position of the pointer (in pixels) at the time of the event.
966 The Emacs ``process'' object in question.
973 The elisp function to call for this timeout. It is called with one
976 Some Lisp object associated with this timeout, to make it easier to
977 tell them apart. The function and object for this event were specified
978 when the timeout was set.
986 The rest of the information in this event is not user-accessible.
992 An elisp function to call when this event is dispatched.
994 The object to pass to the function. The function and object are set
995 when the event is created.
999 @defun event-type event
1000 Return the type of @var{event}.
1002 This will be a symbol; one of
1008 A mouse button was pressed.
1009 @item button-release
1010 A mouse button was released.
1014 Some other user action happened; typically, this is
1015 a menu selection, scrollbar action, or drag and drop action.
1017 Input is available from a subprocess.
1019 A timeout has expired.
1021 This causes a specified action to occur when dispatched.
1023 Some window-system-specific event has occurred.
1027 @node Event Predicates
1028 @subsection Event Predicates
1030 The following predicates return whether an object is an event of a
1033 @defun key-press-event-p object
1034 This is true if @var{object} is a key-press event.
1037 @defun button-event-p object
1038 This is true if @var{object} is a mouse button-press or button-release
1042 @defun button-press-event-p object
1043 This is true if @var{object} is a mouse button-press event.
1046 @defun button-release-event-p object
1047 This is true if @var{object} is a mouse button-release event.
1050 @defun motion-event-p object
1051 This is true if @var{object} is a mouse motion event.
1054 @defun mouse-event-p object
1055 This is true if @var{object} is a mouse button-press, button-release
1059 @defun eval-event-p object
1060 This is true if @var{object} is an eval event.
1063 @defun misc-user-event-p object
1064 This is true if @var{object} is a misc-user event.
1067 @defun process-event-p object
1068 This is true if @var{object} is a process event.
1071 @defun timeout-event-p object
1072 This is true if @var{object} is a timeout event.
1075 @defun event-live-p object
1076 This is true if @var{object} is any event that has not been deallocated.
1080 @node Accessing Mouse Event Positions
1081 @subsection Accessing the Position of a Mouse Event
1083 Unlike other events, mouse events (i.e. motion, button-press,
1084 button-release, and drag or drop type misc-user events) occur in a
1085 particular location on the screen. Many primitives are provided for
1086 determining exactly where the event occurred and what is under that
1090 * Frame-Level Event Position Info::
1091 * Window-Level Event Position Info::
1092 * Event Text Position Info::
1093 * Event Glyph Position Info::
1094 * Event Toolbar Position Info::
1095 * Other Event Position Info::
1099 @node Frame-Level Event Position Info
1100 @subsubsection Frame-Level Event Position Info
1102 The following functions return frame-level information about where
1103 a mouse event occurred.
1105 @defun event-frame event
1106 This function returns the ``channel'' or frame that the given mouse
1107 motion, button press, button release, or misc-user event occurred in.
1108 This will be @code{nil} for non-mouse events.
1111 @defun event-x-pixel event
1112 This function returns the X position in pixels of the given mouse event.
1113 The value returned is relative to the frame the event occurred in.
1114 This will signal an error if the event is not a mouse event.
1117 @defun event-y-pixel event
1118 This function returns the Y position in pixels of the given mouse event.
1119 The value returned is relative to the frame the event occurred in.
1120 This will signal an error if the event is not a mouse event.
1123 @node Window-Level Event Position Info
1124 @subsubsection Window-Level Event Position Info
1126 The following functions return window-level information about where
1127 a mouse event occurred.
1129 @defun event-window event
1130 Given a mouse motion, button press, button release, or misc-user event,
1131 compute and return the window on which that event occurred. This may be
1132 @code{nil} if the event occurred in the border or over a toolbar. The
1133 modeline is considered to be within the window it describes.
1136 @defun event-buffer event
1137 Given a mouse motion, button press, button release, or misc-user event,
1138 compute and return the buffer of the window on which that event
1139 occurred. This may be @code{nil} if the event occurred in the border or
1140 over a toolbar. The modeline is considered to be within the window it
1141 describes. This is equivalent to calling @code{event-window} and then
1142 calling @code{window-buffer} on the result if it is a window.
1145 @defun event-window-x-pixel event
1146 This function returns the X position in pixels of the given mouse event.
1147 The value returned is relative to the window the event occurred in.
1148 This will signal an error if the event is not a mouse-motion,
1149 button-press, button-release, or misc-user event.
1152 @defun event-window-y-pixel event
1153 This function returns the Y position in pixels of the given mouse event.
1154 The value returned is relative to the window the event occurred in.
1155 This will signal an error if the event is not a mouse-motion,
1156 button-press, button-release, or misc-user event.
1159 @node Event Text Position Info
1160 @subsubsection Event Text Position Info
1162 The following functions return information about the text (including the
1163 modeline) that a mouse event occurred over or near.
1165 @defun event-over-text-area-p event
1166 Given a mouse-motion, button-press, button-release, or misc-user event,
1167 this function returns @code{t} if the event is over the text area of a
1168 window. Otherwise, @code{nil} is returned. The modeline is not
1169 considered to be part of the text area.
1172 @defun event-over-modeline-p event
1173 Given a mouse-motion, button-press, button-release, or misc-user event,
1174 this function returns @code{t} if the event is over the modeline of a
1175 window. Otherwise, @code{nil} is returned.
1178 @defun event-x event
1179 This function returns the X position of the given mouse-motion,
1180 button-press, button-release, or misc-user event in characters. This is
1181 relative to the window the event occurred over.
1184 @defun event-y event
1185 This function returns the Y position of the given mouse-motion,
1186 button-press, button-release, or misc-user event in characters. This is
1187 relative to the window the event occurred over.
1190 @defun event-point event
1191 This function returns the character position of the given mouse-motion,
1192 button-press, button-release, or misc-user event. If the event did not
1193 occur over a window, or did not occur over text, then this returns
1194 @code{nil}. Otherwise, it returns an index into the buffer visible in
1198 @defun event-closest-point event
1199 This function returns the character position of the given mouse-motion,
1200 button-press, button-release, or misc-user event. If the event did not
1201 occur over a window or over text, it returns the closest point to the
1202 location of the event. If the Y pixel position overlaps a window and
1203 the X pixel position is to the left of that window, the closest point is
1204 the beginning of the line containing the Y position. If the Y pixel
1205 position overlaps a window and the X pixel position is to the right of
1206 that window, the closest point is the end of the line containing the Y
1207 position. If the Y pixel position is above a window, 0 is returned. If
1208 it is below a window, the value of @code{(window-end)} is returned.
1212 @node Event Glyph Position Info
1213 @subsubsection Event Glyph Position Info
1215 The following functions return information about the glyph (if any) that
1216 a mouse event occurred over.
1218 @defun event-over-glyph-p event
1219 Given a mouse-motion, button-press, button-release, or misc-user event,
1220 this function returns @code{t} if the event is over a glyph. Otherwise,
1221 @code{nil} is returned.
1224 @defun event-glyph-extent event
1225 If the given mouse-motion, button-press, button-release, or misc-user
1226 event happened on top of a glyph, this returns its extent; else
1227 @code{nil} is returned.
1230 @defun event-glyph-x-pixel event
1231 Given a mouse-motion, button-press, button-release, or misc-user event
1232 over a glyph, this function returns the X position of the pointer
1233 relative to the upper left of the glyph. If the event is not over a
1234 glyph, it returns @code{nil}.
1237 @defun event-glyph-y-pixel event
1238 Given a mouse-motion, button-press, button-release, or misc-user event
1239 over a glyph, this function returns the Y position of the pointer
1240 relative to the upper left of the glyph. If the event is not over a
1241 glyph, it returns @code{nil}.
1245 @node Event Toolbar Position Info
1246 @subsubsection Event Toolbar Position Info
1248 @defun event-over-toolbar-p event
1249 Given a mouse-motion, button-press, button-release, or misc-user event,
1250 this function returns @code{t} if the event is over a toolbar.
1251 Otherwise, @code{nil} is returned.
1254 @defun event-toolbar-button event
1255 If the given mouse-motion, button-press, button-release, or misc-user
1256 event happened on top of a toolbar button, this function returns the
1257 button. Otherwise, @code{nil} is returned.
1261 @node Other Event Position Info
1262 @subsubsection Other Event Position Info
1264 @defun event-over-border-p event
1265 Given a mouse-motion, button-press, button-release, or misc-user event,
1266 this function returns @code{t} if the event is over an internal toolbar.
1267 Otherwise, @code{nil} is returned.
1270 @node Accessing Other Event Info
1271 @subsection Accessing the Other Contents of Events
1273 The following functions allow access to the contents of events other
1274 than the position info described in the previous section.
1276 @defun event-timestamp event
1277 This function returns the timestamp of the given event object.
1280 @defun event-device event
1281 This function returns the device that the given event occurred on.
1284 @defun event-key event
1285 This function returns the Keysym of the given key-press event.
1286 This will be the @sc{ascii} code of a printing character, or a symbol.
1289 @defun event-button event
1290 This function returns the button-number of the given button-press or
1291 button-release event.
1294 @defun event-modifiers event
1295 This function returns a list of symbols, the names of the modifier keys
1296 which were down when the given mouse or keyboard event was produced.
1299 @defun event-modifier-bits event
1300 This function returns a number representing the modifier keys which were
1301 down when the given mouse or keyboard event was produced.
1304 @defun event-function event
1305 This function returns the callback function of the given timeout,
1306 misc-user, or eval event.
1309 @defun event-object event
1310 This function returns the callback function argument of the given
1311 timeout, misc-user, or eval event.
1314 @defun event-process event
1315 This function returns the process of the given process event.
1319 @node Working With Events
1320 @subsection Working With Events
1322 SXEmacs provides primitives for creating, copying, and destroying
1323 event objects. Many functions that return events take an event object
1324 as an argument and fill in the fields of this event; or they make accept
1325 either an event object or @code{nil}, creating the event object first in
1328 @defun make-event &optional type plist
1329 This function creates a new event structure. If no arguments are
1330 specified, the created event will be empty. To specify the event type,
1331 use the @var{type} argument. The allowed types are @code{empty},
1332 @code{key-press}, @code{button-press}, @code{button-release},
1333 @code{motion}, or @code{misc-user}.
1335 @var{plist} is a property list, the properties being compatible to those
1336 returned by @code{event-properties}. For events other than
1337 @code{empty}, it is mandatory to specify certain properties. For
1338 @code{empty} events, @var{plist} must be @code{nil}.
1340 The list is @dfn{canonicalized}, which means that if a property keyword
1341 is present more than once, only the first instance is taken into account.
1342 Specifying an unknown or illegal property signals an error.
1344 The following properties are allowed:
1347 @item @code{channel}
1348 The event channel. This is a frame or a console. For mouse events (of
1349 type @code{button-press}, @code{button-release} and @code{motion}), this
1350 must be a frame. For key-press events, it must be a console. If
1351 channel is unspecified by @var{plist}, it will be set to the selected
1352 frame or selected console, as appropriate.
1355 The event key. This is either a symbol or a character. It is allowed
1356 (and required) only for key-press events.
1359 The event button. This an integer, either 1, 2 or 3. It is allowed
1360 only for button-press and button-release events.
1362 @item @code{modifiers}
1363 The event modifiers. This is a list of modifier symbols. It is allowed
1364 for key-press, button-press, button-release and motion events.
1367 The event X coordinate. This is an integer. It is relative to the
1368 channel's root window, and is allowed for button-press, button-release
1372 The event Y coordinate. This is an integer. It is relative to the
1373 channel's root window, and is allowed for button-press, button-release
1374 and motion events. This means that, for instance, to access the
1375 toolbar, the @code{y} property will have to be negative.
1377 @item @code{timestamp}
1378 The event timestamp, a non-negative integer. Allowed for all types of
1382 @emph{WARNING}: the event object returned by this function may be a
1383 reused one; see the function @code{deallocate-event}.
1385 The events created by @code{make-event} can be used as non-interactive
1386 arguments to the functions with an @code{(interactive "e")}
1389 Here are some basic examples of usage:
1393 ;; @r{Create an empty event.}
1395 @result{} #<empty-event>
1399 ;; @r{Try creating a key-press event.}
1400 (make-event 'key-press)
1401 @error{} Undefined key for keypress event
1405 ;; @r{Creating a key-press event, try 2}
1406 (make-event 'key-press '(key home))
1407 @result{} #<keypress-event home>
1411 ;; @r{Create a key-press event of dubious fame.}
1412 (make-event 'key-press '(key escape modifiers (meta alt control shift)))
1413 @result{} #<keypress-event control-meta-alt-shift-escape>
1417 ;; @r{Create a M-button1 event at coordinates defined by variables}
1418 ;; @r{@var{x} and @var{y}.}
1419 (make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y))
1420 @result{} #<buttondown-event meta-button1>
1424 ;; @r{Create a similar button-release event.}
1425 (make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x))
1426 @result{} #<buttonup-event meta-button1up>
1430 ;; @r{Create a mouse-motion event.}
1431 (make-event 'motion '(x 20 y 30))
1432 @result{} #<motion-event 20, 30>
1434 (event-properties (make-event 'motion '(x 20 y 30)))
1435 @result{} (channel #<x-frame "emacs" 0x8e2> x 20 y 30
1436 modifiers nil timestamp 0)
1440 In conjunction with @code{event-properties}, you can use
1441 @code{make-event} to create modified copies of existing events. For
1442 instance, the following code will return an @code{equal} copy of
1446 (make-event (event-type @var{event})
1447 (event-properties @var{event}))
1450 Note, however, that you cannot use @code{make-event} as the generic
1451 replacement for @code{copy-event}, because it does not allow creating
1452 all of the event types.
1454 To create a modified copy of an event, you can use the canonicalization
1455 feature of @var{plist}. The following example creates a copy of
1456 @var{event}, but with @code{modifiers} reset to @code{nil}.
1459 (make-event (event-type @var{event})
1460 (append '(modifiers nil)
1461 (event-properties @var{event})))
1465 @defun copy-event event1 &optional event2
1466 This function makes a copy of the event object @var{event1}. If a
1467 second event argument @var{event2} is given, @var{event1} is copied into
1468 @var{event2} and @var{event2} is returned. If @var{event2} is not
1469 supplied (or is @code{nil}) then a new event will be made, as with
1473 @defun deallocate-event event
1474 This function allows the given event structure to be reused. You
1475 @strong{MUST NOT} use this event object after calling this function with
1478 It is not necessary to call this function, as event objects are
1479 garbage-collected like all other objects; however, it may be more
1480 efficient to explicitly deallocate events when you are sure that it is
1485 @node Converting Events
1486 @subsection Converting Events
1488 SXEmacs provides some auxiliary functions for converting between events
1489 and other ways of representing keys. These are useful when working with
1490 @sc{ascii} strings and with keymaps.
1492 @defun character-to-event key-description &optional event console use-console-meta-flag
1493 This function converts a keystroke description to an event structure.
1494 @var{key-description} is the specification of a key stroke, and
1495 @var{event} is the event object to fill in. This function contains
1496 knowledge about what the codes ``mean''---for example, the number 9 is
1497 converted to the character @key{Tab}, not the distinct character
1500 Note: @var{key-description} can be an integer, a character, a symbol
1501 such as @code{clear} or a list such as @code{(control backspace)}.
1503 If optional arg @var{event} is non-@code{nil}, it is modified;
1504 otherwise, a new event object is created. In both cases, the event is
1507 Optional third arg @var{console} is the console to store in the event,
1508 and defaults to the selected console.
1510 If @var{key-description} is an integer or character, the high bit may be
1511 interpreted as the meta key. (This is done for backward compatibility in
1512 lots of places.) If @var{use-console-meta-flag} is @code{nil}, this
1513 will always be the case. If @var{use-console-meta-flag} is
1514 non-@code{nil}, the @code{meta} flag for @var{console} affects whether
1515 the high bit is interpreted as a meta key. (See @code{set-input-mode}.)
1516 If you don't want this silly meta interpretation done, you should pass
1517 in a list containing the character.
1519 Beware that @code{character-to-event} and @code{event-to-character} are
1520 not strictly inverse functions, since events contain much more
1521 information than the @sc{ascii} character set can encode.
1524 @defun event-to-character event &optional allow-extra-modifiers allow-meta allow-non-ascii
1525 This function returns the closest @sc{ascii} approximation to
1526 @var{event}. If the event isn't a keypress, this returns @code{nil}.
1528 If @var{allow-extra-modifiers} is non-@code{nil}, then this is lenient
1529 in its translation; it will ignore modifier keys other than
1530 @key{control} and @key{meta}, and will ignore the @key{shift} modifier
1531 on those characters which have no shifted @sc{ascii} equivalent
1532 (@key{Control-Shift-A} for example, will be mapped to the same
1533 @sc{ascii} code as @key{Control-A}).
1535 If @var{allow-meta} is non-@code{nil}, then the @key{Meta} modifier will
1536 be represented by turning on the high bit of the byte returned;
1537 otherwise, @code{nil} will be returned for events containing the
1538 @key{Meta} modifier.
1540 If @var{allow-non-ascii} is non-@code{nil}, then characters which are
1541 present in the prevailing character set (@pxref{Keymaps, variable
1542 @code{character-set-property}}) will be returned as their code in that
1543 character set, instead of the return value being restricted to
1546 Note: specifying both @var{allow-meta} and @var{allow-non-ascii} is
1547 ambiguous, as both use the high bit; @key{M-x} and @key{oslash} will be
1551 @defun events-to-keys events &optional no-mice
1552 Given a vector of event objects, this function returns a vector of key
1553 descriptors, or a string (if they all fit in the @sc{ascii} range).
1554 Optional arg @var{no-mice} means that button events are not allowed.
1559 @section Reading Input
1561 The editor command loop reads keyboard input using the function
1562 @code{next-event} and constructs key sequences out of the events using
1563 @code{dispatch-event}.
1565 Lisp programs can also use the function @code{read-key-sequence}, which
1566 reads input a key sequence at a time. See also
1567 @code{momentary-string-display} in @ref{Temporary Displays},
1568 and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
1569 functions and variables for controlling terminal input modes and
1570 debugging terminal input.
1572 For higher-level input facilities, see @ref{Minibuffers}.
1575 * Key Sequence Input:: How to read one key sequence.
1576 * Reading One Event:: How to read just one event.
1577 * Dispatching an Event:: What to do with an event once it has been read.
1578 * Quoted Character Input:: Asking the user to specify a character.
1579 * Peeking and Discarding:: How to reread or throw away input events.
1583 @node Key Sequence Input
1584 @subsection Key Sequence Input
1585 @cindex key sequence input
1587 Lisp programs can read input a key sequence at a time by calling
1588 @code{read-key-sequence}; for example, @code{describe-key} uses it to
1589 read the key to describe.
1591 @defun read-key-sequence prompt &optional continue-echo dont-downcase-last
1592 @cindex key sequence
1593 This function reads a sequence of keystrokes or mouse clicks and returns
1594 it as a vector of event objects read. It keeps reading events until it
1595 has accumulated a full key sequence; that is, enough to specify a
1596 non-prefix command using the currently active keymaps.
1598 The vector and the event objects it contains are freshly created (and
1599 so will not be side-effected by subsequent calls to this function).
1601 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
1602 typed while reading with this function works like any other character,
1603 and does not set @code{quit-flag}. @xref{Quitting}.
1605 The argument @var{prompt} is either a string to be displayed in the echo
1606 area as a prompt, or @code{nil}, meaning not to display a prompt.
1608 Second optional arg @var{continue-echo} non-@code{nil} means this key
1609 echoes as a continuation of the previous key.
1611 Third optional arg @var{dont-downcase-last} non-@code{nil} means do not
1612 convert the last event to lower case. Normally any upper case event is
1613 converted to lower case if the original event is undefined and the lower
1614 case equivalent is defined.
1616 This argument is provided mostly for @var{fsf} compatibility; the
1617 equivalent effect can be achieved more generally by binding
1618 @code{retry-undefined-key-binding-unshifted} to @code{nil} around the
1619 call to @code{read-key-sequence}.
1622 If the user selects a menu item while we are prompting for a key
1623 sequence, the returned value will be a vector of a single menu-selection
1624 event (a misc-user event), but an error will be signalled if you pass
1625 this value to @code{lookup-key} or a related function.
1627 In the example below, the prompt @samp{?} is displayed in the echo area,
1628 and the user types @kbd{C-x C-f}.
1631 (read-key-sequence "?")
1634 ---------- Echo Area ----------
1636 ---------- Echo Area ----------
1638 @result{} [#<keypress-event control-X> #<keypress-event control-F>]
1643 @ignore @c Not in SXEmacs
1644 @defvar num-input-keys
1646 This variable's value is the number of key sequences processed so far in
1647 this SXEmacs session. This includes key sequences read from the terminal
1648 and key sequences read from keyboard macros being executed.
1652 @cindex upper case key sequence
1653 @cindex downcasing in @code{lookup-key}
1654 If an input character is an upper-case letter and has no key binding,
1655 but its lower-case equivalent has one, then @code{read-key-sequence}
1656 converts the character to lower case. Note that @code{lookup-key} does
1657 not perform case conversion in this way.
1659 @node Reading One Event
1660 @subsection Reading One Event
1662 The lowest level functions for command input are those which read a
1663 single event. These functions often make a distinction between
1664 @dfn{command events}, which are user actions (keystrokes and mouse
1665 actions), and other events, which serve as communication between
1666 SXEmacs and the window system.
1668 @defun next-event &optional event prompt
1669 This function reads and returns the next available event from the window
1670 system or terminal driver, waiting if necessary until an event is
1671 available. Pass this object to @code{dispatch-event} to handle it. If
1672 an event object is supplied, it is filled in and returned; otherwise a
1673 new event object will be created.
1675 Events can come directly from the user, from a keyboard macro, or from
1676 @code{unread-command-events}.
1678 In most cases, the function @code{next-command-event} is more
1682 @defun next-command-event &optional event prompt
1683 This function returns the next available ``user'' event from the window
1684 system or terminal driver. Pass this object to @code{dispatch-event} to
1685 handle it. If an event object is supplied, it is filled in and
1686 returned, otherwise a new event object will be created.
1688 The event returned will be a keyboard, mouse press, or mouse release
1689 event. If there are non-command events available (mouse motion,
1690 sub-process output, etc) then these will be executed (with
1691 @code{dispatch-event}) and discarded. This function is provided as a
1692 convenience; it is equivalent to the Lisp code
1698 (not (or (key-press-event-p event)
1699 (button-press-event-p event)
1700 (button-release-event-p event)
1701 (menu-event-p event))))
1702 (dispatch-event event))
1706 Here is what happens if you call @code{next-command-event} and then
1707 press the right-arrow function key:
1711 (next-command-event)
1712 @result{} #<keypress-event right>
1718 This function reads and returns a character of command input. If a
1719 mouse click is detected, an error is signalled. The character typed is
1720 returned as an @sc{ascii} value.
1722 Note: This function is retained for compatibility with Emacs 18, and is
1723 most likely the wrong thing for you to be using: consider using
1724 @code{next-command-event} instead.
1727 @defun enqueue-eval-event function object
1728 This function adds an eval event to the back of the queue. The
1729 eval event will be the next event read after all pending events.
1732 @node Dispatching an Event
1733 @subsection Dispatching an Event
1734 @cindex dispatching an event
1736 @defun dispatch-event event
1737 Given an event object returned by @code{next-event}, this function
1738 executes it. This is the basic function that makes SXEmacs respond to
1739 user input; it also deals with notifications from the window system
1740 (such as Expose events).
1744 @node Quoted Character Input
1745 @subsection Quoted Character Input
1746 @cindex quoted character input
1748 You can use the function @code{read-quoted-char} to ask the user to
1749 specify a character, and allow the user to specify a control or meta
1750 character conveniently, either literally or as an octal character code.
1751 The command @code{quoted-insert} uses this function.
1753 @defun read-quoted-char &optional prompt
1754 @cindex octal character input
1755 @cindex control characters, reading
1756 @cindex nonprinting characters, reading
1757 This function is like @code{read-char}, except that if the first
1758 character read is an octal digit (0-7), it reads up to two more octal
1759 digits (but stopping if a non-octal digit is found) and returns the
1760 character represented by those digits in octal.
1762 Quitting is suppressed when the first character is read, so that the
1763 user can enter a @kbd{C-g}. @xref{Quitting}.
1765 If @var{prompt} is supplied, it specifies a string for prompting the
1766 user. The prompt string is always displayed in the echo area, followed
1767 by a single @samp{-}.
1769 In the following example, the user types in the octal number 177 (which
1773 (read-quoted-char "What character")
1776 ---------- Echo Area ----------
1777 What character-@kbd{177}
1778 ---------- Echo Area ----------
1787 @node Peeking and Discarding
1788 @subsection Miscellaneous Event Input Features
1790 This section describes how to ``peek ahead'' at events without using
1791 them up, how to check for pending input, and how to discard pending
1794 See also the variables @code{last-command-event} and
1795 @code{last-command-char} (@ref{Command Loop Info}).
1797 @defvar unread-command-events
1799 @cindex peeking at input
1800 This variable holds a list of events waiting to be read as command
1801 input. The events are used in the order they appear in the list, and
1802 removed one by one as they are used.
1804 The variable is needed because in some cases a function reads an event
1805 and then decides not to use it. Storing the event in this variable
1806 causes it to be processed normally, by the command loop or by the
1807 functions to read command input.
1809 @cindex prefix argument unreading
1810 For example, the function that implements numeric prefix arguments reads
1811 any number of digits. When it finds a non-digit event, it must unread
1812 the event so that it can be read normally by the command loop.
1813 Likewise, incremental search uses this feature to unread events with no
1814 special meaning in a search, because these events should exit the search
1815 and then execute normally.
1817 @ignore FSF Emacs stuff
1818 The reliable and easy way to extract events from a key sequence so as to
1819 put them in @code{unread-command-events} is to use
1820 @code{listify-key-sequence} (@pxref{Strings of Events}).
1824 @defvar unread-command-event
1825 This variable holds a single event to be read as command input.
1827 This variable is obsolete now that you can use
1828 @code{unread-command-events} instead; it exists only to support programs
1829 written for versions of (X)Emacs prior to 19.12.
1832 @defun input-pending-p
1833 @cindex waiting for command key input
1834 This function determines whether any command input is currently
1835 available to be read. It returns immediately, with value @code{t} if
1836 there is available input, @code{nil} otherwise. On rare occasions it
1837 may return @code{t} when no input is available.
1840 @defvar last-input-event
1841 This variable is set to the last keyboard or mouse button event received.
1843 This variable is off limits: you may not set its value or modify the
1844 event that is its value, as it is destructively modified by
1845 @code{read-key-sequence}. If you want to keep a pointer to this value,
1846 you must use @code{copy-event}.
1848 Note: This variable is an alias for @code{last-input-char} in FSF
1851 In the example below, a character is read (the character @kbd{1}). It
1852 becomes the value of @code{last-input-event}, while @kbd{C-e} (from the
1853 @kbd{C-x C-e} command used to evaluate this expression) remains the
1854 value of @code{last-command-event}.
1858 (progn (print (next-command-event))
1859 (print last-command-event)
1861 @print{} #<keypress-event 1>
1862 @print{} #<keypress-event control-E>
1863 @result{} #<keypress-event 1>
1869 @defvar last-input-char
1870 If the value of @code{last-input-event} is a keyboard event, then this
1871 is the nearest @sc{ascii} equivalent to it.
1873 Remember that there is @emph{not} a 1:1 mapping between keyboard events
1874 and @sc{ascii} characters: the set of keyboard events is much larger, so
1875 writing code that examines this variable to determine what key has been
1876 typed is bad practice, unless you are certain that it will be one of a
1877 small set of characters.
1879 Note: This function exists for compatibility with Emacs version 18.
1882 @defun discard-input
1884 @cindex discard input
1885 @cindex terminate keyboard macro
1886 This function discards the contents of the terminal input buffer and
1887 cancels any keyboard macro that might be in the process of definition.
1888 It returns @code{nil}.
1890 In the following example, the user may type a number of characters right
1891 after starting the evaluation of the form. After the @code{sleep-for}
1892 finishes sleeping, @code{discard-input} discards any characters typed
1896 (progn (sleep-for 2)
1904 @section Waiting for Elapsed Time or Input
1908 The wait functions are designed to wait for a certain amount of time
1909 to pass or until there is input. For example, you may wish to pause in
1910 the middle of a computation to allow the user time to view the display.
1911 @code{sit-for} pauses and updates the screen, and returns immediately if
1912 input comes in, while @code{sleep-for} pauses without updating the
1915 Note: In FSF Emacs the commands @code{sit-for} and @code{sleep-for}
1916 take two arguments to specify the time (one integer and one float
1917 value), instead of a single argument that can be either an integer or a
1920 @defun sit-for seconds &optional nodisplay
1921 This function performs redisplay (provided there is no pending input
1922 from the user), then waits @var{seconds} seconds, or until input is
1923 available. The result is @code{t} if @code{sit-for} waited the full
1924 time with no input arriving (see @code{input-pending-p} in @ref{Peeking
1925 and Discarding}). Otherwise, the value is @code{nil}.
1927 The argument @var{seconds} need not be an integer. If it is a floating
1928 point number, @code{sit-for} waits for a fractional number of seconds.
1930 @cindex forcing redisplay
1931 Redisplay is normally preempted if input arrives, and does not happen at
1932 all if input is available before it starts. (You can force screen
1933 updating in such a case by using @code{force-redisplay}. @xref{Refresh
1934 Screen}.) If there is no input pending, you can force an update with no
1935 delay by using @code{(sit-for 0)}.
1937 If @var{nodisplay} is non-@code{nil}, then @code{sit-for} does not
1938 redisplay, but it still returns as soon as input is available (or when
1939 the timeout elapses).
1942 Iconifying or deiconifying a frame makes @code{sit-for} return, because
1943 that generates an event. @xref{Misc Events}.
1946 The usual purpose of @code{sit-for} is to give the user time to read
1947 text that you display.
1950 @defun sleep-for seconds
1951 This function simply pauses for @var{seconds} seconds without updating
1952 the display. This function pays no attention to available input. It
1955 The argument @var{seconds} need not be an integer. If it is a floating
1956 point number, @code{sleep-for} waits for a fractional number of seconds.
1957 @ignore FSF Emacs stuff
1958 Some systems support only a whole number of seconds; on these systems,
1959 @var{seconds} is rounded down.
1961 The optional argument @var{millisec} specifies an additional waiting
1962 period measured in milliseconds. This adds to the period specified by
1963 @var{seconds}. If the system doesn't support waiting fractions of a
1964 second, you get an error if you specify nonzero @var{millisec}.
1967 Use @code{sleep-for} when you wish to guarantee a delay.
1970 @xref{Time of Day}, for functions to get the current time.
1978 Typing @kbd{C-g} while a Lisp function is running causes SXEmacs to
1979 @dfn{quit} whatever it is doing. This means that control returns to the
1980 innermost active command loop.
1982 Typing @kbd{C-g} while the command loop is waiting for keyboard input
1983 does not cause a quit; it acts as an ordinary input character. In the
1984 simplest case, you cannot tell the difference, because @kbd{C-g}
1985 normally runs the command @code{keyboard-quit}, whose effect is to quit.
1986 However, when @kbd{C-g} follows a prefix key, the result is an undefined
1987 key. The effect is to cancel the prefix key as well as any prefix
1990 In the minibuffer, @kbd{C-g} has a different definition: it aborts out
1991 of the minibuffer. This means, in effect, that it exits the minibuffer
1992 and then quits. (Simply quitting would return to the command loop
1993 @emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit
1994 directly when the command reader is reading input is so that its meaning
1995 can be redefined in the minibuffer in this way. @kbd{C-g} following a
1996 prefix key is not redefined in the minibuffer, and it has its normal
1997 effect of canceling the prefix key and prefix argument. This too
1998 would not be possible if @kbd{C-g} always quit directly.
2000 When @kbd{C-g} does directly quit, it does so by setting the variable
2001 @code{quit-flag} to @code{t}. SXEmacs checks this variable at appropriate
2002 times and quits if it is not @code{nil}. Setting @code{quit-flag}
2003 non-@code{nil} in any way thus causes a quit.
2005 At the level of C code, quitting cannot happen just anywhere; only at the
2006 special places that check @code{quit-flag}. The reason for this is
2007 that quitting at other places might leave an inconsistency in SXEmacs's
2008 internal state. Because quitting is delayed until a safe place, quitting
2009 cannot make SXEmacs crash.
2011 Certain functions such as @code{read-key-sequence} or
2012 @code{read-quoted-char} prevent quitting entirely even though they wait
2013 for input. Instead of quitting, @kbd{C-g} serves as the requested
2014 input. In the case of @code{read-key-sequence}, this serves to bring
2015 about the special behavior of @kbd{C-g} in the command loop. In the
2016 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
2017 to quote a @kbd{C-g}.
2019 You can prevent quitting for a portion of a Lisp function by binding
2020 the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
2021 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
2022 usual result of this---a quit---is prevented. Eventually,
2023 @code{inhibit-quit} will become @code{nil} again, such as when its
2024 binding is unwound at the end of a @code{let} form. At that time, if
2025 @code{quit-flag} is still non-@code{nil}, the requested quit happens
2026 immediately. This behavior is ideal when you wish to make sure that
2027 quitting does not happen within a ``critical section'' of the program.
2029 @cindex @code{read-quoted-char} quitting
2030 In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
2031 handled in a special way that does not involve quitting. This is done
2032 by reading the input with @code{inhibit-quit} bound to @code{t}, and
2033 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
2034 becomes @code{nil} again. This excerpt from the definition of
2035 @code{read-quoted-char} shows how this is done; it also shows that
2036 normal quitting is permitted after the first character of input.
2039 (defun read-quoted-char (&optional prompt)
2040 "@dots{}@var{documentation}@dots{}"
2041 (let ((count 0) (code 0) char)
2043 (let ((inhibit-quit (zerop count))
2045 (and prompt (message "%s-" prompt))
2046 (setq char (read-char))
2047 (if inhibit-quit (setq quit-flag nil)))
2053 If this variable is non-@code{nil}, then SXEmacs quits immediately, unless
2054 @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
2055 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
2058 @defvar inhibit-quit
2059 This variable determines whether SXEmacs should quit when @code{quit-flag}
2060 is set to a value other than @code{nil}. If @code{inhibit-quit} is
2061 non-@code{nil}, then @code{quit-flag} has no special effect.
2064 @deffn Command keyboard-quit
2065 This function signals the @code{quit} condition with @code{(signal 'quit
2066 nil)}. This is the same thing that quitting does. (See @code{signal}
2070 You can specify a character other than @kbd{C-g} to use for quitting.
2071 See the function @code{set-input-mode} in @ref{Terminal Input}.
2074 @node Prefix Command Arguments
2075 @section Prefix Command Arguments
2076 @cindex prefix argument
2077 @cindex raw prefix argument
2078 @cindex numeric prefix argument
2080 Most SXEmacs commands can use a @dfn{prefix argument}, a number
2081 specified before the command itself.
2083 Don't confuse prefix arguments with prefix keys.
2085 The prefix argument is at all times represented by a value, which may
2086 be @code{nil}, meaning there is currently no prefix argument. Each
2087 command may use the prefix argument or ignore it.
2089 There are two representations of the prefix argument: @dfn{raw} and
2090 @dfn{numeric}. The editor command loop uses the raw representation
2091 internally, and so do the Lisp variables that store the information, but
2092 commands can request either representation.
2094 Here are the possible values of a raw prefix argument:
2098 @code{nil}, meaning there is no prefix argument. Its numeric value is
2099 1, but numerous commands make a distinction between @code{nil} and the
2103 An integer, which stands for itself.
2106 A list of one element, which is an integer. This form of prefix
2107 argument results from one or a succession of @kbd{C-u}'s with no
2108 digits. The numeric value is the integer in the list, but some
2109 commands make a distinction between such a list and an integer alone.
2112 The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was
2113 typed, without following digits. The equivalent numeric value is
2114 @minus{}1, but some commands make a distinction between the integer
2115 @minus{}1 and the symbol @code{-}.
2118 We illustrate these possibilities by calling the following function with
2123 (defun display-prefix (arg)
2124 "Display the value of the raw prefix arg."
2131 Here are the results of calling @code{display-prefix} with various
2132 raw prefix arguments:
2135 M-x display-prefix @print{} nil
2137 C-u M-x display-prefix @print{} (4)
2139 C-u C-u M-x display-prefix @print{} (16)
2141 C-u 3 M-x display-prefix @print{} 3
2143 M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
2145 C-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
2147 C-u - M-x display-prefix @print{} -
2149 M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
2151 C-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
2153 C-u - 7 M-x display-prefix @print{} -7
2155 M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
2157 C-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
2160 SXEmacs uses two variables to store the prefix argument:
2161 @code{prefix-arg} and @code{current-prefix-arg}. Commands such as
2162 @code{universal-argument} that set up prefix arguments for other
2163 commands store them in @code{prefix-arg}. In contrast,
2164 @code{current-prefix-arg} conveys the prefix argument to the current
2165 command, so setting it has no effect on the prefix arguments for future
2168 Normally, commands specify which representation to use for the prefix
2169 argument, either numeric or raw, in the @code{interactive} declaration.
2170 (@xref{Using Interactive}.) Alternatively, functions may look at the
2171 value of the prefix argument directly in the variable
2172 @code{current-prefix-arg}, but this is less clean.
2174 @defun prefix-numeric-value raw
2175 This function returns the numeric meaning of a valid raw prefix argument
2176 value, @var{raw}. The argument may be a symbol, a number, or a list.
2177 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
2178 value @minus{}1 is returned; if it is a number, that number is returned;
2179 if it is a list, the @sc{car} of that list (which should be a number) is
2183 @defvar current-prefix-arg
2184 This variable holds the raw prefix argument for the @emph{current}
2185 command. Commands may examine it directly, but the usual way to access
2186 it is with @code{(interactive "P")}.
2190 The value of this variable is the raw prefix argument for the
2191 @emph{next} editing command. Commands that specify prefix arguments for
2192 the following command work by setting this variable.
2195 Do not call the functions @code{universal-argument},
2196 @code{digit-argument}, or @code{negative-argument} unless you intend to
2197 let the user enter the prefix argument for the @emph{next} command.
2199 @deffn Command universal-argument
2200 This command reads input and specifies a prefix argument for the
2201 following command. Don't call this command yourself unless you know
2205 @deffn Command digit-argument arg
2206 This command adds to the prefix argument for the following command. The
2207 argument @var{arg} is the raw prefix argument as it was before this
2208 command; it is used to compute the updated prefix argument. Don't call
2209 this command yourself unless you know what you are doing.
2212 @deffn Command negative-argument arg
2213 This command adds to the numeric argument for the next command. The
2214 argument @var{arg} is the raw prefix argument as it was before this
2215 command; its value is negated to form the new prefix argument. Don't
2216 call this command yourself unless you know what you are doing.
2220 @node Recursive Editing
2221 @section Recursive Editing
2222 @cindex recursive command loop
2223 @cindex recursive editing level
2224 @cindex command loop, recursive
2226 The SXEmacs command loop is entered automatically when SXEmacs starts up.
2227 This top-level invocation of the command loop never exits; it keeps
2228 running as long as SXEmacs does. Lisp programs can also invoke the
2229 command loop. Since this makes more than one activation of the command
2230 loop, we call it @dfn{recursive editing}. A recursive editing level has
2231 the effect of suspending whatever command invoked it and permitting the
2232 user to do arbitrary editing before resuming that command.
2234 The commands available during recursive editing are the same ones
2235 available in the top-level editing loop and defined in the keymaps.
2236 Only a few special commands exit the recursive editing level; the others
2237 return to the recursive editing level when they finish. (The special
2238 commands for exiting are always available, but they do nothing when
2239 recursive editing is not in progress.)
2241 All command loops, including recursive ones, set up all-purpose error
2242 handlers so that an error in a command run from the command loop will
2245 @cindex minibuffer input
2246 Minibuffer input is a special kind of recursive editing. It has a few
2247 special wrinkles, such as enabling display of the minibuffer and the
2248 minibuffer window, but fewer than you might suppose. Certain keys
2249 behave differently in the minibuffer, but that is only because of the
2250 minibuffer's local map; if you switch windows, you get the usual SXEmacs
2253 @cindex @code{throw} example
2255 @cindex exit recursive editing
2257 To invoke a recursive editing level, call the function
2258 @code{recursive-edit}. This function contains the command loop; it also
2259 contains a call to @code{catch} with tag @code{exit}, which makes it
2260 possible to exit the recursive editing level by throwing to @code{exit}
2261 (@pxref{Catch and Throw}). If you throw a value other than @code{t},
2262 then @code{recursive-edit} returns normally to the function that called
2263 it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
2264 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
2265 control returns to the command loop one level up. This is called
2266 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
2268 Most applications should not use recursive editing, except as part of
2269 using the minibuffer. Usually it is more convenient for the user if you
2270 change the major mode of the current buffer temporarily to a special
2271 major mode, which should have a command to go back to the previous mode.
2272 (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
2273 give the user different text to edit ``recursively'', create and select
2274 a new buffer in a special mode. In this mode, define a command to
2275 complete the processing and go back to the previous buffer. (The
2276 @kbd{m} command in Rmail does this.)
2278 Recursive edits are useful in debugging. You can insert a call to
2279 @code{debug} into a function definition as a sort of breakpoint, so that
2280 you can look around when the function gets there. @code{debug} invokes
2281 a recursive edit but also provides the other features of the debugger.
2283 Recursive editing levels are also used when you type @kbd{C-r} in
2284 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
2286 @deffn Command recursive-edit
2287 @cindex suspend evaluation
2288 This function invokes the editor command loop. It is called
2289 automatically by the initialization of SXEmacs, to let the user begin
2290 editing. When called from a Lisp program, it enters a recursive editing
2293 In the following example, the function @code{simple-rec} first
2294 advances point one word, then enters a recursive edit, printing out a
2295 message in the echo area. The user can then do any editing desired, and
2296 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
2299 (defun simple-rec ()
2301 (message "Recursive edit in progress")
2304 @result{} simple-rec
2310 @deffn Command exit-recursive-edit
2311 This function exits from the innermost recursive edit (including
2312 minibuffer input). Its definition is effectively @code{(throw 'exit
2316 @deffn Command abort-recursive-edit
2317 This function aborts the command that requested the innermost recursive
2318 edit (including minibuffer input), by signaling @code{quit}
2319 after exiting the recursive edit. Its definition is effectively
2320 @code{(throw 'exit t)}. @xref{Quitting}.
2323 @deffn Command top-level
2324 This function exits all recursive editing levels; it does not return a
2325 value, as it jumps completely out of any computation directly back to
2326 the main command loop.
2329 @defun recursion-depth
2330 This function returns the current depth of recursive edits. When no
2331 recursive edit is active, it returns 0.
2334 @node Disabling Commands
2335 @section Disabling Commands
2336 @cindex disabled command
2338 @dfn{Disabling a command} marks the command as requiring user
2339 confirmation before it can be executed. Disabling is used for commands
2340 which might be confusing to beginning users, to prevent them from using
2341 the commands by accident.
2344 The low-level mechanism for disabling a command is to put a
2345 non-@code{nil} @code{disabled} property on the Lisp symbol for the
2346 command. These properties are normally set up by the user's
2347 @file{.emacs} file with Lisp expressions such as this:
2350 (put 'upcase-region 'disabled t)
2354 For a few commands, these properties are present by default and may be
2355 removed by the @file{.emacs} file.
2357 If the value of the @code{disabled} property is a string, the message
2358 saying the command is disabled includes that string. For example:
2361 (put 'delete-region 'disabled
2362 "Text deleted this way cannot be yanked back!\n")
2365 @xref{Disabling,,, sxemacs, The SXEmacs User's Manual}, for the details on
2366 what happens when a disabled command is invoked interactively.
2367 Disabling a command has no effect on calling it as a function from Lisp
2370 @deffn Command enable-command command
2371 Allow @var{command} to be executed without special confirmation from now
2372 on, and (if the user confirms) alter the user's @file{.emacs} file so
2373 that this will apply to future sessions.
2376 @deffn Command disable-command command
2377 Require special confirmation to execute @var{command} from now on, and
2378 (if the user confirms) alter the user's @file{.emacs} file so that this
2379 will apply to future sessions.
2382 @defvar disabled-command-hook
2383 This normal hook is run instead of a disabled command, when the user
2384 invokes the disabled command interactively. The hook functions can use
2385 @code{this-command-keys} to determine what the user typed to run the
2386 command, and thus find the command itself. @xref{Hooks}.
2388 By default, @code{disabled-command-hook} contains a function that asks
2389 the user whether to proceed.
2393 @node Command History
2394 @section Command History
2395 @cindex command history
2396 @cindex complex command
2397 @cindex history of commands
2399 The command loop keeps a history of the complex commands that have
2400 been executed, to make it convenient to repeat these commands. A
2401 @dfn{complex command} is one for which the interactive argument reading
2402 uses the minibuffer. This includes any @kbd{M-x} command, any
2403 @kbd{M-:} command, and any command whose @code{interactive}
2404 specification reads an argument from the minibuffer. Explicit use of
2405 the minibuffer during the execution of the command itself does not cause
2406 the command to be considered complex.
2408 @defvar command-history
2409 This variable's value is a list of recent complex commands, each
2410 represented as a form to evaluate. It continues to accumulate all
2411 complex commands for the duration of the editing session, but all but
2412 the first (most recent) thirty elements are deleted when a garbage
2413 collection takes place (@pxref{Garbage Collection}).
2418 @result{} ((switch-to-buffer "chistory.texi")
2419 (describe-key "^X^[")
2420 (visit-tags-table "~/emacs/src/")
2421 (find-tag "repeat-complex-command"))
2426 This history list is actually a special case of minibuffer history
2427 (@pxref{Minibuffer History}), with one special twist: the elements are
2428 expressions rather than strings.
2430 There are a number of commands devoted to the editing and recall of
2431 previous commands. The commands @code{repeat-complex-command}, and
2432 @code{list-command-history} are described in the user manual
2433 (@pxref{Repetition,,, sxemacs, The SXEmacs User's Manual}). Within the
2434 minibuffer, the history commands used are the same ones available in any
2438 @node Keyboard Macros
2439 @section Keyboard Macros
2440 @cindex keyboard macros
2442 A @dfn{keyboard macro} is a canned sequence of input events that can
2443 be considered a command and made the definition of a key. The Lisp
2444 representation of a keyboard macro is a string or vector containing the
2445 events. Don't confuse keyboard macros with Lisp macros
2448 @defun execute-kbd-macro macro &optional count
2449 This function executes @var{macro} as a sequence of events. If
2450 @var{macro} is a string or vector, then the events in it are executed
2451 exactly as if they had been input by the user. The sequence is
2452 @emph{not} expected to be a single key sequence; normally a keyboard
2453 macro definition consists of several key sequences concatenated.
2455 If @var{macro} is a symbol, then its function definition is used in
2456 place of @var{macro}. If that is another symbol, this process repeats.
2457 Eventually the result should be a string or vector. If the result is
2458 not a symbol, string, or vector, an error is signaled.
2460 The argument @var{count} is a repeat count; @var{macro} is executed that
2461 many times. If @var{count} is omitted or @code{nil}, @var{macro} is
2462 executed once. If it is 0, @var{macro} is executed over and over until it
2463 encounters an error or a failing search.
2466 @defvar executing-macro
2467 This variable contains the string or vector that defines the keyboard
2468 macro that is currently executing. It is @code{nil} if no macro is
2469 currently executing. A command can test this variable to behave
2470 differently when run from an executing macro. Do not set this variable
2474 @defvar defining-kbd-macro
2475 This variable indicates whether a keyboard macro is being defined. A
2476 command can test this variable to behave differently while a macro is
2477 being defined. The commands @code{start-kbd-macro} and
2478 @code{end-kbd-macro} set this variable---do not set it yourself.
2481 @defvar last-kbd-macro
2482 This variable is the definition of the most recently defined keyboard
2483 macro. Its value is a string or vector, or @code{nil}.
2486 @c Broke paragraph to prevent overfull hbox. --rjc 15mar92
2487 The commands are described in the user's manual (@pxref{Keyboard
2488 Macros,,, sxemacs, The SXEmacs User's Manual}).