5.5.2 Menu Item Procedures

Procedure: new-item name description

Returns a new allocated menu item of type with a given name and description. It can throw an error if the strings are too large or if a memory allocation error occurs.

Procedure: set-current-item! menu item

Given a menu and an item that has been attached to that menu, this procedure sets item to be the current item. It returns an integer that will be one of E_OK, E_BAD_ARGUMENT, E_NOT_CONNECTED if not menu items are attached to this menu, or E_SYSTEM_ERROR.

Procedure: current-item menu

Returns the current item for menu.

Procedure: set-top-row! menu row

This procedure sets menu’s top row to be row. row is an integer where zero indicates that the first row is the top row.

This procedure will only have an effect when there are more rows in the menu than are displayed on the screen. If all the menu items can be displayed, this procedure will have no effect and return E_BAD_ARGUMENT.

The number of rows and columns that a menu displays is set by set-menu-format!.

It will return one of E_OK, E_BAD_ARGUMENT, E_NOT_CONNECTED if no menu items are attached to this menu, or E_SYSTEM_ERROR.

Procedure: top-row menu

Returns the number of the top menu row being displayed, or #f on failure.

Procedure: item-index item

This procedure returns the zero-origin index of this item in its containing menu’s item list or #f on failure.

Procedure: item-name item

Returns, as a string, the name of the menu item item.

Procedure: item-description item

Returns, as a string, the description of the menu item item.

Procedure: set-item-opts! item opts

Procedure: item-opts-on! item opts

Procedure: item-opts-off! item opts

These functions set or query the bit mask for item. There is only one option bit mask, O_SELECTABLE. When this is on, the item may be selected during menu processing. It defaults to on.

The procedure set-item-opts sets the bit mask of item to opts.

The procedure menu-opts-on turns the bits of opts on in item. The procedure menu-opts-off turns off the bits on opts in item.

These routines will return E_OK on success or E_SYSTEM_ERROR on failure.

Procedure: item-opts item

This procedure returns the options bit mask of item.

Procedure: set-item-value! item value

Procedure: item-value item

If the menu option O_ONEVALUE is turned off, the menu can have more than one item selected simultaneously. In this case, the procedure item-value can be used to query item to see if it is selected. It returns #t or #f.

An item can be selected with the procedure set-item-value!, which takes a menu item and a boolean value. It returns E_OK, E_SYSTEM_ERROR, or E_REQUEST_DENIED.

Procedure: item-visible? item

Returns #t if item is mapped onto the screen. If a menu has more menu items than can be displayed at once, only some of the menu items will be mapped onto the screen.