ACC2: How to Add ToolTips to Form Controls

ID: Q119991


The information in this article applies to:


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 

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


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:

   DoCmd Close A_FORM, "ToolTips" 


REFERENCES

For more information about using ToolTips in Microsoft Access, search for "ToolTips: using," and then "Displaying Information about a Toolbar or its Buttons" using the Microsoft Access Help menu.


Keywords          : kbusage FmsHowto 
Version           : 2.0
Platform          : WINDOWS 
Issue type        : kbhowto 

Last Reviewed: April 6, 1999