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]
Arguments: 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]
Arguments: 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]
Arguments: 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]
Arguments: 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]
Arguments: 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]
Arguments: 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 [Function]
Arguments: 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]
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]
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]
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.