Next: Interactive Codes Up: Defining Commands
This section describes how to write the `interactive' form that
makes a Lisp function an interactively-callable command.
- Special Form: 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 `M-x' or by entering a key sequence bound to it). The
argument ARG-DESCRIPTOR declares the way the arguments to the
command are to be computed when the command is called
A command may be called from Lisp programs like any other
function, but then the arguments are supplied by the caller and
ARG-DESCRIPTOR has no effect.
The `interactive' form has its effect because the command loop
(actually, its subroutine `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
`interactive' form are executed, but at this time `interactive'
simply returns `nil' without even evaluating its argument.
There are three possibilities for the argument ARG-DESCRIPTOR:
* It may be omitted or `nil'; then the command is called with no
arguments. This leads quickly to an error if the command requires
one or more arguments.
* 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
* 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:
(interactive "bFrobnicate buffer: ")
The code letter `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 prompt string can use `%' to include previous argument values
in the prompt. This is done using `format' (Note: 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:
(interactive "bBuffer to rename: \nsRename buffer %s to: ")
If the first character in the string is `*', then an error is
signaled if the buffer is read-only.
If the first character in the string is `@', 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.
If the first character in the string is `_', then this command will
not cause the region to be deactivated when it completes; that is,
`zmacs-region-stays' will be set to `t' when the command exits
You can use `*', `@', and `_' 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 `*',
`@', or `_').
automatically generated by info2www