Common Lisp Interface Manager 2.0 User's Guide > Chapter 11 Commands


11.9 The CLIM Command Processor

Once a set of commands has been defined, CLIM provides a variety of means to read a command. These are all mediated by the command processor.

The command loop of a CLIM application is performed by the application's top-level function (see Chapter 9, Defining Application Frames). By default, this is default-frame-top-level . After performing some initializations, default-frame-top-level enters an infinite loop, reading and executing commands. It invokes the generic function read-frame-command to read a command that is then passed to the generic function execute-frame-command for execution. The specialization of these generic functions is the simplest way to modify the command loop for your application. Other techniques would involve replacing default-frame-top-level with your own top-level function.

read-frame-command invokes the command parser by establishing an input context of command . The input editor keeps track of the user's input, both from the keyboard and the pointer. Each of the command's arguments is parsed by establishing an input context of the arguments presentation type as described in the command's definition. Presentation translators provide the means by which the pointer can be used to enter command names and arguments.

read-command [Function]	

Arguments: command-table &key (stream *query-io* ) command-parser command-unparser partial-command-parser use-keystrokes

Summary: read-command is the standard interface used to read a command line. stream is an extended input stream, and command-table is a command table designator.

command-parser is a function of two arguments, a command table and a stream. It reads a command from the user and returns a command object. The default value for command-parser is the value of *command-parser* .

command-unparser is a function of three arguments, a command table, a stream, and a command to "unparse." It prints a textual description of the command and its supplied arguments onto the stream. The default value for command-unparser is the value of *command-unparser* .

partial-command-parser is a function of four arguments, a command table, a stream, a partial command, and a start position. The partial command is a command object with the value of *unsupplied-argument-marker* in place of any argument that needs to be filled in. The function reads the remaining unsupplied arguments in any way it sees fit (for example, via an accepting-values dialog), and returns a command object. The start position is the original input-editor scan position of the stream, when the stream is an interactive stream. The default value for partial-command-parser is the value of *partial-command-parser* .

command-parser , command-unparser , and partial-command-parser have dynamic extent.

When use-keystrokes is t , the command reader will also process keystroke accelerators.

Input editing, while conceptually an independent facility, fits into the command processor via its use of accept . That is, read-command calls accept to read command objects, and accept itself makes use of the input editing facilities.

read-frame-command[Generic Function]

Arguments: frame &key stream

Summary: read-frame-command reads a command from the user on the stream stream , and returns the command object. frame is an application frame.

The default method for read-frame-command calls read-command on frame's current command table.

execute-frame-command[Generic Function]

Arguments: frame command

Summary: execute-frame-command executes the command command on behalf of the application frame frame.

with-command-table-keystrokes [Macro]	

Arguments: (keystroke-var command-table) &body body

Summary: Binds keystroke-var to a sequence that contains all of the keystroke accelerators in command-table 's menu, and then executes body in that context. command-table is a command table designator. body may have zero or more declarations as its first forms.

read-command-using-keystrokes [Function]	

Arguments: command-table keystrokes &key (stream *query-io* ) command-parser command-unparser partial-command-parser

Summary: Reads a command from the user via command lines, the pointer, or a single keystroke, and returns either a command object or a keyboard gesture object. (The latter only occurs when the user types a keystroke that is in keystrokes but does not have a command associated with it in command-table .)

keystrokes is a sequence of keyboard gesture names that are the keystroke accelerators.

command-table , stream , command-parser , command-unparser , and partial-command-parser are as for read-command .

An application can control which commands are enabled and which are disabled on an individual basis by using enable-command and disable-command . The user is not allowed to enter a disabled command via any interaction style.


Arguments: command-name frame

Summary: Enables the use of the command named by command-name while in the application frame.


Arguments: command-name frame

Summary: Disables the use of the command named by command-name while in the application frame.

The special variable *command-dispatchers* controls the behavior of the command-or-form presentation type.


Summary: This is a list of the characters that indicates that CLIM reads a command when it is accepting a command-or-form . The standard set of command argument delimiters includes the colon character, #\: .

Common Lisp Interface Manager 2.0 User's Guide - 22 Dec 2009