TOOLBAR statement

Purpose

A ToolBar control contains one or more buttons which act as shortcuts to menu items. The TOOLBAR statement is used to manipulate a TOOLBAR control.

Syntax

TOOLBAR ADD BUTTON hDlg, ID, image&, cmd&, style&, text$ [AT item&] [CALL callback]
TOOLBAR ADD SEPARATOR hDlg, ID, size& [,cmd&] [AT item&]
TOOLBAR DELETE BUTTON hDlg, id&, [BYCMD] item&
TOOLBAR GET STATE hDlg, ID, [BYCMD] item& TO datav&
TOOLBAR GET COUNT hDlg, ID TO datav&
TOOLBAR SET IMAGELIST hDlg, ID, hLst, ListType&
TOOLBAR SET STATE hDlg, ID, [BYCMD] item&, state&

hDlg

Handle of the dialog that owns the ToolBar.

hLst

Handle of the ImageList to be used for graphical items.

id&

The control identifier assigned with CONTROL ADD TOOLBAR.

cmd&

Command id number associated with this button.

image&

Image number selected (1=first, 2=second, etc.)

item&

A data item number. First=1, second=2...

size&

Size of the item expressed in pixels.

state&

A state descriptor to define specific attributes.

style&

Style descriptor bits for this button.

text$

A text string to be displayed on this button.

type&

A type descriptor to define specific attributes.

callback

A callback function which receives messages for the control.

datav&

A long integer variable to which result data is assigned.

txtv$

A string variable to which result text is assigned.

Remarks

A TOOLBAR control contains one or more buttons, each of which normally corresponds to a menu item. It is generally placed at the top of the client area of a dialog. When the user "presses" a tool bar button, the program reacts in the same way as if the command had been selected from a menu. It simply acts as a shortcut to common menu commands.

In each of the following descriptions, the TOOLBAR is referenced by the dialog handle (hDlg) and id&. In some cases a specific button is chosen with the item& parameter. If the BYCMD option is included, item& specifies the command id number of the button to be used. If not, item& describes the button by its position on the TOOLBAR. Since separators are considered to be a special class of button by the operating system, they must be counted when you calculate a position item number. Positions are always indexed to one (1=first, 2=second, and so on).

TOOLBAR ADD BUTTON hDlg, ID, image&, cmd&, style&, text$ [AT item&] [CALL callback]

A button is added to this TOOLBAR. The image to be displayed is selected from the attached IMAGELIST based upon the parameter image& (1=first, 2=second, etc.). The cmd& parameter specifies the command id number to be executed (with %WM_COMMAND) when the button is pressed. The style& parameter describes the style of the button from the following most often used attributes:

%BTNS_AUTOSIZE	The width of the button is calculated by the system, based upon the text and the image.
%BTNS_BUTTON	The button behaves like a standard push button.
%BTNS_CHECK	The button is dual-state which toggles between the pressed and nonpressed state each time it's clicked.
%BTNS_GROUP	Defines a group of buttons. When combined with the check style, it creates a button that stays pressed until another button in the group is pressed. This is similar to an option button or radio button.
%BTNS_CHECKGROUP	A combination of check and group styles.
%BTNS_DROPDOWN	Creates a drop-down style button that can display a list when clicked. Drop-down buttons send a %TBN_DROPDOWN notification instead of %WM_COMMAND.
%BTNS_NOPREFIX	The button text will not have an accelerator prefix associated with it.

The text$ parameter specifies the text to be displayed on the button.

If the optional "AT item&" clause is included, the button is inserted at the designated position (1=first, 2=second, etc.). Otherwise, it is added to the end of the list.

If the optional "CALL callback" clause is included, it specifies the name of a Callback Function that receives %WM_COMMAND messages when the button is clicked. If not specified, these command messages are sent to the dialog callback specified in DIALOG SHOW. Message routing by button allows you to easily determine which button generated the event.

If the Callback Function processes a message, it should return TRUE (non-zero) to prevent the message being passed unnecessarily to the dialog callback (if one exists). The dialog callback should also return TRUE if the notification message is processed by that Callback Function. Otherwise, the DDT engine processes unhandled messages.

TOOLBAR ADD SEPARATOR hDlg, ID, size& [,cmd&] [AT item&]

A separator is added to this TOOLBAR. It separates two buttons by the number of pixels specified in size&. It may be used to separate and distinguish two adjacent button groups (%tbstyle_group), or to just enhance the visual appearance. If the optional cmd& parameter is included, it's a unique numeric identifier for this separator. Of course, a separator can't be pressed like a button, so it doesn't literally allow a command to be sent. However, it may be used later with a BYCMD option in TOOLBAR DELETE, TOOLBAR SET STATE, etc. If the "AT item&" clause is included, the separator is inserted at the designated position (1=first, 2=second, etc.). Otherwise, it is added to the end of the list.

TOOLBAR DELETE BUTTON hDlg, ID, [BYCMD] item&

A BUTTON or SEPARATOR, specified by item&, is deleted from the TOOLBAR. The parameter item& may be positional, or it may represent a command id number with BYCMD.

TOOLBAR GET COUNT hDlg, ID to datav&

The number of buttons (and separators) on the TOOLBAR is retrieved and assigned to the long integer variable specified by datav&.

TOOLBAR GET STATE hDlg, ID, [BYCMD] item& TO datav&

The state descriptor bits for a specific button are retrieved and assigned to the variable designated by datav&. The parameter item& tells which button to check -- it may be positional, or it may be the command id number when used with BYCMD. The descriptor bits may consist of one or more of:

%TBSTATE_DISABLED	The button is disabled and grayed. (value=0)
%TBSTATE_CHECKED	The button is checked.
%TBSTATE_PRESSED	The button is pressed.
%TBSTATE_ENABLED	The button is enabled.
%TBSTATE_HIDDEN	The button is hidden.
%TBSTATE_INDETERMINATE	The button is indeterminate and grayed.
%TBSTATE_MARKED	The button is highlighted.

TOOLBAR SET IMAGELIST hDlg, ID, hLst, type&

The IMAGELIST specified by hLst is attached to this TOOLBAR control. The value of ListType& specifies the type of IMAGELIST:

0	Default images
1	Disabled images
2	Hot images

The graphical images contained in the IMAGELIST are displayed on the TOOLBAR buttons. Up to three IMAGELIST structures may be attached to each TOOLBAR control. The image to be displayed is determined by the specification made in TOOLBAR ADD BUTTON, and the current state of the button. When the TOOLBAR control is destroyed, any attached IMAGELIST is automatically destroyed.

TOOLBAR SET STATE hDlg, ID, [BYCMD] item&, state&

The state descriptor bits for the specified button are applied from the expression state&. The parameter item& tells which button to set -- it may be positional, or it may be the command id number when used with BYCMD. The descriptor bits state& may consist of:

%TBSTATE_DISABLED	The button is disabled and grayed. (value=0)
%TBSTATE_CHECKED	The button is checked.
%TBSTATE_PRESSED	The button is pressed.
%TBSTATE_ENABLED	The button is enabled.
%TBSTATE_HIDDEN	The button is hidden.
%TBSTATE_INDETERMINATE	The button is indeterminate and grayed.
%TBSTATE_MARKED	The button is highlighted.