9.4 DUIM-Frames Module

add-command-table-menu-item

Generic function

Summary

Adds a menu item to the specified command table.

Signature

add-command-table-menu-item command-table string type value #key documentation after accelerator mnemonic text-style error? items label-key value-key test callback => menu-item

Arguments

command-table: An instance of type <command-table>.
string: An instance of type false-or(<string>).
type: An instance of type one-of(#"command", #"function", #"menu", #"divider").
value: An instance of type <object>.
documentation: An instance of type <string>.
after: An instance of type one-of(#"start", #"end", #"sort"), or an instance of <string>. Default value: #"end".
accelerator: An instance of type false-or(<gesture>).
mnemonic: An instance of type false-or(<gesture>).
text-style: An instance of type <text-style>.
error?: An instance of type <boolean>. Default value: #t.
items: An instance of type limited(<sequence>, of: ).
label-key: An instance of type <function>.
value-key: An instance of type <function>.
test: An instance of type <function>.
callback: An instance of type <function>.

Values

menu-item: An instance of type <command-table-menu-item>.

Library

duim-frames

Module

duim-frames

Description

Adds a command menu item to the menu in command-table. The string argument is the name of the command menu item; its character case is ignored. The type of the item is either #"command", #"function", #"menu", or #"divider".

When type is #"command", value must be one of the following:

A command (a list consisting of a command name followed by a list of the arguments for the command).
A command name. In this case, value behaves as though a command with no arguments was supplied.

When all the required arguments for the command are supplied, clicking on an item in the menu invokes the command immediately. Otherwise, the user is prompted for the remaining required arguments.

When type is #"function", value must be a function having indefinite extent that, when called, returns a command. The function is called with two arguments:

The gesture used to select the item (either a keyboard or button press event).
A "numeric argument".

When type is #"menu", this indicates that a sub-menu is required, and 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. When type is #"divider", value is ignored.

The argument documentation specifies a documentation string, This can be used to provide the user with some online documentation for the menu item. Documentation strings are often displayed in a status bar at the bottom of an application; highlighting the menu item using the mouse pointer displays the documentation string in the status bar.

The text-style argument, if supplied, represents text style. This specifies the font family, style, and weight with which to display the menu item in the menu. For most menu items, you should just use the default text style (that is, the one that the user chooses for all applications). However, in certain cases, some variation is allowed.

The text-style argument is of most use in context sensitive pop-up menus, which often have a default menu item. This is usually the command that is invoked by pressing the RETURN key on the current selection: for example, in a list of files, the default command usually opens the selected file in the application associated with it. In Windows 95, the default command is displayed using a bold font, to differentiate it from other commands in the menu, and you should use the text-style argument to specify this.

When altering the text style of a menu item, you should always try to stick to any relevant interface guidelines.

The items argument is used to specify the gadgets that are to be supplied to the command table as menu items. You can supply either push boxes, check boxes, or radio boxes.

The after argument denotes where in the menu the new item is to be added. It must be one of the following:

#"start"

Adds the new item to the beginning of the menu.

#"end"

Adds the new item to the end of the menu.

A string naming an existing entry

Adds the new item after that entry.

#"sort"

Insert the item in such as way as to maintain the menu in alphabetical order.

If mnemonic is supplied, the item is added to the keyboard mnemonic table for the command table. The value of mnemonic must be a keyboard gesture name.

When mnemonic is supplied and type is #"command" or #"function", typing a key on the keyboard that matches the mnemonic invokes the command specified by value.

When type is #"menu", the command is read from the submenu indicated by value in a window system specific manner. This usually means that the submenu itself is displayed, allowing the user to see the available options at that point.

When accelerator is supplied, typing a key sequence on the keyboard that matches the accelerator invokes the command specified by value, no matter what type is.

If the item named by string is already present in the command table and error? is #t, then an error is signalled. When the item is already present in the command table and error? is #f, the old item is removed from the menu before adding the new item. Note that the character case of string is ignored when searching the command table.