GNU Info

(sawfish.info)Commands

---

Next: Keymaps Prev: Events Up: Top

---

Enter node , (file) or (file)node

Commands
********

   A "command" is a Lisp function which may be called interactively,
that is, either as a result of being bound to an input event.

   Commands are defined in the same way as functions (using `defun'),
but the body forms of the command must contain an "interactive
declaration". This marks that the function may be called interactively
and tells the `call-command' function how to compute the argument
values to apply to the command.

   The interactive declaration looks like a call to the special form
`interactive', in actual fact this special form always returns `nil'
and has no side-effects. The only effect of this form is to show the
`call-command' function that the function definition may be called
interactively. The second element of the declaration form (after the
`interactive' symbol) defines how the argument values applied to the
command are computed.

   The structure of an interactive declaration, then, is:

     (interactive [CALLING-SPEC])

   When a command is defined this is how it includes the interactive
declaration:

     (defun some-command (arg1)
       "Optional documentation string."
       (interactive ...)
       ...

   The CALLING-SPEC form defines the argument values applied to the
command when it is called interactively, it may be one of,

   * `nil' or undefined (i.e. `(interactive)'); no arguments are given
     to the command, this type of interactive declaration just shows
     that the function may be called interactively.

   * A string; zero or more lines (each separated by a newline
     character), each line defines how to compute one argument value.
     The first one or two characters of each line is a prefix defining
     exactly how to compute the argument, the rest of the line is an
     optional argument which some prefixes may use.

     The currently available prefixes are,

    `e'
          The event which caused this command to be invoked.

    `E'
          The event which caused this command, cooked into a string.

    `p'
          The prefix argument as a number, this will be 1 if no prefix
          argument has been entered.

    `P'
          The raw prefix argument.

    `t'
          The symbol `t'.

    `%f'
          The window which currently has the input focus, or `nil' if no
          window is focused.

    `%w'
          The result of calling the `current-event-window' function.

    `%W'
          The result of calling the `current-event-window' function, or
          if this returns `nil' or `root', the currently focused window.

     A null line produces an argument value of `nil'.

   * Anything else; the form is evaluated and expected to return a
     _list_ of arguments to apply to the command.

   When a command is to be invoked, the `call-command' function is
used. This builds a list of argument values to apply to the command
(using its interactive declaration) then calls the command.

 - Function: commandp OBJECT
     This function returns `t' if its argument may be called
     interactively.  If OBJECT is a function (i.e. a symbol or a
     lambda-expression) it is a command if it contains an interactive
     declaration

     The only other object which is a command is a function call form;
     the use of these types of commands is discouraged but they can be
     useful sometimes.

 - Function: call-command command &optional prefix-arg
     This function calls the command COMMAND interactively. See the
     documentation of `commandp' above for what constitutes a command.

     If the PREFIX-ARGUMENT is non-nil it defines the value of the
     `current-prefix-arg' variable for this command, normally the value
     of this variable would be taken from the global `prefix-arg'
     variable.