Toolbar Custom Control
  Dockable Toolbar V1.2

Properties	Events	Methods

Description

The dockable toolbar is a custom control which allows toolbars to be added to a Visual Basic application quickliy and easily. In addition, when added to an MDI form the toolbars may be docked at the top, bottom, left or right of the form or made to float freely over the form. This functionality is becoming increasingly common in the applications offered by many of the major software producers.

File Name

TOOLBAR.VBX

Object Type

GSToolbar

See Also

Designing a Toolbar

Toolbars on MDI Forms

Using the Toolbar Control as a Container

Colour Mapping

256 Colour Support

ToolTips and Status Bar Support

Registration


  Designing a Toolbar

The first step in designing a toolbar is to create a bitmap (or bitmaps) containing the images to appear on the toolbar buttons. Each button requires a single image which represents the button in its normal state; the Toolbar control will add the button frame and bevels as well as generating the images required to display the button in each of the possible states.

You may choose either to create a single bitmap containing images for all buttons on the toolbar or to create a separate bitmap for each button. Internally the Toolbar control will always uses a single bitmap in order to reduce the resource requirements.

Using a single bitmap for all buttons

Using separate bitmaps for each button

The button size can be adjusted using the BtnWidth and BtnHeight properties while the spacing between buttons is controlled by the BtnSpacing property. The spacing between button groups (see below) is controlled by the GrpSpacing property.

The next step will normally involve setting the BtnGroup property of each button on the toolbar in order to provide the visual and functional groups required. This is easily done be selecting each button in turn using the right mouse button and entering the required group number into the VB property window. The order in which the buttons are displayed can be altered by setting the BtnPosition property; any button which is not required can be removed from the displayed toolbar by setting the BtnPosition property to -1.

When the visual design of the toolbar is complete the BtnName and BtnType properties should be set for each button. If the ToolTip control is being used to provide tooltips and status bar support then the BtnToolTip and BtnDescription properties should also be set.

The behaviour of each button group can be modified by setting the BtnGrpExclusive and BtnGrpAllUp properties for any button in the group.

The code required to handle button clicks should be placed in the ButtonClick event where the BtnName parameter can be used to identify the button which has been pressed.


Using a Single Bitmap

When creating a single bitmap for the toolbar all button images must be the same size and they should be arranged in order left-to-right and (if two or more rows are used) top-to-bottom.

Once the bitmap has been created it should be used to set the Picture property and the PicWidth and PicHeight properties should be set to the size of the image for each button.

This method is best suited to standard toolbars where the same combination of buttons is used is several applications. Some typical examples are supplied with the Toolbar control.

Note: The bitmaps used by the Toolbar control are fully compatible with those used by Visual C++  for in connection with the MFC Ctoolbar class.


Using a Bitmap for Each Button

When creating separate images for each button they must all be the same size. The toolbar can then be built by first setting the Buttons property to the required number of buttons and the PicWidth and PicHeight properties to the image size. Each button is then selected (using the right mouse button) and the required image is assigned to the BtnPicture property.

This method allows you to build up a library of button images and then assemble custom toolbars as required.

Note: This approach will be extended in a future release to allow all button details (e.g. name, description, tooltip) to be saved together with the button image so that building a new toolbar will be a simple case of selecting buttons from the library and arranging them on the toolbar.


  Dockable Toolbars on MDI Forms

When a toolbar control is placed directly on an MDI form it becomes dockable - i.e. it may be detached from its original position and reattached to the top, bottom, left or right of the MDI client area; it may also be left to float above the MDI form. The user manipulates a dockable toolbar by pressing the left mouse button when over any part of the toolbar which does not contain a button and dragging it to the new position. If dragged to the top, bottom, left or right of the MDI client area the toolbar will be docked in the new location otherwise a floating toolbar will be created.

The programmer can restrict the users control over the toolbar using the following properties:

AllowMove

AllowDockTop

AllowDockBottom

AllowDockLeft

AllowDockRight

AllowFloat

AllowSize

A docked toolbar can be changed to a floating toolbar by either dragging it as described above or by double clicking any area of the toolbar not covered by a button. Likewise, a floating toolbar can be returned to its most recent docked position by double clicking.

A floating toolbar can be closed by clicking in the close box at the top left corner; the only way to redisplay the toolbar is to set the Visible property to True in code.

The following events are provided to allow actions to be taken when the user manipulates a dockable toolbar:

StatusChange

FloatResize

FloatClose


  Using the Toolbar Control as a Container

The Toolbar control is a container and so other controls can be created within it. There is no problem in using this facility with fixed toolbars - i.e. toolbars created on non-MDI forms or within a container on an MDI form. However, controls placed within a toolbar which is created directly on an MDI form will not be visible at runtime. It is hoped that this limitation will be removed in a future release of the Toolbar control.


  Colour Mapping

The Toolbar control provides the ability to map colours in the bitmap used for the button images to colours selected by the programmer or by the user via the control panel. This capability may be controlled by setting the following properties:

MapBtnFace

MapBtnText

MapBtnHiLite

MapBtnShadow

If any of these properties are set to True then the corresponding colour in the button bitmap will be mapped to the colour defined by the ColorBtnFace, ColorBtnText, ColorBtnHiLite or ColorBtnShadow property as appropriate. If any of these properties are set to one of the system colours then the actual colour used to display the button image will be determined by the current control panel settings.

The bitmap colours affected are:

BtnFace	Light gray

BtnText	Black

BtnHiLite	White

BtnShadow	Dark gray


256 Colour Support

The toolbar control is palette aware and does support the use of 256 colour bitmaps. There are, however, some details which you must take into account if you wish to use this feature.

1.	The palette used by the toolbar control is determined when the Picture property is set. If the toolbar bitmap is constructed by setting the Buttons property and then loading individual bitmaps using the BtnPicture property then no palette will be used.

2.	Whenever the BtnPicture property is used to assign a new image to a button on the toolbar it is assumed that the new image uses the same palette as that currently being used by the toolbar.


  ToolTips and Status Bar Support

The Toolbar control does not provide direct support for tooltips or a context sensitive status bar. Instead, it works together with the ToolTip control to provide these capabilities. This not only reduces the size and complexity of the Toolbar control but also allows the handling of all tooltips and other context sensitive help to be co-ordinated by a single ToolTip control for the whole application. Design modularity is preserved through the BtnToolTip and BtnDescription properties which allow the tooltip text and status bar description for each toolbar button to be specified as part of the toolbar design process.

The Toolbar control is a container and so a ToolTip control can be placed within it. Since the ToolTip control is invisible at runtime this will not affect the appearance of the Toolbar control in any way.

Further details concerning the use of the ToolTip control can be found in the ToolTip Help file.


  Registration

The demonstration version of the Toolbar control are fully functional but may only be used in the development environment. Any attempt to use this version in conjunction with an EXE file will display a dialog box identifying it as a demonstration version and the control will fail to load.

If you find the Toolbar control useful then you can receive a full version, which may be distributed with your applications, by registering as follows :

1) In the SWREG forum on Compuserve. The fee is be $45.00 and the registration ID is xxxx.

2) By sending a cheque or money order for £30 to :

GC Consulting Services Ltd
Fellsgarth House
Hognaston
Ashbourne
Derbyshire DE6 1PR
ENGLAND

Note: The registered version of the Toolbar control includes a registered version of the ToolTip control to provide tooltips and status bar support. Anybody who has already registered the ToolTip control should see the ReadMe file for upgrade details.

In return for your registration you will receive the latest version of the Toolbar and ToolTip controls and be eligible for product support (via e-mail or through the MSBASIC forum on Compuserve).

Any questions should be sent to Graham Cockell (Compuserve ID 100113,2774) via e-mail or the MSBASIC forum.


Properties

Properties which apply only to the Toolbar control are marked with an asterisk (*). For all other standard properties please refer to the Microsoft Visual Basic Language Reference.

* (About)	* BtnName	* DockRankCount	* HwndDock
Align	* BtnNumber	* DockSeq	* HwndTB
* AllowDockBottom	* BtnPicture	* DockSeqCount	Index
* AllowDockLeft	* BtnPosition	DragIcon	Left
* AllowDockRight	* BtnSpacing	DragMode	* MapBtnFace
* AllowDockTop	* BtnState	Enabled	* MapBtnHiLite
* AllowFloat	* BtnTag	* FloatBtns	* MapBtnShadow
* AllowMove	* BtnToolTip	* FloatHeight	* MapBtnText
* AllowSize	* BtnType	* FloatLeft	* MouseBtn
* AutoSize	* BtnVisible	* FloatTop	MousePointer
BackColor	* BtnWidth	* FloatWidth	Name
* BackColorDock	* Buttons	FontBold	Parent
* BevelWidth	Caption	FontItalic	* PicHeight
* BorderX	* CaptionType	FontName	* Picture
* BorderY	ClipControls	FontSize	* PicWidth
* BtnDescription	* CloseBox	FontStrike	* Status
* BtnEnabled	* ColorBtnFace	FontUnder	* Style
* BtnGroup	* ColorBtnHilite	* GrpSpacing	Tag
* BtnGrpAllUp	* ColorBtnShadow	Height	Top
* BtnGrpExclusive	* ColorBtnText	HelpContextID	Visible
* BtnHeight	* DockRank	Hwnd	Width


About Property
(About) Property

Description

Displays version and other related information about the Toolbar control.

Usage

Click on the ellipses button (...) next to the property text to display the About dialog box.

Remarks

Only available at design time.


Style Property

Description

Determines the appearance of the toolbar.

Usage

[form.]toobar.Style[ = setting]

Remarks

The Style property settings are:

Setting	Description

0	(Default) 2D. The toolbar is drawn flat using the colour specified by the BackColor property.

1	3D Raised. The toolbar is drawn as if it is raised from the screen.

2	3D Inset. The toolbar is drawn as if it is inset into the screen.

When one of the 3D styles is chosen the BackColor property is ignored and the colours used to display the toolbar are determined by the ColorBtnFace, ColorBtnHiLite and ColorBtnShadow properties.

Data Type

Integer (Enumerated)

See Also

BevelWidth Property, ColorBtnFace, ColorBtnHiLite, ColorBtnShadow Properties


BevelWidth Property

Description

Determines the width in pixels of the bevel used to give the toolbar a 3D appearance.

Usage

[form.]toobar.BevelWidth[ = numericexpression]

Remarks

The colours used to draw the bevel are determined by the ColorBtnHiLite and ColorBtnShadow properties.

This property is ignored if the Style property is set to 0 (2D).

Data Type

Integer

See Also

Style Property, ColorBtnHiLite, ColorBtnShadow Properties


BorderX, BorderY Properties

Description

Determines the width in pixels of the border between the edge of the toolbar and the toolbar buttons.

Usage

[form.]toobar.BorderX[ = numericexpression]

[form.]toobar.BorderY[ = numericexpression]

Remarks

If the Style property is set to one of the 3D styles then the border is measured from the inside of the bevel used to produce the 3D effect.

Data Type

Integer

See Also

Style Property, BevelWidth Property


ColorBtnFace, ColorBtnText, ColorBtnHiLite, ColorBtnShadow Properties

Description

•	ColorBtnFace - Determines the colour used to paint the area of the button face not covered by the picture and the background colour of the toolbar if a 3D style is used.

•	ColorBtnText - Determines the colour used to draw text on the button face (not currently supported).

•	ColorBtnHiLite, ColorBtnShadow - Determines the colours used to paint the bevel for each button and for the toolbar if a 3D style is used.

Usage

[form.]toobar.ColorBtnFace[ = color]

[form.]toobar.ColorBtnText[ = color]

[form.]toobar.ColorBtnHiLite[ = color]

[form.]toobar.ColorBtnShadow[ = color]

Remarks

In addition to controlling the colours used to draw the toolbar these properties can also be used to transform the colours used in the pictures on the toolbar buttons. This colour mapping process is controlled by the MapBtnFace, MapBtnText, MapBtnHiLite and MapBtnShadow properties.

Data Type

Long

See Also

MapBtnFace, MapBtnText, MapBtnHiLite, MapBtnShadow Properties


MapBtnFace, MapBtnText, MapBtnHiLite, MapBtnShadow Properties

Description

Controls the colour mapping process used to determine the colours used when drawing the toolbar button pictures.

Usage

[form.]toobar.MapBtnFace[ = {True|False}]

[form.]toobar.MapBtnText[ = {True|False}]

[form.]toobar.MapBtnHiLite[ = {True|False}]

[form.]toobar.MapBtnShadow[ = {True|False}]

Remarks

If colour mapping is enabled by setting one or more of these properties to True then the colours used in the bitmap assigned to the Picture property will be transformed when displayed on the toolbar buttons as described below:

•	If the MapBtnFace property is True then any light gray pixels (RGB(192,192,192)) in the picture bitmap will be transformed to the colour specified by the ColorBtnFace property when the picture is drawn on the toolbar button.

•	If the MapBtnText property is True then any black pixels (RGB(0,0,0)) in the picture bitmap will be transformed to the colour specified by the ColorBtnText property when the picture is drawn on the toolbar button.

•	If the MapBtnHiLite property is True then any white pixels (RGB(255,255,255)) in the picture bitmap will be transformed to the colour specified by the ColorBtnHiLite property when the picture is drawn on the toolbar button.

•	If the MapBtnShadow property is True then any dark gray pixels (RGB(128,128,128)) in the picture bitmap will be transformed to the colour specified by the ColorBtnShadow property when the picture is drawn on the toolbar button.

If the corresponding ColorBtnxxx properties are set to system default colours then the colours used when the toolbar buttons are drawn will be determined by the current control panel settings.

Data Type

Integer (Boolean)

See Also

ColorBtnFace, ColorBtnText, ColorBtnHiLite, ColorBtnShadow Properties


AllowMove Property

Description

Determines whether or not the user can move the toolbar at runtime.

Usage

[form.]toobar.AllowMove[ = {True|False}]

Remarks

If this property is set to True the user can move the toolbar at runtime by dragging any part of it which is not covered by a button. The toolbar may be moved within a docking area, moved from one docking area to another or made to float in its own window.

If this property is set to False then the user cannot move the toolbar at runtime. Programmatic control using the Status, DockRank and DockSeq properties is not affected - i.e. you may change the toolbar status in code even if this property is set to False.

This property only relates to toolbars placed directly on an MDI form.

Data Type

Integer (Boolean)

See Also

AllowDockTop, AllowDockBottom, AllowDockLeft, AllowDockRight Properties, AlloFloat Property


AllowDockTop, AllowDockBottom, AllowDockLeft, AllowDockRight Properties

Description

Determines whether or not the user can dock the toolbar at runtime.

Usage

[form.]toobar.AllowDockTop[ = {True|False}]

[form.]toobar.AllowDockBottom[ = {True|False}]

[form.]toobar.AllowDockLeft[ = {True|False}]

[form.]toobar.AllowDockRight[ = {True|False}]

Remarks

A toolbar can be placed in any of the docking areas in code, even if the relevant property is set to False, by setting the Status property accordingly.

These properties only relates to toolbars placed directly on an MDI form.

Data Type

Integer (Boolean)

See Also

AllowMove Property, AllowFloat Property, DockRank Property, DockSeq Property


AllowFloat Property

Description

Determines whether or not the user can make the toolbar float at runtime.

Usage

[form.]toobar.AllowFloat[ = {True|False}]

Remarks

A toolbar can be made to float in code, even if this property is set to False, by setting the Status property to 4 (Floating).

This property only relates to toolbars placed directly on an MDI form.

Data Type

Integer (Boolean)

See Also

AllowMove Property, AllowDockTop, AllowDockBottom, AllowDockLeft, AllowDockRight Properties, AlloFloat Property


AllowSize Property

Description

Determines whether or not the user can change the size of a floating toolbar at runtime.

Usage

[form.]toobar.AllowSize[ = {True|False}]

Remarks

The size of a floating toolbar can be changed in code, even if this property is set to False, by setting the value of the FloatBtns property.

This property only relates to toolbars placed directly on an MDI form.

Data Type

Integer (Boolean)

See Also

AllowFloat Property


Status Property

Description

Determines the location, docked or floating, of the toolbar at runtime.

Usage

[form.]toobar.Status[ = setting]

Remarks

The status property settings are:

Setting	Description

0	(Default) Docked Top. The toolbar is docked in the docking area at the top of the MDI client area.

1	Docked Bottom. The toolbar is docked in the docking area at the bottom of the MDI client area.

2	Docked Left. The toolbar is docked in the docking area at the left of the MDI client area.

3	Docked Right. The toolbar is docked in the docking area at the right of the MDI client area.

4	Floating. The toolbar is not docked and is in a window of its own which floats over the main MDI form.

If the toolbar is docked by setting the Status property then the position of the toolbar within the docking area will be determined by the DockRank and DockSeq properties.

If a toolbar is made to float by setting the Status property then the poistion and size of the floating window will be determined by the FloatLeft, FloatTop and FloatBtns properties.

This property only relates to toolbars placed directly on an MDI form.

Data Type

Integer (Enumerated)

See Also

DockRank Property, DockSeq Property, FloatLeft, FloatTop Properties, FloatBtns Property


BackColorDock Property

Description

Determines the colour used to paint sections of the docking areas which are not covered by a toolbar.

Usage

[form.]toobar.BackColorDock[ = color]

Remarks

Setting this property for one toolbar will automatically update the property value for all other toolbars on the same MDI form.

This property only relates to toolbars placed directly on an MDI form.

Data Type

Long


DockRank, DockRankMax Properties
DockRank, DockRankCount Properties

Description

•	DockRank - Determines the position of the toolbar within a docking area.

•	DockRankCount - Determines the number of ranks in the docking area in which the toolbar is located.

Usage

[form.]toobar.DockRank[ = numericexpression]

[form.]toobar.DockRankCount

Remarks

The DockRank property controls the relative positions of toolbars when several are docked in the same docking area. Positioning of toolbars within a rank is controlled by the DockSeq property.

The DockRankCount property is only available at runtime and is read-only. The value for a non-docked toolbar will always be zero.

These properties only relate to toolbars placed directly on an MDI form.

Note: Currently setting DockRank and DockSeq properties at design time has no effect - each toolbar is added to the docking area specified by the Status property and is placed in a new rank with the ordering determined by order in which the toolbars are created. If you place multiple toolbars in the same docking area then you should include code in the Form_Load event to set the DockRank and DockSeq properties of each toolbar to achieve the order required. This behaviour will be changed in a later release when design time settings will be enforced.

Data Type

Integer

See Also

Status Property, DockSeq, DockSeqCount Properties


DockSeq, DockSeqMax Properties

Description

•	DockSeq - Determines the position of the toolbar within a docking area rank.

•	DockSeqCount - Determines the number of toolbars in the docking area rank in which the toolbar is located.

Usage

[form.]toobar.DockSeq[ = numericexpression]

[form.]toobar.DockSeqCount

Remarks

The DockSeq property is used to control the relative positions of toolbars when several are docked within the same docking area rank.

The DockSeqCount property is only available at runtime and is read-only. The value for a non-docked toolbar will always be zero.

These properties only relate to toolbars placed directly on an MDI form.

Note: Currently setting DockRank and DockSeq properties at design time has no effect - each toolbar is added to the docking area specified by the Status property and is placed in a new rank with the ordering determined by order in which the toolbars are created. If you place multiple toolbars in the same docking area then you should include code in the Form_Load event to set the DockRank and DockSeq properties of each toolbar to achieve the order required. This behaviour will be changed in a later release when design time settings will be enforced.

Data Type

Integer

See Also

Status Property, DockRank, DockRankCount Properties


FloatLeft, FloatRight Properties
FloatLeft, FloatTop Properties

Description

Determines the position of a floating toolbar relative to the top left corner of the MDI client area.

Usage

[form.]toobar.FloatLeft[ = numericexpression]

[form.]toobar.FloatTop[ = numericexpression]

Remarks

The value of these properties is always expressed in twips.

These properties only relate to toolbars placed directly on an MDI form.

Data Type

Long

See Also

FloatWidth, FloatHeight Properties, FloatBtns Property


FloatWidth, FloatHeight Properties

Description

Determines the size of a floating toolbar.

Usage

[form.]toobar.FloatWidth

[form.]toobar.FloatHeight

Remarks

These properties are used to determine the actual size of a floating toolbar window. They cannot, however, be used to change the size.which must be done by setting the FloatingBtns property.

The value of these properties is always expressed in twips.

These properties are only available at runtime and are read-only.

These properties only relate to toolbars placed directly on an MDI form.

Data Type

Long

See Also

FloatBtns Property, FloatLeft, FloatTop Properties


FloatBtns Property

Description

Determines the size of a floating toolbar window by controlling the maximum number of buttons which may be displayed in a row.

Usage

[form.]toobar.FloatBtns[ = numericexpression]

Remarks

The size of a floating toolbar is controlled by setting this property to the maximum number of buttons to be displayed in a single row. Setting this property to the number of buttons in the toolbar will produce a single row of buttons similar to a toolbar docked at the top or bottom of the MDI form whilst setting it to 1 will produce a layout similar to a toolbar docked at the left or right. Values between these two extremes will generally produce a rectangular window with the toolbar buttons arranged in several rows.

The default value is zero and this produces a layout where the width of the floating toolbar is controlled by the number of buttons in the largest group.

This property only relates to toolbars placed directly on an MDI form.

Data Type

Integer

See Also

FloatWidth, FloatHeight Properties


CaptionType Property

Description

Determines the size of the caption displayed for a floating toolbar.

Usage

[form.]toobar.CaptionType[ = setting]

Remarks

The CaptionType property settings are:

Setting	Description

0	None. The floating toolbar window does not have a caption.

1	(Default) Small. The floating toolbar has a small caption similar to that of the Visual Basic toolbox.

2	Standard. The floating toolbar has a standard sized caption.

This property only relates to toolbars placed directly on an MDI form.

Data Type

Integer (Enumerated)

See Also

CloseBox Property


CloseBox
CloseBox Property

Description

Determines whether or not the floating toolbar will have a close box.

Usage

[form.]toobar.CloseBox[ = {True|False}]

Remarks

If this property is set to True then a close box will be displayed at the top left corner of a floating toolbar (in the place normally used for the system menu button) and the user may close the floating toolbar by clicking on this box. The action of closing a floating toolbar in this way will set the Visible property to False and the only way of re-opening the toolbar is to set this property back to True in code.

This property will be ignored if the CaptionType property is set to 0 (None).

This property only relates to toolbars placed directly on an MDI form.

Data Type

Integer (Boolean)

See Also

CaptionType property


AutoSize Property

Description

Determines whether or not the size of a non-aligned toolbar is automatically adjusted according to the buttons contained on the toolbar.

Usage

[form.]toobar.AutoSize[ = {True|False}]

Remarks

If this property is set True then the size of a non-aligned toolbar will be automatically changed to fit the number of toolbar buttons contained. When set to False the user may control the size of the toolbar by dragging (design time only) or setting the Height and Width properties.

Data Type

Integer (Boolean)


Picture Property

Description

Determines the bitmap which provides the pictures to be drawn on each of the toolbar buttons.

Usage

[form.]toobar.Picture[ = picture]

Remarks

The Picture property settings are:

Setting	Description

(none)	(Default) No picture.

(bitmap)	Specifies the bitmap to be used to provide the picture for the top of each toolbar button.

The bitmap must contain images for each of the toolbar buttons in its normal state; the toolbar control will manipulate this image in order to display all other states as necessary. The bitmap is divided into rectangular sections according to the value of the PicWidth and PicHeight properties and each section defines a single toolbar button. Each button is identified by a BtnNumber which corresponds to the position of the image within the bitmap - letf-to-right and top-to-bottom.

Whenever a new value is assigned to this property the number of buttons will be recalculated and button details will be created/destroyed as necessary. In addition, the button display list will be reset and all buttons will be shown in the same order as they appear in the bitmap.

Note: Bitmaps used in conjunction with the Visual C++ MFC CToolbar class are fully compatible with the Toolbar control.

Data Type

Integer

See Also

PicWidth, PicHeight Properties, BtnPicture Property


PicWidth, PicHeight Properties

Description

Determines the size in pixels of a section of the Picture bitmap which defines the image for a single toolbar button.

Usage

[form.]toobar.PicWidth[ = numericexpression]

[form.]toobar.PicHeight[ = numericexpression]

Remarks

Whenever a new value is assigned to either of these properties the number of buttons will be recalculated and button details will be created/destroyed as necessary. In addition, the button display list will be reset and all buttons will be shown in the same order as they appear in the bitmap.

The default values used in conjunction with the default values for the BtnWidth and BtnHeight parameters will produce a toolbar with a standard appearance as defined in The Windows Interface Application Design Guide.

Data Type

Integer

See Also

Picture Property, BtnWidth, BtnHeight Properties


Buttons Property

Description

Determines the number of buttons on the toolbar.

Usage

[form.]toobar.Buttons

Remarks

Setting the value of this property will cause button definitions to be created/destroyed and the bitmap will be resized accordingly. This is most often used to add buttons to a toolbar at either design or runtime.

Changing the Picture, PicWidth or PicHeight properties will cause the number of buttons to be recalculated from the size of the Picture bitmap and the value of the PicWidth and PicHeight properties.

The BtnPosition property for each button can be used to determine if the button is currently displayed on the toolbar and, if so, at what position. A button which is not currently displayed is still a part of the toolbar and its property values are preserved.

Data Type

Integer

See Also

Picture Property, PicWidth, PicHeight Properties, BtnPosition Property


BtnWidth, BtnHeight Properties

Description

Determines the size in pixels of each button on the toolbar.

Usage

[form.]toobar.BtnWidth[ = numericexpression]

[form.]toobar.BtnHeight[ = numericexpression]

Remarks

The default values used in conjunction with the default values for the PicWidth and PicHeight parameters will produce a toolbar with a standard appearance.

Data Type

Integer

See Also

Picture Property, PicWidth, PicHeight Properties


BtnSpacing Property

Description

Determines the gap in pixels between adjacent buttons which are members of the same group.

Usage

[form.]toobar.BtnSpacing[ = numericexpression]

Remarks

The default value of -1 causes the button frames to overlap by a single pixel and produces the standard toolbar appearance.

Data Type

Integer

See Also

GrpSpacing Property, BtnGroup Property


GrpSpacing Property

Description

Determines the gap in pixels between adjacent buttons which are not members of the same group.

Usage

[form.]toobar.GrpSpacing[ = numericexpression]

Remarks

The default value of 6 is produces a standard toolbar appearance.

Data Type

Integer

See Also

BtnSpacing Property, BtnGroup Property


BtnNumber Property

Description

Determines the button whose properties are currently accessible.

Usage

[form.]toobar.BtnNumber[ = numericexpression]

Remarks

Property values for each button are accessed by first setting the BtnNumber property to the required button and then reading/writing the required property. The following button properties are affected by the BtnNumber setting:

BtnPosition

BtnPicture

BtnName

BtnType

BtnGroup

BtnGrpExclusive

BtnGrpAllUp

BtnToolTip

BtnDescription

BtnVisible

BtnEnabled

BtnState

 If this property is set to -1 then no button is selected and access to the above properties is illegal. At design time this property may be automatically set by clicking on a toolbar button with the right mouse button.

Note: If you are using VBAssist then you should either disable the property pop-ups or hold down the control key when using the right mouse button to select toolbar buttons at design time.

It is important to remember that the BtnNumber used to identify each button is determined by the position of the button image within the bitmap and not by the position of the button on the toolbar which is controlled by the BtnPosition property.

Data Type

Integer

See Also

Buttons Property, BtnPosition Property


BtnPosition Property

Description

Determines the position of a button on the toolbar.

Usage

[form.]toobar.BtnPosition[ = numericexpression]

Remarks

The order of buttons displayed on the toolbar is determined by the value of the BtnPosition property. Setting this property to -1 causes the button to be left out of the tollbar layout. This is not the same as setting the BtnVisible property to False which causes the button not to be displayed but continues to allocate space for the button when calculating the toolbar layout.

When the button information array is initialised (i.e. when the Picture, PicWidth or PicHeight property is set) the BtnPosition for each button is set to the BtnNumber.

The BtnNumber property must be set to select the required button before accessing this property.

Data Type

Integer

See Also

BtnNumber Property, BtnVisible Property


BtnPicture Property

Description

Determines the bitmap which provides the image drawn on the button.

Usage

[form.]toobar.BtnPicture[ = picture]

Remarks

The Picture property settings are:

Setting	Description

(none)	(Default) No picture.

(bitmap)	Specifies the bitmap to be used to provide the picture for the top of each toolbar button.

The bitmap must contain the image for the button in its normal state; the toolbar control will manipulate this image in order to display all other states as necessary. The bitmap should be the same size as specified by the PicWidth and PicHeight properties.

This property allows the image for an individual button to be accessed. Note that this can be used to copy button images from one toolbar to another at runtime.

The BtnNumber property must be set to select the required button before accessing this property.

Data Type

Picture

See Also

BtnNumber Property, Picture Property, PicWidth, PicHeight Properties


BtnName Property

Description

Determines the name used to identify the button when the ButtonClick event is fired.

Usage

[form.]toobar.BtnName[ = stringexpression]

Remarks

This property allows a meaningful name to be assigned to a button for use in the ButtonClick event.

The BtnNumber property must be set to select the required button before accessing this property.

Data Type

String

See Also

BtnNumber Property, ButtonClick Event


BtnType Property

Description

Determines the button characteristics.

Usage

[form.]toobar.BtnType[ = setting]

Remarks

The BtnType property settings are:

Setting	Description

0	Command. The button will depress when clicked with the left mouse button and then automatically return to the up position.

1	Toggle. The button will toggle between the up and down states when clicked with the left mouse button.

In addition to the up and down states of a Toggle button an indeterminate state may be selected by setting the BtnState property from code

The BtnNumber property must be set to select the required button before accessing this property.

Data Type

Integer (Enumerated)

See Also

BtnNumber Property, BtnState Property


BtnGroup Property

Description

Determines the group of which the button is a part.

Usage

[form.]toobar.BtnGroup[ = numericexpression]

Remarks

This property is used to arrange the buttons on the toolbar into groups. This affects both the visual appearance of the toolbar - groups are normally separated from one another by a small gap - and the behaviour of toggle buttons. The BtnGrpExclusive and BtnGrpAllUp properties are used to control the interaction of toggle buttons in the same group.

The BtnNumber property must be set to select the required button before accessing this property.

Data Type

Integer

See Also

BtnNumber Property, BtnGrpExclusive Property, BtnGrpAllUp Property


BtnGrpExclusive Property

Description

Determines whether more than one toggle button within a button group may be in the down state.

Usage

[form.]toobar.BtnGrpExclusive[ = {True|False}]

Remarks

If this property is set to True then only one toggle button within a group may be in the down state. Setting this property to True when more than one button is already in the down state will not change the state of those buttons.

Setting this property for one button will automatically update the property value for all other buttons in the same group.

The BtnNumber property must be set to select the required button before accessing this property.

Data Type

Integer (Boolean)

See Also

BtnNumber Property, BtnGroup Property, BtnGrpAllUp Property


BtnGrpAllUp Property

Description

Determines whether all the toggle buttons within a button group may be in the up state.

Usage

[form.]toobar.BtnGrpAllUp[ = {True|False}]

Remarks

If this property is set to False then at least one of the toggle buttons in a group must be in the down state. Setting this property to False when no button in the group is in the down state will not change the state of any button.

Setting this property for one button will automatically update the property value for all other buttons in the same group.

The BtnNumber property must be set to select the required button before accessing this property.

Data Type

Integer (Boolean)

See Also

BtnNumber Property, BtnGroup Property, BtnGrpExclusive Property


BtnToolTip Property

Description

Determines the tooltip text which is passed to the ToolTip control when the mouse hovers over the button.

Usage

[form.]toobar.BtnToolTip[ = stringexpression]

Remarks

This property is used to provide the text which is passed to the ToolTip control GetToolTip event and is not used directly by the Toolbar control (which does not provide tooltips itself). This approach allows the handling of all tooltips and other context sensitive help related functions to be handled centrally by the ToolTip control rather than being distributed over several controls.

The BtnNumber property must be set to select the required button before accessing this property.

Data Type

String

See Also

BtnNumber Property, BtnDescription Property, ToolTips and Status Bar Support


BtnDescription Property

Description

Determines the button description which is passed to the ToolTip control when the mouse moves over the button.

Usage

[form.]toobar.BtnDescription[ = stringexpression]

Remarks

This property is used to provide the text which is passed to the ToolTip control MouseEnter event and is not used directly by the Toolbar control. This approach allows the handling of all tooltips and other context sensitive help related functions to be handled centrally by the ToolTip control rather than being distributed over several controls.

The BtnNumber property must be set to select the required button before accessing this property.

Data Type

String

See Also

BtnNumber Property, BtnToolTip Property, ToolTips and Status Bar Supportl


BtnVisible Property

Description

Determines whether or not the button is visible.

Usage

[form.]toobar.BtnVisible[ = {True|False}]

Remarks

If this property is set to False then the button will not be displayed but space will still be allocated when calculating the toolbar layout. The button can be removed completely from the toolbar display layout using the BtnPosition property.

The BtnNumber property must be set to select the required button before accessing this property.

Data Type

Integer (Boolean)

See Also

BtnNumber Property, BtnPosition Property


BtnEnabled Property

Description

Determines whether or not the button is enabled.

Usage

[form.]toobar.BtnEnabled[ = {True|False}]

Remarks

If this property is set to False then the button will not respond to mouse clicks.

The BtnNumber property must be set to select the required button before accessing this property.

Data Type

Integer (Boolean)

See Also

BtnNumber Property


BtnState Property

Description

Determines the state of a toggle button.

Usage

[form.]toobar.BtnState[ = setting]

Remarks

The BtnState property settings are:

Setting	Description

0	(Default) Normal. Toggle button in up state.

1	Checked. Toggle button in down state.

2	Indeterminate. Toggle button in indeterminate state.

Changing the state of a toggle button will generate a ButtonClick event. Setting this property to 1 (Checked) for a command button will generate a ButtonClick event.

The BtnNumber property must be set to select the required button before accessing this property.

Data Type

Integer (Enumerated)

See Also

BtnNumber Property, BtnType Property


BtnTag Property

Description

Used to store any additional information concerning the button which is required by your program.

Usage

[form.]toobar.BtnTag[ = stringexpression]

Remarks

The BtnNumber property must be set to select the required button before accessing this property.

Data Type

Integer (Enumerated)

See Also

BtnNumber Property


MouseBtn Property

Description

This property can be used to determine which button is under the mouse at any time.

Usage

[form.]toobar.MouseBtn

Remarks

If the mouse is over a button this property will return the button number; if the mouse is not over a button the value returned will be -1.

This property is only available at runtime and are read-only.

Data Type

Integer

See Also

BtnNumber Property


HwndDock, HwndTB Properties

Description

Specifies the window handles of the MDI docking area which currently contains the toolbar and the window currently being used to display the toolbar.

Usage

[form.]toobar.HwndDock

[form.]toobar.HwndTB

Remarks

An MDI form has four docking areas - top, bottom, left and right - each of which is represented by a window. The HwndDock property can be used to obtain the window handle of the docking area in which the toolbar is currently placed. The value returned will be zero for floating and non-MDI toolbars.

Docked and floating toolbars use special windows to display the toolbar.The HwndTB property can be used to obtain the window handle of the actual window being used to display the toolbar.

These properties are only available at runtime and are read-only.

Data Type

Integer


Events

Events which apply only to the Toolbar control are marked with an asterisk (*). For all other standard events please refer to the Microsoft Visual Basic Language Refernece.

* ButtonClick	* FloatClose	MouseMove
DragDrop	* FloatResize	MouseUp
DragOver	MouseDown	* StatusChange


ButtonClick Event

Description

Occurs when the user presses and release the left mouse button over a toolbar button.

Syntax

Sub toolbar_ButtonClick([Index As Integer,] BtnName As String, BtnNumber As Integer, BtnState As Integer)

Remarks

The ButtonClick event uses these arguments:

Argument	Description

Index	Uniquely identifies a control if it is in a control array.

BtnName	The name of the button which was clicked.

BtnNumber	The number of  the button which was clicked.

BtnState	The state of the toggle button after being clicked.


StatusChange Event

Description

Occurs when the docking status of the toolbar is changed.

Syntax

Sub toolbar_StatusChange([Index As Integer,] PrevStatus As Integer)

Remarks

The StatusChange event uses these arguments:

Argument	Description

Index	Uniquely identifies a control if it is in a control array.

PrevStatus	The previous status of the toolbar (see Status property for details of possible values).

See Also

Status Property


FloatResize Event

Description

Occurs when the user resizes the floating toolbar.

Syntax

Sub toolbar_FloatResize([Index As Integer])

Remarks

The argument Index uniquely identifies a control if it is in a control array.

See Also

AllowSize Property


FloatClose Event

Description

Occurs when the user closes a floating toolbar.

Syntax

Sub toolbar_FloatClose([Index As Integer])

Remarks

The argument Index uniquely identifies a control if it is in a control array.

See Also

CloseBox Property


Methods

The following standard methods are supported - please refer to the Microsoft Visual Basic Language Refernece for more details.

Drag	Move	Refresh