Microsoft KB Archive/119991

= ACC2: How to Add ToolTips to Form Controls =

Article ID: 119991

Article Last Modified on 11/6/2000

-

APPLIES TO


 * Microsoft Access 2.0 Standard Edition

-



This article was previously published under Q119991



SUMMARY
Advanced: Requires expert coding, interoperability, and multiuser skills.

This article describes how to add ToolTips to form controls. ToolTips refers to the "balloon help" feature that displays the name of a control when the user passes the pointer over a particular control.

This article assumes that you are familiar with Access Basic and with creating Microsoft Access applications using the programming tools provided with Microsoft Access. For more information on Access Basic, please refer to the "Building Applications" manual.



MORE INFORMATION
NOTE: Microsoft Access for Windows 95 introduces the new ControlTip Text property for controls on a form to implement tooltips.

The following steps demonstrate how to create a pop-up form to display ToolTips for a form control, and how to create an Access Basic module with procedures for displaying and hiding the ToolTips form.

NOTE: The following technique cannot be used to tooltip enable controls on pop-up or dialog forms. The tooltip itself is a pop-up form. Pop-up forms cannot float on top of other pop-up forms.

NOTE: In the following sample code, an underscore (_) at the end of a line is used as a line-continuation character. Remove the underscore from the end of the line when re-creating this code in Access Basic.

  Create a new, unbound form with the following properties:

     RecordSource: ScrollBars: Neither RecordSelectors: No     NavigationButtons: No      PopUp: Yes BorderStyle: None Width: 4 in     OnTimer: [Event Procedure]

OnTimer Event Procedure ---     Sub Form_Timer ShowToolTips Me     End Sub

NOTE: To create the event procedure, click in the OnTimer property field, then choose the Build button to the right of the field. Select Code Builder, and then choose OK. After you enter the code in the form module, close the module.   Add a text box with the following properties to the form:

     Name: TipText Left: 0 Top: 0 Width: 4 in     Height: 0.166 in      BackColor: 8454143 BorderStyle: Clear FontName: MS Sans Serif FontSize: 8 TextAlign: Center OnMouseMove: [Event Procedure]

OnMouseMove Event Procedure -     Sub TipText_MouseMove (Button As Integer, Shift As Integer, _         X As Single, Y As Single) HideToolTips End Sub  Delete the text box's label.  Set the detail section's Height property to:

     0.166 in                         Save the form as ToolTips, and then close it.</li>  Create a new module and type the following lines in the Declarations section:

<pre class="fixed_text">     Option Explicit

' Tip Delay (time to wait to display tip) constants (in     ' milliseconds). Const TipDelayIfHidden = 1000 Const TipDelayIfVisible = 100

' Tip size and placement adjustment constants. Const AdjustTipWidth = .75 Const AdjustTipWidthPixel = 5 Const AdjustTipLeft = .3 Const AdjustTipTop = .6

' Windows API constants and Declarations. Type POINTAPI X As Integer Y As Integer End Type

Type RECT Left As Integer Top As Integer Right As Integer Bottom As Integer End Type

Global Const SM_CXCURSOR = 13 Global Const SM_CYCURSOR = 14 Global Const SW_SHOWNOACTIVATE = 4 Global Const TwipsPerPixel = 15

Declare Sub GetCursorPos Lib "User" (lpPoint As POINTAPI) Declare Sub GetWindowRect Lib "User" (ByVal hWnd%, lpRect As RECT) Declare Sub MoveWindow Lib "User" (ByVal hWnd%, ByVal X%, _        ByVal Y%, ByVal nWidth%, ByVal nHeight%, ByVal bRepaint%) Declare Function GetDC Lib "User" (ByVal hWnd%) As Integer Declare Function GetSystemMetrics Lib "User" (ByVal nIndex%) _ As Integer Declare Function GetTextExtent Lib "GDI" (ByVal hDC%, _        ByVal lpString As String, ByVal nCount%) As Long Declare Function ReleaseDC Lib "User" (ByVal hWnd%, ByVal hDC%) _ As Integer Declare Function ShowWindow Lib "User" (ByVal hWnd%, _        ByVal CmdShow%) As Integer

' ToolTips variables to store tip information. Global TipPoint As POINTAPI Global TipText As String Global TipTextLast As String </li>  Type the following four Access Basic procedures in the module:

Sub ToolTips (MyTipText) ' **********************************************************     ' PURPOSE: Sets up ToolTips for view after a delay of      '    TipDelayIfHidden or TipDelayIfVisible milliseconds '   using the ToolTips form's Timer event. ' USAGE: Call this procedure from the MouseMove event of any '   control for which you want to display ToolTips. ' PARAMETERS: '   MyTipText: The ToolTips caption text. ' **********************************************************        Dim Tip As Form

' Get tip form and open if not yet opened. On Error Resume Next Set Tip = Forms!ToolTips If Err Then StartToolTips

' If the tip is already visible with the desired ' text, then exit. If Tip.Visible And TipText = MyTipText Then Exit Sub

' Record new tip information. TipTextLast = TipText  ' Save last tip. TipText = MyTipText    ' Save new tip text. GetCursorPos TipPoint  ' Get and save the current mouse ' pointer position.

' Set new tip delay (time to wait before displaying the tip).

' If the tip is NOT visible... If Not Tip.Visible Then ' ...then set the standard delay to display the tip '   from a hidden state. Tip.TimerInterval = TipDelayIfHidden Else ' ...otherwise the pointer is moving from tip to tip, so           '    set a shorter delay. Set a shorter delay only if the '   shorter delay has not yet been set. If Tip.TimerInterval <> TipDelayIfVisible Then Tip.TimerInterval = TipDelayIfVisible End If        End If      End Sub

Sub HideToolTips ' **********************************************************     ' PURPOSE: Hides ToolTips from view. ' USAGE: Call from the MouseMove event of all form sections '  that contain ToolTips-enabled controls. '  OPTIONAL (but recommended): Call from the MouseMove event '  of all form sections on all forms and from MouseMove '  events of controls that are not ToolTips-enabled. ' CALLED FROM: MouseMove event of the TipText text box, the '   ShowToolTips procedure, the MouseMove event of form '   sections, and non-ToolTips-enabled controls. ' **********************************************************        Dim F As Form

' Get tip form and open if not yet opened On Error Resume Next Set F = Forms!ToolTips If Err Then StartToolTips

' Hide tip and turn delay off F.Visible = False F.TimerInterval = 0 End Sub </li></ol>

Sub ShowToolTips (Tip As Form) ' **********************************************************     ' PURPOSE: Displays ToolTips caption. ' CALLED FROM: ToolTips form Timer event only. ' **********************************************************        Dim P As POINTAPI Dim R As RECT Dim hDC As Integer Dim RetVal As Integer Dim TipLeft As Integer, TipTop As Integer Dim TipWidth As Integer, TipHeight As Integer

' Get the current mouse pointer position. GetCursorPos P

' If displaying the tip from a hidden state was delayed... If Tip.TimerInterval = TipDelayIfHidden Then ' ...and the mouse pointer position does not match the '   pre-delay position... If Not (P.X = TipPoint.X And P.Y = TipPoint.Y) Then ' ...then hide the tip and exit. HideToolTips Exit Sub End If        End If

' Turn the tip delay off. Tip.TimerInterval = 0

' Compute approximate TipWidth. hDC = GetDC(0) TipWidth = GetTextExtent(hDC, TipText, Len(TipText)) And &HFFFF& RetVal = ReleaseDC(0, hDC) TipWidth = (TipWidth * AdjustTipWidth) + AdjustTipWidthPixel

' Compute TipHeight. GetWindowRect Tip.hWnd, R        TipHeight = R.Bottom - R.Top

' Compute TipLeft. TipLeft = P.X + (GetSystemMetrics(SM_CXCURSOR) * AdjustTipLeft) TipLeft = TipLeft - (TipWidth / 2)

' Compute TipTop. TipTop = P.Y + (GetSystemMetrics(SM_CYCURSOR) * AdjustTipTop)

' Hide tip form. Tip.Visible = False

' Set tip text. Tip!TipText = TipText

' Set tip text box width. Tip!TipText.Width = TipWidth * TwipsPerPixel

' Move and size tip form. MoveWindow Tip.hWnd, TipLeft, TipTop, TipWidth, TipHeight, False

' Show tip form. RetVal = ShowWindow(Tip.hWnd, SW_SHOWNOACTIVATE) End Sub

Private Sub StartToolTips ' **********************************************************     ' PURPOSE: Opens the ToolTips form. ' CALLED FROM: HideToolTips, ShowToolTips procedures only. ' **********************************************************         DoCmd OpenForm "ToolTips",, , , , A_HIDDEN End Sub


 * 1) Save the module as ToolTips.

How to Use the ToolTips Form and ToolTips Procedures
To enable ToolTips for a control on a form, follow these steps:

<ol>  Call the ToolTips procedure from the control's MouseMove event, supplying the text for the tip as an argument. For example, the MouseMove event procedure for a command button called SaveRecord would look as follows:

Sub SaveRecord_MouseMove (Button As Integer, Shift As Integer, _                               X As Single, Y As Single) ToolTips "Save Record" End Sub </li>  Call the HideToolTips procedure from the MouseMove event of form sections holding any ToolTips-enabled controls. For example, the MouseMove event of a form detail section containing the SaveRecord button from the above example would look like:

Sub Detail0_MouseMove (Button As Integer, Shift As Integer, _     X As Single, Y As Single) HideToolTips End Sub </li></ol>

NOTE: You must call the HideToolTips procedure to dismiss ToolTips. To be sure that tips are dismissed when unnecessary, you should call the HideToolTips procedure from the MouseMove event of all controls that are not ToolTips-enabled, as well as from all form section MouseMove events. You should also call this procedure from forms that do not contain ToolTips, but that may be running in conjunction with ToolTips-enabled forms.

For example, if you have two buttons next to each other on a form, and one of the buttons is ToolTips-enabled and the other is not, ToolTips will not be dismissed if the mouse pointer passes from the ToolTips-enabled button to the other button unless the other button calls the HideToolTips procedure from its MouseMove event.

If you plan to use ToolTips for buttons on a toolbar, make sure to leave some part of the section surrounding the buttons visible, so that the section's MouseMove event can call the HideToolTips procedure.

Fine-Tuning the Size and Placement of ToolTips
The Declarations section of the ToolTips module contains some constants that you can use to adjust the size, placement, and behavior of the ToolTips form.

ToolTips Delay Constants:

The TipDelayIfHidden and TipDelayIfVisible constants specify the amount of time (in milliseconds) to wait before the ToolTips form is displayed. The TipDelayIfHidden constant specifies how long to wait if the mouse pointer is positioned over a ToolTips-enabled control and the tip is not yet visible. The TipDelayIfVisible constant specifies how long to wait if the mouse pointer is being moved from one visible tip to another.

ToolTips Size Constants:

The width of the ToolTips form is based on the width of the tip text, and is approximated using the GetTextExtent Windows API call and the AdjustTipWidth and AdjustTipWidthPixel constants. To increase the amount of empty space to the left and right of the centered tip text, increase the value of the constants. To decrease the amount of empty space, decrease the constants.

NOTE: Tips with a number of wide letters (like "M" and "W") using a proportionally-spaced font may be truncated if the values of the AdjustTipWidth and AdjustTipWidthPixel constants are too small. Tips with a number of narrow characters (like "i" and "j") may contain too much empty space if these constants are too small.

ToolTips Position Constants:

The AdjustTipLeft and AdjustTipTop constants specify the position of the ToolTips in relation to the mouse pointer. Increase these values to position the ToolTips lower and further to the right. Decrease these values to position the ToolTips higher and further to the left. Note that you can use negative numbers for these values.

Closing the ToolTips Form
When you are working with and debugging the ToolTips form and ToolTips code, the ToolTips form may get "stuck" on. If this happens, you will have to close the running, hidden ToolTips form manually. To close the form, run the following statement in the Immediate window:

<pre class="fixed_text">  DoCmd Close A_FORM, "ToolTips"

<div class="references_section">