@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
* Distinguish Interactive:: Making a command distinguish interactive calls.
* Command Loop Info:: Variables set by the command loop for you to examine.
* Adjusting Point:: Adjustment of point after a command.
-* Input Events:: What input looks like when you read it.
+* Input Events:: What input looks like when you read it.
* Reading Input:: How to read input events from the keyboard or mouse.
* Special Events:: Events processed immediately and individually.
* Waiting:: Waiting for user input or elapsed time.
command, which it then calls. This is done by the command
@code{execute-extended-command} (@pxref{Interactive Call}).
- To execute a command requires first reading the arguments for 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
+ Prior to executing the command, Emacs runs @code{undo-boundary} to
+create an undo boundary. @xref{Maintaining Undo}.
+
+ To execute a command, Emacs first reads its arguments 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 function body of @code{find-file} does not
+use the minibuffer, so if you call @code{find-file} as a function from
+Lisp code, 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
@cindex functions, making them interactive
@cindex interactive function
- A Lisp function becomes a command when its body contains, at top
-level, a form that calls the special form @code{interactive}, or if
-the function's symbol has an @code{interactive-form} property. 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.
+ The special form @code{interactive} turns a Lisp function into a
+command. The @code{interactive} form must be located at top-level in
+the function body (usually as the first form in the body), or in the
+@code{interactive-form} property of the function symbol. When the
+@code{interactive} form is located in the function body, it does
+nothing when actually executed. Its presence serves as a flag, which
+tells the Emacs command loop that the function can be called
+interactively. The argument of the @code{interactive} form controls
+the reading of arguments for an interactive call.
@menu
* Using Interactive:: General rules for @code{interactive}.
examine a command's @code{interactive} form.
@defspec interactive arg-descriptor
-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 how to compute the arguments to the
-command when the command is called interactively.
+This special form declares that a function 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
+how to compute the arguments to the command when the command is called
+interactively.
A command may be called from Lisp programs like any other function, but
then the caller supplies the arguments 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.
-
@cindex @code{interactive-form}, function property
-An interactive form can be added to a function post-facto via the
-@code{interactive-form} property of the function's symbol.
-@xref{Symbol Plists}.
+The @code{interactive} form must be located at top-level in the
+function body, or in the function symbol's @code{interactive-form}
+property (@pxref{Symbol Plists}). It has its effect because the
+command loop looks for it before calling the function
+(@pxref{Interactive Call}). Once the function is called, all its body
+forms are executed; at this time, if the @code{interactive} form
+occurs within the body, the form simply returns @code{nil} without
+even evaluating its argument.
+
+By convention, you should put the @code{interactive} form in the
+function body, as the first top-level form. If there is an
+@code{interactive} form in both the @code{interactive-form} symbol
+property and the function body, the former takes precedence. The
+@code{interactive-form} symbol property can be used to add an
+interactive form to an existing function, or change how its arguments
+are processed interactively, without redefining the function.
@end defspec
There are three possibilities for the argument @var{arg-descriptor}:
or more arguments.
@item
-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:
+It may be a string; its contents are a sequence of elements separated
+by newlines, one for each parameter@footnote{Some elements actually
+supply two parameters.}. Each element consists of a code character
+(@pxref{Interactive Codes}) optionally followed by a prompt (which
+some code characters use and some ignore). Here is an example:
@smallexample
-(interactive "bFrobnicate buffer: ")
+(interactive "P\nbFrobnicate 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.
+The code letter @samp{P} sets the command's first argument to the raw
+command prefix (@pxref{Prefix Command Arguments}). @samp{bFrobnicate
+buffer: } prompts the user with @samp{Frobnicate buffer: } to enter
+the name of an existing buffer, which becomes the second and final
+argument.
@c Emacs 19 feature
The prompt string can use @samp{%} to include previous argument values
@section Interactive Call
@cindex interactive call
- After the command loop has translated a key sequence into a command it
-invokes that command using the function @code{command-execute}. If the
-command is a function, @code{command-execute} calls
+ After the command loop has translated a key sequence into a command,
+it invokes that command using the function @code{command-execute}. If
+the command is a function, @code{command-execute} calls
@code{call-interactively}, which reads the arguments and calls the
command. You can also call these functions yourself.
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 made from such lambda
-expressions, autoload objects that are declared as interactive
-(non-@code{nil} fourth argument to @code{autoload}), and some of the
-primitive functions.
+Interactively-callable objects include strings and vectors (which are
+treated as keyboard macros), lambda expressions that contain a
+top-level @code{interactive} form (@pxref{Using Interactive}),
+byte-code function objects made from such lambda expressions, autoload
+objects that are declared as interactive (non-@code{nil} fourth
+argument to @code{autoload}), and some primitive functions.
-A symbol satisfies @code{commandp} if its function definition
+A symbol satisfies @code{commandp} if it has a non-@code{nil}
+@code{interactive-form} property, or if its function definition
satisfies @code{commandp}. Keys and keymaps are not commands.
Rather, they are used to look up commands (@pxref{Keymaps}).
The above method with the additional argument is usually best,
because it allows callers to say ``treat this call as interactive.''
-But you can also do the job in a simpler way by testing
-@code{called-interactively-p}.
+But you can also do the job by testing @code{called-interactively-p}.
-@defun called-interactively-p
+@defun called-interactively-p kind
This function returns @code{t} when the calling function was called
using @code{call-interactively}.
-If the containing function was called by Lisp evaluation (or with
-@code{apply} or @code{funcall}), then it was not called interactively.
+The argument @var{kind} should be either the symbol @code{interactive}
+or the symbol @code{any}. If it is @code{interactive}, then
+@code{called-interactively-p} returns @code{t} only if the call was
+made directly by the user---e.g., if the user typed a key sequence
+bound to the calling function, but @emph{not} if the user ran a
+keyboard macro that called the function (@pxref{Keyboard Macros}). If
+@var{kind} is @code{any}, @code{called-interactively-p} returns
+@code{t} for any kind of interactive call, including keyboard macros.
+
+If in doubt, use @code{any}; the only known proper use of
+@code{interactive} is if you need to decide whether to display a
+helpful message while a function is running.
+
+A function is never considered to be called interactively if it was
+called via Lisp evaluation (or with @code{apply} or @code{funcall}).
@end defun
- Here's an example of using @code{called-interactively-p}:
+@noindent
+Here is an example of using @code{called-interactively-p}:
@example
@group
(defun foo ()
(interactive)
- (when (called-interactively-p)
- (message "foo"))
- 'haha)
- @result{} foo
+ (when (called-interactively-p 'any)
+ (message "Interactive!")
+ 'foo-called-interactively))
@end group
@group
;; @r{Type @kbd{M-x foo}.}
- @print{} foo
+ @print{} Interactive!
@end group
@group
(foo)
- @result{} haha
+ @result{} nil
@end group
@end example
- Here is another example that contrasts direct and indirect
-calls to @code{called-interactively-p}.
+@noindent
+Here is another example that contrasts direct and indirect calls to
+@code{called-interactively-p}.
@example
@group
(defun bar ()
(interactive)
- (setq foobar (list (foo) (called-interactively-p))))
- @result{} bar
+ (message "%s" (list (foo) (called-interactively-p 'any))))
@end group
@group
;; @r{Type @kbd{M-x bar}.}
-;; @r{This does not display a message.}
-@end group
-
-@group
-foobar
- @result{} (nil t)
+ @print{} (nil t)
@end group
@end example
- If you want to treat commands run in keyboard macros just like calls
-from Lisp programs, test @code{interactive-p} instead of
-@code{called-interactively-p}.
-
-@defun interactive-p
-This function returns @code{t} if the containing function (the one
-whose code includes the call to @code{interactive-p}) was called in
-direct response to user input. This means that it was called with the
-function @code{call-interactively}, and that a keyboard macro is
-not running, and that Emacs is not running in batch mode.
-@end defun
-
@node Command Loop Info
@comment node-name, next, previous, up
@section Information from the Command Loop
argument for the following command.
This variable is always local to the current terminal and cannot be
-buffer-local. @xref{Multiple Displays}.
+buffer-local. @xref{Multiple Terminals}.
@end defvar
@defvar real-last-command
@noindent
The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
-The alias @code{last-command-char} exists for compatibility with
-Emacs version 18.
+The alias @code{last-command-char} is obsolete.
@end defvar
@c Emacs 19 feature
@end defun
@menu
-* Keyboard Events:: Ordinary characters--keys with symbols on them.
-* Function Keys:: Function keys--keys with names, not symbols.
+* Keyboard Events:: Ordinary characters--keys with symbols on them.
+* Function Keys:: Function keys--keys with names, not symbols.
* Mouse Events:: Overview of mouse events.
-* 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.
+* 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.
+* Motion Events:: Just moving the mouse, not pushing a button.
+* Focus Events:: Moving the mouse between frames.
* Misc Events:: Other events the system can generate.
-* Event Examples:: Examples of the lists for mouse events.
-* Classifying Events:: Finding the modifier keys in an event symbol.
- Event types.
-* Accessing Mouse:: Functions to extract info from mouse events.
-* Accessing Scroll:: Functions to get info from scroll bar events.
+* Event Examples:: Examples of the lists for mouse events.
+* Classifying Events:: Finding the modifier keys in an event symbol.
+ Event types.
+* Accessing Mouse:: Functions to extract info from mouse events.
+* Accessing Scroll:: Functions to get info from scroll bar events.
* Strings of Events:: Special considerations for putting
- keyboard character events in a string.
+ keyboard character events in a string.
@end menu
@node Keyboard Events
latter as the symbol @code{tab}.
Most of the time, it's not useful to distinguish the two. So normally
-@code{function-key-map} (@pxref{Translation Keymaps}) is set up to map
-@code{tab} into 9. Thus, a key binding for character code 9 (the
-character @kbd{C-i}) also applies to @code{tab}. Likewise for the other
-symbols in this group. The function @code{read-char} likewise converts
-these events into characters.
+@code{local-function-key-map} (@pxref{Translation Keymaps}) is set up
+to map @code{tab} into 9. Thus, a key binding for character code 9
+(the character @kbd{C-i}) also applies to @code{tab}. Likewise for
+the other symbols in this group. The function @code{read-char}
+likewise converts these events into characters.
In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace}
converts into the character code 127 (@key{DEL}), not into code 8
@item @var{x}, @var{y}
These are the pixel coordinates of the click, relative to
the top left corner of @var{window}, which is @code{(0 . 0)}.
-For the mode or header line, @var{y} does not have meaningful data.
-For the vertical line, @var{x} does not have meaningful data.
+For a click on text, these are relative to the top left corner of
+the window's text area. For the mode or header line, they are
+relative to the top left window edge. For fringes, margins, and the
+vertical border, @var{x} does not have meaningful data. For fringes
+and margins, @var{y} is relative to the bottom edge of the header
+line.
@item @var{timestamp}
This is the time at which the event occurred, in milliseconds.
@item @var{col}, @var{row}
These are the actual coordinates of the glyph under the @var{x},
@var{y} position, possibly padded with default character width
-glyphs if @var{x} is beyond the last glyph on the line.
+glyphs if @var{x} is beyond the last glyph on the line. For clicks on
+the header or mode line, these are measured from the top left edge of
+the header or mode line. For clicks on the fringes and on the
+vertical border, these have no meaningful data. For clicks on the
+margins, @var{col} is measured from the left edge of the margin area
+and @var{row} is measured from the top of the margin area.
@item @var{image}
This is the image object on which the click occurred. It is either
These are the pixel width and height of @var{object} or, if this is
@code{nil}, those of the character glyph clicked on.
@end table
-
+
@sp 1
For mouse clicks on a scroll-bar, @var{position} has this form:
represented by lists that look like this:
@example
-(mouse-movement (POSITION))
+(mouse-movement POSITION)
@end example
The second element of the list describes the current position of the
@noindent
where @var{new-frame} is the frame switched to.
-Most X 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 a 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
+Some X window managers are set up so that just moving the mouse into a
+window is enough to set the focus there. Usually, there is no need
+for a Lisp program to know about the focus change until some other
+kind of input arrives. Emacs generates a 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
usual meaning is a kind of scroll or zoom.
The element @var{position} is a list describing the position of the
-event, in the same format as used in a mouse-click event.
+event, in the same format as used in a mouse-click event (@pxref{Click
+Events}).
+@vindex mouse-wheel-up-event
+@vindex mouse-wheel-down-event
This kind of event is generated only on some kinds of systems. On some
systems, @code{mouse-4} and @code{mouse-5} are used instead. For
portable code, use the variables @code{mouse-wheel-up-event} and
dropped onto an Emacs frame.
The element @var{position} is a list describing the position of the
-event, in the same format as used in a mouse-click event, and
-@var{files} is the list of file names that were dragged and dropped.
-The usual way to handle this event is by visiting these files.
+event, in the same format as used in a mouse-click event (@pxref{Click
+Events}), and @var{files} is the list of file names that were dragged
+and dropped. The usual way to handle this event is by visiting these
+files.
This kind of event is generated, at present, only on some kinds of
systems.
@end defun
@defun posn-col-row position
-Return the row and column (in units of the frame's default character
-height and width) of @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}.
+This function returns a cons cell @code{(@var{col} . @var{row})},
+containing the estimated column and row corresponding to buffer
+position @var{position}. The return value is given in units of the
+frame's default character width and height, as computed from the
+@var{x} and @var{y} values corresponding to @var{position}. (So, if
+the actual characters have non-default sizes, the actual row and
+column may differ from these computed values.)
+
+Note that @var{row} is counted from the top of the text area. If the
+window possesses a header line (@pxref{Header Lines}), it is
+@emph{not} counted as the first line.
@end defun
@defun posn-actual-col-row position
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.
+* Key Sequence Input:: How to read one key sequence.
+* Reading One Event:: How to read just one event.
* Event Mod:: How Emacs modifies events as they are read.
* Invoking the Input Method:: How reading an event uses the input method.
-* Quoted Character Input:: Asking the user to specify a character.
-* Event Input Misc:: How to reread or throw away input events.
+* Quoted Character Input:: Asking the user to specify a character.
+* Event Input Misc:: How to reread or throw away input events.
@end menu
@node Key Sequence Input
@vindex this-command-keys-shift-translated
When reading input results in such a @dfn{shift-translation}, Emacs
sets the variable @code{this-command-keys-shift-translated} to a
-non-nil value. Lisp programs can examine this variable if they need
-to modify their behavior when invoked by shift-translated keys. For
-example, the function @code{handle-shift-selection} examines the value
-of this variable to determine how to activate or deactivate the region
-(@pxref{The Mark, handle-shift-selection}).
+non-@code{nil} value. Lisp programs can examine this variable if they
+need to modify their behavior when invoked by shift-translated keys.
+For example, the function @code{handle-shift-selection} examines the
+value of this variable to determine how to activate or deactivate the
+region (@pxref{The Mark, handle-shift-selection}).
The function @code{read-key-sequence} also transforms some mouse events.
It converts unbound drag events into click events, and discards unbound
@cindex reading a single event
@cindex event, reading only one
- The lowest level functions for command input are those that read a
-single event.
-
-None of the three functions below suppresses quitting.
+ The lowest level functions for command input are @code{read-event},
+@code{read-char}, and @code{read-char-exclusive}.
@defun read-event &optional prompt inherit-input-method seconds
This function reads and returns the next event of command input, waiting
gets a character. The arguments work as in @code{read-event}.
@end defun
+ None of the above functions suppress quitting.
+
@defvar num-nonmacro-input-events
This variable holds the total number of input events received so far
from the terminal---not counting those generated by keyboard macros.
@end defvar
+ We emphasize that, unlike @code{read-key-sequence}, the functions
+@code{read-event}, @code{read-char}, and @code{read-char-exclusive} do
+not perform the translations described in @ref{Translation Keymaps}.
+If you wish to read a single key taking these translations into
+account, use the function @code{read-key}:
+
+@defun read-key &optional prompt
+This function reads a single key. It is ``intermediate'' between
+@code{read-key-sequence} and @code{read-event}. Unlike the former, it
+reads a single key, not a key sequence. Unlike the latter, it does
+not return a raw event, but decodes and translates the user input
+according to @code{input-decode-map}, @code{local-function-key-map},
+and @code{key-translation-map} (@pxref{Translation Keymaps}).
+
+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.
+@end defun
+
@node Event Mod
@subsection Modifying and Translating Input Events
@end defvar
@defvar keyboard-translate-table
-This variable is the translate table for keyboard characters. It lets
-you reshuffle the keys on the keyboard without changing any command
-bindings. Its value is normally a char-table, or else @code{nil}.
-(It can also be a string or vector, but this is considered obsolete.)
+This terminal-local variable is the translate table for keyboard
+characters. It lets you reshuffle the keys on the keyboard without
+changing any command bindings. Its value is normally a char-table, or
+else @code{nil}. (It can also be a string or vector, but this is
+considered obsolete.)
If @code{keyboard-translate-table} is a char-table
(@pxref{Char-Tables}), then each character read from the keyboard is
translation.
Note also that this translation is done before the characters are
-supplied to input methods (@pxref{Input Methods}).
+supplied to input methods (@pxref{Input Methods}). Use
+@code{translation-table-for-input} (@pxref{Translation of Characters}),
+if you want to translate characters after input methods operate.
@end defvar
@defun keyboard-translate from to
@end group
@end example
-The alias @code{last-input-char} exists for compatibility with
-Emacs version 18.
+The alias @code{last-input-char} is obsolete.
@end defvar
@defmac while-no-input body@dots{}
(while (not done)
(let ((inhibit-quit first)
@dots{})
- (and prompt (message "%s-" prompt))
- (setq char (read-event))
- (if inhibit-quit (setq quit-flag nil)))
+ (and prompt (message "%s-" prompt))
+ (setq char (read-event))
+ (if inhibit-quit (setq quit-flag nil)))
@r{@dots{}set the variable @code{code}@dots{}})
code))
@end example
@code{end-kbd-macro} set this variable---do not set it yourself.
The variable is always local to the current terminal and cannot be
-buffer-local. @xref{Multiple Displays}.
+buffer-local. @xref{Multiple Terminals}.
@end defvar
@defvar last-kbd-macro
macro. Its value is a string or vector, or @code{nil}.
The variable is always local to the current terminal and cannot be
-buffer-local. @xref{Multiple Displays}.
+buffer-local. @xref{Multiple Terminals}.
@end defvar
@defvar kbd-macro-termination-hook
macro terminates, regardless of what caused it to terminate (reaching
the macro end or an error which ended the macro prematurely).
@end defvar
-
-@ignore
- arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1
-@end ignore