StatusBar class

A StatusBar is a bar along the edge of a form that shows short pieces of information in panels: a message, the state of the Caps Lock key, the time. It can also show one piece of text across its whole width.

A status bar along the bottom of a form with four panels: Ready, which takes the free width, Ln 12, Col 5 and UTF-8, each as wide as its text, and 100% in the middle of a panel of its own width
StatusBar1.Panels(1).Text = "Ready"
StatusBar1.Panels.Add , "pos", "Ln 1"
StatusBar1.Panels.Add , "caps", , SbrPanelStyleCaps
Debug.Print StatusBar1.Panels.Count
Debug.Print StatusBar1.Panels("pos").Index
' Output:
'  3
'  2

The control stands in place of the StatusBar of the Microsoft common controls (MSCOMCTL.OCX).

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.

Its sub-objects have pages of their own:

Panels

A status bar drawn on a form has one panel, with no text and a sunken border. Panels returns the collection, and its Add method makes more. The panels are numbered from 1, from the left, and a program can also name each by a key.

Each panel has its own text, picture, colors, alignment and border, and its own width: see SbrPanel.

What a panel shows

A panel’s Style says what it shows. SbrPanelStyleText, the default, shows the panel’s Text. The other styles show something the control works out itself, so Text has no effect on what is drawn:

  • the name of a key (CAPS, NUM, INS, SCRL, and the keys of East Asian keyboards), drawn in the gray of disabled text while the key is not on;
  • the current time, the current date, or both, in the format of DTFormat. The control changes the text as the time passes.

For these styles Text still returns the string that was assigned, and the panel’s Enabled is the state of the key: an assignment to it does not last.

StatusBar1.Panels(1).Style = SbrPanelStyleDate
StatusBar1.Panels(1).DTFormat = SbrPanelDTFormatCustom
StatusBar1.Panels(1).Text = "yyyy"            ' with a custom format, Text is the format
Debug.Print StatusBar1.Panels(1).Text
' Output:
' yyyy

The width of a panel

A panel’s AutoSize decides its width:

  • SbrPanelAutoSizeNone, the default: the panel is MinWidth wide, or as wide as the program sets with Width.
  • SbrPanelAutoSizeContent: the panel is as wide as its text and its picture need, but not narrower than MinWidth.
  • SbrPanelAutoSizeSpring: the panel starts at MinWidth and the panels that have this value share the free width of the bar.
StatusBar1.Panels(1).AutoSize = SbrPanelAutoSizeContent
StatusBar1.Panels(1).Text = String$(200, "W")
Debug.Print StatusBar1.Panels(1).Width > StatusBar1.Panels(1).MinWidth
' Output:
' True

A panel that is not Visible has no width, and the panels after it move up.

One piece of text

With Style set to SbrStyleSimple the bar shows SimpleText across its whole width, and the panels are not shown. They keep their values, and SbrStyleNormal shows them again.

SimpleText keeps its text while the style is normal, and each change of Style raises StyleChange.

Clicks

A click on the bar raises the mouse events of Mouse and, when the pointer is over a panel, PanelClick. A double click raises PanelDblClick and then DblClick. PanelMouseEnter and PanelMouseLeave are raised while MouseTrack is True, and HitTest names the panel at a point.

PanelClick comes after MouseDown and before MouseUp, and Click comes last.

Dim Watch As New StatusBarWatcher
Set Watch.Bar = StatusBar1
SbClick StatusBar1, 10                  ' a click on the first panel
' Output:
' MouseDown
' PanelClick 1
' MouseUp
' Click

SbClick in this sample is a procedure of the program’s own that sends the messages Windows sends to the bar for a click of the left button, and StatusBarWatcher is a class of the program’s own that holds the control WithEvents and prints its events.

Properties

Align

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

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, also for a status bar drawn on a form. A program places and sizes the status bar itself.

AllowSizeGrip

Whether the bar may have a size grip at its right end, the corner by which the user changes the size of the form. Boolean. Default: True. The grip is there when the bar is attached to the bottom edge of a form whose border the user can drag, and it is hidden while the form is maximized. IncludesSizeGrip says whether it is there. A change makes the bar’s window again.

BackColor

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

ContainedControls

The controls that were put inside the status bar when the form was designed. A ContainedControls collection, read-only.

DoubleBuffer

Whether the control draws itself in a bitmap off the screen first, which reduces flicker. Boolean. Default: True.

hWndToolTip

The handle of the tool tip window that shows the panels’ ToolTipText. LongPtr, read-only. It is 0 while ShowTips is False.

Panels

The collection of the panels. An SbrPanels object, read-only.

ShowTips

Whether a panel shows its ToolTipText when the pointer rests on it. Boolean. Default: False.

Setting it to True makes the tool tip window, and False removes it again: hWndToolTip shows which.

SimpleText

The text that the bar shows across its width while Style is SbrStyleSimple. String. Default: empty. See One piece of text.

Style

Whether the bar shows its panels or one piece of text. A member of SbrStyleConstants. Default: SbrStyleNormal. A change raises StyleChange.

A value that is not a member raises run-time error 380.

Methods

HitTest

Returns the panel at a point of the bar, or Nothing where there is none.

Syntax: object.HitTest( X, Y ) As SbrPanel

X, Y
required Single: the point, measured from the top left corner of the control in the scale units of the control’s container.

IncludesSizeGrip

Returns whether the bar has a size grip at its right end now. See AllowSizeGrip for when it has.

Syntax: object.IncludesSizeGrip As Boolean

Events

PanelClick

Raised when the user clicks a panel with the left or the right mouse button. It comes between MouseDown and MouseUp, see Clicks.

Syntax: object_PanelClick( Panel As SbrPanel, Button As Integer )

Panel
The SbrPanel that was clicked.
Button
vbLeftButton or vbRightButton, members of MouseButtonConstants.

PanelDblClick

Raised when the user double-clicks a panel with the left or the right mouse button, before DblClick.

Syntax: object_PanelDblClick( Panel As SbrPanel, Button As Integer )

Panel, Button
As in PanelClick.

PanelMouseEnter

Raised when the pointer moves onto a panel, while MouseTrack is True. When the pointer moves from one panel to another, PanelMouseLeave of the first comes before PanelMouseEnter of the second.

Syntax: object_PanelMouseEnter( Panel As SbrPanel )

Panel
The SbrPanel the pointer is on.

PanelMouseLeave

Raised when the pointer leaves a panel, while MouseTrack is True.

Syntax: object_PanelMouseLeave( Panel As SbrPanel )

Panel
The SbrPanel the pointer was on.

Resize

Raised when the size of the control changes.

Syntax: object_Resize( )

StyleChange

Raised when the Style of the bar changes.

Syntax: object_StyleChange( )

SbrStyleConstants

The values of Style.

Member Value Description
SbrStyleNormal 0 The bar shows its panels.
SbrStyleSimple 1 The bar shows SimpleText across its width.

SbrPanelStyleConstants

The values of the Style of a panel.

Member Value Description
SbrPanelStyleText 0 The panel shows its Text.
SbrPanelStyleCaps 1 The text CAPS, dimmed while Caps Lock is off.
SbrPanelStyleNum 2 The text NUM, dimmed while Num Lock is off.
SbrPanelStyleIns 3 The text INS, dimmed while Insert mode is off.
SbrPanelStyleScrl 4 The text SCRL, dimmed while Scroll Lock is off.
SbrPanelStyleTime 5 The current time, in the format of DTFormat.
SbrPanelStyleDate 6 The current date, in the format of DTFormat.
SbrPanelStyleKana 7 The text KANA, dimmed while the Kana key is off.
SbrPanelStyleHangul 8 The text HANGUL, dimmed while the Hangul key is off.
SbrPanelStyleJunja 9 The text JUNJA, dimmed while the Junja key is off.
SbrPanelStyleFinal 10 The text FINAL, dimmed while the Final key is not held down.
SbrPanelStyleKanji 11 The text KANJI, dimmed while the Kanji key is not held down.
SbrPanelStyleHanja 12 The text HANJA, dimmed while the Hanja key is not held down.
SbrPanelStyleDateTime 13 The current date and time, in the format of DTFormat.

SbrPanelBevelConstants

The values of the Bevel of a panel.

Member Value Description
SbrPanelBevelFlat 0 No border.
SbrPanelBevelInset 1 A sunken border.
SbrPanelBevelRaised 2 A raised border.

SbrPanelAutoSizeConstants

The values of the AutoSize of a panel. See The width of a panel.

Member Value Description
SbrPanelAutoSizeNone 0 The width is MinWidth, or the one the program sets.
SbrPanelAutoSizeSpring 1 The panel takes a share of the free width of the bar.
SbrPanelAutoSizeContent 2 The panel is as wide as its text and picture need.

SbrPanelAlignmentConstants

The values of the Alignment of a panel.

Member Value Description
SbrPanelAlignmentLeft 0 The text is at the left edge.
SbrPanelAlignmentCenter 1 The text is in the middle.
SbrPanelAlignmentRight 2 The text is at the right edge.
SbrPanelAlignmentLeftRight 3 The text and the picture are at opposite edges. A panel without a picture has its text at the left.

SbrPanelDTFormatConstants

The values of the DTFormat of a panel.

Member Value Description
SbrPanelDTFormatShort 0 The short format of the user’s settings.
SbrPanelDTFormatLong 1 The long format of the user’s settings.
SbrPanelDTFormatMedium 2 The medium format.
SbrPanelDTFormatGeneral 3 The general format of the user’s settings.
SbrPanelDTFormatCustom 4 The format string that is the panel’s Text.

See Also