Next Prev Up Top Contents Index

11.4 CLIM Command Tables

CLIM command tables are represented by instances of the CLOS class command-table . A command table serves to mediate between a command input context, a set of commands, and the interactions of the application's user. Command tables contain the following information:

The name of the command table, which is a symbol

An ordered list of command tables to inherit from

The set of commands that are present in this command table

A table that associates command-line names to command names (used to support command-line processor interactions)

A set of presentation translators, defined via define-presentation-translator and define-presentation-to-command-translator

A table that associates keyboard gesture names to menu items (used to support keystroke accelerator interactions). The keystroke accelerator table does not contain any items inherited from superior command tables.

A menu that associates menu names with command menu items (used to support interaction via command menus). The command menu items can invoke commands or submenus. The menu does not contain any command menu items inherited from superior command tables.

We say that a command is present in a command table when it has been added to that command table by being associated with some form of interaction. We say that a command is accessible in a command table when it is present in that command table or is present in any of the command tables from which that command table inherits.

command-table [Protocol Class]	

Summary: The protocol class that corresponds to command tables. If you want to create a new class that behaves like a command table, it should be a subclass of command-table . Subclasses of command-tabl e must obey the command table protocol. Members of this class are mutable.

command-table-p [Function]	

Arguments: object

Summary: Returns t if object is a command table; otherwise, it returns nil .

standard-command-table

Summary: The instantiable class that implements command tables, a subclass of command-table . make-command-table returns objects that are members of this class.

command-table-name [Generic Function]

Arguments: command-table

Summary: Returns the name of the command table command-table .

command-table-inherit-from [Generic Function]

Arguments: command-table

Summary: Returns a list of the command tables from which the command table command-table inherits. This function returns objects that reveal CLIM's internal state; do not modify those objects.

define-command-table [Macro]	

Arguments: name &key inherit-from menu

Summary: Defines a command table whose name is the symbol name . The new command table inherits from all of the command tables specified by inherit-from , which is a list of command table designators (that is, either a command table or a symbol that names a command table). The inheritance is done by union with shadowing. If no inheritance is specified, the command table will be made to inherit from CLIM's global command table. (This command table contains such things as the "menu" translator that is associated with the right-hand button on pointers.)

menu can be used to specify a menu for the command table. The value of menu is a list of clauses. Each clause is a list with the syntax ( string type value &key keystroke documentation text-style ), where string , type , value , keystroke , documentation , and text-style are as for add-menu-item-to-command-table .

If the command table named by name already exists, define-command-table will modify the existing command table to have the new value for inherit-from and menu , and leaves the other attributes for the existing command table alone.

None of define-command-table 's arguments are evaluated.

make-command-table [Function]	

Arguments: name &key inherit-from menu (errorp t )

Summary: Creates a command table named name . inherit-from and menu are the same as for define-command-table . make-command-table does not implicitly include CLIM's global command table in the inheritance list for the new command table. If the command table already exists and errorp is t , the command-table-already-exists error will be signaled. If the command table already exists and errorp is nil , then the old command table will be discarded. The returned value is the command table.

find-command-table [Function]	

Arguments: name &key (errorp t )

Summary: Returns the command table named by name . If name is itself a command table, it is returned. If the command table is not found and errorp is t , the command-table-not-found error will be signaled.

add-command-to-command-table [Function]	

Arguments: command-name command-table &key name menu keystroke (errorp t )

Summary: Adds the command named by command-name to the command table specified by the command table designator command-table .

name is the command-line name for the command, and can be nil , t , or a string. When it is nil , the command will not be available via command-line interactions. When it is a string, that string is the command-line name for the command. When it is t , the command-line name is generated automatically. (The automatically generated name consists of the command's name with the hyphens replaced by spaces, and the words capitalized; any com- prefix is removed. For example, if the command name is com-show-file , the command-line name will be Show File .) For the purposes of command-line-name lookup, the character case of name is ignored.

menu is a menu item for the command, and can be nil , t , a string, or a cons. When it is nil , the command will not be available via menus. When it is a string, the string will be used as the menu name. When menu is t and name is a string, then name will be used as the menu name. When menu is t and name is not a string, an automatically generated menu name will be used. When menu is a cons of the form ( string . menu-options ), string is the menu name and menu-options consists of keyword-value pairs. The valid keywords are :after , :documentation , and :text-style , which are interpreted as for add-menu-item-to-command-table .

The value for keystroke is either a keyboard gesture name or nil . When it is a gesture name, it is the keystroke accelerator for the command; if it is nil , the command will not be available via keystroke accelerators.

If the command is already present in the command table and errorp is t , the command-already-present error will be signaled. When errorp is nil , the old command-line name, menu, and keystroke accelerator will first be removed from the command table.

remove-command-from-command-table [Function]	

Arguments: command-name command-table &key (errorp t )

Summary: Removes the command named by command-name from the command table specified by the command table designator command-table .

If the command is not present in the command table and errorp is t , the command-not-present error will be signaled.


CommonLisp Interface Manager 2.0 User's Guide - 8 Aug 2003

Next Prev Up Top Contents Index