@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}:
@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}).
projects / emacs.git / commitdiff