27.3 Command Menus

Each command table may have 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 a command menu item. The menu of an application frame's top-level command table may be presented in a window system specific way, for example, as a menu bar. [annotate]

Command menu items are stored as a list of the form (type value . options), where type and value are as in 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 documention 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. [annotate]

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. [annotate]

add-menu-item-to-command-table  command-table string type value &key documentation (after ':end) keystroke text-style (errorp t) [Function]
          

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. [annotate]

Minor issue: How do we make iconic command menus? Probably another keyword... --- SWM [annotate]

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. [annotate]

When type is :function, value must be function having indefinite extent that, when called, returns a command. The function 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". [annotate]

When type is :menu, this item indicates that a sub-menu will be invoked, and so value must be another command table or the name of another command table. [annotate]

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. [annotate]

documentation is a documentation string, which can be used as mouse documentation for the command menu item. [annotate]

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. [annotate]

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. [annotate]

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 sub-menu indicated by value in a window system specific manner. [annotate]

Note: This is the part where emacs-like bindings come into play (i.e C-x C-t). That logic should be captured in read-command-using-keystrokes. [edit]-- DK 2020-10-15 11:45Z
 

If the item named by string is already present in the command table's menu and errorp is true, then the command-already-present error will be signalled. When the item is already present in the command table's menu and errorp is false, 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. [annotate]

[annotate]

remove-menu-item-from-command-table  command-table string &key (errorp t) [Function]
          

Removes the item named by string from command-table's menu. command-table is a command table designator. [annotate]

If the item is not present in the command table's menu and errorp is true, then the command-not-present error will be signalled. Note that the character case of string is ignored when searching the command table's menu. [annotate]

[annotate]

map-over-command-table-menu-items  function command-table [Function]
          

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. [annotate]

map-over-command-table-menu-items does not descend into sub-menus. If the programmer requires this behavior, he should examine the type of the command menu item to see if it is :menu. [annotate]

[annotate]

find-menu-item  menu-name command-table &key (errorp t) [Function]
          

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. [annotate]

If there is no command menu item corresponding to menu-name present in command-table and errorp is true, then the command-not-accessible error will be signalled. Note that the character case of string is ignored when searching the command table's menu. [annotate]

[annotate]

command-menu-item-type  menu-item [Function]
          

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. [annotate]

[annotate]

command-menu-item-value  menu-item [Function]
          

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. [annotate]

[annotate]

command-menu-item-options  menu-item [Function]
          

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. [annotate]

[annotate]

display-command-table-menu  command-table stream &key max-width max-height n-rows n-columns x-spacing y-spacing initial-spacing row-wise (cell-align-x :left) (cell-align-y :top) (move-cursor t) [Generic Function]
          

Displays command-table's menu on stream. Implementations may choose to use formatting-item-list or may 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. [annotate]

max-width, max-height, n-rows, n-columns, x-spacing, y-spacing, row-wise, initial-spacing, cell-align-x, cell-align-y, and move-cursor are as for formatting-item-list. [annotate]

[annotate]

menu-choose-command-from-command-table  command-table &key associated-window default-style label cache unique-id id-test cache-value cache-test [Function]
          

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 sub-menus. [annotate]

associated-window, default-style, label, cache, unique-id, id-test, cache-value, and cache-test are as for menu-choose. [annotate]

Minor issue: Should this be generic on application frames? --- SWM [annotate]

[annotate]