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.
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
- What a panel shows
- The width of a panel
- One piece of text
- Clicks
- Properties
- Methods
- Events
- SbrStyleConstants
- SbrPanelStyleConstants
- SbrPanelBevelConstants
- SbrPanelAutoSizeConstants
- SbrPanelAlignmentConstants
- SbrPanelDTFormatConstants
- See Also
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
- Common members – the members this control shares with the package’s other controls
- SbrPanels – the collection of the panels
- SbrPanel – one panel