The material in this section is advanced; most CLIM programmers can skip to the next chapter.
For more information on CLIM command tables, see 11.4 CLIM Command Tables.
do-command-table-inheritance Macro
do-command-table-inheritance (command-table-var command-table) &body body
Summary: Successively executes body with command-table-var bound first to the command table specified by the command table designator command-table, and then (recursively) to all of the command tables from which command-table inherits.
The command-table-var argument is not evaluated. body may have zero or more declarations as its first forms.
map-over-command-table-commands Function
map-over-command-table-commands function command-table &key (inherited t)
Summary: Applies function to all of the commands accessible in the command table specified by the command table designator command-table. function must be a function that takes a single argument, the command name; it has dynamic extent.
If inherited is nil, this applies function only to those commands present in command-table, that is, it does not map over any inherited command tables. If inherited is t, then the inherited command tables are traversed in the same order as for do-command-table-inheritance.
map-over-command-table-names Function
map-over-command-table-names function command-table &key (inherited t)
Summary: Applies function to all of the command-line name accessible in the command table specified by the command table designator command-table. function must be a function of two arguments, the command-line name and the command name; it has dynamic extent.
If inherited is nil, this applies function only to those command-line names present in command-table, that is, it does not map over any inherited command tables. If inherited is t, then the inherited command tables are traversed in the same order as for do-command-table-inheritance.
command-present-in-command-table-p Function
command-present-in-command-table-p command-name command-table
Summary: Returns t if the command named by command-name is present in the command table specified by the command table designator command-table; otherwise, it returns nil.
command-accessible-in-command-table-p Function
command-accessible-in-command-table-p command-name command-table
Summary: If the command named by command-name is not accessible in the command table specified by the command table designator command-table, then this function returns nil. Otherwise, it returns the command table in which the command was found.
find-command-from-command-line-name Function
find-command-from-command-line-name name command-table &key (errorp t)
Summary: Given a command-line name name and a command table, returns two values, the command name and the command table in which the command was found. If the command is not accessible in command-table and errorp is t, the command-not-accessible error will be signaled. command-table is a command table designator.
find-command-from-command-line-name ignores character case.
command-line-name-for-command Function
command-line-name-for-command command-name command-table &key (errorp t)
Summary: Returns the command-line name for command-name as it is installed in command-table. command-table is a command table designator.
If the command is not accessible in command-table or has no command-line name, then there are three possible results. If errorp is nil, then the returned value will be nil. If errorp is :create, then a command-line name will be generated, as described in add-command-to-command-table. Otherwise, if errorp is t, then the command-not-accessible error will be signaled. The returned command-line name should not be modified.
command-table-complete-input Function
command-table-complete-input command-table string action &key frame
Summary: A function that can be used as in conjunction with complete-input in order to complete over all of the command lines names accessible in the command table command-table. string is the input string to complete over, and action is as for complete-from-possibilities.
frame is either an application frame, or nil. If frame is supplied, no disabled commands should be offered as valid completions.
Each command table may describe a menu consisting of an ordered sequence of command menu items. The menu specifies a mapping from a menu name (the name displayed in the menu) to either a command object or a submenu. The menu of an application's top-level command table may be presented in a window-system specific way, for example, as a menu bar or in a :menu application frame pane.
Command menu items are stored as a list of the form (type value . options), where type and value are as for add-menu-item-to-command-table, and options is a list of keyword-value pairs. The allowable keywords are :documentation, which is used to supply optional pointer documentation for the command menu item, and :text-style, which is used to indicate what text style should be used for this command menu item when it is displayed in a command menu.
The following functions can be used to display a command menu in one of the panes of an application frame or to choose a command from a menu. add-menu-item-to-command-table, remove-menu-item-from-command-table, and find-menu-item ignore the character case of the command menu item's name when searching through the command table's menu.
display-command-table-menu Generic Function
display-command-table-menu command-table stream &key max-width max-height n-rows n-columns x-spacing y-spacing initial-spacing (cell-align-x :left) (cell-align-y :top) (move-cursor t)
Summary: Displays command-table's menu on stream. It may use formatting-item-list or display the command table's menu in a platform-dependent manner, such as using the menu bar on a Macintosh. command-table is a command table designator.
max-width, max-height, n-rows, n-columns, x-spacing, y-spacing, initial-spacing, cell-align-x, cell-align-y, and move-cursor are as for formatting-item-list.
display-command-menu Generic Function
display-command-menu frame stream &key command-table initial-spacing max-width max-height n-rows n-columns (cell-align-x :left) (cell-align-y :top)
Summary: Displays the menu described by the command table associated with the application frame frame on stream. This is generally used as the display function for extended stream panes of type :command-menu.
menu-choose-command-from-command-table Function
menu-choose-command-from-command-table command-table &key associated-window default-style label cache unique-id id-test cache-value cache-test
Summary: Invokes a window-system-specific routine that displays a menu of commands from command-table's menu, and allows the user to choose one of the commands. command-table is a command table designator. The returned value is a command object. This may invoke itself recursively when there are submenus.
associated-window, default-style, label, cache, unique-id, id-test, cache-value, and cache-test are as for menu-choose.
A number of lower level functions for manipulating command menus are also provided:
add-menu-item-to-command-table Function
add-menu-item-to-command-table command-table string type value &key documentation (after :end) keystroke text-style (errorp t)
Summary: Adds a command menu item to command-table's menu. string is the name of the command menu item; its character case is ignored. type is either :command, :function, :menu, or :divider. command-table is a command table designator.
When type is :command, value must be a command (a cons of a command name followed by a list of the command's arguments), or a command name. (When value is a command name, it behaves as though a command with no arguments was supplied.) In the case where all of the command's required arguments are supplied, clicking on an item in the menu invokes the command immediately. Otherwise, the user will be prompted for the remaining required arguments.
When type is :function, value must be a function having indefinite extent that, when called, returns a command. It is called with two arguments, the gesture the user used to select the item (either a keyboard or button press event) and a "numeric argument".
When type is :menu, this item indicates that a submenu will be invoked, and so value must be another command table or the name of another command table.
When type is :divider, some sort of a dividing line is displayed in the menu at that point. If string is supplied, it will be drawn as the divider instead of a line. If the look and feel provided by the underlying window system has no corresponding concept, :divider items may be ignored. value is ignored.
documentation is a documentation string, which can be used as mouse documentation for the command menu item.
text-style is either a text style spec or nil. It is used to indicate that the command menu item should be drawn with the supplied text style in command menus.
after must be either :start (meaning to add the new item to the beginning of the menu), :end or nil (meaning to add the new item to the end of the menu), or a string naming an existing entry (meaning to add the new item after that entry). If after is :sort, then the item is inserted in such as way as to maintain the menu in alphabetical order.
If keystroke is supplied, the item will be added to the command table's keystroke accelerator table. The value of keystroke must be a keyboard gesture name. This is exactly equivalent to calling add-keystroke-to-command-table with the arguments command-table, keystroke, type and value. When keystroke is supplied and type is :command or :function, typing a key on the keyboard that matches to the keystroke accelerator gesture will invoke the command specified by value. When type is :menu, the command will continue to be read from the submenu indicated by value in a window-system-specific manner.
If the item named by string is already present in the command table's menu and errorp is t, then the command-already-present error will be signaled. When the item is already present in the command table's menu and errorp is nil, the old item will first be removed from the menu. Note that the character case of string is ignored when searching the command table's menu.
remove-menu-item-from-command-table Function
remove-menu-item-from-command-table command-table string &key (errorp t)
Summary: Removes the item named by string from command-table's menu. command-table is a command table designator.
If the item is not present in the command table's menu and errorp is t, then the command-not-present error will be signaled. Note that the character case of string is ignored when searching the command table's menu.
map-over-command-table-menu-items Function
map-over-command-table-menu-items function command-table
Summary: Applies function to all of the items in command-table's menu. function must be a function of three arguments, the menu name, the keystroke accelerator gesture (which will be nil if there is none), and the command menu item; it has dynamic extent. The command menu items are mapped over in the order specified by add-menu-item-to-command-table. command-table is a command table designator.
find-menu-item menu-name command-table &key (errorp t)
Summary: Given a menu name and a command table, returns two values, the command menu item and the command table in which it was found. (Since menus are not inherited, the second returned value will always be command-table.) command-table is a command table designator. This function returns objects that reveal CLIM's internal state; do not modify those objects.
If there is no command menu item corresponding to menu-name present in command-table and errorp is t, then the command-not-accessible error will be signaled. Note that the character case of string is ignored when searching the command table's menu.
command-menu-item-type Function
command-menu-item-type menu-item
Summary: Returns the type of the command menu item menu-item, for example, :menu or :command. If menu-item is not a command menu item, the result is unspecified.
command-menu-item-value Function
command-menu-item-value menu-item
Summary: Returns the value of the command menu item menu-item. For example, if the type of menu-item is :command, this will return a command or a command name. If menu-item is not a command menu item, the result is unspecified.
command-menu-item-options Function
command-menu-item-options menu-item
Summary: Returns a list of the options for the command menu item menu-item. If menu-item is not a command menu item, the result is unspecified.
A command table maintains a database of presentation translators. A presentation translator translates from its from-presentation-type to its to-presentation-type when its associated gesture (e.g., clicking a mouse button) is input. A presentation translator is triggered when its to-presentation-type matches the input context and its from-presentation-type matches the presentation type of the displayed presentation (the appearance of one of your application's objects on the display) on which the gesture is performed.
define-presentation-to-command-translator can be used to associate a presentation and a gesture with a command to be performed on the object which the presentation represents.
Translators can also be used to translate from an object of one type to an object of another type based on context. For example, consider a computer-aided design system for electrical circuits. You might have a translator that translates from a resistor object to the numeric value of its resistance. When asked to enter a resistance (as an argument to a command or for some other query), the user could click on the presentation of a resistor.
Here are some utilities for maintaining presentation translators in command tables. See 6.1 Conceptual Overview of CLIM Presentation Types for a discussion of the facilities supporting the mouse translator interaction style.
add-presentation-translator-to-command-table Function
add-presentation-translator-to-command-table command-table translator-name &key (errorp t)
Summary: Adds the translator named by translator-name to command-table. The translator must have been previously defined with define-presentation-translator or define-presentation-to-command-translator. command-table is a command table designator.
If translator-name is already present in command-table and errorp is t, then the command-already-present error will be signaled. When the translator is already present and errorp is nil, the old translator will first be removed.
remove-presentation-translator-from-command-table Function
remove-presentation-translator-from-command-table command-table translator-name &key (errorp t)
Summary: Removes the translator named by translator-name from command-table. command-table is a command table designator.
If the translator is not present in the command table and errorp is t, then the command-not-present error will be signaled.
map-over-command-table-translators Function
map-over-command-table-translators function command-table &key (inherited t)
Summary: Applies function to all of the translators accessible in command-table. function must be a function of one argument, the translator; it has dynamic extent. command-table is a command table designator.
If inherited is nil, this applies function only to those translators present in command-table, that is, it does not map over any inherited command tables. If inherited is t, then the inherited command tables are traversed in the same order as for do-command-table-inheritance.
find-presentation-translator Function
find-presentation-translator translator-name command-table &key (errorp t)
Summary: Given a translator name and a command table, returns two values, the presentation translator and the command table in which it was found. If the translator is not present in command-table and errorp is t, then the command-not-accessible error will be signaled. command-table is a command table designator.
One interaction style supported by CLIM is the command line style of interaction provided on most conventional operating systems. A command prompt is displayed in the application's :interactor pane. The user enters a command by typing its command line name followed by its arguments. What the user types (or enters via the pointer) is echoed to the interactor window. When the user has finished typing the command, it is executed.
In CLIM, this interaction style is augmented by the input editing facility, which allows the user to correct typing mistakes, and by the prompting and help facilities, which provide a description of the command and the expected arguments (see 16 Input Editing and Completion Facilities). Command entry is also facilitated by the presentation substrate, which allows the input of objects matching the input context, both for command names and command arguments.
See 11.4 CLIM Command Tables and 11.10.1 CLIM Command Tables for complete descriptions of these functions.
find-command-from-command-line-name Function
find-command-from-command-line-name name command-table &key (errorp t)
Summary: Given a command-line name name and a command-table, this function returns two values, the command name and the command table in which the command was found.
command-line-name-for-command Function
command-line-name-for-command command-name command-table &key (errorp t)
Summary: Returns the command-line name for command-name as it is installed in command-table.
map-over-command-table-names Function
map-over-command-table-names function command-table &key (inherited t)
Summary: Applies function to all the command-line names accessible in command-table.
Each command table may have a mapping from keystroke accelerator gesture names to command menu items. When a user presses a key that corresponds to the gesture for keystroke accelerator, the corresponding command menu item will be invoked. Command menu items are shared among the command table's menu and the accelerator table. This lets the menu display the keystroke associated with a particular item, if there is one.
Note that, despite the fact the keystroke accelerators are specified using keyboard gesture names rather than characters, the conventions for typed characters vary widely from one platform to another. Therefore the programmer must be careful in choosing keystroke accelerators. Some sort of per-platform conditionalization is to be expected.
Keystroke accelerators will typically be associated with commands through the use of the :keystroke option to define-command (or the application's command defining macro).
add-keystroke-to-command-table Function
add-keystroke-to-command-table command-table gesture type value &key documentation (errorp t)
Summary: Adds a command menu item to command-table's keystroke accelerator table. gesture is a keyboard gesture name to be used as the accelerator. type and value are as for add-menu-item-to-command-table, except that type must be either :command, :function or :menu. command-table is a command table designator.
documentation is a documentation string, which can be used as documentation for the keystroke accelerator.
If the command menu item associated with gesture is already present in the command table's accelerator table and errorp is t, then the command-already-present error will be signaled. When the item is already present in the command table's accelerator table and errorp is nil, the old item will first be removed.
remove-keystroke-from-command-table Function
remove-keystroke-from-command-table command-table gesture &key (errorp t)
Summary: Removes the command menu item named by keyboard gesture name gesture from command-table's accelerator table. command-table is a command table designator.
The command-not-present error will be signaled if the command menu item associated with gesture is not in the command table's menu and errorp is t.
map-over-command-table-keystrokes Function
map-over-command-table-keystrokes function command-table
Summary: Applies function to all the keystroke accelerators in command-table's accelerator table. function must be a function of three arguments, the menu name (which will be nil if there is none), the keystroke accelerator, and the command menu item; it has dynamic extent. command-table is a command table designator.
map-over-command-table-keystrokes is not recursive. If you want it to descend into submenus, check that the type of the command menu item is eql to :menu before using map-over-command-table-keystrokes recursively.
find-keystroke-item gesture command-table &key (errorp t)
Summary: Given a keyboard gesture gesture and a command table, returns two values, the command menu item associated with the gesture and the command table in which it was found. (Since keystroke accelerators are not inherited, the second returned value will always be command-table.)
This function returns objects that reveal CLIM's internal state; do not modify those objects.
Note that gesture may be either a keyboard gesture name or a gesture object. When it is a gesture name, eql will be used to compare the supplied gesture to the gesture names stored in the command table's menu. When it is a gesture object, event-matches-gesture-name-p will be used to do the comparison.
If the keystroke accelerator is not present in command-table and errorp is t, then the command-not-present error will be signaled. command-table is a command table designator.
lookup-keystroke-item Function
lookup-keystroke-item gesture command-table
Summary: Given a keyboard gesture gesture and a command table, returns two values, the command menu item associated with the gesture and the command table in which it was found. gesture may be either a keyboard gesture name or a gesture object, and is handled in the same way as in find-keystroke-item. This function returns objects that reveal CLIM's internal state; do not modify those objects.
Unlike find-keystroke-item, this follows the submenu chains that can be created with add-menu-item-to-command-table. If the keystroke accelerator cannot be found in the command table or any of the command tables from which it inherits, lookup-keystroke-item will return nil. command-table is a command table designator.
lookup-keystroke-command-item Function
lookup-keystroke-command-item gesture command-table &key numeric-arg
Summary: Given a keyboard gesture gesture and a command table, returns the command associated with the keystroke, or gesture if no command is found. Note that gesture may be either a keyboard gesture name or a gesture object, and is handled in the same way as in find-keystroke-item. This function returns objects that reveal CLIM's internal state; do not modify those objects.
This is like find-keystroke-item, except that only keystrokes that map to an enabled application command will be matched. command-table is a command table designator.
numeric-arg (which defaults to 1) is substituted into the resulting command for any occurrence of *numeric-argument-marker* in the command. This is intended to allow programmers to define keystroke accelerators that take simple numeric arguments, which will be passed on by the input editor.
substitute-numeric-argument-marker Function
substitute-numeric-argument-marker command numeric-arg
Summary: Given a command object command, this substitutes the value of numeric-arg for all occurrences of the value of *numeric-argument-marker* in the command, and returns a command object with those substitutions.
For a description of the CLIM command processor, see 11.9 The CLIM Command Processor.
command-line-command-parser Function
command-line-command-parser command-table stream
Summary: The default command-line parser. It reads a command name and the command's arguments as a command line from stream (with completion as much as is possible), and returns a command object. command-table is a command table designator that specifies the command table to use; the commands are read via the textual command-line name.
command-line-command-unparser Function
command-line-command-unparser command-table stream command
Summary: The default command-line unparser. It prints the command command as a command name and its arguments as a command line on stream. command-table is a command table designator that specifies the command table to use; the commands are displayed using the textual command-line name.
command-line-read-remaining-arguments-for-partial-command Function
command-line-read-remaining-arguments-for-partial-command command-table stream partial-command start-position
Summary: The default partial command-line parser. If the remaining arguments are at the end of the command line, it reads them as a command line; otherwise, it constructs a dialog using accepting-values and reads the remaining arguments from the dialog. command-table is a command table designator.
menu-command-parser command-table stream
Summary: The default menu-driven command parser. It uses only pointer clicks to construct a command. It relies on presentations of all arguments being visible. command-table and stream are as for command-line-parser.
There is no menu-driven command unparser, since it makes no sense to unparse a completely menu-driven command.
menu-read-remaining-arguments-for-partial-command Function
menu-read-remaining-arguments-for-partial-command command-table stream partial-command start-position
Summary: The default menu-driven partial command parser. It uses only pointer clicks to fill in the command. Again, it relies on presentations of all arguments being visible. command-table is a command table designator.
Summary: Contains the currently active command parsing function. The default value is the function command-line-command-parser, which is the default command-line parser.
Summary: Contains the currently active command unparsing function. The default value is the function command-line-command-unparser, which is the default command-line unparser.
*partial-command-parser* Variable
Summary: Contains the currently active partial command parsing function. The default value is the function command-line-read-remaining-arguments-for-partial-command.
*unsupplied-argument-marker* Variable
Summary: The value of *unsupplied-argument-marker* is an object that can be uniquely identified as standing for an unsupplied argument in a command object.
*numeric-argument-marker* Variable
Summary: The value of *numeric-argument-marker* is an object that can be uniquely identified as standing for a numeric argument in a command object.
*command-name-delimiters* Variable
Summary: This is a list of the characters that separate the command name from the command arguments in a command line. The standard set of command name delimiters includes #\Space.
*command-argument-delimiters* Variable
Summary: This is a list of the characters that separate the command arguments from each other in a command line. The standard set of command argument delimiters includes #\Space.
CLIM 2.0 User Guide - 01 Dec 2021 19:38:58