Copyright: Copyright c 1992-1993 Haas Service GmbH


Help Contents
Contents

Introduction

StBar Description

StBar Components and Installation

Control Reference

StBar Properties

StBar Events

StBar Functions

Additional Information

Special MenuCaption and MenuTag strings

The StBar configuration file


StBar Description

The Visual Basic Status Bar Control (StBar) is a custom control, which allows to add a status line to your Visual Basic applications. This gives your program an appearance comparable to standard Windows applications.

The different segments of the status bar can be used to display program information and as an indicator for toggle keys (NUM, CAPS, ...). In addition, the control offers special events to reflect the occurrence of some important system messages (menu selection, color changes, ...).

Related Topics:

What is a Custom Control

How to use the Status Bar control

StBar and MDI applications


What is a Custom Control

A custom control is an extension to the Visual Basic Toolbox. You add a control to a project by using the Add File command from the File menu. By convention, custom control files have a .VBX extension (the name of StBar's control  file is STBAR.VBX).

After you have loaded a control file, two things happen:

•	The custom control file appears in the Project window.

•	A bitmap for the custom control is added to the toolbox.

You can now use the new control just as if it was one of Visual Basic's built in controls.


How to use the Status Bar control

The main idea behind StBar is to use an extra instance of the control for each segment (information field, NUM and CAPS indicators, ...) of the status line.

To add a status line to an application

•	Add STBAR.VBX to the project (compare What is a Custom Control).

•	For each status bar segment, add an instance of the control to the form (double click on the toolbar bitmap or click and draw as with any other control). The status bar segments are automatically placed at the bottom of the form. Sizing the form also stretches or shrinks the status line (in fact, only the width of the leftmost StBar instance changes). This automatic placing and sizing works in design as well as in run mode.

•	Set the properties for each status line segment (for more information see StBar Properties).


StBar and MDI applications

Visual Basic 2.0 and above support the Multiple Document Interface (MDI). In an MDI application, the user expects to have a status line only at the bottom of the main window. Here is how you can achieve this with the StBar control:

•	Draw a picture control on the MDI form (align to bottom, no border).  Make it high enough to contain the status bar.

•	Draw the StBar instances inside the picture control (just like you draw a check box inside a frame control).

•	Add the following code to the MDIForm_Load procedure to adjust the height of the picture box:

picStBar.Height = sbMain.Height


StBar Components and Installation

You may obtain StBar as a stand alone product or bundled with other controls and development tools. A demo version and a version containing the source code are also available. This description applies to the stand alone product.

Related Topics:

Contents of the distribution disk

Installation


Contents of the distribution disk

The StBar distribution disk contains the following files (there may be a READ.ME file on the disk with additional information):

Filename	Description
STBAR.VBX	Development version of the control.
STBARR.VBX	Runtime version of the control. If you want to distribute an application, that uses StBar, rename this file to STBAR.VBX and copy it to your distribution disks.
STBAR.HLP	On-line help for StBar.
STBAR.INI	Sample configuration file for StBar's indicator captions. For more information see The StBar configuration file.
HDRSTBAR.BAS	Visual Basic module with definitions for some global constants and StBar's support procedures. Add this module to your project to access these definitions.
EXAMPLE.MAK MAIN.FRM CHILD.FRM	Sample application to demonstrate some of the features of StBar.
You are not allowed to distribute the development version of the control.
Distribution of  the runtime version is free of charge.


Installation

If the installation is not accomplished by an installation program, simply copy the files from the distribution disk to a separate directory on your hard disk. The custom control file STBAR.VBX should also be copied to your Windows system directory to allow compiled programs to access the control. If you decide to use the configuration file, copy the sample file from the distribution disk to your Windows directory and customize its contents to your needs.


StBar Properties

All of the properties of the StBar control are listed in the following sections:

Related Topics:

Standard Properties

Automatic Properties

Special Properties


Standard Properties

The following properties work as with any other Visual Basic control. They are documented in the Visual Basic Language Reference.

Caption	FontBold	FontItalic	FontName
FontSize	FontStrikethru	FontUnderline	hWnd
Index	Name	Parent	Tag
Visible
The Caption property holds the text, which is displayed in the corresponding status line segment. This property is set automatically for indicator segments.

You can set the Visible property for all segments of a status bar with one call to the StBarVisible function (for more information see The StBarVisible subroutine).

Related Topics:

How to display a progress bar:


How to display a progress bar:

A special format for the Caption property can be used to display a progress bar. If the caption begins with an integer number included between two percent signs, this number is interpreted as the amount of work done (in percent). The rest of the caption is displayed (centered) in the corresponding segment of the status line.

Example:

SbMain.Caption = "%75%Work in progress, 75% done"


Automatic Properties

The following properties are set automatically (changes are also automatic in response to resizing the form or modifying system colors):

BackColor	Height	Left	Top
Width


Special Properties

These are the properties specific to StBar:

(About)	DrawMode	Indicator	LinkedTo
LinkedToHwnd
Related Topics:

(About)

DrawMode

Indicator

LinkedTo

LinkedToHwnd


(About)

This property is only available at design time. Click the ellipsis (...) on the right side of the Properties window to open a dialog box that displays copyright and version information.


DrawMode

This property is used to change the appearance of the corresponding status bar segment.

Setting	Description
0 - Down	Gives the status bar segment a sunken look (Default).
1 - Flat	Gives the status bar segment a flat look (e.g. used for blank segments at the end of the status bar).
2 - Up	Gives the status bar segment a raised look (similar to push buttons).


Indicator

This property is used to make a segment of the status bar an indicator for the NUM, CAPS,  SCROLL or INSERT key. The actual abbreviation for each indicator can be modified by changing the configuration file STBAR.INI (compare The StBar configuration file).

Setting	Description
0 - None	Information segment (Default)
1 - Num	Indicator for Num Lock key.
2 - Caps	Indicator for Caps Lock key
3 - Scroll	Indicator for Scroll Lock key
4 - EditMode	Indicator for Insert/Overtype key
Note: The Insert key is not 'hardware' but 'form' dependent, i.e. pressing that key only changes the setting for the form that has the input focus.


LinkedTo

Use this property to link one status bar segment to another StBar instance on a different form.

 Syntax:

FormName.ControlName

If you want to have a  (visible) status bar on only one (main) form of your application, set the visible property of  the status bar segments on other forms to False and link them to the corresponding segments on the main form.


LinkedToHwnd

This is a runtime only property. In contrast to the LinkedTo property (s.a.) it is not restricted to status bar controls in the same task, but can be used to link a status line segment to status bar controls in any task. In fact, you can assign to this property the handle of any window, which responds to the WM_SETTEXT message, i.e. you can even link a status bar text to the caption of a top level window or to a document in an editor window.

Use the hWnd property to retrieve the window handle of the status bar control you want to link to.


StBar Events

The following sections describe each of the StBar events. It is very important to understand this stuff, because proper use of  the events can vastly improve your application.

Related Topics:

Events fired to any status bar segment

Events fired only to the first status bar segment

Events fired to indicator segments


Events fired to any status bar segment

There is only one StBar event, that is fired for any status bar segment on a form.

Related Topics:

EmptyCaption


EmptyCaption

Syntax:

Sub StBar_EmptyCaption()

This event is triggered, if the status bar caption gets empty. It can be used, if the developer wants a status bar segment to display a default text, whenever it is cleared (e.g. in a lost focus event).


Events fired only to the first status bar segment

There are some events, which are only fired to the first segment of a status line. These events inform the application about task switches, menu selections and changes in the system configuration.

Related Topics:

AppActivate

InitMenu

MenuSelect

SelectedTag

SysColorChange


AppActivate

Syntax:

Sub StBar_AppActivate(Activate As Integer)

This event reflects the WM_ACTIVATEAPP message being sent to the status bar's parent form.

The WM_ACTIVATEAPP message is sent when a window is about to be activated and that window belongs to a different task than the active window. The message is sent to all top-level windows of the task being activated (non zero value for Activate parameter) and to all top-level windows of  the task being deactivated (zero value for Activate parameter).


InitMenu

Syntax:

Sub StBar_InitMenu()

This event is fired, when a menu is about to become active. It occurs when the user clicks an item on the menu bar or presses a menu key. This allows an application to modify the menu before it is displayed.


MenuSelect

Syntax:

Sub StBar_MenuSelect (Closing As Integer, MenuCaption As String)

This event is fired, when the user has selected (Closing = False) or de selected (Closing = True) a menu item. This is different from Visual Basic's Click event, which is fired when a menu command is executed. You can use the MenuCaption parameter to identify the menu item and to display additional instructions in the status bar.

This event is also triggered for the system menu with special MenuCaption strings (for more information see Special MenuCaption and MenuTag strings).


SelectedTag

Syntax:

Sub StBar_SelectedTag (hWndForm As Integer, MenuTag As String)

This event is fired when a menu item has been selected (use the MenuSelect event to detect when a menu item is de selected).

The MenuTag parameter can be used to identify the menu item and to put an explanation in the status bar.

The hWndForm window handle is that of the window, to which the message is directed. This is useful in MDI applications to distinguish between the system menu's Close item for the application window (Quit application) and for child windows (Close document). Note that StBar detects the destination window also for maximized MDI child windows, though Windows sends the WM_MENUSELECT message to the MDI container (the system menu of a maximized child becomes a menu item of the MDI container).

For a list of special MenuTag values for the system menu see Special MenuCaption and MenuTag strings.

This event is supported only for Visual Basic 2.0 and above.


SysColorChange

Syntax:

Sub StBar_SysColorChange()

This event is fired, when a change is made in the system color settings.


Events fired to indicator segments

There is one event that is fired to status bar segments, which serve as indicator for one of the toggle keys (compare StBar Properties).

Related Topics:

SetIndicator


SetIndicator

Syntax:

Sub StBar_SetIndicator (State As Integer)

Whenever one of the toggle keys is pressed, this event is fired with the new key state (ON = 1 / OFF = 0) to all status bar segments with the Indicator property configured to monitor that key.


StBar Functions

There are some support subroutines and functions exported from STBAR.VBX. The following sections describe these functions and show their declarations (taken from HDRSTBAR.BAS).

Related Topics:

The StBarVisible subroutine

The StBarGetHInstance function


The StBarVisible subroutine

Declaration:

Declare Sub StBarVisible Lib "STBAR.VBX" (ByVal hWnd As Integer, ByVal fVisible As Integer)

Use this procedure to show or hide the complete status line of a form. The expected parameters are the window handle of the form (hWnd property) and a Boolean value to indicate, if the status line should be shown (fVisible = True) or hidden (fVisible = False).


The StBarGetHInstance function

Declaration:

Declare Function StBarGetHInstance Lib "STBAR.VBX" () As Integer

This function retrieves the instance handle of the currently running task (this is VB.EXE, if you are in the development environment). This value is needed in some functions of the Windows API.


Special MenuCaption and MenuTag strings

The MenuSelect and SelectedTag events use special strings for their MenuCaption respectively MenuTag parameters, if these events are fired for system menu items.

Related Topics:

Strings for the MenuSelect and SelectedTag events

Special String for the SelectedTag event


Strings for the MenuSelect and SelectedTag events

The following strings are used in both events:

String Value	Menu Item
SYS_POPUP	The system menu.
SYS_SIZE	The Size menu item.
SYS_MOVE	The Move menu item.
SYS_MINIMIZE	The Minimize menu item.
SYS_MAXIMIZE	The Maximize menu item.
SYS_CLOSE	The Close menu item.
SYS_RESTORE	The Restore menu item.
SYS_NEXT	The  Next Window menu item (MDI).
SYS_TASKLIST	The Task List menu item.
Please note, that SYS_RESTORE is also sent, if the restore button in the application menu is selected for a maximized MDI child window.


Special String for the SelectedTag event

There is one other special string value for the SelectedTag event:

String Value	Menu Item
SYS_SWITCH	Any item in the window list of MDI applications.


The StBar configuration file

The actual text strings displayed in the indicator segments of a status line can be configured with a configuration file. This file, STBAR.INI, is in standard windows INI file format, and must reside in the Windows directory.

Related Topics:

STBAR.INI contents

STBAR.INI sample file


STBAR.INI contents

There is only one section ([KeyNames]) in the configuration file that may contain the following entries:

Keyword	Description
sNum	Text to display for pressed Num Lock key (Default: NUM).
sCaps	Text to display for pressed Caps Lock key (Default: CAPS).
sScrl	Text to display for pressed Scroll Lock key (Default: SCRL).
sIns	Text to display for the EditMode indicator in insert mode (Default: INS).
sOvr	Text to display for the EditMode indicator in overtype mode (Default: OVR).
The modifiers for the indicator captions should not exceed 4 characters.


STBAR.INI sample file

Here is the contents of the STBAR.INI sample file from the distribution disk, which contains indicator captions that are identical to those of the German version of WinWord:

[KeyNames]
sNum="ZA"
sCaps="UA"
sScrl="ROLL"
sIns="EINF"
sOvr="ÜB"


A progress bar displays the amount of work done for a specific task.