Balloon Control

Description

The BALLOON Control adds a new technique of providing help to the user that is not available any other way. This control allows the developer to provide the user with a dynamic popup help system for all the controls on each form in the VB application. The popup help text information provided is especially useful to new user and is ideal for custom in-house applications where the user may not have a manual to refer to.

When enabled, the control provides a custom event which defines when the user moves the mouse cursor over a form's control. The VB application then passes a help text string to the BALLOON.VBX control which then moves the popup window to the vicinity of the selected control and displays the help text in the popup window. If for a particular control help text is not desired, then no return text should be provided by the VB application.

A separate BALLOON Control must be placed on each form that will have a popup help session available.

A "popup help session" is defined from the time the popup appears on-screen to the point at which the popup window is removed.

File Name

BALLOON.VBX

Remarks

When you create and distribute applications that use the BALLOON control you should install the file BALLOON.VBX in the customer's Microsoft Windows \SYSTEM sub directory. All of the properties, events, and methods for this control are listed below.  Properties and events that apply only to this control, or require special consideration when used with it, are underlined.  They are documented in this help file.  See the Visual Basic Language Reference or on-line Help for documentation of the remaining properties, events, and methods.

Properties

Action

MessageText

CtlName

Index

Left

Top

Tag

Events

BalloonClick

Methods

The Action property is used as a pseudo method.


Typical Problems

1. Some Visual Basic controls do not have hwnd properties.

The Visual Basic control types of Image, Shape and Label do not have hwnds and are not intended to be highlighted and have help text displayed. Use Text boxes and Picture controls as controls that perform the same functions and have hwnd properties. Any control that does not have a hwnd property will not be highlighted and will not trigger a BalloonClick() event.

If any controls without hwnd properties need to have help text displayed, include the control in an enclosing frame which has a hwnd parameter. Use the hwnd of the container control in the Select Case statement of the BalloonClick() event.

2. Once the help message session has begun, the VB application MUST NOT take any action which would cause a screen update.

For instance; You may NOT send a dialog box to the screen during a help message session. Doing so will cause the help session to immediately terminate, and may leave windows and the VB application in an unstable state.

To properly terminate a help message session, send a Balloon.Action = STOP command to the control. This clears the help session and allows normal application processing to resume.

3. Terminating the help message session from within the VB application can cause the user to become confused. The VB application should always allow a help message session to terminate by the user.


MessageText Property, Balloon Control

Description

Sets the text to be displayed in the popup window.

Usage

[form.]BALLOON.hwndForm[ = setting %]

Data Type

String

How to use

The MessageText property moves the popup help window to the location of the control the mouse is over and puts the text in the popup window.

If the mouse is over a control that help text is NOT desired, then do not set the MessageText property. This "do nothing" default does not move the popup window and does not update the text. The next active control the mouse is placed over will continue the move-update sequence. As an example, in the Case Select statement the entry for the window to skip can be committed, left blank or use an "exit sub" program statement.


Action Property, BALLOON Control

Description

Setting the Action property cause the control to attach or detach from the forms menu. The control must be attached ( hooked ) to the forms menu before the BalloonClick event can be provided.

The Form's hwnd that the control is to monitor is sent immediately before the Action call.

Usage

[form.]BALLOON.Action[ = setting %]

Settings

The Action property settings are:

Setting	Description

ID_START   = 1	Start a popup help session.

Remarks

The code fragment to begin monitoring the form for mouse move events is

Form.Balloon.Action = ID_START

The user terminates a popup help session by mouse clicks or any keyboard activity.

Data Type

Integer


BalloonClick Event; BALLOON Control
BalloonClick Event, BALLOON Control

Description

This event is generated only after a help session is initiated. A popup help window will appear on-screen. When the user moves the mouse over any control on a form, the control will be displayed in inverse video and the popup window moves to the control windows location, sends the BalloonClick Event to the application and awaits the help text to be applied to the popup help window.

Syntax

Sub BALLOON_BalloonClick ( hwndAtMouse As Integer )

Remarks

Code fragments to illustrate the use of BALLOON Control.

Start up the control;

Form.Balloon.MessageText = "Initial message text to display"

Form.Balloon.Action = ID_START

Process the returned hwndAtMouse and return the desired help text;

BALLOON1_ShadowBxClick( hwndAtMouse As Integer )

Select Case hwndAtMouse

Case Control.hwnd-X1

Form.Balloon.MessageText = "message text desired"

Case Control.hwnd-X2

Form.Balloon.MessageText = "message text desired"

.

.

.

Case Control.hwnd-Xn

' No text desired

Exit Sub

Case Else

Exit Sub

End Sub