Creating toolbar controls

Using Toolbar Controls

Top Previous Next

About Toolbar controls

A toolbar is a control window that contains one or more buttons. Each button sends a command message to the parent window when the user chooses it. Typically, the buttons in a toolbar correspond to items in the application's menu, providing an additional and more direct way for the user to access an application's commands.

Creating the control

A toolbar control is created and added to a window with the LOADTOOLBAR function. A bitmap is used as the images for the toolbar buttons and can be loaded directly from a handle returned by LOADIMAGE or from a bitmap resource compiled in the executable. A toolbar has a control ID that allows communicating to the control with the CONTROLCMD statement. The syntax of LOADTOOLBAR:

success = LOADTOOLBAR( window | dialog, resourceID | handle, toolbarID, buttonIDs[] , numIDs, style )

When a button on a toolbar is pressed Windows will send an @IDCONTROL message to your handler subroutine with the ID of the button contained in @CONTROLID. The variable buttonIDs is an array of type INT that is dimensioned to the number of buttons in the toolbar. Each value in the array corresponds to the ID of a button or 0 for a separator. numIDs is the size of the buttonIDs array

The function returns zero on failure or non-zero for success.

The following is an example snippet of loading a toolbar with 7 button images. A separator is used between buttons 3 and 4.

Assume an open window w1

DEF hbitmap:UINT
DEF tbArray[8]:INT
tbArray = 2,3,4,0,5,6,7,8
hbitmap = LOADIMAGE(GETSTARTPATH + "toolbar.bmp",@IMGBITMAP | @IMGMAPCOLORS)

REM this toolbar is loaded from a bitmap handle
IF LOADTOOLBAR(w1,hbitmap,998, tbArray, 8, @TBTOP | @TBFROMHANDLE)
CONTROLCMD w1,998,@TBENABLEBUTTON,3,0
ENDIF

In the snippet above we assign an ID of 998 to the toolbar control. After the toolbar is loaded CONTROLCMD is used to disable a the button with an ID of 3.

Toolbar control styles

The following toolbar style flags can be specified in the LOADTOOLBAR function.

@TBTOP

Creates a toolbar that is positioned at the top of the window. This is the default

@TBBOTTOM

Creates a toolbar this is positioned at the bottom of the window

@TBRIGHT

Creates a toolbar that is positioned at the right of the window. Must be combined with @TBNORESIZE. Vertical toolbars cannot be resized automatically with @TBRESIZE. The width and height of a vertical toolbar must be set with the SETSIZE statement.

@TBLEFT

Creates a toolbar the is positioned at the left edge of the window. Must be combined with @TBNORESIZE. Vertical toolbars cannot be resized automatically with @TBRESIZE. The width and height of a vertical toolbar must be set with the SETSIZE statement.

@TBNOALIGN

Prevents the control from automatically moving to the top or bottom of the parent window. Instead, the control keeps its position within the parent window despite changes to the size of the parent window. If the @TBTOP or @TBBOTTOM style is also used, the height is adjusted to the default, but the position and width remain unchanged.

@TBWRAPABLE

Creates a toolbar control that can have multiple lines of buttons. Toolbar buttons can "wrap" to the next line when the toolbar becomes too narrow to include all buttons on the same line.

@TBFLAT

Creates a toolbar with flat buttons. The buttons and toolbar are transparent with this style. Available on systems with Internet Explorer 3.0 and above installed.

@TBLIST

Creates a toolbar with buttons that can have text to the right of the buttons. Available on systems with Internet Explorer 3.0 and above installed.

@TBNORESIZE

Prevents the control from using the default width and height when setting its initial size or a new size. Instead, the control uses the width and height specified in the request for creation or sizing. Control may then be positioned with the SETSIZE statement

@TBFROMHANDLE

Specifies the bitmap is to loaded from a handle returned by LOADIMAGE instead of from resources.

@TBTRANSPARENT

Allows non flat toolbars to have transparent backgrounds. Useable on systems with Internet Explore 4.0 or higher installed.

@TBTOOLTIPS

Allows toolbars to display a tool tip when the cursor hovers over a button. The text for the tool tips is set with the @TBSETTIP command.

NOTE: always check @NOTIFYCODE if your toolbar has tooltips. The tooltips themselves send notification messages using the same button ID. @NOTIFYCODE will be 0 if the button was clicked on.

Controlling the toolbar control.

The toolbar control is accessed through the CONTROLCMD statement/function. CONTROLCMD can be used as a statement or function depending on the command issued.

Statements and Functions

CONTROLCMD window | dialog, toolbarID, @TBRESIZE

Use in response to the @IDSIZE message to automatically change the size of the toolbar to fit the window. This command is ignored if the toolbar is created with the @TBNORESIZE flag.

CONTROLCMD window | dialog, toolbarID, @TBSETBITMAPSIZE, width, height

Sets the size of the bitmap images for the buttons. The default size is 16 x 15

CONTROLCMD window | dialog, toolbarID, @TBSETBUTTONSIZE, width, height

Sets the size of the buttons. The default size is 24 x 23. The size of the buttons must be at least 7 pixels greater in width and height than the bitmap size otherwise the bitmap images will be clipped.

CONTROLCMD window | dialog, toolbarID, @TBENABLEBUTTON, buttonID, enable

Enables or disables the button specified by buttonID. use 1 to enable and 0 to disable the button. A button that is disabled can not be pressed and has a 'grayed out' appearance.

CONTROLCMD window | dialog, toolbarID, @TBSETLABELS, strLabels

Sets the button labels used with the @TBLIST and @TBFLAT styles. Strings consist of text labels separated by a bar '|' symbol and ending with two bar '||' symbols. Example:

CONTROLCMD d1, 999, @TBSETLABELS, "New|Open|Save|Cut|Copy|Paste|Print|Help||"

CONTROLCMD window | dialog, toolbarID, @TBSETBUTTONSTYLE, buttonID, style

Changes the behavior of a toolbar button. This command is only available on systems that have Internet Explorer 4.0 or greater installed. Style can be a combination of:

@TBBUTTONCHECK - Button stays pressed down until released by clicking on again

@TBBUTTONGROUP - When combined with @TBBUTTONCHECK creates a button that stays pressed until another button in the group is pressed.

state = CONTROLCMD ( window | dialog, toolbarID, @TBGETBUTTONSTATE, buttonID )

Returns 1 if button is currently pressed. Only applied to buttons with the @TBBUTTONCHECK style.

width = CONTROLCMD ( window | dialog, toolbarID, @TBGETBUTTONWIDTH )

Returns the width of the toolbar buttons

height = CONTROLCMD ( window | dialog, toolbarID, @TBGETBUTTONHEIGHT )

Returns the height of the toolbar buttons

CONTROLCMD window | dialog, toolbarID, @TBSETTIP, buttonID, tiptext

Sets the tool tip text for a button. Toolbar must have been created with @TBTOOLTIPS.

Design Considerations

Horizontal toolbars are more natural to view then vertical ones. The eyes naturally follow the left to right ordering of a standard toolbar placed at the top of a window. Vertical toolbars tend to be more awkward to use.

MDI windows will automatically resize the client window to fit toolbars and status windows. A regular window places the toolbar in its client area so you need to take the height (width) of the toolbar into account when drawing to the window. Even though a vertical toolbar won't respond to the @TBRESIZE command you should still use CONTROLCMD window | dialog, ID, @TBRESIZE on vertical toolbars in an MDI window. This tells the MDI frame to reserve space for the toolbar after sizing. Use the command after resizing the toolbar with SETSIZE

Toolbars on the bottom and right will flicker slightly when resized. This is due to the toolbar needing to refresh when moved. Consider using the top and right positions.

If you need more than one toolbar at the top you will need to specify @NORESIZE and handle the resizing and positioning manually with the SETSIZE statement. @TBRESIZE only handles single toolbars on an edge.