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& [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, type&
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 samples and descriptions, the TOOLBAR control which is the subject of the statement is identified by the handle of the dialog that owns the TOOLBAR (hDlg), and the unique control identifier (id&) you gave it upon creation in CONTROL ADD TOOLBAR.

On many forms of the TOOLBAR statement, 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.  Position parameters are always indexed to one (1=first, 2=second, and so on).

TOOLBAR ADD BUTTON hDlg, id&, image&, cmd&, style&, text$ [AT item&]

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:

%TBSTYLE_BUTTON

The button behaves like a standard push button.

%TBSTYLE_CHECK

The button is dual-state which toggles between the pressed and non-pressed state each time it's clicked.

%TBSTYLE_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.

%TBSTYLE_CHECKGROUP

A combination of check and group styles.

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& [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 "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 type& 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.

See also

DIALOG SHOW MODAL, DIALOG SHOW MODELESS, Dynamic Dialog Tools, CONTROL ADD TOOLBAR, CONTROL SET FONT, IMAGELIST