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]

Given a command object command, returns the command name.

command-arguments [Function]
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]

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]

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.

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:

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