CoolBar class

A CoolBar is a bar of bands. Each band has a grip, a caption and an optional picture, and holds one control, such as a toolbar or a combo box. The user drags a band by its grip to another place, and along a row to give it more room or less.

A cool bar of two rows: the bands File and Edit share the first row, and the band Find has the second. Each band has a grip at its left and shows its caption.
CoolBar1.Bands.Clear
CoolBar1.Bands.Add , "file", "File"
CoolBar1.Bands.Add , "edit", "Edit"
CoolBar1.Bands.Add , "find", "Find", , True      ' on a row of its own
Debug.Print CoolBar1.Bands.Count; CoolBar1.RowCount
' Output:
'  3  2

The control stands in place of the CoolBar of the Microsoft Windows common controls 3 (COMCT332.OCX). The package’s classes for its parts are CbrBands, the collection of the bands, and CbrBand, one band.

Of the common members, the control has those under Name and place but HelpContextID, Window handles, Font and visual styles, Mouse, Dragging the control, OLE drag and drop and Right-to-left, RightToLeftLayout included. It never takes the focus, so it has no keyboard events.

Bands and rows

Bands returns the collection of the bands, and Add puts a band into it. The bands lie in rows: a band starts a row where its NewRow is True, and otherwise goes after the band before it. A control newly drawn on a form has three bands, the second of them on a row of its own.

Dim Band As CbrBand
For Each Band In CoolBar1.Bands
    Debug.Print Band.Index; Band.NewRow
Next
Debug.Print CoolBar1.RowCount
' Output:
'  1 False
'  2 True
'  3 False
'  2

The sample is a control as the form designer makes it. A form file that was saved with other bands has those bands.

A band has two places. Its Index is its place in the collection, and stays when the user or the program moves the band. Its Position is its place in the cool bar, counted along the rows from the first band, and ItemFromPosition returns the band at a position.

CoolBar1.Bands.Clear
CoolBar1.Bands.Add , "file", "File"
CoolBar1.Bands.Add , "edit", "Edit"
CoolBar1.Bands("edit").Position = 1
Debug.Print CoolBar1.Bands("edit").Position; CoolBar1.Bands("edit").Index
Debug.Print CoolBar1.Bands.ItemFromPosition(1).Key
' Output:
'  1  2
' edit

The height of a horizontal cool bar follows its rows of bands, and the width of a vertical one follows them. When it changes, the cool bar raises Resize and then HeightChanged.

Holding a control

A band holds the control that its Child names. The control has to be on the cool bar: drawn on it in the form designer, or moved onto it with Set control.Container. The cool bar then keeps the control in the band’s area, moving and sizing it as the band moves and changes its size.

Set ComboBoxW1.Container = CoolBar1          ' the combo box is now on the cool bar
Set CoolBar1.Bands(2).Child = ComboBoxW1     ' and in the second band

A control that is not on the cool bar, though it is on the same form, and the cool bar itself, raise run-time error 380 when they are given as Child, or as the Child argument of Add. A band without a control has a placeholder window of the cool bar’s own.

MinWidth and MinHeight are the smallest room the band keeps for the control, and IdealWidth the width at which the control shows everything it has. ContainedControls lists the controls on the cool bar.

Moving and resizing by the user

The user drags a band by its grip to another place in the same row or in another row, and drags the boundary between two bands of a row to give one of them more room. FixedOrder set to True keeps the order of the bands, though a band can still go to another row, and a band’s Gripper says whether its grip shows. BandBeforeDrag is raised when a drag begins, and a handler can refuse it. BandAfterDrag is raised when it ends, and LayoutChanged after the layout has changed. DblClickToggle lets a double-click on a band maximize it or minimize it, and MinMax is raised before.

Private Sub CoolBar1_BandBeforeDrag(ByVal Band As CbrBand, Cancel As Boolean)
    Cancel = (Band.Key = "menu")           ' the menu band stays where it is
End Sub

A band of style CbrBandStyleFixedSize keeps its width, and the user cannot resize it.

The chevron

A band whose UseChevron is True shows a chevron button when the cool bar gives it less room than its IdealWidth. Pressing the button raises BandChevronPushed with the button’s place, where the program shows the part of the band that no longer fits. PushChevron presses it from code.

Private Sub CoolBar1_BandChevronPushed(ByVal Band As CbrBand, ByVal Left As Single, ByVal Top As Single, ByVal Width As Single, ByVal Height As Single)
    Debug.Print Band.Key; Left; Top
End Sub

Appearance

BandBorders draws a line between the bands, and BorderStyle a border around the cool bar. Picture is a bitmap that fills the background of the bands, and a band’s FixedBackground says whether the picture moves with the band or stays fixed to the cool bar. A band takes the cool bar’s picture and colors unless its UseCoolBarPicture or UseCoolBarColors is False. A program with visual styles draws the bands in the style of Windows, and the cool bar’s BackColor then has no effect.

ImageList gives the bands their pictures, which a band names by its Image. Orientation set to CbrOrientationVertical makes the cool bar a column of bands, with the grips on top of the bands unless VerticalGripper is True.

Finding a band

HitTest returns the band at a point, and says what part of the band it is: the grip, the caption, the area of the control, the chevron, or the boundary between two bands.

Private Sub CoolBar1_MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single)
    Dim Band As CbrBand, Part As CbrHitResultConstants
    Set Band = CoolBar1.HitTest(X, Y, Part)
    If Not Band Is Nothing Then Debug.Print Band.Key; Part
End Sub

With MouseTrack set to True the cool bar raises BandMouseEnter and BandMouseLeave as well.

When the pointer moves onto a band from outside the cool bar, MouseEnter comes first, then BandMouseEnter. When it leaves the cool bar, BandMouseLeave comes before MouseLeave. A click raises MouseDown, MouseUp and then Click.

Properties

Align

The edge of the form that the control is attached to, where it takes the form’s whole width or height. A member of AlignConstants. Default: vbAlignNone.

Note 1.8.141.0 BETA 1042

twinBASIC has not implemented Align: an assignment compiles with the warning TB0009 and changes nothing, and the property goes on returning vbAlignNone. A program places and sizes the cool bar itself.

BackColor

The color behind the bands. OLE_COLOR. Default: vbButtonFace. It shows only while the control is drawn without visual styles, with VisualStyles set to False.

BandBorders

Whether a line is drawn between the bands. Boolean. Default: True.

Bands

The collection of the bands. A CbrBands object, read-only.

BorderStyle

Whether the cool bar has a border of one line. Integer: 0 for none or 1 for a line (the default).

Another value raises run-time error 380.

ContainedControls

The controls that were put onto the cool bar. A ContainedControls collection, read-only.

DblClickToggle

Whether the cool bar maximizes or minimizes a band when the user double-clicks it. Boolean. Default: False.

DoubleBuffer

Whether the cool bar paints in a bitmap and draws that, which avoids flicker. Boolean. Default: True.

FixedOrder

Whether the user is kept from moving the bands to other places. Boolean. Default: False.

ForeColor

The color of the captions of the bands. OLE_COLOR. Default: vbButtonText.

hWndToolTip

The handle of the window that shows the bands’ tips. LongPtr, read-only. It is 0 until ShowTips has been set to True.

ImageList

The image list whose pictures the bands show. A Variant: an ImageList control, the handle of an image list as a Long, or the name of an ImageList control on the same form as a string. Reading it returns what was assigned, or Nothing. A name that no such control has, and Nothing, take the image list away.

A control that is not an ImageList raises run-time error 35610, and a value of another type raises error 13.

An image list that has no picture is not taken, as ImageList says.

Orientation

Whether the bands run in rows or in columns. A member of CbrOrientationConstants. Default: CbrOrientationHorizontal.

A change exchanges the cool bar’s width and height. A value that is not a member raises run-time error 380.

Picture

A bitmap that fills the background of the bands. A picture object. Default: Nothing. A band shows it while its UseCoolBarPicture is True.

RowCount

The number of rows of bands. Long, read-only.

ShowTips

Whether the cool bar shows the ToolTipText of a band in a small window when the pointer rests on the band’s caption. Boolean. Default: False.

VariantHeight

Whether the bands of a row can have different heights. Boolean. Default: True. With False a row is as high as the highest band, and all its bands that high.

VerticalGripper

Whether the grip of a band in a vertical cool bar is drawn upright, beside the band’s contents, instead of lying along the band’s top. Boolean. Default: False.

Methods

HitTest

Returns the band at a point, and says which part of it the point is on.

Syntax: object.HitTest( X, Y [, HitResult ] ) As CbrBand

X, Y
required Single: the point, in the container’s scale units, measured from the cool bar’s top left corner.
HitResult
optional A member of CbrHitResultConstants, by reference: the part of the band that the point is on.

Where no band is at the point, the method returns Nothing and leaves HitResult as it was.

Events

BandAfterDrag

Raised when the user has dragged a band to another place.

Syntax: object_BandAfterDrag( Band As CbrBand, NewPosition As Long )

Band
The band.
NewPosition
The Position the band has now.

BandBeforeDrag

Raised when the user begins to drag a band.

Syntax: object_BandBeforeDrag( Band As CbrBand, Cancel As Boolean )

Band
The band.
Cancel
By reference. A handler sets it to True to stop the drag.

BandChevronPushed

Raised when the user presses the chevron button of a band, or the program does with PushChevron. See The chevron.

Syntax: object_BandChevronPushed( Band As CbrBand, Left As Single, Top As Single, Width As Single, Height As Single )

Band
The band.
Left, Top, Width, Height
The place of the chevron button, in the container’s scale units.

BandMouseEnter

Raised while MouseTrack is True, when the pointer moves onto a band.

Syntax: object_BandMouseEnter( Band As CbrBand )

Band
The band.

BandMouseLeave

Raised while MouseTrack is True, when the pointer moves off a band.

Syntax: object_BandMouseLeave( Band As CbrBand )

Band
The band.

HeightChanged

Raised when the cool bar’s height changes, for a horizontal cool bar, or its width, for a vertical one, because the rows of bands need more or less room.

Syntax: object_HeightChanged( NewHeight As Single )

NewHeight
The new height, in the container’s scale units.

LayoutChanged

Raised when the user has changed the layout of the bands.

Syntax: object_LayoutChanged( )

MinMax

Raised before the user maximizes or minimizes a band.

Syntax: object_MinMax( Cancel As Boolean )

Cancel
By reference. A handler sets it to True to stop the change.

Resize

Raised when the size of the cool bar changes, also where the cool bar changes its own height to that of its rows of bands.

Syntax: object_Resize( )

CbrBandGripperConstants

The values of the Gripper of a band.

Member Value Description
CbrBandGripperNormal 0 The grip shows on a band that the user can move or resize.
CbrBandGripperAlways 1 The grip shows on the band always, also where it could not be dragged.
CbrBandGripperNever 2 The band has no grip.

CbrBandStyleConstants

The values of the Style of a band.

Member Value Description
CbrBandStyleNormal 0 The user can resize the band.
CbrBandStyleFixedSize 1 The band keeps its size.

CbrHitResultConstants

The values that HitTest gives for the part of a band.

Member Value Description
CbrHitResultNoWhere 0 No part of a band.
CbrHitResultCaption 1 The band’s caption.
CbrHitResultClient 2 The area of the band that holds its control.
CbrHitResultGrabber 3 The band’s grip.
CbrHitResultChevron 4 The band’s chevron button.
CbrHitResultSplitter 5 The boundary between two bands of a row.

CbrOrientationConstants

The values of Orientation.

Member Value Description
CbrOrientationHorizontal 0 The bands lie in rows.
CbrOrientationVertical 1 The bands lie in columns.

See Also

  • CbrBands class – the collection of the bands
  • CbrBand class – one band
  • ImageList class – the pictures of the bands
  • Common members – the members this control shares with the package’s other controls