@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 Free Software Foundation, Inc.
+@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
* 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.
+* 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.
@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}. This
+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.
@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}.
@end defspec
There are three possibilities for the argument @var{arg-descriptor}:
@cindex @samp{*} in @code{interactive}
@cindex read-only buffers in interactive
-If the first character in the string is @samp{*}, then an error is
+If @samp{*} appears at the beginning of the string, then an error is
signaled if the buffer is read-only.
@cindex @samp{@@} in @code{interactive}
@c Emacs 19 feature
-If the first character in the string is @samp{@@}, and if the key
+If @samp{@@} appears at the beginning of the string, 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{@@}).
+@cindex @samp{^} in @code{interactive}
+@cindex shift-selection, and @code{interactive} spec
+If @samp{^} appears at the beginning of the string, and if the command
+was invoked through @dfn{shift-translation}, set the mark and activate
+the region temporarily, or extend an already active region, before the
+command is run. If the command was invoked without shift-translation,
+and the region is temporarily active, deactivate the region before the
+command is run. Shift-translation is controlled on the user level by
+@code{shift-select-mode}; see @ref{Shift Selection,,, emacs, The GNU
+Emacs Manual}.
+
+You can use @samp{*}, @samp{@@}, and @code{^} 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{*}, @samp{@@}, or @samp{^}).
@item
It may be a Lisp expression that is not a string; then it should be a
Select the window mentioned in the first mouse event in the key
sequence that invoked this command. Special.
+@item ^
+If the command was invoked through shift-translation, set the mark and
+activate the region temporarily, or extend an already active region,
+before the command is run. If the command was invoked without
+shift-translation, and the region is temporarily active, deactivate
+the region before the command is run. Special.
+
@item a
A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
Completion, Prompt.
@group
(defun foo2 (n) ; @r{@code{foo2} takes one argument,}
- (interactive "p") ; @r{which is the numeric prefix.}
+ (interactive "^p") ; @r{which is the numeric prefix.}
+ ; @r{under @code{shift-select-mode},}
+ ; @r{will activate or extend region.}
(forward-word (* 2 n)))
@result{} foo2
@end group
@end example
@end deffn
-@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.
+@node Distinguish Interactive
+@section Distinguish Interactive Calls
+
+ Sometimes a command should display additional visual feedback (such
+as an informative message in the echo area) for interactive calls
+only. There are three ways to do this. The recommended way to test
+whether the function was called using @code{call-interactively} is to
+give it an optional argument @code{print-message} and use the
+@code{interactive} spec to make it non-@code{nil} in interactive
+calls. Here's an example:
+
+@example
+(defun foo (&optional print-message)
+ (interactive "p")
+ (when print-message
+ (message "foo")))
+@end example
+
+@noindent
+We use @code{"p"} because the numeric prefix argument is never
+@code{nil}. Defined in this way, the function does display the
+message when called from a keyboard macro.
+
+ 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}.
+
+@defun called-interactively-p
+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.
@end defun
- The most common use of @code{interactive-p} is for deciding whether
-to give the user additional visual feedback (such as by printing an
-informative message). For example:
+ Here's an example of using @code{called-interactively-p}:
@example
@group
-;; @r{Here's the usual way to use @code{interactive-p}.}
(defun foo ()
(interactive)
- (when (interactive-p)
- (message "foo")))
+ (when (called-interactively-p)
+ (message "foo"))
+ 'haha)
@result{} foo
@end group
@group
-;; @r{This function is just to illustrate the behavior.}
-(defun bar ()
- (interactive)
- (setq foobar (list (foo) (interactive-p))))
- @result{} bar
+;; @r{Type @kbd{M-x foo}.}
+ @print{} foo
@end group
@group
-;; @r{Type @kbd{M-x foo}.}
- @print{} foo
+(foo)
+ @result{} haha
+@end group
+@end example
+
+ 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
@end group
@group
@end group
@end example
- If you want to test @emph{only} whether the function was called
-using @code{call-interactively}, add an optional argument
-@code{print-message} which should be non-@code{nil} in an interactive
-call, and use the @code{interactive} spec to make sure it is
-non-@code{nil}. Here's an 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}.
-@example
-(defun foo (&optional print-message)
- (interactive "p")
- (when print-message
- (message "foo")))
-@end example
-
-@noindent
-Defined in this way, the function does display the message when called
-from a keyboard macro. We use @code{"p"} because the numeric prefix
-argument is never @code{nil}.
-
-@defun called-interactively-p
-This function returns @code{t} when the calling function was called
-using @code{call-interactively}.
-
-When possible, instead of using this function, you should use the
-method in the example above; that method makes it possible for a
-caller to ``pretend'' that the function was called interactively.
+@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
@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.
+records for itself and for commands that are run. With the exception of
+@code{this-command} and @code{last-command} it's generally a bad idea to
+change any of these variables in a Lisp program.
@defvar last-command
This variable records the name of the previous command executed by the
but never altered by Lisp programs.
@end defvar
+@defvar last-repeatable-command
+This variable stores the most recently executed command that was not
+part of an input event. This is the command @code{repeat} will try to
+repeat, @xref{Repeating,,, emacs, The GNU Emacs Manual}.
+@end defvar
+
@defvar this-command
@cindex current command
This variable records the name of the command now being executed by
@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
* 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.
+* 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.
@end menu
@end example
@end defun
-@node Accessing Events
-@subsection Accessing Events
+@node Accessing Mouse
+@subsection Accessing Mouse Events
@cindex mouse events, data in
This section describes convenient functions for accessing the data in
the entire window area including scroll bars, margins and fringes.
@end defun
+@node Accessing Scroll
+@subsection Accessing Scroll Bar Events
+@cindex scroll bar events, data in
+
These functions are useful for decoding scroll bar events.
@defun scroll-bar-event-ratio event
@cindex upper case key sequence
@cindex downcasing in @code{lookup-key}
+@cindex shift-translation
If an input character is upper-case (or has the shift modifier) and
has no key binding, but its 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.
+@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-@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
button-down events entirely. It also reshuffles focus events and
translation.
Note also that this translation is done before the characters are
-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.
+supplied to input methods (@pxref{Input Methods}).
@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{}