21.2.1 Using interactive

This section describes how to write the interactive form that makes a Lisp function an interactively-callable command, and how to examine a command's interactive form.

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 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 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 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 (starting with the first argument) in the prompt. This is done using format (voir la section 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.

  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 ‘@’).

• 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. Usually this form will call various functions to read input from the user, most often through the minibuffer (voir la section Minibuffers) or directly from the keyboard (voir la section Reading Input).

  Providing point or the mark as an argument value is also common, but if you do this and read input (whether using the minibuffer or not), be sure to get the integer values of point or the mark after reading. The current buffer may be receiving subprocess output; if subprocess output arrives while the command is waiting for input, it could relocate point and the mark.

  Here's an example of what not to do:

  (interactive (list (region-beginning) (region-end) (read-string "Foo: " nil 'my-history)))

  Here's how to avoid the problem, by examining point and the mark after reading the keyboard input:

  (interactive (let ((string (read-string "Foo: " nil 'my-history))) (list (region-beginning) (region-end) string)))

  Warning: the argument values should not include any data types that can't be printed and then read. Some facilities save command-history in a file to be read in the subsequent sessions; if a command's arguments contain a data type that prints using ‘#<…>’ syntax, those facilities won't work.

  There are, however, a few exceptions: it is ok to use a limited set of expressions such as (point), (mark), (region-beginning), and (region-end), because Emacs recognizes them specially and puts the expression (rather than its value) into the command history. To see whether the expression you wrote is one of these exceptions, run the command, then examine (car command-history).

Function: interactive-form function

This function returns the interactive form of function. If function is an interactively callable function (voir la section Interactive Call), the value is the command's interactive form (interactive spec), which specifies how to compute its arguments. Otherwise, the value is nil. If function is a symbol, its function definition is used.

Ce document a été généré par Eric Reinbold le 13 Octobre 2007 en utilisant texi2html 1.78.