| Description | The DBTTip 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 | DBTTIP.VBX |
| Object Type | DBTTip |
| Remarks | Unlike most other tool tips, DBTTips don't have to be rectangles. Instead, Windows Meta Files are used as backgrounds. With DBTTip, 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 DBTTip. |
| About | |
| This control was developed by Dan Byström. For more information, contact me at e-mail: "dan.bystrom@visual-design.se", phone: +46 708 68 65 78 (no support calls, please) or fax: +46 457 274 81. I would be happy to discuss development of customized VBX'es or OCX'es for you. | |
| Distribution | You have the right to do whatever you want with DBTTip, as long as you don't attempt to modify any of its code. "Do whatever you want" includes using DBTTip in your own commercial applications and/or distributing it for free. |
| When the control is loaded in design mode a message is sometimes displayed. This message may not be removed or changed in any way. Anyway, the message won't ever appear at run-time. | |
| I'm giving DBTTip away for free. If you should decide to use it in an application of yours, this means that I have saved you a whole lot of trouble, time and $$$ doing it yourself. Therefore I think a nice gesture would be to include some sort of credit in your application's about box and/or documentation. You could include the name of the VBX, my name and my e-mail address. I would be glad if you did this. Anyway - happy VB programming with DBTTip! |
| Revision | Feb 95: | Beta release. |
| history | v0.9: | DBTTip now handles irregular shaped graphical controls. |
| v1.0: | New property added: Sensivity. | |
| v1.1: | New property added: UseIndex. | |
| v1.2: | BUGFIX: Unloading a control while it was tipped could cause GP-fault. | |
| New event added: PopDown. | ||
| New feature: Invisible tool tips! | ||
| v1.21: | BUGFIX: The tip now stays on top of forms made topmost. | |
| v1.22: | A space of two pixels on each side of the tool tip text has been added. | |
| The tool tip text may now contain double pipe characters meaning CRLF. | ||
| v1.23: | The tip cannot popup in break (debug) mode. | |
| BUGFIX: A control on a minimized form could get tipped. | ||
| v1.24: | Max tool tip text length increased to 1200 characters. | |
| The screen area under the tool tip is saved - no repaint is needed. | ||
| v1.3: | BUGFIX: The Sensivity property didn't work correctly. | |
| New property added: CtlEnabled. | ||
| v1.31: | BUGFIX: Don't tip other forms while a modal form is displayed. | |
| v1.32: | Popup wasn't fast when the mouse was moved (with the tip up) directly from one control to another. |
Properties
| *Alignment | *Aspect | *CtlEnabled | *Delay |
| *ExtraOffX | *ExtraOffY | FontBold | FontItalic |
| FontName | FontSize | FontStrikethru | FontUnderline |
| ForeColor | *HotSpotX | *HotSpotY | Index |
| *IsVisible | *MouseOffX | *MouseOffX | Name |
| Parent | *Picture | *PopupMode | *Sensivity |
| Tag | *TextBottom | *TextLeft | *TextRight |
| *TextTop | *TractorBeam | *UseIndex |
* = The property applies only to DBTTip.
Events
| * PopDown | * Popup |
* = The event applies only to DBTTip.
Alignment Property
Description
Determines the alignment of the tool tip text.
Remarks
The Alignment property settings are:
| Setting | Description |
| 0 | The caption text appears left-justified. |
| 1 | The caption text appears right-justified. |
| 2 | (Default) The caption text appears (horizontally) centered. |
Data Type
Integer (enumerated)
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
DBTTipVersion Function
Description
This function may be used to investigate the version of the system's
DBTTIP.VBX and supplying the user with an appropriate error message if
an old version is found.
Remarks
The major version number is returned in the high byte and the minor
version number is returned in the low byte. For an example, refer to the
last section of this document.
Data Type
Integer
CtlEnabled Property
Description
This property may be used during the PopUp event to determine
whether the control about to be tipped is enabled or disabled. I think
disabled controls should get tips as well, but not all users agree.
Data Type
Integer (Boolean)
Delay Property
Description
Determines the delay in ms the mouse must have been parked (immobile)
before DBTTip starts searching for a control and generates a Popup
event.
Data Type
Integer
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
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
Integer (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
Picture Property
Description
Determines the picture to be used as the tool tip's background.
Remarks
This property must be loaded with a picture, otherwise nothing
is displayed. Only Windows Meta Files (WMF) may be used. This is because
WMFs may be resized with no loss of quality and the tool tip must be resized
for each text it displays. Another reason is that they don't have to be
rectangular.
Data Type
Picture
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 | (Default) Automatic. DBTTip 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). |
If it for some reason is desirable to have multiple DBTTips in an application, it may be better to use the manual pop-up mode (to avoid competition between the DBTTips and wasting precious timer resources). All but the desired DBTTip may then have their PopupMode set to manual in response to a control's MouseMove event.
Data Type
Integer (enumerated)
Sensivity 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
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
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
PopDown Event
Description
Occurs when a tool tip gets removed from the screen.
Sub DBTTip_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 DBTTip_Popup ( CtlName As String, CtlIndex As Integer, hWnd As Integer, strText As String, X As Single, Y As Single )
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). |
| hWnd | The hWnd of the control being tipped (this parameter is zero for graphical controls). |
| strText | The desired tool tip text. If the control has as standard Tag property beginning with the text "DBTTip:", 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 twips, relative the control. These parameters may be used in conjunction with the ExtraOffX and 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.
UseIndex Property
Description
This property is used to select which DBTTip (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 DBTTip
index number specified in a control's Tag property. I.e. a tag containing
"DBTTip2:A tool tip text" results in UseIndex = 2. This
value may be changed during the Popup event.
Data Type
Integer
The appearance of the tool tip in design mode is quite different than at run-time. Below is a typical scenario.
Fig 1: Appearance of DBTTip in design mode.
In design mode, the background of the tool tip is always white with a black border. The picture is bounded by a dotted rectangle. The reason for the area between the dotted rectangle and the border is to display a mouse cursor in order to give a visual representation of the MouseOffX and MouseOffY properties. The hot spot is indicated by a small red circle. The text surface area (the TextBottom, TextLeft, TextRight & TextTop properties) is visualized by a white frame within a black frame. No text is ever shown in design mode. The size of the tool tip in design mode is unimportant.
The tool tip text of each control may also be determined in design mode, just add the tool tip text to the controls Tag properties, prefixed with the text "DBTTip:".
Whenever the mouse is being parked at the same position for Delay
ms, DBTTip investigates if it is parked over a VB control. If it is, the
Popup event is fired. If the strText argument to the Popup
event contains text on return, the tool tip pops up. As soon as the mouse
moves away from the control, the tool tip is removed.
Note 1: DBTTip operates application-wide! There is no need to include a tool tip in more than one form. In order to have multiple tool tips in an application, make sure that no more than one is enabled at the same time.
Note 2: It is only necessary to add code to the Popup event if
the default behavior must be overridden in some way. Under normal circumstances,
no code is needed!
To summarize, below is the steps necessary to bring tool tips to your
application. Note that steps 1-5 need only be done once in an application.
Later on, you may skip these steps by copy-and-paste a DBTTip from a previous
application of yours (or from the demo supplied with DBTTip).
| 1. | Load or paste an appropriate background picture into the Picture property. The easiest way may be to select a predefined shape in Microsoft PowerPoint and copy-and-paste it. |
| 2. | Adjust the properties TextLeft, TextTop, TextRight and TextBottom to get the black/white frame to surround the area of the picture which will contain text. |
| 3. | Adjust the HotSpotX and 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. | Give the Delay property a reasonable value, say 1000 ms. |
| 6. | Finally, add the desired tool tip text of each control to it's Tag property, respectively, and prefix it with the text "DBTTip:", like this: "DBTTip:Beam me up, Scotty!". (Don't type the quotation marks!) |
This section describes the new feature of DBTTip v1.1: the ability to
use different DBTTip properties (like the background shape) for different
controls, without any coding and without having any extra timers running.
Just follow these steps:
| 1. | Make a control array of DBTTips, 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) DBTTip. |
| 2. | Tag the controls to be tipped with "DBTTipNN:", where NN is the index number of the DBTTip containing the desired configuration. (The tag "DBTTip:" is interpreted as "DBTTip0:".) |
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 DBTTip,
only the value of the first DBTTip is used.
If the UseIndex property refers to a non-existing DBTTip, 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 DBTTip's tracking feature. In particular,
DBTTip tracks movements above a disabled control, this would otherwise
be a tricky task.
The source code for the tool tip window itself is included in the file
TIPWND.C, if anyone should want to know what that little obscure thing
is made up of. (It's a quite normal window, the source should prove just
that.)
When the tool tip is up, the mouse is captured by DBTTip. Mouse messages
are sent to the underlying control (if it's enabled, that is) by
DBTTip while this happens. If DBTTip for some reason looses the capture,
the tool tip is removed.
The following code shows an easy way to check the version of DBTTIP.VBX before it is accessed by VB. In a global module, put the following declaration:
Declare Function DBTTipVersion Lib "dbttip.vbx" () As Integer
Then use a Sub Main() as your program's entry point:
Sub Main()
If DBTTipVersion() < &H131& Then
MsgBox "Your DBTTIP.VBX is too old for
this program!", 16
End
End If
'Load your main form here
End Sub