Mercurial > emacs
changeset 6260:d8bf24309d5e
Initial revision
| author | Richard M. Stallman <rms@gnu.org> |
|---|---|
| date | Tue, 08 Mar 1994 22:47:20 +0000 |
| parents | 035ce1fb4969 |
| children | b838645548a0 |
| files | lispref/commands.texi |
| diffstat | 1 files changed, 2257 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/commands.texi Tue Mar 08 22:47:20 1994 +0000 @@ -0,0 +1,2257 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/commands +@node Command Loop, Keymaps, Minibuffers, Top +@chapter Command Loop +@cindex editor command loop +@cindex command loop + + When you run Emacs, it enters the @dfn{editor command loop} almost +immediately. This loop reads key sequences, executes their definitions, +and displays the results. In this chapter, we describe how these things +are done, and the subroutines that allow Lisp programs to do them. + +@menu +* Command Overview:: How the command loop reads commands. +* Defining Commands:: Specifying how a function should read arguments. +* Interactive Call:: Calling a command, so that it will read arguments. +* Command Loop Info:: Variables set by the command loop for you to examine. +* Input Events:: What input looks like when you read it. +* Reading Input:: How to read input events from the keyboard or mouse. +* Waiting:: Waiting for user input or elapsed time. +* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. +* Prefix Command Arguments:: How the commands to set prefix args work. +* Recursive Editing:: Entering a recursive edit, + and why you usually shouldn't. +* Disabling Commands:: How the command loop handles disabled commands. +* Command History:: How the command history is set up, and how accessed. +* Keyboard Macros:: How keyboard macros are implemented. +@end menu + +@node Command Overview +@section Command Loop Overview + + The first thing the command loop must do is read a key sequence, which +is a sequence of events that translates into a command. It does this by +calling the function @code{read-key-sequence}. Your Lisp code can also +call this function (@pxref{Key Sequence Input}). Lisp programs can also +do input at a lower level with @code{read-event} (@pxref{Reading One +Event}) or discard pending input with @code{discard-input} +(@pxref{Peeking and Discarding}). + + The key sequence is translated into a command through the currently +active keymaps. @xref{Key Lookup}, for information on how this is done. +The result should be a keyboard macro or an interactively callable +function. If the key is @kbd{M-x}, then it reads the name of another +command, which is used instead. This is done by the command +@code{execute-extended-command} (@pxref{Interactive Call}). + + Once the command is chosen, it must be executed, which includes +reading arguments to be given to it. This is done by calling +@code{command-execute} (@pxref{Interactive Call}). For commands written +in Lisp, the @code{interactive} specification says how to read the +arguments. This may use the prefix argument (@pxref{Prefix Command +Arguments}) or may read with prompting in the minibuffer +(@pxref{Minibuffers}). For example, the command @code{find-file} has an +@code{interactive} specification which says to read a file name using +the minibuffer. The command's function body does not use the +minibuffer; if you call this command from Lisp code as a function, you +must supply the file name string as an ordinary Lisp function argument. + + If the command is a string or vector (i.e., a keyboard macro) then +@code{execute-kbd-macro} is used to execute it. You can call this +function yourself (@pxref{Keyboard Macros}). + + If a command runs away, typing @kbd{C-g} terminates its execution +immediately. This is called @dfn{quitting} (@pxref{Quitting}). + +@defvar pre-command-hook +The editor command loop runs this normal hook before each command. +@end defvar + +@defvar post-command-hook +The editor command loop runs this normal hook after each command, +and also when the command loop is entered, or reentered after +an error or quit. +@end defvar + +@node Defining Commands +@section Defining Commands +@cindex defining commands +@cindex commands, defining +@cindex functions, making them interactive +@cindex interactive function + + A Lisp function becomes a command when its body contains, at top +level, a form which calls the special form @code{interactive}. This +form does nothing when actually executed, but its presence serves as a +flag to indicate that interactive calling is permitted. Its argument +controls the reading of arguments for an interactive call. + +@menu +* Using Interactive:: General rules for @code{interactive}. +* Interactive Codes:: The standard letter-codes for reading arguments + in various ways. +* Interactive Examples:: Examples of how to read interactive arguments. +@end menu + +@node Using Interactive +@subsection Using @code{interactive} + + This section describes how to write the @code{interactive} form that +makes a Lisp function an interactively-callable command. + +@defspec interactive arg-descriptor +@cindex argument descriptors +This special form declares that the function in which it appears is a +command, and that it may therefore be called interactively (via +@kbd{M-x} or by entering a key sequence bound to it). The argument +@var{arg-descriptor} declares the way the arguments to the command are +to be computed when the command is called interactively. + +A command may be called from Lisp programs like any other function, but +then the arguments are supplied by the caller and @var{arg-descriptor} +has no effect. + +The @code{interactive} form has its effect because the command loop +(actually, its subroutine @code{call-interactively}) scans through the +function definition looking for it, before calling the function. Once +the function is called, all its body forms including the +@code{interactive} form are executed, but at this time +@code{interactive} simply returns @code{nil} without even evaluating its +argument. +@end defspec + +There are three possibilities for the argument @var{arg-descriptor}: + +@itemize @bullet +@item +It may be omitted or @code{nil}; then the command is called with no +arguments. This leads quickly to an error if the command requires one +or more arguments. + +@item +It may be a Lisp expression that is not a string; then it should be a +form that is evaluated to get a list of arguments to pass to the +command. +@cindex argument evaluation form + +@item +@cindex argument prompt +It may be a string; then its contents should consist of a code character +followed by a prompt (which some code characters use and some ignore). +The prompt ends either with the end of the string or with a newline. +Here is a simple example: + +@smallexample +(interactive "bFrobnicate buffer: ") +@end smallexample + +@noindent +The code letter @samp{b} says to read the name of an existing buffer, +with completion. The buffer name is the sole argument passed to the +command. The rest of the string is a prompt. + +If there is a newline character in the string, it terminates the prompt. +If the string does not end there, then the rest of the string should +contain another code character and prompt, specifying another argument. +You can specify any number of arguments in this way. + +@c Emacs 19 feature +The prompt string can use @samp{%} to include previous argument values +in the prompt. This is done using @code{format} (@pxref{Formatting +Strings}). For example, here is how you could read the name of an +existing buffer followed by a new name to give to that buffer: + +@smallexample +@group +(interactive "bBuffer to rename: \nsRename buffer %s to: ") +@end group +@end smallexample + +@cindex @samp{*} in interactive +@kindex buffer-read-only +If the first character in the string is @samp{*}, then an error is +signaled if the buffer is read-only. + +@cindex @samp{@@} in interactive +@c Emacs 19 feature +If the first character in the string is @samp{@@}, and if the key +sequence used to invoke the command includes any mouse events, then +the window associated with the first of those events is selected +before the command is run. + +You can use @samp{*} and @samp{@@} together; the order does not matter. +Actual reading of arguments is controlled by the rest of the prompt +string (starting with the first character that is not @samp{*} or +@samp{@@}). +@end itemize + +@node Interactive Codes +@comment node-name, next, previous, up +@subsection Code Characters for @code{interactive} +@cindex interactive code description +@cindex description for interactive codes +@cindex codes, interactive, description of +@cindex characters for interactive codes + + The code character descriptions below contain a number of key words, +defined here as follows: + +@table @b +@item Completion +@cindex interactive completion +Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name +completion because the argument is read using @code{completing-read} +(@pxref{Completion}). @kbd{?} displays a list of possible completions. + +@item Existing +Require the name of an existing object. An invalid name is not +accepted; the commands to exit the minibuffer do not exit if the current +input is not valid. + +@item Default +@cindex default argument string +A default value of some sort is used if the user enters no text in the +minibuffer. The default depends on the code character. + +@item No I/O +This code letter computes an argument without reading any input. +Therefore, it does not use a prompt string, and any prompt string you +supply is ignored. + +@item Prompt +A prompt immediately follows the code character. The prompt ends either +with the end of the string or with a newline. + +@item Special +This code character is meaningful only at the beginning of the +interactive string, and it does not look for a prompt or a newline. +It is a single, isolated character. +@end table + +@cindex reading interactive arguments + Here are the code character descriptions for use with @code{interactive}: + +@table @samp +@item * +Signal an error if the current buffer is read-only. Special. + +@item @@ +Select the window mentioned in the first mouse event in the key +sequence that invoked this command. Special. + +@item a +A function name (i.e., a symbol which is @code{fboundp}). Existing, +Completion, Prompt. + +@item b +The name of an existing buffer. By default, uses the name of the +current buffer (@pxref{Buffers}). Existing, Completion, Default, +Prompt. + +@item B +A buffer name. The buffer need not exist. By default, uses the name of +a recently used buffer other than the current buffer. Completion, +Prompt. + +@item c +A character. The cursor does not move into the echo area. Prompt. + +@item C +A command name (i.e., a symbol satisfying @code{commandp}). Existing, +Completion, Prompt. + +@item d +@cindex position argument +The position of point as a number (@pxref{Point}). No I/O. + +@item D +A directory name. The default is the current default directory of the +current buffer, @code{default-directory} (@pxref{System Environment}). +Existing, Completion, Default, Prompt. + +@item e +The first or next mouse event in the key sequence that invoked the command. +More precisely, @samp{e} gets events which are lists, so you can look at +the data in the lists. @xref{Input Events}. No I/O. + +You can use @samp{e} more than once in a single command's interactive +specification. If the key sequence which invoked the command has +@var{n} events with parameters, the @var{n}th @samp{e} provides the +@var{n}th list event. Events which are not lists, such as function keys +and @sc{ASCII} characters, do not count where @samp{e} is concerned. + +Even though @samp{e} does not use a prompt string, you must follow +it with a newline if it is not the last code character. + +@item f +A file name of an existing file (@pxref{File Names}). The default +directory is @code{default-directory}. Existing, Completion, Default, +Prompt. + +@item F +A file name. The file need not exist. Completion, Default, Prompt. + +@item k +A key sequence (@pxref{Keymap Terminology}). This keeps reading events +until a command (or undefined command) is found in the current key +maps. The key sequence argument is represented as a string or vector. +The cursor does not move into the echo area. Prompt. + +This kind of input is used by commands such as @code{describe-key} and +@code{global-set-key}. + +@item m +@cindex marker argument +The position of the mark as a number. No I/O. + +@item n +A number read with the minibuffer. If the input is not a number, the +user is asked to try again. The prefix argument, if any, is not used. +Prompt. + +@item N +@cindex raw prefix argument usage +The raw prefix argument. If the prefix argument is @code{nil}, then a +number is read as with @kbd{n}. Requires a number. Prompt. + +@item p +@cindex numeric prefix argument usage +The numeric prefix argument. (Note that this @samp{p} is lower case.) +No I/O.@refill + +@item P +The raw prefix argument. (Note that this @samp{P} is upper case.) +@xref{Prefix Command Arguments}. No I/O.@refill + +@item r +@cindex region argument +Point and the mark, as two numeric arguments, smallest first. This is +the only code letter that specifies two successive arguments rather than +one. No I/O. + +@item s +Arbitrary text, read in the minibuffer and returned as a string +(@pxref{Text from Minibuffer}). Terminate the input with either +@key{LFD} or @key{RET}. (@kbd{C-q} may be used to include either of +these characters in the input.) Prompt. + +@item S +An interned symbol whose name is read in the minibuffer. Any whitespace +character terminates the input. (Use @kbd{C-q} to include whitespace in +the string.) Other characters that normally terminate a symbol (e.g., +parentheses and brackets) do not do so here. Prompt. + +@item v +A variable declared to be a user option (i.e., satisfying the predicate +@code{user-variable-p}). @xref{High-Level Completion}. Existing, +Completion, Prompt. + +@item x +A Lisp object specified in printed representation, terminated with a +@key{LFD} or @key{RET}. The object is not evaluated. @xref{Object from +Minibuffer}. Prompt. + +@item X +@cindex evaluated expression argument +A Lisp form is read as with @kbd{x}, but then evaluated so that its +value becomes the argument for the command. Prompt. +@end table + +@node Interactive Examples +@comment node-name, next, previous, up +@subsection Examples of Using @code{interactive} +@cindex examples of using @code{interactive} +@cindex @code{interactive}, examples of using + + Here are some examples of @code{interactive}: + +@example +@group +(defun foo1 () ; @r{@code{foo1} takes no arguments,} + (interactive) ; @r{just moves forward two words.} + (forward-word 2)) + @result{} foo1 +@end group + +@group +(defun foo2 (n) ; @r{@code{foo2} takes one argument,} + (interactive "p") ; @r{which is the numeric prefix.} + (forward-word (* 2 n))) + @result{} foo2 +@end group + +@group +(defun foo3 (n) ; @r{@code{foo3} takes one argument,} + (interactive "nCount:") ; @r{which is read with the Minibuffer.} + (forward-word (* 2 n))) + @result{} foo3 +@end group + +@group +(defun three-b (b1 b2 b3) + "Select three existing buffers. +Put them into three windows, selecting the last one." +@end group + (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:") + (delete-other-windows) + (split-window (selected-window) 8) + (switch-to-buffer b1) + (other-window 1) + (split-window (selected-window) 8) + (switch-to-buffer b2) + (other-window 1) + (switch-to-buffer b3)) + @result{} three-b +@group +(three-b "*scratch*" "declarations.texi" "*mail*") + @result{} nil +@end group +@end example + +@node Interactive Call +@section Interactive Call +@cindex interactive call + + After the command loop has translated a key sequence into a +definition, it invokes that definition using the function +@code{command-execute}. If the definition is a function that is a +command, @code{command-execute} calls @code{call-interactively}, which +reads the arguments and calls the command. You can also call these +functions yourself. + +@defun commandp object +Returns @code{t} if @var{object} is suitable for calling interactively; +that is, if @var{object} is a command. Otherwise, returns @code{nil}. + +The interactively callable objects include strings and vectors (treated +as keyboard macros), lambda expressions that contain a top-level call to +@code{interactive}, byte-code function objects, autoload objects that +are declared as interactive (non-@code{nil} fourth argument to +@code{autoload}), and some of the primitive functions. + +A symbol is @code{commandp} if its function definition is +@code{commandp}. + +Keys and keymaps are not commands. Rather, they are used to look up +commands (@pxref{Keymaps}). + +See @code{documentation} in @ref{Accessing Documentation}, for a +realistic example of using @code{commandp}. +@end defun + +@defun call-interactively command &optional record-flag +This function calls the interactively callable function @var{command}, +reading arguments according to its interactive calling specifications. +An error is signaled if @var{command} cannot be called interactively +(i.e., it is not a command). Note that keyboard macros (strings and +vectors) are not accepted, even though they are considered commands. + +@cindex record command history +If @var{record-flag} is non-@code{nil}, then this command and its +arguments are unconditionally added to the list @code{command-history}. +Otherwise, the command is added only if it uses the minibuffer to read +an argument. @xref{Command History}. +@end defun + +@defun command-execute command &optional record-flag +@cindex keyboard macro execution +This function executes @var{command} as an editing command. The +argument @var{command} must satisfy the @code{commandp} predicate; i.e., +it must be an interactively callable function or a string. + +A string or vector as @var{command} is executed with +@code{execute-kbd-macro}. A function is passed to +@code{call-interactively}, along with the optional @var{record-flag}. + +A symbol is handled by using its function definition in its place. A +symbol with an @code{autoload} definition counts as a command if it was +declared to stand for an interactively callable function. Such a +definition is handled by loading the specified library and then +rechecking the definition of the symbol. +@end defun + +@deffn Command execute-extended-command prefix-argument +@cindex read command name +This function reads a command name from the minibuffer using +@code{completing-read} (@pxref{Completion}). Then it uses +@code{command-execute} to call the specified command. Whatever that +command returns becomes the value of @code{execute-extended-command}. + +@cindex execute with prefix argument +If the command asks for a prefix argument, the value +@var{prefix-argument} is supplied. If @code{execute-extended-command} +is called interactively, the current raw prefix argument is used for +@var{prefix-argument}, and thus passed on to whatever command is run. + +@c !!! Should this be @kindex? +@cindex @kbd{M-x} +@code{execute-extended-command} is the normal definition of @kbd{M-x}, +so it uses the string @w{@samp{M-x }} as a prompt. (It would be better +to take the prompt from the events used to invoke +@code{execute-extended-command}, but that is painful to implement.) A +description of the value of the prefix argument, if any, also becomes +part of the prompt. + +@example +@group +(execute-extended-command 1) +---------- Buffer: Minibuffer ---------- +M-x forward-word RET +---------- Buffer: Minibuffer ---------- + @result{} t +@end group +@end example +@end deffn + +@defun interactive-p +This function returns @code{t} if the containing function (the one that +called @code{interactive-p}) was called interactively, with the function +@code{call-interactively}. (It makes no difference whether +@code{call-interactively} was called from Lisp or directly from the +editor command loop.) Note that if the containing function was called +by Lisp evaluation (or with @code{apply} or @code{funcall}), then it was +not called interactively. + +The usual application of @code{interactive-p} is for deciding whether to +print an informative message. As a special exception, +@code{interactive-p} returns @code{nil} whenever a keyboard macro is +being run. This is to suppress the informative messages and speed +execution of the macro. + +For example: + +@example +@group +(defun foo () + (interactive) + (and (interactive-p) + (message "foo"))) + @result{} foo +@end group + +@group +(defun bar () + (interactive) + (setq foobar (list (foo) (interactive-p)))) + @result{} bar +@end group + +@group +;; @r{Type @kbd{M-x foo}.} + @print{} foo +@end group + +@group +;; @r{Type @kbd{M-x bar}.} +;; @r{This does not print anything.} +@end group + +@group +foobar + @result{} (nil t) +@end group +@end example +@end defun + +@node Command Loop Info +@comment node-name, next, previous, up +@section Information from the Command Loop + +The editor command loop sets several Lisp variables to keep status +records for itself and for commands that are run. + +@defvar last-command +This variable records the name of the previous command executed by the +command loop (the one before the current command). Normally the value +is a symbol with a function definition, but this is not guaranteed. + +The value is set by copying the value of @code{this-command} when a +command returns to the command loop, except when the command specifies a +prefix argument for the following command. +@end defvar + +@defvar this-command +@cindex current command +This variable records the name of the command now being executed by +the editor command loop. Like @code{last-command}, it is normally a symbol +with a function definition. + +This variable is set by the command loop just before the command is run, +and its value is copied into @code{last-command} when the command +finishes (unless the command specifies a prefix argument for the +following command). + +@cindex kill command repetition +Some commands change the value of this variable during their execution, +simply as a flag for whatever command runs next. In particular, the +functions that kill text set @code{this-command} to @code{kill-region} +so that any kill commands immediately following will know to append the +killed text to the previous kill. +@end defvar + +If you do not want a particular command to be recognized as the previous +command in the case where it got an error, you must code that command to +prevent this. One way is to set @code{this-command} to @code{t} at the +beginning of the command, and set @code{this-command} back to its proper +value at the end, like this: + +@example +(defun foo (args@dots{}) + (interactive @dots{}) + (let ((old-this-command this-command)) + (setq this-command t) + @r{@dots{}do the work@dots{}} + (setq this-command old-this-command))) +@end example + +@defun this-command-keys +This function returns a string or vector containing the key sequence +that invoked the present command, plus any previous commands that +generated the prefix argument for this command. The value is a string +if all those events were characters. @xref{Input Events}. + +@example +@group +(this-command-keys) +;; @r{Now type @kbd{C-u C-x C-e}.} + @result{} "^U^X^E" +@end group +@end example +@end defun + +@defvar last-nonmenu-event +This variable holds the last input event read as part of a key +sequence, aside from events resulting from mouse menus. + +One use of this variable is to figure out a good default location to +pop up another menu. +@end defvar + +@defvar last-command-event +@defvarx last-command-char +This variable is set to the last input event that was read by the +command loop as part of a command. The principal use of this variable +is in @code{self-insert-command}, which uses it to decide which +character to insert. + +@example +@group +last-command-char +;; @r{Now type @kbd{C-u C-x C-e}.} + @result{} 5 +@end group +@end example + +@noindent +The value is 5 because that is the @sc{ASCII} code for @kbd{C-e}. + +The alias @code{last-command-char} exists for compatibility with +Emacs version 18. +@end defvar + +@c Emacs 19 feature +@defvar last-event-frame +This variable records which frame the last input event was directed to. +Usually this is the frame that was selected when the event was +generated, but if that frame has redirected input focus to another +frame, the value is the frame to which the event was redirected. +@xref{Input Focus}. +@end defvar + +@defvar echo-keystrokes +This variable determines how much time should elapse before command +characters echo. Its value must be an integer, which specifies the +number of seconds to wait before echoing. If the user types a prefix +key (say @kbd{C-x}) and then delays this many seconds before continuing, +the key @kbd{C-x} is echoed in the echo area. Any subsequent characters +in the same command will be echoed as well. + +If the value is zero, then command input is not echoed. +@end defvar + +@node Input Events +@section Input Events +@cindex events +@cindex input events + +The Emacs command loop reads a sequence of @dfn{input events} that +represent keyboard or mouse activity. The events for keyboard activity +are characters or symbols; mouse events are always lists. This section +describes the representation and meaning of input events in detail. + +A command invoked using events that are lists can get the full values of +these events using the @samp{e} interactive code. @xref{Interactive +Codes}. + +A key sequence that starts with a mouse event is read using the keymaps +of the buffer in the window that the mouse was in, not the current +buffer. This does not imply that clicking in a window selects that +window or its buffer---that is entirely under the control of the command +binding of the key sequence. + +@defun eventp object +This function returns non-@code{nil} if @var{event} is an input event. +@end defun + +@menu +* Keyboard Events:: Ordinary characters--keys with symbols on them. +* Function Keys:: Function keys--keys with names, not symbols. +* Click Events:: Pushing and releasing a mouse button. +* Drag Events:: Moving the mouse before releasing the button. +* Button-Down Events:: A button was pushed and not yet released. +* Repeat Events:: Double and triple click (or drag, or down). +* Motion Events:: Just moving the mouse, not pushing a button. +* Focus Events:: Moving the mouse between frames. +* Event Examples:: Examples of the lists for mouse events. +* Classifying Events:: Finding the modifier keys in an event symbol. + Event types. +* Accessing Events:: Functions to extract info from events. +* Strings of Events:: Special considerations for putting + keyboard character events in a string. +@end menu + +@node Keyboard Events +@subsection Keyboard Events + +There are two kinds of input you can get from the keyboard: ordinary +keys, and function keys. Ordinary keys correspond to characters; the +events they generate are represented in Lisp as characters. In Emacs +versions 18 and earlier, characters were the only events. + +@cindex modifier bits (of input character) +@cindex basic code (of input character) +An input character event consists of a @dfn{basic code} between 0 and +255, plus any or all of these @dfn{modifier bits}: + +@table @asis +@item meta +The 2**23 bit in the character code indicates a character +typed with the meta key held down. + +@item control +The 2**22 bit in the character code indicates a non-@sc{ASCII} +control character. + +@sc{ASCII} control characters such as @kbd{C-a} have special basic +codes of their own, so Emacs needs no special bit to indicate them. +Thus, the code for @kbd{C-a} is just 1. + +But if you type a control combination not in @sc{ASCII}, such as +@kbd{%} with the control key, the numeric value you get is the code +for @kbd{%} plus 2**22 (assuming the terminal supports non-@sc{ASCII} +control characters). + +@item shift +The 2**21 bit in the character code indicates an @sc{ASCII} control +character typed with the shift key held down. + +For letters, the basic code indicates upper versus lower case; for +digits and punctuation, the shift key selects an entirely different +character with a different basic code. In order to keep within +the @sc{ASCII} character set whenever possible, Emacs avoids using +the 2**21 bit for those characters. + +However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from +@kbd{C-A}, so Emacs uses the 2**21 bit in @kbd{C-A} and not in +@kbd{C-a}. + +@item hyper +The 2**20 bit in the character code indicates a character +typed with the hyper key held down. + +@item super +The 2**19 bit in the character code indicates a character +typed with the super key held down. + +@item alt +The 2**18 bit in the character code indicates a character typed with +the alt key held down. (On some terminals, the key labeled @key{ALT} +is actually the meta key.) +@end table + + In the future, Emacs may support a larger range of basic codes. We +may also move the modifier bits to larger bit numbers. Therefore, you +should avoid mentioning specific bit numbers in your program. +Instead, the way to test the modifier bits of a character is with the +function @code{event-modifiers} (@pxref{Classifying Events}). + +@node Function Keys +@subsection Function Keys + +@cindex function keys +Most keyboards also have @dfn{function keys}---keys which have names or +symbols that are not characters. Function keys are represented in Lisp +as symbols; the symbol's name is the function key's label. For example, +pressing a key labeled @key{F1} places the symbol @code{f1} in the input +stream. + +For all keyboard events, the event type (which classifies the event for +key lookup purposes) is identical to the event---it is the character or +the symbol. @xref{Classifying Events}. + +Here are a few special cases in the symbol naming convention for +function keys: + +@table @asis +@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete} +These keys correspond to common @sc{ASCII} control characters that have +special keys on most keyboards. + +In @sc{ASCII}, @kbd{C-i} and @key{TAB} are the same character. Emacs +lets you distinguish them if you wish, by returning the former as the +integer 9, and the latter as the symbol @code{tab}. + +Most of the time, it's not useful to distinguish the two. So normally +@code{function-key-map} is set up to map @code{tab} into 9. Thus, a +key binding for character code 9 also applies to @code{tab}. Likewise +for the other symbols in this group. The function @code{read-char} +also converts these events into characters. + +In @sc{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace} +converts into the character code 127 (@key{DEL}), not into code 8 +(@key{BS}). This is what most users prefer. + +@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{} +Keypad keys (to the right of the regular keyboard). +@item @code{kp-0}, @code{kp-1}, @dots{} +Keypad keys with digits. +@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} +Keypad PF keys. +@item @code{left}, @code{up}, @code{right}, @code{down} +Cursor arrow keys +@end table + +You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER}, +@key{SUPER}, @key{ALT} and @key{SHIFT} with function keys. The way +to represent them is with prefixes in the symbol name: + +@table @samp +@item A- +The alt modifier. +@item C- +The control modifier. +@item H- +The hyper modifier. +@item M- +The meta modifier. +@item S- +The shift modifier. +@item s- +The super modifier. +@end table + +Thus, the symbol for the key @key{F3} with @key{META} held down is +@kbd{M-@key{F3}}. When you use more than one prefix, we recommend you +write them in alphabetical order (though the order does not matter in +arguments to the key-binding lookup and modification functions). + +@node Click Events +@subsection Click Events +@cindex click event +@cindex mouse click event + +When the user presses a mouse button and releases it at the same +location, that generates a @dfn{click} event. Mouse click events have +this form: + +@example +(@var{event-type} + (@var{window} @var{buffer-pos} + (@var{x} . @var{y}) @var{timestamp}) + @var{click-count}) +@end example + +Here is what the elements normally mean: + +@table @var +@item event-type +This is a symbol that indicates which mouse button was used. It is +one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the +buttons are numbered numbered left to right. + +You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-}, +@samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift +and super, just as you would with function keys. + +This symbol also serves as the event type of the event. Key bindings +describe events by their types; thus, if there is a key binding for +@code{mouse-1}, that binding would apply to all events whose +@var{event-type} is @code{mouse-1}. + +@item window +This is the window in which the click occurred. + +@item x +@itemx y +These are the pixel-based coordinates of the click, relative to the top +left corner of @var{window}, which is @code{(0 . 0)}. + +@item buffer-pos +This is the buffer position of the character clicked on. + +@item timestamp +This is the time at which the event occurred, in milliseconds. (Since +this value wraps around the entire range of Emacs Lisp integers in about +five hours, it is useful only for relating the times of nearby events.) + +@item click-count +This is the number of rapid repeated presses so far of the same mouse +button. @xref{Repeat Events}. +@end table + +The meanings of @var{buffer-pos}, @var{row} and @var{column} are +somewhat different when the event location is in a special part of the +screen, such as the mode line or a scroll bar. + +If the location is in a scroll bar, then @var{buffer-pos} is the symbol +@code{vertical-scroll-bar} or @code{horizontal-scroll-bar}, and the pair +@code{(@var{x} . @var{y})} is replaced with a pair @code{(@var{portion} +. @var{whole})}, where @var{portion} is the distance of the click from +the top or left end of the scroll bar, and @var{whole} is the length of +the entire scroll bar. + +If the position is on a mode line or the vertical line separating +@var{window} from its neighbor to the right, then @var{buffer-pos} is +the symbol @code{mode-line} or @code{vertical-line}. For the mode line, +@var{row} does not have meaningful data. For the vertical line, +@var{column} does not have meaningful data. + +@var{buffer-pos} may be a list containing a symbol (one of the symbols +listed above) instead of just the symbol. This is what happens after +the imaginary prefix keys for these events are inserted into the input +stream. @xref{Key Sequence Input}. + +@node Drag Events +@subsection Drag Events +@cindex drag event +@cindex mouse drag event + +With Emacs, you can have a drag event without even changing your +clothes. A @dfn{drag event} happens every time the user presses a mouse +button and then moves the mouse to a different character position before +releasing the button. Like all mouse events, drag events are +represented in Lisp as lists. The lists record both the starting mouse +position and the final position, like this: + +@example +(@var{event-type} + (@var{window1} @var{buffer-pos1} + (@var{x1} . @var{y1}) @var{timestamp1}) + (@var{window2} @var{buffer-pos2} + (@var{x2} . @var{y2}) @var{timestamp2}) + @var{click-count}) +@end example + +For a drag event, the name of the symbol @var{event-type} contains the +prefix @samp{drag-}. The second and third elements of the event give +the starting and ending position of the drag. Aside from that, the data +have the same meanings as in a click event (@pxref{Click Events}). You +can access the second element of any mouse event in the same way, with +no need to distinguish drag events from others. + +The @samp{drag-} prefix follows the modifier key prefixes such as +@samp{C-} and @samp{M-}. + +If @code{read-key-sequence} receives a drag event which has no key +binding, and the corresponding click event does have a binding, it +changes the drag event into a click event at the drag's starting +position. This means that you don't have to distinguish between click +and drag events unless you want to. + +@node Button-Down Events +@subsection Button-Down Events +@cindex button-down event + +Click and drag events happen when the user releases a mouse button. +They cannot happen earlier, because there is no way to distinguish a +click from a drag until the button is released. + +If you want to take action as soon as a button is pressed, you need to +handle @dfn{button-down} events.@footnote{Button-down is the +conservative antithesis of drag.}. These occur as soon as a button is +pressed. They are represented by lists which look exactly like click +events (@pxref{Click Events}), except that the name of @var{event-type} +contains the prefix @samp{down-}. The @samp{down-} prefix follows the +modifier key prefixes such as @samp{C-} and @samp{M-}. + +The function @code{read-key-sequence}, and the Emacs command loop, +ignore any button-down events that don't have command bindings. This +means that you need not worry about defining button-down events unless +you want them to do something. The usual reason to define a button-down +event is so that you can track mouse motion (by reading motion events) +until the button is released. +@ifinfo +@xref{Motion Events}. +@end ifinfo + +@node Repeat Events +@subsection Repeat Events +@cindex repeat events +@cindex double-click events +@cindex triple-click events + +If you press the same mouse button more than once in quick succession +without moving the mouse, Emacs uses special @dfn{repeat} mouse events +for the second and subsequent presses. + +The most common repeat events are @dfn{double-click} events. Emacs +generates a double-click event when you click a button twice; the event +happens when you release the button (as is normal for all click +events). + +The event type of a double-click event contains the prefix +@code{double}. Thus, a double click on the second mouse button with +@key{meta} held down comes to the Lisp program as +@code{M-double-mouse-2}. If a double-click event has no binding, the +binding of the corresponding ordinary click event is used to execute +it. Thus, you need not pay attention to the double click feature +unless you really want to. + +When the user performs a double click, Emacs generates first an ordinary +click event, and then a double-click event. Therefore, the command +binding of the double click event must be written to assume that the +single-click command has already run. It must produce the desired +results of a double click, starting from the results of a single click. + +This means that it is most convenient to give double clicks a meaning +that somehow ``builds on'' the meaning of a single click. This is what +user interface experts recommend that double clicks should do. + +If you click a button, then press it down again and start moving the +mouse with the button held down, then you get a @dfn{double-drag} event +when you ultimately release the button. Its event type contains +@samp{double-drag} instead of just @samp{drag}. If a double-drag event +has no binding, Emacs looks for an alternate binding as if the event +were an ordinary click. + +Before the double-click or double-drag event, Emacs generates a +@dfn{double-down} event when the button is pressed down for the second +time. Its event type contains @samp{double-down} instead of just +@samp{down}. If a double-down event has no binding, Emacs looks for an +alternate binding as if the event were an ordinary button-down event. +If it finds no binding that way either, the double-down event is ignored. + +To summarize, when you click a button and then press it again right +away, Emacs generates a double-down event, followed by either a +double-click or a double-drag. + +If you click a button twice and then press it again, all in quick +succession, Emacs generates a @dfn{triple-down} event, followed by +either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of +these events contain @samp{triple} instead of @samp{double}. If any +triple event has no binding, Emacs uses the binding that it would use +for the corresponding double event. + +If you click a button three or more times and then press it again, +the events for the presses beyond the third are all triple events. +Emacs does not have quadruple, quintuple, etc. events as separate +event types. However, you can look at the event list to find out +precisely how many times the button was pressed. + +@defun event-click-count event +This function returns the number of consecutive button presses that led +up to @var{event}. If @var{event} is a double-down, double-click or +double-drag event, the value is 2. If @var{event} is a triple event, +the value is 3 or greater. If @var{event} is an ordinary mouse event +(not a repeat event), the value is 1. +@end defun + +@defvar double-click-time +To count as double- and triple-clicks, mouse clicks must be at the same +location as the first click, and the number of milliseconds between the +first release and the second must be less than the value of +@code{double-click-time}. Setting @code{double-click-time} to +@code{nil} disables multi-click detection entirely. Setting it to +@code{t} removes the time limit; Emacs then detects multi-clicks by +position only. +@end defvar + +@node Motion Events +@subsection Motion Events +@cindex motion event +@cindex mouse motion events + +Emacs sometimes generates @dfn{mouse motion} events to describe motion +of the mouse without any button activity. Mouse motion events are +represented by lists that look like this: + +@example +(mouse-movement + (@var{window} @var{buffer-pos} + (@var{x} . @var{y}) @var{timestamp})) +@end example + +The second element of the list describes the current position of the +mouse, just as in a click event (@pxref{Click Events}). + +The special form @code{track-mouse} enables generation of motion events +within its body. Outside of @code{track-mouse} forms, Emacs does not +generate events for mere motion of the mouse, and these events do not +appear. + +@defspec track-mouse body@dots{} +This special form executes @var{body}, with generation of mouse motion +events enabled. Typically @var{body} would use @code{read-event} +to read the motion events and modify the display accordingly. + +When the user releases the button, that generates a click event. +Normally @var{body} should return when it sees the click event, and +discard the event. +@end defspec + +@node Focus Events +@subsection Focus Events +@cindex focus event + +Window systems provide general ways for the user to control which window +gets keyboard input. This choice of window is called the @dfn{focus}. +When the user does something to switch between Emacs frames, that +generates a @dfn{focus event}. The normal definition of a focus event, +in the global keymap, is to select a new frame within Emacs, as the user +would expect. @xref{Input Focus}. + +Focus events are represented in Lisp as lists that look like this: + +@example +(switch-frame @var{new-frame}) +@end example + +@noindent +where @var{new-frame} is the frame switched to. + +In X windows, most window managers are set up so that just moving the +mouse into a window is enough to set the focus there. Emacs appears to +do this, because it changes the cursor to solid in the new frame. +However, there is no need for the Lisp program to know about the focus +change until some other kind of input arrives. So Emacs generates the +focus event only when the user actually types a keyboard key or presses +a mouse button in the new frame; just moving the mouse between frames +does not generate a focus event. + +A focus event in the middle of a key sequence would garble the +sequence. So Emacs never generates a focus event in the middle of a key +sequence. If the user changes focus in the middle of a key +sequence---that is, after a prefix key---then Emacs reorders the events +so that the focus event comes either before or after the multi-event key +sequence, and not within it. + +@node Event Examples +@subsection Event Examples + +If the user presses and releases the left mouse button over the same +location, that generates a sequence of events like this: + +@smallexample +(down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320)) +(mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180)) +@end smallexample + +Or, while holding the control key down, the user might hold down the +second mouse button, and drag the mouse from one line to the next. +That produces two events, as shown here: + +@smallexample +(C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)) +(C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219) + (#<window 18 on NEWS> 3510 (0 . 28) -729648)) +@end smallexample + +Or, while holding down the meta and shift keys, the user might press the +second mouse button on the window's mode line, and then drag the mouse +into another window. That produces the following pair of events: + +@smallexample +(M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)) +(M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844) + (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3) + -453816)) +@end smallexample + +@node Classifying Events +@subsection Classifying Events +@cindex event type + + Every event has an @dfn{event type} which classifies the event for key +binding purposes. For a keyboard event, the event type equals the event +value; thus, the event type for a character is the character, and the +event type for a function key symbol is the symbol itself. For events +which are lists, the event type is the symbol in the @sc{car} of the +list. Thus, the event type is always a symbol or a character. + + Two events of the same type are equivalent where key bindings are +concerned; thus, they always run the same command. That does not +necessarily mean they do the same things, however, as some commands look +at the whole event to decide what to do. For example, some commands use +the location of a mouse event to decide what text to act on. + + Sometimes broader classifications of events are useful. For example, +you might want to ask whether an event involved the @key{META} key, +regardless of which other key or mouse button was used. + + The functions @code{event-modifiers} and @code{event-basic-type} are +provided to get such information conveniently. + +@defun event-modifiers event +This function returns a list of the modifiers that @var{event} has. +The modifiers are symbols; they include @code{shift}, @code{control}, +@code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition, +the property of a mouse event symbol always has one of @code{click}, +@code{drag}, and @code{down} among the modifiers. For example: + +@example +(event-modifiers ?a) + @result{} nil +(event-modifiers ?\C-a) + @result{} (control) +(event-modifiers ?\C-%) + @result{} (control) +(event-modifiers ?\C-\S-a) + @result{} (control shift) +(event-modifiers 'f5) + @result{} nil +(event-modifiers 's-f5) + @result{} (super) +(event-modifiers 'M-S-f5) + @result{} (meta shift) +(event-modifiers 'mouse-1) + @result{} (click) +(event-modifiers 'down-mouse-1) + @result{} (down) +@end example + +The modifiers list for a click event explicitly contains @code{click}, +but the event symbol name itself does not contain @samp{click}. +@end defun + +@defun event-basic-type event +This function returns the key or mouse button that @var{event} +describes, with all modifiers removed. For example: + +@example +(event-basic-type ?a) + @result{} 97 +(event-basic-type ?A) + @result{} 97 +(event-basic-type ?\C-a) + @result{} 97 +(event-basic-type ?\C-\S-a) + @result{} 97 +(event-basic-type 'f5) + @result{} f5 +(event-basic-type 's-f5) + @result{} f5 +(event-basic-type 'M-S-f5) + @result{} f5 +(event-basic-type 'down-mouse-1) + @result{} mouse-1 +@end example +@end defun + +@defun mouse-movement-p object +This function returns non-@code{nil} if @var{object} is a mouse movement +event. +@end defun + +@node Accessing Events +@subsection Accessing Events + + This section describes convenient functions for accessing the data in +an event which is a list. + + The following functions return the starting or ending position of a +mouse-button event. The position is a list of this form: + +@smallexample +(@var{window} @var{buffer-position} (@var{col} . @var{row}) @var{timestamp}) +@end smallexample + +@defun event-start event +This returns the starting position of @var{event}. + +If @var{event} is a click or button-down event, this returns the +location of the event. If @var{event} is a drag event, this returns the +drag's starting position. +@end defun + +@defun event-end event +This returns the ending position of @var{event}. + +If @var{event} is a drag event, this returns the position where the user +released the mouse button. If @var{event} is a click or button-down +event, the value is actually the starting position, which is the only +position such events have. +@end defun + + These four functions take a position-list as described above, and +return various parts of it. + +@defun posn-window position +Return the window that @var{position} is in. +@end defun + +@defun posn-point position +Return the buffer location in @var{position}. +@end defun + +@defun posn-x-y position +Return the pixel-based x and y coordinates column in @var{position}, as +a cons cell @code{(@var{x} . @var{y})}. +@end defun + +@defun posn-col-row position +Return the row and column (in units of characters) in @var{position}, as +a cons cell @code{(@var{col} . @var{row})}. These are computed from the +@var{x} and @var{y} values actually found in @var{position}. +@end defun + +@defun posn-timestamp position +Return the timestamp of @var{position}. +@end defun + +@defun scroll-bar-scale ratio total +This function multiples (in effect) @var{ratio} by @var{total}, +rounding the result to an integer. @var{ratio} is not a number, +but rather a pair @code{(@var{num} . @var{denom})}. + +This is handy for scaling a position on a scroll bar into a buffer +position. Here's how to do that: + +@example +(+ (point-min) + (scroll-bar-scale + (posn-col-row (event-start event)) + (- (point-max) (point-min)))) +@end example +@end defun + +@node Strings of Events +@subsection Putting Keyboard Events in Strings + + In most of the places where strings are used, we conceptualize the +string as containing text characters---the same kind of characters found +in buffers or files. Occasionally Lisp programs use strings which +conceptually contain keyboard characters; for example, they may be key +sequences or keyboard macro definitions. There are special rules for +how to put keyboard characters into a string, because they are not +limited to the range of 0 to 255 as text characters are. + + A keyboard character typed using the @key{META} key is called a +@dfn{meta character}. The numeric code for such an event includes the +2**23 bit; it does not even come close to fitting in a string. However, +earlier Emacs versions used a different representation for these +characters, which gave them codes in the range of 128 to 255. That did +fit in a string, and many Lisp programs contain string constants that +use @samp{\M-} to express meta characters, especially as the argument to +@code{define-key} and similar functions. + + We provide backward compatibility to run those programs with special +rules for how to put a keyboard character event in a string. Here are +the rules: + +@itemize @bullet +@item +If the keyboard event value is in the range of 0 to 127, it can go in the +string unchanged. + +@item +The meta variants of those events, with codes in the range of 2**23 to +2**23+127, can also go in the string, but you must change their numeric +values. You must set the 2**7 bit instead of the 2**23 bit, resulting +in a value between 128 and 255. + +@item +Other keyboard character events cannot fit in a string. This includes +keyboard events in the range of 128 to 255. +@end itemize + + Functions such as @code{read-key-sequence} that can construct strings +containing events follow these rules. + + When you use the read syntax @samp{\M-} in a string, it produces a +code in the range of 128 to 255---the same code that you get if you +modify the corresponding keyboard event to put it in the string. Thus, +meta events in strings work consistently regardless of how they get into +the strings. + + New programs can avoid dealing with these rules by using vectors +instead of strings for key sequences when there is any possibility that +these issues might arise. + + The reason we changed the representation of meta characters as +keyboard events is to make room for basic character codes beyond 127, +and support meta variants of such larger character codes. + +@node Reading Input +@section Reading Input + + The editor command loop reads keyboard input using the function +@code{read-key-sequence}, which uses @code{read-event}. These and other +functions for keyboard input are also available for use in Lisp +programs. See also @code{momentary-string-display} in @ref{Temporary +Displays}, and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, +for functions and variables for controlling terminal input modes and +debugging terminal input. + + For higher-level input facilities, see @ref{Minibuffers}. + +@menu +* Key Sequence Input:: How to read one key sequence. +* Reading One Event:: How to read just one event. +* Quoted Character Input:: Asking the user to specify a character. +* Peeking and Discarding:: How to reread or throw away input events. +@end menu + +@node Key Sequence Input +@subsection Key Sequence Input +@cindex key sequence input + + The command loop reads input a key sequence at a time, by calling +@code{read-key-sequence}. Lisp programs can also call this function; +for example, @code{describe-key} uses it to read the key to describe. + +@defun read-key-sequence prompt +@cindex key sequence +This function reads a key sequence and returns it as a string or +vector. It keeps reading events until it has accumulated a full key +sequence; that is, enough to specify a non-prefix command using the +currently active keymaps. + +If the events are all characters and all can fit in a string, then +@code{read-key-sequence} returns a string (@pxref{Strings of Events}). +Otherwise, it returns a vector, since a vector can hold all kinds of +events---characters, symbols, and lists. The elements of the string or +vector are the events in the key sequence. + +Quitting is suppressed inside @code{read-key-sequence}. In other words, +a @kbd{C-g} typed while reading with this function is treated like any +other character, and does not set @code{quit-flag}. @xref{Quitting}. + +The argument @var{prompt} is either a string to be displayed in the echo +area as a prompt, or @code{nil}, meaning not to display a prompt. + +In the example below, the prompt @samp{?} is displayed in the echo area, +and the user types @kbd{C-x C-f}. + +@example +(read-key-sequence "?") + +@group +---------- Echo Area ---------- +?@kbd{C-x C-f} +---------- Echo Area ---------- + + @result{} "^X^F" +@end group +@end example +@end defun + +@defvar num-input-keys +@c Emacs 19 feature +This variable's value is the number of key sequences processed so far in +this Emacs session. This includes key sequences read from the terminal +and key sequences read from keyboard macros being executed. +@end defvar + +@cindex upper case key sequence +@cindex downcasing in @code{lookup-key} +If an input character is an upper case letter and has no key binding, +but the lower case equivalent has one, then @code{read-key-sequence} +converts the character to lower case. Note that @code{lookup-key} does +not perform case conversion in this way. + +The function @code{read-key-sequence} also transforms some mouse events. +It converts unbound drag events into click events, and discards unbound +button-down events entirely. It also reshuffles focus events so that they +never appear in a key sequence with any other events. + +When mouse events occur in special parts of a window, such as a mode +line or a scroll bar, the event itself shows nothing special---only the +symbol that would normally represent that mouse button and modifier +keys. The information about the screen region is kept elsewhere in the +event---in the coordinates. But @code{read-key-sequence} translates +this information into imaginary prefix keys, all of which are symbols: +@code{mode-line}, @code{vertical-line}, @code{horizontal-scroll-bar} and +@code{vertical-scroll-bar}. + +For example, if you call @code{read-key-sequence} and then click the +mouse on the window's mode line, this is what happens: + +@smallexample +(read-key-sequence "Click on the mode line: ") + @result{} [mode-line + (mouse-1 + (#<window 6 on NEWS> mode-line + (40 . 63) 5959987))] +@end smallexample + +You can define meanings for mouse clicks in special window regions by +defining key sequences using these imaginary prefix keys. + +@node Reading One Event +@subsection Reading One Event + + The lowest level functions for command input are those which read a +single event. + +@defun read-event +This function reads and returns the next event of command input, waiting +if necessary until an event is available. Events can come directly from +the user or from a keyboard macro. + +The function @code{read-event} does not display any message to indicate +it is waiting for input; use @code{message} first, if you wish to +display one. If you have not displayed a message, @code{read-event} +does @dfn{prompting}: it displays descriptions of the events that led to +or were read by the current command. @xref{The Echo Area}. + +If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event} +moves the cursor temporarily to the echo area, to the end of any message +displayed there. Otherwise @code{read-event} does not move the cursor. +@end defun + +Here is what happens if you call @code{read-event} and then press the +right-arrow function key: + +@example +@group +(read-event) + @result{} right +@end group +@end example + +@defun read-char +This function reads and returns a character of command input. It +discards any events that are not characters until it gets a character. + +In the first example, the user types @kbd{1} (which is @sc{ASCII} code +49). The second example shows a keyboard macro definition that calls +@code{read-char} from the minibuffer. @code{read-char} reads the +keyboard macro's very next character, which is @kbd{1}. The value of +this function is displayed in the echo area by the command +@code{eval-expression}. + +@example +@group +(read-char) + @result{} 49 +@end group + +@group +(symbol-function 'foo) + @result{} "^[^[(read-char)^M1" +@end group +@group +(execute-kbd-macro foo) + @print{} 49 + @result{} nil +@end group +@end example +@end defun + +@node Quoted Character Input +@subsection Quoted Character Input +@cindex quoted character input + + You can use the function @code{read-quoted-char} when you want the user +to specify a character, and allow the user to specify a control or meta +character conveniently with quoting or as an octal character code. The +command @code{quoted-insert} calls this function. + +@defun read-quoted-char &optional prompt +@cindex octal character input +@cindex control characters, reading +@cindex nonprinting characters, reading +This function is like @code{read-char}, except that if the first +character read is an octal digit (0-7), it reads up to two more octal digits +(but stopping if a non-octal digit is found) and returns the +character represented by those digits as an octal number. + +Quitting is suppressed when the first character is read, so that the +user can enter a @kbd{C-g}. @xref{Quitting}. + +If @var{prompt} is supplied, it specifies a string for prompting the +user. The prompt string is always printed in the echo area and followed +by a single @samp{-}. + +In the following example, the user types in the octal number 177 (which +is 127 in decimal). + +@example +(read-quoted-char "What character") + +@group +---------- Echo Area ---------- +What character-@kbd{177} +---------- Echo Area ---------- + + @result{} 127 +@end group +@end example +@end defun + +@need 3000 + +@node Peeking and Discarding +@subsection Peeking and Discarding + +@defvar unread-command-events +@cindex next input +@cindex peeking at input +This variable holds a list of events waiting to be read as command +input. The events are used in the order they appear in the list. + +The variable is used because in some cases a function reads a event and +then decides not to use it. Storing the event in this variable causes +it to be processed normally by the command loop or when the functions to +read command input are called. + +@cindex prefix argument unreading +For example, the function that implements numeric prefix arguments reads +any number of digits. When it finds a non-digit event, it must unread +the event so that it can be read normally by the command loop. +Likewise, incremental search uses this feature to unread events it does +not recognize. +@end defvar + +@defvar unread-command-char +This variable holds a character to be read as command input. +A value of -1 means ``empty''. + +This variable is pretty much obsolete now that you can use +@code{unread-command-events} instead; it exists only to support programs +written for Emacs versions 18 and earlier. +@end defvar + +@defun listify-key-sequence key +This function converts the string or vector @var{key} to a list of +events which you can put in @code{unread-command-events}. Converting a +vector is simple, but converting a string is tricky because of the +special representation used for meta characters in a string +(@pxref{Strings of Events}). +@end defun + +@defun input-pending-p +@cindex waiting for command key input +This function determines whether any command input is currently +available to be read. It returns immediately, with value @code{t} if +there is input, @code{nil} otherwise. On rare occasions it may return +@code{t} when no input is available. +@end defun + +@defvar last-input-event +@defvarx last-input-char + This variable records the last terminal input event read, whether +as part of a command or explicitly by a Lisp program. + + In the example below, a character is read (the character @kbd{1}, +@sc{ASCII} code 49). It becomes the value of @code{last-input-char}, +while @kbd{C-e} (from the @kbd{C-x C-e} command used to evaluate this +expression) remains the value of @code{last-command-char}. + +@example +@group +(progn (print (read-char)) + (print last-command-char) + last-input-char) + @print{} 49 + @print{} 5 + @result{} 49 +@end group +@end example + +The alias @code{last-input-char} exists for compatibility with +Emacs version 18. +@end defvar + +@defun discard-input +@cindex flush input +@cindex discard input +@cindex terminate keyboard macro +This function discards the contents of the terminal input buffer and +cancels any keyboard macro that might be in the process of definition. +It returns @code{nil}. + +In the following example, the user may type a number of characters right +after starting the evaluation of the form. After the @code{sleep-for} +finishes sleeping, any characters that have been typed are discarded. + +@example +(progn (sleep-for 2) + (discard-input)) + @result{} nil +@end example +@end defun + +@node Waiting +@section Waiting for Elapsed Time or Input +@cindex pausing +@cindex waiting + + The waiting commands are designed to make Emacs wait for a certain +amount of time to pass or until there is input. For example, you may +wish to pause in the middle of a computation to allow the user time to +view the display. @code{sit-for} pauses and updates the screen, and +returns immediately if input comes in, while @code{sleep-for} pauses +without updating the screen. + +@defun sit-for seconds &optional millisec nodisp +This function performs redisplay (provided there is no pending input +from the user), then waits @var{seconds} seconds, or until input is +available. The result is @code{t} if @code{sit-for} waited the full +time with no input arriving (see @code{input-pending-p} in @ref{Peeking +and Discarding}). Otherwise, the value is @code{nil}. + +@c Emacs 19 feature ??? maybe not working yet +The optional argument @var{millisec} specifies an additional waiting +period measured in milliseconds. This adds to the period specified by +@var{seconds}. Not all operating systems support waiting periods other +than multiples of a second; on those that do not, you get an error if +you specify nonzero @var{millisec}. + +@cindex forcing redisplay +Redisplay is always preempted if input arrives, and does not happen at +all if input is available before it starts. Thus, there is no way to +force screen updating if there is pending input; however, if there is no +input pending, you can force an update with no delay by using +@code{(sit-for 0)}. + +If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not +redisplay, but it still returns as soon as input is available (or when +the timeout elapses). + +The usual purpose of @code{sit-for} is to give the user time to read +text that you display. +@end defun + +@defun sleep-for seconds &optional millisec +This function simply pauses for @var{seconds} seconds without updating +the display. It pays no attention to available input. It returns +@code{nil}. + +@c Emacs 19 feature ??? maybe not working yet +The optional argument @var{millisec} specifies an additional waiting +period measured in milliseconds. This adds to the period specified by +@var{seconds}. Not all operating systems support waiting periods other +than multiples of a second; on those that do not, you get an error if +you specify nonzero @var{millisec}. + +Use @code{sleep-for} when you wish to guarantee a delay. +@end defun + + @xref{Time of Day}, for functions to get the current time. + +@node Quitting +@section Quitting +@cindex @kbd{C-g} +@cindex quitting + + Typing @kbd{C-g} while the command loop has run a Lisp function causes +Emacs to @dfn{quit} whatever it is doing. This means that control +returns to the innermost active command loop. + + Typing @kbd{C-g} while the command loop is waiting for keyboard input +does not cause a quit; it acts as an ordinary input character. In the +simplest case, you cannot tell the difference, because @kbd{C-g} +normally runs the command @code{keyboard-quit}, whose effect is to quit. +However, when @kbd{C-g} follows a prefix key, the result is an undefined +key. The effect is to cancel the prefix key as well as any prefix +argument. + + In the minibuffer, @kbd{C-g} has a different definition: it aborts out +of the minibuffer. This means, in effect, that it exits the minibuffer +and then quits. (Simply quitting would return to the command loop +@emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit +directly when the command reader is reading input is so that its meaning +can be redefined in the minibuffer in this way. @kbd{C-g} following a +prefix key is not redefined in the minibuffer, and it has its normal +effect of canceling the prefix key and prefix argument. This too +would not be possible if @kbd{C-g} quit directly. + + @kbd{C-g} causes a quit by setting the variable @code{quit-flag} to a +non-@code{nil} value. Emacs checks this variable at appropriate times +and quits if it is not @code{nil}. Setting @code{quit-flag} +non-@code{nil} in any way thus causes a quit. + + At the level of C code, quits cannot happen just anywhere; only at the +special places which check @code{quit-flag}. The reason for this is +that quitting at other places might leave an inconsistency in Emacs's +internal state. Because quitting is delayed until a safe place, quitting +cannot make Emacs crash. + + Certain functions such as @code{read-key-sequence} or +@code{read-quoted-char} prevent quitting entirely even though they wait +for input. Instead of quitting, @kbd{C-g} serves as the requested +input. In the case of @code{read-key-sequence}, this serves to bring +about the special behavior of @kbd{C-g} in the command loop. In the +case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used +to quote a @kbd{C-g}. + + You can prevent quitting for a portion of a Lisp function by binding +the variable @code{inhibit-quit} to a non-@code{nil} value. Then, +although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the +usual result of this---a quit---is prevented. Eventually, +@code{inhibit-quit} will become @code{nil} again, such as when its +binding is unwound at the end of a @code{let} form. At that time, if +@code{quit-flag} is still non-@code{nil}, the requested quit happens +immediately. This behavior is ideal for a ``critical section'', where +you wish to make sure that quitting does not happen within that part of +the program. + +@cindex @code{read-quoted-char} quitting + In some functions (such as @code{read-quoted-char}), @kbd{C-g} is +handled in a special way which does not involve quitting. This is done +by reading the input with @code{inhibit-quit} bound to @code{t} and +setting @code{quit-flag} to @code{nil} before @code{inhibit-quit} +becomes @code{nil} again. This excerpt from the definition of +@code{read-quoted-char} shows how this is done; it also shows that +normal quitting is permitted after the first character of input. + +@example +(defun read-quoted-char (&optional prompt) + "@dots{}@var{documentation}@dots{}" + (let ((count 0) (code 0) char) + (while (< count 3) + (let ((inhibit-quit (zerop count)) + (help-form nil)) + (and prompt (message "%s-" prompt)) + (setq char (read-char)) + (if inhibit-quit (setq quit-flag nil))) + @dots{}) + (logand 255 code))) +@end example + +@defvar quit-flag +If this variable is non-@code{nil}, then Emacs quits immediately, +unless @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} sets +@code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}. +@end defvar + +@defvar inhibit-quit +This variable determines whether Emacs should quit when @code{quit-flag} +is set to a value other than @code{nil}. If @code{inhibit-quit} is +non-@code{nil}, then @code{quit-flag} has no special effect. +@end defvar + +@deffn Command keyboard-quit +This function signals the @code{quit} condition with @code{(signal 'quit +nil)}. This is the same thing that quitting does. (See @code{signal} +in @ref{Errors}.) +@end deffn + + You can specify a character other than @kbd{C-g} to use for quitting. +See the function @code{set-input-mode} in @ref{Terminal Input}. + +@node Prefix Command Arguments +@section Prefix Command Arguments +@cindex prefix argument +@cindex raw prefix argument +@cindex numeric prefix argument + + Most Emacs commands can use a @dfn{prefix argument}, a number +specified before the command itself. (Don't confuse prefix arguments +with prefix keys.) The prefix argument is represented by a value that +is always available (though it may be @code{nil}, meaning there is no +prefix argument). Each command may use the prefix argument or ignore +it. + + There are two representations of the prefix argument: @dfn{raw} and +@dfn{numeric}. The editor command loop uses the raw representation +internally, and so do the Lisp variables that store the information, but +commands can request either representation. + + Here are the possible values of a raw prefix argument: + +@itemize @bullet +@item +@code{nil}, meaning there is no prefix argument. Its numeric value is +1, but numerous commands make a distinction between @code{nil} and the +integer 1. + +@item +An integer, which stands for itself. + +@item +A list of one element, which is an integer. This form of prefix +argument results from one or a succession of @kbd{C-u}'s with no +digits. The numeric value is the integer in the list, but some +commands make a distinction between such a list and an integer alone. + +@item +The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was +typed, without following digits. The equivalent numeric value is +@minus{}1, but some commands make a distinction between the integer +@minus{}1 and the symbol @code{-}. +@end itemize + +The various possibilities may be illustrated by calling the following +function with various prefixes: + +@example +@group +(defun display-prefix (arg) + "Display the value of the raw prefix arg." + (interactive "P") + (message "%s" arg)) +@end group +@end example + +@noindent +Here are the results of calling @code{display-prefix} with various +raw prefix arguments: + +@example + M-x display-prefix @print{} nil + +C-u M-x display-prefix @print{} (4) + +C-u C-u M-x display-prefix @print{} (16) + +C-u 3 M-x display-prefix @print{} 3 + +M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)} + +C-u - M-x display-prefix @print{} - + +M- - M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)} + +C-u -7 M-x display-prefix @print{} -7 + +M- -7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)} +@end example + + Emacs uses two variables to store the prefix argument: +@code{prefix-arg} and @code{current-prefix-arg}. Commands such as +@code{universal-argument} that set up prefix arguments for other +commands store them in @code{prefix-arg}. In contrast, +@code{current-prefix-arg} conveys the prefix argument to the current +command, so setting it has no effect on the prefix arguments for future +commands. + + Normally, commands specify which representation to use for the prefix +argument, either numeric or raw, in the @code{interactive} declaration. +(@xref{Interactive Call}.) Alternatively, functions may look at the +value of the prefix argument directly in the variable +@code{current-prefix-arg}, but this is less clean. + + Do not call the functions @code{universal-argument}, +@code{digit-argument}, or @code{negative-argument} unless you intend to +let the user enter the prefix argument for the @emph{next} command. + +@deffn Command universal-argument +This command reads input and specifies a prefix argument for the +following command. Don't call this command yourself unless you know +what you are doing. +@end deffn + +@deffn Command digit-argument arg +This command adds to the prefix argument for the following command. The +argument @var{arg} is the raw prefix argument as it was before this +command; it is used to compute the updated prefix argument. Don't call +this command yourself unless you know what you are doing. +@end deffn + +@deffn Command negative-argument arg +This command adds to the numeric argument for the next command. The +argument @var{arg} is the raw prefix argument as it was before this +command; its value is negated to form the new prefix argument. Don't +call this command yourself unless you know what you are doing. +@end deffn + +@defun prefix-numeric-value arg +This function returns the numeric meaning of a valid raw prefix argument +value, @var{arg}. The argument may be a symbol, a number, or a list. +If it is @code{nil}, the value 1 is returned; if it is any other symbol, +the value @minus{}1 is returned. If it is a number, that number is +returned; if it is a list, the @sc{car} of that list (which should be a +number) is returned. +@end defun + +@defvar current-prefix-arg +This variable is the value of the raw prefix argument for the +@emph{current} command. Commands may examine it directly, but the usual +way to access it is with @code{(interactive "P")}. +@end defvar + +@defvar prefix-arg +The value of this variable is the raw prefix argument for the +@emph{next} editing command. Commands that specify prefix arguments for +the following command work by setting this variable. +@end defvar + +@node Recursive Editing +@section Recursive Editing +@cindex recursive command loop +@cindex recursive editing level +@cindex command loop, recursive + + The Emacs command loop is entered automatically when Emacs starts up. +This top-level invocation of the command loop is never exited until the +Emacs is killed. Lisp programs can also invoke the command loop. Since +this makes more than one activation of the command loop, we call it +@dfn{recursive editing}. A recursive editing level has the effect of +suspending whatever command invoked it and permitting the user to do +arbitrary editing before resuming that command. + + The commands available during recursive editing are the same ones +available in the top-level editing loop and defined in the keymaps. +Only a few special commands exit the recursive editing level; the others +return to the recursive editing level when finished. (The special +commands for exiting are always available, but do nothing when recursive +editing is not in progress.) + + All command loops, including recursive ones, set up all-purpose error +handlers so that an error in a command run from the command loop will +not exit the loop. + +@cindex minibuffer input + Minibuffer input is a special kind of recursive editing. It has a few +special wrinkles, such as enabling display of the minibuffer and the +minibuffer window, but fewer than you might suppose. Certain keys +behave differently in the minibuffer, but that is only because of the +minibuffer's local map; if you switch windows, you get the usual Emacs +commands. + +@cindex @code{throw} example +@kindex exit +@cindex exit recursive editing +@cindex aborting + To invoke a recursive editing level, call the function +@code{recursive-edit}. This function contains the command loop; it also +contains a call to @code{catch} with tag @code{exit}, which makes it +possible to exit the recursive editing level by throwing to @code{exit} +(@pxref{Catch and Throw}). If you throw a value other than @code{t}, +then @code{recursive-edit} returns normally to the function that called +it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. +Throwing a @code{t} value causes @code{recursive-edit} to quit, so that +control returns to the command loop one level up. This is called +@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}). + + Most applications should not use recursive editing, except as part of +using the minibuffer. Usually it is more convenient for the user if you +change the major mode of the current buffer temporarily to a special +major mode, which has a command to go back to the previous mode. (This +technique is used by the @kbd{w} command in Rmail.) Or, if you wish to +give the user different text to edit ``recursively'', create and select +a new buffer in a special mode. In this mode, define a command to +complete the processing and go back to the previous buffer. (The +@kbd{m} command in Rmail does this.) + + Recursive edits are useful in debugging. You can insert a call to +@code{debug} into a function definition as a sort of breakpoint, so that +you can look around when the function gets there. @code{debug} invokes +a recursive edit but also provides the other features of the debugger. + + Recursive editing levels are also used when you type @kbd{C-r} in +@code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}). + +@defun recursive-edit +@cindex suspend evaluation +This function invokes the editor command loop. It is called +automatically by the initialization of Emacs, to let the user begin +editing. When called from a Lisp program, it enters a recursive editing +level. + + In the following example, the function @code{simple-rec} first +advances point one word, then enters a recursive edit, printing out a +message in the echo area. The user can then do any editing desired, and +then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}. + +@example +(defun simple-rec () + (forward-word 1) + (message "Recursive edit in progress.") + (recursive-edit) + (forward-word 1)) + @result{} simple-rec +(simple-rec) + @result{} nil +@end example +@end defun + +@deffn Command exit-recursive-edit +This function exits from the innermost recursive edit (including +minibuffer input). Its definition is effectively @code{(throw 'exit +nil)}. +@end deffn + +@deffn Command abort-recursive-edit +This function aborts the command that requested the innermost recursive +edit (including minibuffer input), by signaling @code{quit} +after exiting the recursive edit. Its definition is effectively +@code{(throw 'exit t)}. @xref{Quitting}. +@end deffn + +@deffn Command top-level +This function exits all recursive editing levels; it does not return a +value, as it jumps completely out of any computation directly back to +the main command loop. +@end deffn + +@defun recursion-depth +This function returns the current depth of recursive edits. When no +recursive edit is active, it returns 0. +@end defun + +@node Disabling Commands +@section Disabling Commands +@cindex disabled command + + @dfn{Disabling a command} marks the command as requiring user +confirmation before it can be executed. Disabling is used for commands +which might be confusing to beginning users, to prevent them from using +the commands by accident. + +@kindex disabled + The low-level mechanism for disabling a command is to put a +non-@code{nil} @code{disabled} property on the Lisp symbol for the +command. These properties are normally set up by the user's +@file{.emacs} file with Lisp expressions such as this: + +@example +(put 'upcase-region 'disabled t) +@end example + +@noindent +For a few commands, these properties are present by default and may be +removed by the @file{.emacs} file. + + If the value of the @code{disabled} property is a string, that string +is included in the message printed when the command is used: + +@example +(put 'delete-region 'disabled + "Text deleted this way cannot be yanked back!\n") +@end example + + @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on +what happens when a disabled command is invoked interactively. +Disabling a command has no effect on calling it as a function from Lisp +programs. + +@deffn Command enable-command command +Allow @var{command} to be executed without special confirmation from now +on. The user's @file{.emacs} file is optionally altered so that this +will apply to future sessions. +@end deffn + +@deffn Command disable-command command +Require special confirmation to execute @var{command} from now on. The +user's @file{.emacs} file is optionally altered so that this will apply +to future sessions. +@end deffn + +@defvar disabled-command-hook +This variable is a normal hook that is run instead of a disabled command, +when the user runs the disabled command interactively. The hook functions +can use @code{this-command-keys} to determine what the user typed to run +the command, and thus find the command itself. + +By default, @code{disabled-command-hook} contains a function that asks +the user whether to proceed. +@end defvar + +@node Command History +@section Command History +@cindex command history +@cindex complex command +@cindex history of commands + + The command loop keeps a history of the complex commands that have +been executed, to make it convenient to repeat these commands. A +@dfn{complex command} is one for which the interactive argument reading +uses the minibuffer. This includes any @kbd{M-x} command, any +@kbd{M-ESC} command, and any command whose @code{interactive} +specification reads an argument from the minibuffer. Explicit use of +the minibuffer during the execution of the command itself does not cause +the command to be considered complex. + +@defvar command-history +This variable's value is a list of recent complex commands, each +represented as a form to evaluate. It continues to accumulate all +complex commands for the duration of the editing session, but all but +the first (most recent) thirty elements are deleted when a garbage +collection takes place (@pxref{Garbage Collection}). + +@example +@group +command-history +@result{} ((switch-to-buffer "chistory.texi") + (describe-key "^X^[") + (visit-tags-table "~/emacs/src/") + (find-tag "repeat-complex-command")) +@end group +@end example +@end defvar + + This history list is actually a special case of minibuffer history +(@pxref{Minibuffer History}), with one special twist: the elements are +expressions rather than strings. + + There are a number of commands devoted to the editing and recall of +previous commands. The commands @code{repeat-complex-command}, and +@code{list-command-history} are described in the user manual +(@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the +minibuffer, the history commands used are the same ones available in any +minibuffer. + +@node Keyboard Macros +@section Keyboard Macros +@cindex keyboard macros + + A @dfn{keyboard macro} is a canned sequence of input events that can +be considered a command and made the definition of a key. Don't confuse +keyboard macros with Lisp macros (@pxref{Macros}). + +@defun execute-kbd-macro macro &optional count +This function executes @var{macro} as a sequence of events. If +@var{macro} is a string or vector, then the events in it are executed +exactly as if they had been input by the user. The sequence is +@emph{not} expected to be a single key sequence; normally a keyboard +macro definition consists of several key sequences concatenated. + +If @var{macro} is a symbol, then its function definition is used in +place of @var{macro}. If that is another symbol, this process repeats. +Eventually the result should be a string or vector. If the result is +not a symbol, string, or vector, an error is signaled. + +The argument @var{count} is a repeat count; @var{macro} is executed that +many times. If @var{count} is omitted or @code{nil}, @var{macro} is +executed once. If it is 0, @var{macro} is executed over and over until it +encounters an error or a failing search. +@end defun + +@defvar last-kbd-macro +This variable is the definition of the most recently defined keyboard +macro. Its value is a string or vector, or @code{nil}. +@end defvar + +@defvar executing-macro +This variable contains the string or vector that defines the keyboard +macro that is currently executing. It is @code{nil} if no macro is +currently executing. +@end defvar + +@defvar defining-kbd-macro +This variable indicates whether a keyboard macro is being defined. It +is set to @code{t} by @code{start-kbd-macro}, and @code{nil} by +@code{end-kbd-macro}. You can use this variable to make a command +behave differently when run from a keyboard macro (perhaps indirectly by +calling @code{interactive-p}). However, do not set this variable +yourself. +@end defvar + +@ignore @c It's hard to make this format ok. + The user-level commands for defining, running and editing keyboard +macros include @code{call-last-kbd-macro}, @code{insert-kbd-macro}, +@code{start-kbd-macro}, @code{end-kbd-macro}, @code{kbd-macro-query}, +and @code{name-last-kbd-macro}. +@end ignore + +@c Broke paragraph to prevent overfull hbox. --rjc 15mar92 + The commands are described in the user's manual (@pxref{Keyboard +Macros,,, emacs, The GNU Emacs Manual}). +