ACC2: How to Add ToolTips to Form Controls

• Microsoft Access version 2.0

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.

1. Create a new, unbound form with the following properties:

         RecordSource: <blank>
         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.
   
   

2. 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
   
   

3. Delete the text box's label.

4. Set the detail section's Height property to:

         0.166 in
   

5. Save the form as ToolTips, and then close it.

6. Create a new module and type the following lines in the Declarations section:

         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
   
   

7. 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
   
         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
   
   

8. 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:

1. 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
   
   

2. 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
   
   

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:

   DoCmd Close A_FORM, "ToolTips"

REFERENCES