Adding Multiline Balloon ToolTips to ListView Items

Environment: VB4 (32-bit), VB5, VB6

The accompanying code demonstrates a technique you can use to create multiline balloon tooltips for ListView items.

The code is based on the following simple idea. In the MouseMove event, you need to check the index of the item under the mouse pointer, and if this item is changed, you simply redefine the text of the tooltip attached to the ListView control. Notice that you should destroy the tooltip if there is no item under the mouse pointer.

To determine the index of the list-view item under the mouse pointer, we send the LVM_HITTEST message to the ListView control. The SendMessage function you should use to send this message returns the index of the item at the specified position, if any, or -1 otherwise. Before you send the message, populate the pt field of an instance of the LVHITTESTINFO structure with the coordinates of the mouse pointer (you pass the reference to this structure as the value of the lParam parameter in SendMessage). You can use for this purpose the X and Y parameters of the MouseMove event of the control, but draw attention at the fact that these parameters can be measured in twips and you need to convert them in pixels.

This simple idea can be used to create such tooltips for ListBox items, any grid control items, and so on. For instance, we use this technique in extra samples for an iGrid ActiveX Control we produce. (This is an editable replacement for ListView and FlexGrid. Visit www.10Tec.com for more info.)

VERSION 5.00
Object = "{831FDD16-0C5C-11D2-A9FC-0000F8754DA1}#2.0#0"; _
        "MSCOMCTL.OCX"
Begin VB.Form Form1
   Caption         =   "Form1"
   ClientHeight    =   3195
   ClientLeft      =   60
   ClientTop       =   345
   ClientWidth     =   5745
   LinkTopic       =   "Form1"
   ScaleHeight     =   3195
   ScaleWidth      =   5745
   StartUpPosition =   3    'Windows Default
   Begin MSComctlLib.ListView ListView1
      Height          =   2595
      Left            =   120
      TabIndex        =   0
      Top             =   300
      Width           =   5475
      _ExtentX        =   9657
      _ExtentY        =   4577
      View            =   3
      LabelWrap       =   -1    'True
      HideSelection   =   -1    'True
      AllowReorder    =   -1    'True
      _Version        =   393217
      ForeColor       =   -2147483640
      BackColor       =   -2147483643
      BorderStyle     =   1
      Appearance      =   1
      NumItems        =   3
      BeginProperty ColumnHeader(1) _
           {BDD1F052-858B-11D1-B16A-00C0F0283628}
         Text            =   "Column 1"
         Object.Width    =   2540
      EndProperty
      BeginProperty ColumnHeader(2) _
           {BDD1F052-858B-11D1-B16A-00C0F0283628}
         SubItemIndex    =   1
         Text            =   "Column 2"
         Object.Width    =   2540
      EndProperty
      BeginProperty ColumnHeader(3) _
           {BDD1F052-858B-11D1-B16A-00C0F0283628}
         SubItemIndex    =   2
         Text            =   "Column 3"
         Object.Width    =   2540
      EndProperty
   End
End
Attribute VB_Name            = "Form1"
Attribute VB_GlobalNameSpace = False
Attribute VB_Creatable       = False
Attribute VB_PredeclaredId   = True
Attribute VB_Exposed         = False
Option Explicit

Private Declare Function SendMessage Lib "user32" _
        Alias "SendMessageA" (ByVal hwnd As Long, _
                              ByVal wMsg As Long, _
                              ByVal wParam As Long, _
                              lParam As Any) As Long

Const LVM_FIRST   = &H1000&
Const LVM_HITTEST = LVM_FIRST + 18

Private Type POINTAPI
    x As Long
    y As Long
End Type

Private Type LVHITTESTINFO
   pt As POINTAPI
   flags As Long
   iItem As Long
   iSubItem As Long
End Type

Dim TT As CTooltip
Dim m_lCurItemIndex As Long

Private Sub Form_Load()
   With ListView1.ListItems
      .Add Text:="Test item #1"
      .Add Text:="Test item #2"
      .Add Text:="Long long long test item #3"
   End With

   Set TT = New CTooltip
   TT.Style = TTBalloon
   TT.Icon = TTIconInfo
End Sub

Private Sub ListView1_MouseMove(Button As Integer, _
                                Shift As Integer, _
                                x As Single, _
                                y As Single)
   Dim lvhti As LVHITTESTINFO
   Dim lItemIndex As Long

   lvhti.pt.x = x / Screen.TwipsPerPixelX
   lvhti.pt.y = y / Screen.TwipsPerPixelY
   lItemIndex = SendMessage(ListView1.hwnd, _
                            LVM_HITTEST, 0, lvhti) + 1

   If m_lCurItemIndex <> lItemIndex Then
      m_lCurItemIndex    = lItemIndex
      If m_lCurItemIndex = 0 Then   ' no item under the mouse
                                    ' pointer
         TT.Destroy
      Else
         TT.Title = "Multiline tooltip"
         TT.TipText = ListView1.ListItems(m_lCurItemIndex).Text
         TT.Create ListView1.hwnd
      End If
   End If
End Sub


VERSION 1.0 CLASS
BEGIN
  MultiUse            = -1   'True
  Persistable         = 0    'NotPersistable
  DataBindingBehavior = 0    'vbNone
  DataSourceBehavior  = 0    'vbNone
  MTSTransactionMode  = 0    'NotAnMTSObject
END
Attribute VB_Name            = "CTooltip"
Attribute VB_GlobalNameSpace = False
Attribute VB_Creatable       = True
Attribute VB_PredeclaredId   = False
Attribute VB_Exposed         = False
Attribute VB_Ext_KEY         = "SavedWithClassBuilder6" ,"Yes"
Attribute VB_Ext_KEY         = "Top_Level" ,"Yes"
Option Explicit

Private Declare Sub InitCommonControls Lib "comctl32.dll" ()

''Windows API Functions
Private Declare Function CreateWindowEx Lib "user32" _
        Alias "CreateWindowExA" (ByVal dwExStyle As Long, _
        ByVal lpClassName As String, ByVal lpWindowName As String, _
        ByVal dwStyle As Long, ByVal X As Long, ByVal Y As Long, _
        ByVal nWidth As Long, ByVal nHeight As Long, _
        ByVal hWndParent As Long, ByVal hMenu As Long, _
        ByVal hInstance As Long, lpParam As Any) As Long
Private Declare Function SendMessage Lib "user32" _
        Alias "SendMessageA" (ByVal hwnd As Long, _
        ByVal wMsg As Long, ByVal wParam As Long, _
        lParam As Any) As Long
Private Declare Function SendMessageLong Lib "user32" _
        Alias "SendMessageA" (ByVal hwnd As Long, _
        ByVal wMsg As Long, ByVal wParam As Long, _
        ByVal lParam As Long) As Long
Private Declare Function DestroyWindow Lib "user32" _
        (ByVal hwnd As Long) As Long

''Windows API Constants
Private Const WM_USER       = &H400
Private Const CW_USEDEFAULT = &H80000000

''Windows API Types
Private Type RECT
        Left As Long
        Top As Long
        Right As Long
        Bottom As Long
End Type

''Tooltip Window Constants
Private Const TTS_NOPREFIX        = &H2
Private Const TTF_TRANSPARENT     = &H100
Private Const TTF_CENTERTIP       = &H2
Private Const TTM_ADDTOOLA        = (WM_USER + 4)
Private Const TTM_ACTIVATE        = WM_USER + 1
Private Const TTM_UPDATETIPTEXTA  = (WM_USER + 12)
Private Const TTM_SETMAXTIPWIDTH  = (WM_USER + 24)
Private Const TTM_SETTIPBKCOLOR   = (WM_USER + 19)
Private Const TTM_SETTIPTEXTCOLOR = (WM_USER + 20)
Private Const TTM_SETTITLE        = (WM_USER + 32)
Private Const TTS_BALLOON         = &H40
Private Const TTS_ALWAYSTIP       = &H1
Private Const TTF_SUBCLASS        = &H10
Private Const TTF_IDISHWND        = &H1
Private Const TTM_SETDELAYTIME    = (WM_USER + 3)
Private Const TTDT_AUTOPOP        = 2
Private Const TTDT_INITIAL        = 3

Private Const TOOLTIPS_CLASSA = "tooltips_class32"

''Tooltip Window Types
Private Type TOOLINFO
    lSize As Long
    lFlags As Long
    hwnd As Long
    lId As Long
    lpRect As RECT
    hInstance As Long
    lpStr As String
    lParam As Long
End Type


Public Enum ttIconType
    TTNoIcon      = 0
    TTIconInfo    = 1
    TTIconWarning = 2
    TTIconError   = 3
End Enum

Public Enum ttStyleEnum
    TTStandard
    TTBalloon
End Enum

'local variable(s) to hold property value(s)
Private mvarBackColor As Long
Private mvarTitle As String
Private mvarForeColor As Long
Private mvarIcon As ttIconType
Private mvarCentered As Boolean
Private mvarStyle As ttStyleEnum
Private mvarTipText As String
Private mvarVisibleTime As Long
Private mvarDelayTime As Long

'private data
Private m_lTTHwnd As Long        ' hwnd of the tooltip
Private m_lParentHwnd As Long    ' hwnd of the window the tooltip
                                 ' attached to
Private ti As TOOLINFO

Public Property Let Style(ByVal vData As ttStyleEnum)
   'used when assigning a value to the property, on the left side
   'of an assignment.
   'Syntax: X.Style = 5
   mvarStyle        = vData
End Property

Public Property Get Style() As ttStyleEnum
   'used when retrieving value of a property, on the right side
   'of an assignment.
   'Syntax: Debug.Print X.Style
   Style = mvarStyle
End Property

Public Property Let Centered(ByVal vData As Boolean)
   'used when assigning a value to the property, on the left side
   'of an assignment.
   'Syntax: X.Centered = 5
   mvarCentered        = vData
End Property

Public Property Get Centered() As Boolean
   'used when retrieving value of a property, on the right side
   'of an assignment.
   'Syntax: Debug.Print X.Centered
   Centered = mvarCentered
End Property

Public Function Create(ByVal ParentHwnd As Long) As Boolean
   Dim lWinStyle As Long

   If m_lTTHwnd <> 0 Then
      DestroyWindow m_lTTHwnd
   End If

   m_lParentHwnd = ParentHwnd

   lWinStyle = TTS_ALWAYSTIP Or TTS_NOPREFIX

   ''create baloon style if desired
   If mvarStyle = TTBalloon Then lWinStyle = lWinStyle _
                                             Or TTS_BALLOON
 
   m_lTTHwnd = CreateWindowEx(0&, _
      TOOLTIPS_CLASSA, _
      vbNullString, _
      lWinStyle, _
      CW_USEDEFAULT, _
      CW_USEDEFAULT, _
      CW_USEDEFAULT, _
      CW_USEDEFAULT, _
      0&, _
      0&, _
      App.hInstance, _
      0&)

   ''now set our tooltip info structure
   With ti
      ''if we want it centered, then set that flag
      If mvarCentered Then
         .lFlags = TTF_SUBCLASS Or TTF_CENTERTIP Or TTF_IDISHWND
      Else
         .lFlags = TTF_SUBCLASS Or TTF_IDISHWND
      End If
       
      ''set the hwnd prop to our parent control's hwnd
      .hwnd      = m_lParentHwnd
      .lId       = m_lParentHwnd '0
      .hInstance = App.hInstance
      '.lpstr    = ALREADY SET
      '.lpRect   = lpRect
      .lSize     = Len(ti)
   End With

   ''add the tooltip structure
   SendMessage m_lTTHwnd, TTM_ADDTOOLA, 0&, ti

   ''if we want a title or we want an icon
   If mvarTitle <> vbNullString Or mvarIcon <> TTNoIcon Then
      SendMessage m_lTTHwnd, TTM_SETTITLE, CLng(mvarIcon), _
                  ByVal mvarTitle
   End If

   If mvarForeColor <> Empty Then
      SendMessage m_lTTHwnd, TTM_SETTIPTEXTCOLOR, mvarForeColor, 0&
   End If

   If mvarBackColor <> Empty Then
      SendMessage m_lTTHwnd, TTM_SETTIPBKCOLOR, mvarBackColor, 0&
   End If

   SendMessageLong m_lTTHwnd, TTM_SETDELAYTIME, TTDT_AUTOPOP, _
                              mvarVisibleTime
   SendMessageLong m_lTTHwnd, TTM_SETDELAYTIME, TTDT_INITIAL, _
                              mvarDelayTime
End Function

Public Property Let Icon(ByVal vData As ttIconType)
   mvarIcon = vData
   If m_lTTHwnd <> 0 And mvarTitle <> Empty And mvarIcon <> _
      TTNoIcon Then
      SendMessage m_lTTHwnd, TTM_SETTITLE, CLng(mvarIcon), _
      ByVal mvarTitle
   End If
End Property

Public Property Get Icon() As ttIconType
   Icon = mvarIcon
End Property

Public Property Let ForeColor(ByVal vData As Long)
   mvarForeColor = vData
   If m_lTTHwnd <> 0 Then
      SendMessage m_lTTHwnd, TTM_SETTIPTEXTCOLOR, mvarForeColor, 0&
   End If
End Property

Public Property Get ForeColor() As Long
   ForeColor = mvarForeColor
End Property

Public Property Let Title(ByVal vData As String)
   mvarTitle = vData
   If m_lTTHwnd <> 0 And mvarTitle <> Empty And mvarIcon <> _
                     TTNoIcon Then
      SendMessage m_lTTHwnd, TTM_SETTITLE, CLng(mvarIcon), _
                  ByVal mvarTitle
   End If
End Property

Public Property Get Title() As String
   Title = ti.lpStr
End Property

Public Property Let BackColor(ByVal vData As Long)
   mvarBackColor = vData
   If m_lTTHwnd <> 0 Then
      SendMessage m_lTTHwnd, TTM_SETTIPBKCOLOR, mvarBackColor, 0&
   End If
End Property

Public Property Get BackColor() As Long
   BackColor = mvarBackColor
End Property

Public Property Let TipText(ByVal vData As String)
   mvarTipText = vData
   ti.lpStr    = vData
   If m_lTTHwnd <> 0 Then
      SendMessage m_lTTHwnd, TTM_UPDATETIPTEXTA, 0&, ti
   End If
End Property

Public Property Get TipText() As String
   TipText = mvarTipText
End Property

Private Sub Class_Initialize()
   InitCommonControls
   mvarDelayTime   =  500
   mvarVisibleTime = 5000
End Sub

Private Sub Class_Terminate()
   Destroy
End Sub

Public Sub Destroy()
   If m_lTTHwnd <> 0 Then
      DestroyWindow m_lTTHwnd
   End If
End Sub

Public Property Get VisibleTime() As Long
   VisibleTime = mvarVisibleTime
End Property

Public Property Let VisibleTime(ByVal lData As Long)
   mvarVisibleTime = lData
End Property

Public Property Get DelayTime() As Long
   DelayTime = mvarDelayTime
End Property

Public Property Let DelayTime(ByVal lData As Long)
   mvarDelayTime = lData
End Property

Downloads