Chapter 11 Commands
11.3 Command Objects
A command is an object that represents a single user interaction. Each command has a command name, which is a symbol. A command can also have both positional and keyword arguments. CLIM represents commands as command objects. The internal representation of a command object is a cons of the command name and a list of the command's arguments, and is therefore analogous to a Lisp expression. Functions are provided for extracting the command name and the arguments list from a command object:
command-name [Function]
- Arguments:
- command
- Summary:
- Given a command object command, returns the command name.
command-arguments [Function]
- Arguments:
- command
- Summary:
- Given a command object command, returns the command's arguments.
It is possible to represent a command for which some of the arguments have not yet been specified. The value of the symbol *unsupplied-argument* is used in place of any argument that has not yet been specified. partial-command-p [Function]
- Arguments:
- command
- Summary:
- Returns t if the command is a partial command, that is, has any occurrences of *unsupplied-argument-marker* in it. Otherwise, this function returns nil.
One can think of define-command as defining templates for command objects. It defines a symbol as a command name and associates with it the presentation types corresponding to each of the command's arguments. define-command [Macro]
- Arguments:
- name-and-options arguments
&body body
- The most basic command-defining form. Usually the programmer will not use define-command directly, but will instead use a define-frame-command form automatically generated by define-application-frame. define-frame-command adds the command to the application frame's command table. By default, define-command does not add the command to any command table.
- define-command defines two functions. The first function has the same name as the command name and implements the body of the command. It takes as required and keyword arguments the arguments to the command as specified by the define-command form .The name of the other function defined by Lisp is unspecified. It implements the code used by the command processor for parsing and returning the command's arguments.
- name-and-options is either a command name or a cons of the command name and a list of keyword-value pairs.
- :command-table command-table-name, where command-table-name either names a command table to which the command will be added, or is nil (the default), indicating that the command should not be added to any command table. If the command table does not exist, the command-table-not-found error will be signaled. This keyword is only accepted by define-command, not by define-frame-command.
- :name string, where string is a string that will be used as the command-line name for the command for keyboard interactions in the command table specified by the :command-table option. The default is nil, meaning that the command will not be available via command-line interactions. If string is t, then the command-line name will be generated automatically, as described in add-command-to-command-table.
- :menu menu-spec, where menu-spec describes an item in the menu of the command table specified by the :command-table option. The default is nil, meaning that the command will not be available via menu interactions. If menu-spec is a string, then that string will be used as the name of the command in the menu. If menu-spec is t, and if a command-line name was supplied, it will be used as the name of the command in the menu; otherwise the menu name will be generated automatically, as described in add-command-to-command-table. Otherwise, menu-spec must be a cons of the form (string . menu-options), where string is the menu name and menu-options consists of keyword-value pairs. The valid keywords are :after, :documentation, and :text-style, which are as for add-menu-item-to-command-table.
- :keystroke gesture, where gesture is a keyboard gesture name that specifies a keystroke accelerator to use for this command in the command table specified by the :command-table option. The default is nil, meaning that there is no keystroke accelerator.
- The :name, :menu, and :keystroke options are only allowed if the :command-table option is supplied explicitly or implicitly, as in define-frame-command.
- arguments is a list consisting of argument descriptions. A single occurrence of the symbol
&key may appear in arguments to separate required command arguments from keyword arguments. Each argument description consists of a parameter variable, followed by a presentation type specifier, followed by keyword-value pairs. The keywords can be:- :default value, where value is the default that should be used for the argument, as for accept.
- :default-type is the same as for accept.
- :display-default is the same as for accept.
- :mentioned-default value, where value is the default that should be used for the argument when a keyword is explicitly supplied via the command-line processor, but no value is supplied for it. :mentioned-default is only allowed on keyword arguments.
- :prompt string, where string is a prompt to print out during command-line parsing, as for accept.
- :documentation string, where string is a documentation string that describes what the argument is.
- :when form. form is evaluated in a scope where the parameter variables for the required parameters are bound, and if the result is nil, the keyword argument is not available. :when is only allowed on keyword arguments, and form cannot use the values of other keyword arguments.
- :gesture gesture, where gesture is either a pointer gesture name or a list of a pointer gesture name followed by keyword-value pairs. When a gesture is supplied, a presentation translator will be defined that translates from this argument's presentation type to an instance of this command with the selected object as the argument; the other arguments will be filled in with their default values. The keyword-value pairs are used as options for the translator. Valid keywords are :tester, :menu, :priority, :echo, :documentation, and :pointer-documentation. The default for gesture is nil, meaning no translator will be written. :gesture is only allowed when the :command-table option was supplied to the command-defining form.
- body implements the body of the command. It has lexical access to all of the commands arguments. If the body of the command needs access to the application frame itself, it should use *application-frame*. The returned values of body are ignored. body may have zero or more declarations as its first forms.
- define-command must arrange for the function that implements the body of the command to get the proper values for unsupplied keyword arguments.
- name-and-options and body are not evaluated. In the argument descriptions, the parameter variable name is not evaluated. The others are evaluated at run-time when argument parsing reaches them, except that the value for :when is evaluated when parsing reaches the keyword arguments. :gesture is not evaluated.
CLIM 2.0 User's Guide - OCT 1998 Generated with Harlequin WebMaker