CW_ITTOOLBAR

The CW_ITTOOLBAR function creates a toolbar base compound widget. The items in the toolbar correspond to the operations or manipulators 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_ITTOOLBAR widget automatically performs the following actions:

For each item in the container, creates either a bitmap button or a droplist/combobox:

If the item was registered with the DROPLIST_ITEMS property set, a droplist or combobox is created. If the DROPLIST_EDIT property is set on the item, an editable combobox widget is included on the toolbar — otherwise a droplist is included. The value of the DROPLIST_INDEX property is used to select the initial value. The value of the DISABLE property determines the initial sensitivity of the droplist or combobox. See IDLitTool::RegisterOperation for details on using these properties.

If the item was not registered with the DROPLIST_ITEMS property set, a bitmap button is created. The value of the item's ICON property is used for the bitmap filename (or, if the ICON property is not set, the file resource/bitmaps/new.bmp is used). The value of the DISABLE property determines the initial sensitivity of the button. The value of the NAME property is used for the button tooltip.

Registers itself 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 toolbar will be notified and will automatically update itself. The CW_ITTOOLBAR widget listens for the following messages:

Table B-4: Messages Understood by CW_ITTOOLBAR
Message	Value	Description / Result
ADDITEMS	Object identifier	An object was added to the container. New buttons or droplists are added to the toolbar as necessary.
REMOVEITEMS	Object identifier	An object was removed from the container. Buttons or droplists are removed from the toolbar as necessary.
SELECT	0 or 1	For exclusive toolbars, the exclusive button is displayed as selected (1) or unselected (0).
SENSITIVE	0 or 1	The button is displayed as sensitive (1) or insensitive (0).
SETPROPERTY	Property identifier	If NAME property changed, the button tooltip is updated with the new value.
SETVALUE	String value	The droplist or combobox value is changed to match the new string value. If the item is a combobox and the specified string does not match an existing list item, the new value is added at the top.

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

When a toolbar button or droplist/combobox item is selected, calls the IDLitTool::DoAction method to execute the corresponding operation.

Syntax

Result = CW_ITTOOLBAR(Parent, UI, Target [, /EXCLUSIVE] [, ROW=integer] [, UNAME=string] [, UVALUE=value] )

Return Value

This function returns the widget ID of the newly-created toolbar base.

Arguments

Parent

The widget ID of the parent base for the new toolbar.

UI

An object reference of 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 toolbar. Target can either be a full identifier or be relative to the IDLitTool object associated with the user interface object specified by UI.

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

Keywords

EXCLUSIVE

Set this keyword to create a toolbar with exclusive buttons, where only one button can be selected at a time, and remains selected until another button is selected. The default is to create a pushbutton toolbar, which allows multiple selections.

Note
An EXCLUSIVE toolbar cannot contain a droplist or combobox item.

ROW

Set this keyword equal to an integer specifying the number of rows used for laying out the toolbar buttons and droplists. The default is 1.

Tip
To create a vertical toolbar, set ROW equal to the number of children in the container specified by Target.

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_ITTOOLBAR 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