VDTTip v1.1 June 1998

Description	The VDTTip control is used to create small pop-up windows typically containing a short descriptive text regarding the control over which the mouse cursor is currently located.
File Name	VDGT.OCX
Object Type	VDTTip
Remarks	Unlike most other tool tips, VDTTips don't have to be rectangles. Instead, Windows Meta Files may be used as backgrounds. With VDTTip, tool tips can be implemented without writing a single line of code! Refer to the quick start section to see just how easy it is to use VDTTip.
About	This control was developed by Visual Design Softscape AB. For more information, visit us at www.visual-design.se or contact us at info@visual-design.se.
Distribution	As soon as you have licensed the control, you may distribute it freely along with your EXE files.
Disclaimer	Disclaimer

Release history

Aug 96	v0.1	First beta release.
Sep	v1.0	Added methods to allow tipping of graphical controls (as well as tipping of any area on a form, not necessarily related to a control). This requires one code line of cooperation.
June 98	v1.1	Recompiled with Visual C++ v5

Properties

*Alignment	*Aspect	BackColor	*ctlEnabled
*Delay	*ExtraOffX	*ExtraOffY	Font
ForeColor	*HotSpotX	*HotSpotY	*IsVisible
*MouseOffX	*MouseOffY	*Picture	*PopupMode
*Sensitivity	*TextBottom	*TextLeft	*TextRight
*TextTop	*TractorBeam	*UseIndex

* = The property applies only to VDTTip.

Methods

*TipAreaRemoveAll

*TipAreaScale

*TipRectArea

* = The method applies only to VDTTip.

Events

* PopDown

* Popup

* = The event applies only to VDTTip.

Properties

Alignment Property

Description
Determines the alignment of the tool tip text.

Remarks
The Alignment property settings are:

Setting	Description
0	The tool tip text appears left-justified.
1	The tool tip text appears right-justified.
2	The tool tip text appears (horizontally) centered.

Data Type
Integer (enumerated)

Default value
2

Aspect Property

Description
Determines the aspect ratio between the text box' width and height, multiplied by 10.

Remarks
A setting of 10 means that the text box within the tool tip will have approximately the same width as height. A setting of 20 means it will have twice the width as height.

Data Type
Integer

Default value
20

ctlEnabled Property

Description
This property may be used during the PopUp event to stop a disabled control from getting tipped whether the control about to be tipped is enabled or disabled.

Data Type
Boolean

Example
If Not VDTTip.ctlEnabled Then strText = "" : Exit Sub

Delay Property

Description
Determines the delay in ms the mouse must have been parked (immobile - see also the Sensitivity property) before VDTTip starts searching for a control beneath the cursor.

Data Type
Integer

Default value
500

ExtraOffX & ExtraOffY Properties

Description
During the processing of the Popup event, these properties may be set in order to move the tool tip window into a different position, not necessarily related to the mouse position.

Remarks
These properties are given in pixels and are added to the MouseOffX & MouseOffY property values, respectively. These properties are reset to zero each time the tool tip window is removed from the screen.

Data Type
Integer

HotSpotX & HotSpotY Properties

Description
Determines the position of the picture's logical hot spot. These properties, in conjunction with the MouseOffX & MouseOffY properties, define exactly where the tool tip will pop up with respect to the mouse cursor.

Remarks
These properties are given in percentage of the picture where (0,0) means the upper left corner and (100,100) means the lower right corner.

Data Type
Integer

Default values
50 & 0

IsVisible Property

Description
Determines or sets the tool tip window 's visible state.

Remarks
It is possible to remove a tool tip by setting IsVisible to False. It is also possible to simulate the mouse being parked by setting IsVisible to True. If the mouse isn't over a VB control, however, nothing happens. This may be used in conjunction with the PopupMode property in order to create a manual pop-up mechanism.

Data Type
Boolean

MouseOffX & MouseOffY Properties

Description
Determines the offset between the mouse cursor and the tool tip's hot spot. These properties, in conjunction with the HotSpotX & HotSpotY properties, defines exactly where the tool tip will pop up with respect to the mouse cursor.

Remarks
These properties are given in pixels. A value of (0,-10) means ten pixels straight above the mouse cursor.

Data Type
Integer

Default values
0 & 20

Picture Property

Description
Determines the picture (if any) to be used as the tool tip's background. If no picture is used, the tool tip shape is a solid rectangle with the color BackColor and a one pixel thich black frame.

Remarks
It is strongly recommended that you use a WMF instead of a BMP, since WMFs may be resized with no loss of quality and the tool tip must be resized for each text it displays. Another reason is thatVDTTip doesn't support transparent BMPs. If you want an irregular shaped tool tip, a WMF is the only way to go.

Since working with WMFs and copying & pasting pictures in VB seems to be a mystery to many users, here's one way to load VDTTip with a WMF:

Start MS Powerpoint and draw an appropriate bubble (maybe one of the predefined shapes will do?).
Select all (ctrl+A) and copy it (ctrl+C).
Switch to VB and select the VDTTip control.
Paste the WMF into the VDTTip's Picture property by clicking in the "(none)" field after the Picture property and then pressing (ctrl+V).

Data Type
Picture; WMF or BMP

PopupMode Property

Description
This property is used to turn off the automatic tracking of the mouse. If set to manual, the tip will only pop-up in response to the IsVisible property.

Remarks
The PopupMode property settings are:

Setting	Description
0	Automatic. VDTTip tracks the mouse continuously by keeping a 50 ms timer running.
1	Manual. The timer only starts when IsVisible is set to True and stops when the tip is removed (or if the pop-up fails in the first place, which happens if: the mouse isn't above any control or if the Popup event returns an empty string).

Data Type
Integer (enumerated)

Default value
0 - Automatic

Sensitivity Property

Description
Determines the distance (in pixels) which the mouse may be moved and still be considered parked (immobile) above a control.

Data Type
Integer

Default value
0

TextBottom, TextLeft, TextRight & TextTop Properties

Description
Determines the area within the tool tip where text may be drawn. The appropriate setting of these values depend on the shape of the picture used.

Remarks
These properties are given in percentage of the picture where (0,0) means the upper left corner and (100,100) means the lower right corner.

Data Type
Integer

Default values
1, 1, 99 & 99

TractorBeam Property

Description
This property may be used to make the tool tip follow the mouse cursor while it moves over a control.

Remarks
The value of the property is the distance in pixels which the mouse is allowed to move before the tip follows. A value of zero turns off this feature.

Data Type
Integer

Default value
0

UseIndex Property

Description
This property is used to select which VDTTip (out of a control array) that shall be used in conjunction with a particular control. Refer to the section Multiple shapes, fonts and colors for more information.

Remarks
Before a Popup event, this property is set to the VDTTip index number specified in a control's Tag property. I.e. a tag containing "VDTTip2:A tool tip text" results in UseIndex = 2. This value may be changed during the Popup event.

Data Type
Integer

Methods

TipAreaRemoveAll Method

Description
Removes all tipping areas, added by the TipRectArea method, from the form.

VDTTip.TipAreaClear

Remarks
To remove selective tipping areas, use the TipRectArea method and pass zero as width and/or height.

TipAreaScale Method

Description
This method is just a convinient way to avoid a lot of scaling factors when using the TipRectArea method.

VDTTip.TipAreaScale scaleX, scaleY

scaleX As Double
Factor to multiply the left and width parameters passed to TipRectArea with.
scaleY As Double
Factor to multiply the top and height parameters passed to TipRectArea with.

Remarks
By default, both scaling factors will be 1 - meaning no scaling is performed.

Example
The statement below

VDTTip1.TipRectArea "Image1", -1, "A tool tip text", 0, Image1.Left / Screen.TwipsPerPixelX, Image1.Top / Screen.TwipsPerPixelY, Image1.Width / Screen.TwipsPerPixelX, Image1.Height / Screen.TwipsPerPixelY

may also be written

VDTTip1.TipAreaScale 1 / Screen.TwipsPerPixelX, 1 / Screen.TwipsPerPixelY VDTTip1.TipArea "Image1", -1, "A tool tip text", 0, Image1.Left, Image1.Top, Image1.Width, Image1.Height

TipRectArea Method

Description
This method is used to add or remove a tipping area. A tipping area is a rectangular area anywhere on the same form as the VDTTip control. It need not be near a control, but overlapping graphical controls with tipping areas is a way to allow graphical controls to have tool tips.

VDTTip.TipRectArea ctlName, ctlIndex, strText, useindex, left, top, width, height

ctlName As String
A symbolic name used to refer to the control later on. This will be passed as ctlName argument to the Popup event, but has no meaning to VDTTip.
ctlIndex As Integer
This will be passed as ctlIndex argument to the Popup event, but has no meaning to VDTTip..
strText As String
The tool tip text. This will be passed as strText argument to the Popup event.
useindex As Integer
Index to the VDTTip that shall be used for the tool tip's bubble shape. Normally you'll pass zero here. This is the same as the XX part of a control's Tag property set to VDTTipXX:. See UseIndex property.
left, top, width & height As Double
The area which will have tool tips. This area must be described in pixel coordinates of the form's client area. Instead of passing pixel coordinates directly, it may be more convinient to use the TipAreaScale method to set a scaling factor first.

Remarks
The area may later be changed. Passing a new area with the same ctlName and ctlIndex will first remove the old area. Passing a zero width or height will remove any existing area without adding a new one. Remove all areas at once with the TipAreaClear method.

Call this method for each area/control which shall be tipped and that are not bound to a windowed control. The best place to call this method is in Form_Load.

Note 1: Passing the same ctlName + ctlIndex as an existing tipping area will not add a new tipping area - it will modify the existing one.
Note 2: Since the coordinates are given in the form's coordinate system, controls residing in a container control (like a picture box) must have their container's position added to their left / top properties. The sample shows how to do this for a label control in a frame container control.

Example

VDTTip1.TipRectArea "lblInfo", -1, "A tool tip text", 0, lblInfo.Left / Screen.TwipsPerPixelX, lblInfo.Top / Screen.TwipsPerPixelY, lblInfo.Width / Screen.TwipsPerPixelX, lblInfo.Height / Screen.TwipsPerPixelY

VDTTip1.TipRectArea "lblInfo", -1, "", 0, 0, 0, 0, 0 'remove the tipping area

Events

PopDown Event

Description
Occurs when a tool tip gets removed from the screen.

Sub VDTTip_PopDown ( )

Remarks
The UseIndex property is still valid when this event occurs.

Popup Event

Description
Occurs before the tool tip pops up. This event is triggered each time the mouse has been parked for at least Delay ms above a VB control (if the automatic tracking hasn't been disabled with the PopupMode property, that is).

Sub VDTTip_Popup ( ctlName As String, ByVal ctlIndex As Integer, ByVal ctlHwnd As Long, strText As String, ByVal x As Long, ByVal y As Long)

Remarks

ctlName	The name of the control being tipped.
ctlIndex	The index of the control being tipped (to be used if the control belongs to a property array).
ctlHwnd	The hWnd of the control being tipped.
strText	The desired tool tip text. If the control has as standard Tag property beginning with the text "VDTTipx:" (or "DBTTipx:" for compatibitlity reasons), the rest of the Tag property will be in strText when Popup is called. If all controls have their Tag properties set correctly - no code is needed! Setting strText to an empty string cancels the pop-up. Any apperance of "\|\|" (double pipe characters) in strText will be replaced by CRLF.
x & y	The mouse coordinates in pixels, relative the control. These parameters may be used in conjunction with the ExtraOffX & ExtraOffY properties to calculate a different pop-up location for the tool tip window.

No new event will be triggered (automatically) before the mouse is moved outside the control and the tool tip has been removed. It is possible to trigger this event manually by setting the property IsVisible to True.

Quick start

Below is the steps necessary to bring tool tips to your application if you want a custom shaped tool tip, otherwise, just do step 5!

1.	Load a picture into the Picture property.
2.	Adjust the properties TextLeft, TextTop, TextRight & TextBottom to get the black/white frame to surround the area of the picture which will contain text.
3.	Adjust the HotSpotX & HotSpotY properties so that the little red circle is moved into the logical hot spot position of the picture.
4.	Adjust the MouseOffX and MouseOffY properties to move the picture of the cursor relative the hot spot. Now the pop-up location of the tool tip has been exactly determined (unless overridden later by application code).
5.	Add the desired tool tip text of each control to it's Tag property, respectively, and prefix it with the text "VDTTip:", like this: "VDTTip:Beam me up, Scotty!". (Don't type the quotation marks and note that "VDTTip:" is case sensitive!)

Multiple shapes, fonts and colors

VDTTip has the ability to display different tool tip shapes, without any coding and without having any extra timers running. Just follow these steps:

1.	Make a control array of VDTTips, each setup like described in the "Quick start" section and then change the PopupMode property to "1 - Manual" in each but the first (Index zero) VDTTip.
2.	Tag the controls to be tipped with "VDTTipNN:", where NN is the index number of the VDTTip containing the desired configuration. (The tag "VDTTip:" is interpreted as "VDTTip0:".)

That's all there is to it! It is possible to yield even more control by investigating and/or altering the UseIndex property during the Popup event. It is loaded with the NN value before each Popup event.

One caveat: The Delay property is not unique for each VDTTip, only the value of the first VDTTip is used.

Invisible tool tips

If the UseIndex property refers to a non-existing VDTTip, nothing will be displayed on the screen. But the PopDown event will still be executed as usual when the mouse gets removed from the control. Because of this, advantage may be taken of VDTTip's tracking feature. In particular, VDTTip tracks movements above a disabled control, this would otherwise be a tricky task.

Migrating DBTTip

Since you're not likely to have many DBTTips in your app (typically just one per project), no special action has been taken to support migration; just load your 16-bit project and accept the error when DBTTip.VBX cannot be loaded and then add VDTTip to the project.

The major changes to be aware of are:

The Popup event parameters are named differently, some must be declared ByVal and the x & y parameters are mow measured in pixels instead of twips.
The Sensitivity property was misspelled in DBTTip.
Graphical controls require cooperation by code to work. See TipRectArea method.
Each form that should support tool tips must contain a VDTTip. DBTTip was able to work application wide. If you use pictures as tool tip bubble backgrounds you may wish to cut down the EXE file size by only including the picture in the VDTTip on the main form and then, in other form's Load event: VDTTip.Picture = frmMain.VDTTip.Picture.

Rev 1998-06-02