CW_ITMENU

The CW_ITMENU function creates a top-level pulldown menu compound widget. The menu items in the pulldown menu correspond to the operations contained in a specified container object within the OPERATIONS container of the associated iTool. (See iTool Object Hierarchy for a description of the iTool object hierarchy.)

Warning
This routine can only be used in the context of a user-created iTool. See Overview of iTools Compound Widgets for details.

The CW_ITMENU widget automatically performs the following actions:

For each child in the folder, creates either a submenu (if the child is a container object) or a menu item (if the child is a registered operation). In both cases the child's NAME property is used for the menu item value.

If the child is a container, CW_ITMENU recursively creates submenus and menu items for that child's children.

If the child is an operation, CW_ITMENU creates a menu item. The child's ACCELERATOR property is used for the keyboard accelerator (unless the CONTEXT_MENU keyword is set). The DISABLE property is used to determine initial sensitivity. If the CHECKED property is set, a checked menu item is created. If SEPARATOR is set, a menu separator is inserted before the menu item. See IDLitTool::RegisterOperation for details on using these properties.

Registers the newly-created menu with the specified user interface object.

Adds itself as an observer of the specified container. If any changes occur to items within the container, then the menu will be notified and will automatically update itself. The CW_ITMENU widget listens for the following messages:

Table B-1: Messages Understood by CW_ITMENU
Message	Value	Description / Result
ADDITEMS	Object identifier	An object was added to the container. New menu and submenu items are added as necessary.
REMOVEITEMS	Object identifier	An object was removed from the container. Menu and submenu items are removed as necessary.
SELECT	0 or 1	For checked menu items, the menu item is displayed as checked (1) or unchecked (0).
SENSITIVE	0 or 1	The menu item is displayed as sensitive (1) or insensitive (0).
SETPROPERTY	Property identifier	If the NAME property changed, the menu item name is updated with the new value.

See iTool Messaging System for a discussion of observers and notifications.

When a menu item is selected, calls the IDLitTool::DoAction method to execute the corresponding operation.

Syntax

Result = CW_ITMENU(Parent, UI, Target [, /CONTEXT_MENU] [, UNAME=string] [, UVALUE=value] )

Return Value

This function returns the widget ID of the newly-created pulldown menu.

Arguments

Parent

The widget ID of the parent for the new menu. The parent must be one of the following:

A base widget.

A widget created using the MBAR keyword on a top-level base.

A button widget which has the MENU keyword set.

If the CONTEXT_MENU keyword is set, a widget that supports context events.

UI

An object reference to the IDLitUI object associated with the iTool. See User Interface Object for information on creating user interface objects.

Target

A string specifying the identifier of an item of class IDLitContainer that contains the items to be included in the menu. Target can be either a full identifier or relative to the IDLitTool object associated with the user interface object specified by UI.

All items within the Target container must either be of class IDLitContainer or be operations registered with the IDLitTool object associated with the user interface object specified by UI.

Keywords

CONTEXT_MENU

Set this keyword to create a context menu instead of a standard pulldown menu. If this keyword is set, Parent must be a widget of one of the following types: WIDGET_BASE, WIDGET_DRAW, WIDGET_TEXT, WIDGET_LIST, WIDGET_PROPERTYSHEET, WIDGET_TABLE, WIDGET_TEXT, or WIDGET_TREE.

Note
If the CONTEXT_MENU keyword is set, the ACCELERATOR property is ignored for all contained items.

UNAME

Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID.

To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name.

UVALUE

The "user value" to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created. If UVALUE is not present, the widget's initial user value is undefined.

The user value for a widget can be accessed and modified at any time by using the GET_UVALUE and SET_UVALUE keywords to the WIDGET_CONTROL procedure.

Keywords to WIDGET_CONTROL and WIDGET_INFO

The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets.

See Creating a Compound Widget (User Interface Programming) for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO.

Widget Events Returned by the CW_ITMENU Widget

CW_IT* compound widgets do not return widget events. All interaction with the iTool user interface is accomplished via the iTool messaging system and the callback mechanism implemented in the user interface creation routine.

Version History

Introduced: 6.1