+File: lispref.info, Node: Using Interactive, Next: Interactive Codes, Up: Defining Commands
+
+Using `interactive'
+-------------------
+
+ 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 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 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.
+
+ If this expression reads keyboard input (this includes using the
+ minibuffer), keep in mind that the integer value of point or the
+ mark before reading input may be incorrect after reading input.
+ This is because 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
+ only after reading the keyboard input:
+
+ (interactive
+ (let ((string (read-string "Foo: " nil 'my-history)))
+ (list (region-beginning) (region-end) string)))
+
+ * 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' (*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
+ successfully.
+
+ 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 `_').
+
+ - Function: function-interactive function
+ This function retrieves the interactive specification of FUNCTION,
+ which may be any funcallable object. The specification will be
+ returned as the list of the symbol `interactive' and the specs. If
+ FUNCTION is not interactive, `nil' will be returned.
+
+\1f
+File: lispref.info, Node: Interactive Codes, Next: Interactive Examples, Prev: Using Interactive, Up: Defining Commands
+
+Code Characters for `interactive'
+---------------------------------
+
+ The code character descriptions below contain a number of key words,
+defined here as follows:
+
+Completion
+ Provide completion. <TAB>, <SPC>, and <RET> perform name
+ completion because the argument is read using `completing-read'
+ (*note Completion::). `?' displays a list of possible completions.
+
+Existing
+ Require the name of an existing object. An invalid name is not
+ accepted; the commands to exit the minibuffer do not exit if the
+ current input is not valid.
+
+Default
+ A default value of some sort is used if the user enters no text in
+ the minibuffer. The default depends on the code character.
+
+No I/O
+ This code letter computes an argument without reading any input.
+ Therefore, it does not use a prompt string, and any prompt string
+ you supply is ignored.
+
+ Even though the code letter doesn't use a prompt string, you must
+ follow it with a newline if it is not the last code character in
+ the string.
+
+Prompt
+ A prompt immediately follows the code character. The prompt ends
+ either with the end of the string or with a newline.
+
+Special
+ This code character is meaningful only at the beginning of the
+ interactive string, and it does not look for a prompt or a newline.
+ It is a single, isolated character.
+
+ Here are the code character descriptions for use with `interactive':
+
+`*'
+ Signal an error if the current buffer is read-only. Special.
+
+`@'
+ Select the window mentioned in the first mouse event in the key
+ sequence that invoked this command. Special.
+
+`_'
+ Do not cause the region to be deactivated when this command
+ completes. Special.
+
+`a'
+ A function name (i.e., a symbol satisfying `fboundp'). Existing,
+ Completion, Prompt.
+
+`b'
+ The name of an existing buffer. By default, uses the name of the
+ current buffer (*note Buffers::). Existing, Completion, Default,
+ Prompt.
+
+`B'
+ A buffer name. The buffer need not exist. By default, uses the
+ name of a recently used buffer other than the current buffer.
+ Completion, Default, Prompt.
+
+`c'
+ A character. The cursor does not move into the echo area. Prompt.
+
+`C'
+ A command name (i.e., a symbol satisfying `commandp'). Existing,
+ Completion, Prompt.
+
+`d'
+ The position of point, as an integer (*note Point::). No I/O.
+
+`D'
+ A directory name. The default is the current default directory of
+ the current buffer, `default-directory' (*note System
+ Environment::). Existing, Completion, Default, Prompt.
+
+`e'
+ The last mouse-button or misc-user event in the key sequence that
+ invoked the command. No I/O.
+
+ You can use `e' more than once in a single command's interactive
+ specification. If the key sequence that invoked the command has N
+ mouse-button or misc-user events, the Nth `e' provides the Nth
+ such event.
+
+`f'
+ A file name of an existing file (*note File Names::). The default
+ directory is `default-directory'. Existing, Completion, Default,
+ Prompt.
+
+`F'
+ A file name. The file need not exist. Completion, Default,
+ Prompt.
+
+`k'
+ A key sequence (*note Keymap Terminology::). This keeps reading
+ events until a command (or undefined command) is found in the
+ current key maps. The key sequence argument is represented as a
+ vector of events. The cursor does not move into the echo area.
+ Prompt.
+
+ This kind of input is used by commands such as `describe-key' and
+ `global-set-key'.
+
+`K'
+ A key sequence, whose definition you intend to change. This works
+ like `k', except that it suppresses, for the last input event in
+ the key sequence, the conversions that are normally used (when
+ necessary) to convert an undefined key into a defined one.
+
+`m'
+ The position of the mark, as an integer. No I/O.
+
+`n'
+ A number read with the minibuffer. If the input is not a number,
+ the user is asked to try again. The prefix argument, if any, is
+ not used. Prompt.
+
+`N'
+ The raw prefix argument. If the prefix argument is `nil', then
+ read a number as with `n'. Requires a number. *Note Prefix
+ Command Arguments::. Prompt.
+
+`p'
+ The numeric prefix argument. (Note that this `p' is lower case.)
+ No I/O.
+
+`P'
+ The raw prefix argument. (Note that this `P' is upper case.) No
+ I/O.
+
+`r'
+ Point and the mark, as two numeric arguments, smallest first.
+ This is the only code letter that specifies two successive
+ arguments rather than one. No I/O.
+
+`s'
+ Arbitrary text, read in the minibuffer and returned as a string
+ (*note Text from Minibuffer::). Terminate the input with either
+ <LFD> or <RET>. (`C-q' may be used to include either of these
+ characters in the input.) Prompt.
+
+`S'
+ An interned symbol whose name is read in the minibuffer. Any
+ whitespace character terminates the input. (Use `C-q' to include
+ whitespace in the string.) Other characters that normally
+ terminate a symbol (e.g., parentheses and brackets) do not do so
+ here. Prompt.
+
+`v'
+ A variable declared to be a user option (i.e., satisfying the
+ predicate `user-variable-p'). *Note High-Level Completion::.
+ Existing, Completion, Prompt.
+
+`x'
+ A Lisp object, specified with its read syntax, terminated with a
+ <LFD> or <RET>. The object is not evaluated. *Note Object from
+ Minibuffer::. Prompt.
+
+`X'
+ A Lisp form is read as with `x', but then evaluated so that its
+ value becomes the argument for the command. Prompt.
+
+\1f
+File: lispref.info, Node: Interactive Examples, Prev: Interactive Codes, Up: Defining Commands
+
+Examples of Using `interactive'
+-------------------------------
+
+ Here are some examples of `interactive':
+
+ (defun foo1 () ; `foo1' takes no arguments,
+ (interactive) ; just moves forward two words.
+ (forward-word 2))
+ => foo1
+
+ (defun foo2 (n) ; `foo2' takes one argument,
+ (interactive "p") ; which is the numeric prefix.
+ (forward-word (* 2 n)))
+ => foo2
+
+ (defun foo3 (n) ; `foo3' takes one argument,
+ (interactive "nCount:") ; which is read with the Minibuffer.
+ (forward-word (* 2 n)))
+ => foo3
+
+ (defun three-b (b1 b2 b3)
+ "Select three existing buffers.
+ Put them into three windows, selecting the last one."
+ (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
+ (delete-other-windows)
+ (split-window (selected-window) 8)
+ (switch-to-buffer b1)
+ (other-window 1)
+ (split-window (selected-window) 8)
+ (switch-to-buffer b2)
+ (other-window 1)
+ (switch-to-buffer b3))
+ => three-b
+ (three-b "*scratch*" "declarations.texi" "*mail*")
+ => nil
+
+\1f
+File: lispref.info, Node: Interactive Call, Next: Command Loop Info, Prev: Defining Commands, Up: Command Loop
+
+Interactive Call
+================
+
+ After the command loop has translated a key sequence into a
+definition, it invokes that definition using the function
+`command-execute'. If the definition is a function that is a command,
+`command-execute' calls `call-interactively', which reads the arguments
+and calls the command. You can also call these functions yourself.
+
+ - Function: commandp function
+ Returns `t' if FUNCTION is suitable for calling interactively;
+ that is, if FUNCTION is a command. Otherwise, returns `nil'.
+
+ The interactively callable objects include strings and vectors
+ (treated as keyboard macros), lambda expressions that contain a
+ top-level call to `interactive', compiled-function objects made
+ from such lambda expressions, autoload objects that are declared
+ as interactive (non-`nil' fourth argument to `autoload'), and some
+ of the primitive functions.
+
+ A symbol is `commandp' if its function definition is `commandp'.
+
+ Keys and keymaps are not commands. Rather, they are used to look
+ up commands (*note Keymaps::).
+
+ See `documentation' in *Note Accessing Documentation::, for a
+ realistic example of using `commandp'.
+
+ - Function: call-interactively command &optional record-flag keys
+ This function calls the interactively callable function COMMAND,
+ reading arguments according to its interactive calling
+ specifications. An error is signaled if COMMAND is not a function
+ or if it cannot be called interactively (i.e., is not a command).
+ Note that keyboard macros (strings and vectors) are not accepted,
+ even though they are considered commands, because they are not
+ functions.
+
+ If RECORD-FLAG is the symbol `lambda', the interactive calling
+ arguments for COMMAND are read and returned as a list, but the
+ function is not called on them.
+
+ If RECORD-FLAG is `t', then this command and its arguments are
+ unconditionally added to the list `command-history'. Otherwise,
+ the command is added only if it uses the minibuffer to read an
+ argument. *Note Command History::.
+
+ - Function: command-execute command &optional record-flag keys
+ This function executes COMMAND as an editing command. The
+ argument COMMAND must satisfy the `commandp' predicate; i.e., it
+ must be an interactively callable function or a keyboard macro.
+
+ A string or vector as COMMAND is executed with
+ `execute-kbd-macro'. A function is passed to
+ `call-interactively', along with the optional RECORD-FLAG.
+
+ A symbol is handled by using its function definition in its place.
+ A symbol with an `autoload' definition counts as a command if it
+ was declared to stand for an interactively callable function.
+ Such a definition is handled by loading the specified library and
+ then rechecking the definition of the symbol.
+
+ - Command: execute-extended-command prefix-argument
+ This function reads a command name from the minibuffer using
+ `completing-read' (*note Completion::). Then it uses
+ `command-execute' to call the specified command. Whatever that
+ command returns becomes the value of `execute-extended-command'.
+
+ If the command asks for a prefix argument, it receives the value
+ PREFIX-ARGUMENT. If `execute-extended-command' is called
+ interactively, the current raw prefix argument is used for
+ PREFIX-ARGUMENT, and thus passed on to whatever command is run.
+
+ `execute-extended-command' is the normal definition of `M-x', so
+ it uses the string `M-x ' as a prompt. (It would be better to
+ take the prompt from the events used to invoke
+ `execute-extended-command', but that is painful to implement.) A
+ description of the value of the prefix argument, if any, also
+ becomes part of the prompt.
+
+ (execute-extended-command 1)
+ ---------- Buffer: Minibuffer ----------
+ 1 M-x forward-word RET
+ ---------- Buffer: Minibuffer ----------
+ => t
+
+ - Function: interactive-p
+ This function returns `t' if the containing function (the one that
+ called `interactive-p') was called interactively, with the function
+ `call-interactively'. (It makes no difference whether
+ `call-interactively' was called from Lisp or directly from the
+ editor command loop.) If the containing function was called by
+ Lisp evaluation (or with `apply' or `funcall'), then it was not
+ called interactively.
+
+ The most common use of `interactive-p' is for deciding whether to
+ print an informative message. As a special exception,
+ `interactive-p' returns `nil' whenever a keyboard macro is being
+ run. This is to suppress the informative messages and speed
+ execution of the macro.
+
+ For example:
+
+ (defun foo ()
+ (interactive)
+ (and (interactive-p)
+ (message "foo")))
+ => foo
+
+ (defun bar ()
+ (interactive)
+ (setq foobar (list (foo) (interactive-p))))
+ => bar
+
+ ;; Type `M-x foo'.
+ -| foo
+
+ ;; Type `M-x bar'.
+ ;; This does not print anything.
+
+ foobar
+ => (nil t)
+
+\1f
projects / chise / xemacs-chise.git- / blobdiff