TUTORIAL 27: Tooltip Control
We Well Learn About The Tooltip Control: What It is and how to create and use it.
Theory: A tooltip is a small rectangular window that is displayed when the mouse pointer hovers over some specific area A tooltip window contains some text that the programmer wants to be displayed In this regard, a tooltip servers the same role as the status window.. but it disappears when the user clicks or moves the mouse pointer away from the designated area. you'll probably be familiar with the tooltips that are associated with toolbar buttons. Those "tooltips" are conveniencies provided by the toolbar control. If you want tooltips For Other Windows / Controls, you need to create your owltip control.
Now That You Know What a Tooltip IS, Let's Go ON To HOW We can create and use it. The steps are outlined Below:
Create a tooltip control with CreateWindowEx Define a region that the tooltip control will monitor for mouse pointer movement. Submit the region to the tooltip control Relay mouse messages of the submitted region to the tooltip control (this step may occur earlier, depending on the method used TO RELAY THE Messages WE WLL Next Examine Each Step in detail.
Tooltip Creationa Tooltip Control Is A Common Control. As Such, You NEED TO CALL
INITCOMMONCONTROLS Somewhere In Your Source Code So That Masm Implicitly Links Your Program To ComctL32.dll. You Create A Tooltip Control with CreateWindowEx. The Typical Scenario Would Be Like this:
.DATA
TooltipClassName DB "Tooltips_Class32", 0
.code
.....
Invoke INITCOMMONCONTROLS
invoke CreateWindowEx, NULL, addr TooltipClassName, NULL, TIS_ALWAYSTIP, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, NULL, NULL, hInstance, NULLNote the window style:
TIS_ALWAYSTIP. This style specifies that the tooltip will be shown when the mouse pointer is over the designated area regardless of the status of the window that contains the area. Put simply, if you use this flag, when the mouse pointer hovers over the area you Register to the tooltip control, The Tooltip Window Will Appear Even IF The window Under The Mouse Pointer is inactive.
You don't have to include
WS_POPUP AND
WS_EX_TOOLWINDOW styles in CreateWindowEx because the tooltip control's window procedure adds them automatically You also do not need to specify the coordinate, the height and width of the tooltip window:. The tooltip control will adjust them automatically to fit the tooltip text that will be displayed , Thus We Supply
CW_USEDEFAULT IN All Four Parameters. The Remaining Parameters Are Not Remarkable.
Specifying the toolThe tooltip control is created but it's not shown immediately. We want the tooltip window to show up when the mouse pointer hovers over some area. Now is the time to specify that area. We call such area "
tool ". A tool is a rectangular area on the client area of a window which the tooltip control will monitor for mouse pointer. If the mouse pointer hovers over the tool, the tooltip window will appear. The rectangular area can cover the whole client area or only a part of it So we can divided tool into two types:... one that is implemented as a window and another that is implemented as a rectangular area in the client area of some window Both has their uses The tool that covers the whole client area of a window is most frequently used with controls such as buttons, edit controls and so on You do not need to specify the coordinate and the dimensions of the tool:. it's assumed to be the whole client area of the window. The tool that is implemented as a rectangular area on the client area is useful when you want to divide the client area of a window into several regions without using child windows. With this type of tool, you need to specify the coordinate of the upper left Corner and the wi Dth and Height of the Tool.You Specify The Tool with the THE
ToolInfo Structure Which Has The Following Definition:
ToolInfo Struct
CBSIZE DWORD?
UFLAGS DWORD?
HWND DWORD?
Uid DWORD?
Rect RECT <>
Hinst DWORD?
LPSZTEXT DWORD?
LPARAM LPARAM?
ToolInfo Ends
Field NameExplanationcbSizeThe size of the TOOLINFO structure. You MUST fill this member. Windows will not flag error if this field is not filled properly but you will receive strange, unpredictable results.uFlagsThe bit flags that specifies the characteristics of the tool. This value can be A Combination of the Following Flags:
TTF_IDISHWND "ID is hWnd". If you specify this flag, it means you want to use a tool that covers the whole client area of a window (the first type of tool above). If you use this flag, you must fill the uId member of this structure with the handle of the window you want to use. If you do not specify this flag, it means you want to use the second type of tool, the one that is implemented as the rectangular area on the client window. In that case, you need to fill the rect member with the dimension of the rectangle. TTF_CENTERTIP Normally the tooltip window will appear to the right and below the mouse pointer. If you specify this flag, the tooltip window will always appear directly below the tool and is centered regardless of the position of the mouse pointer. TTF_RTLREADING You can forget about this flag if your program is not designed specifically for Arabic or Hebrew systems. This flag displays the tooltip text with right-to-left reading order. Does not Work under other systems. TTF_ SUBCLASS If you use this flag, it means you tell the tooltip control to subclass the window that the tool is on so that the tooltip control can intercept mouse messages that are sent to the window. This flag is very handy. If you do not use this flag, you have to do more work to relay the mouse messages to the tooltip control. hWndHandle to the window that contains the tool. If you specify TTF_IDISHWND flag, this field is ignored since Windows will use the value in uId member as the Window Handle. You NEED TO FILL THIS FIELD IF:
You do not use TTF_IDISHWND flag (in other words, you use a rectangular tool) You specify the value LPSTR_TEXTCALLBACK in lpszText member. This value tells the tooltip control that, when it needs to display the tooltip window, it must ask the window that contains the tool for the text to be displayed. This is a kind of dynamic realtime tooltip text update. If you want to change your tooltip text dynamically, you should specify LPSTR_TEXTCALLBACK value in lpszText member. The tooltip control will send TTN_NEEDTEXT notification message to the window identified by the handle in hWnd field. uIdThe value in this field can have two meanings, depending on whether the uFlags member contains the flag TTF_IDISHWND.Application-defined tool ID if the TTF_IDISHWND flag is not specified. Since this means you use a tool Which Covers Only a Part of The Client Area, IT '
s logical that you can have many such tools on the same client area (without overlap). The tooltip control needs a way to differentiate between them. In this case, the window handle in hWnd member is not enough since all tools are on the same window. The application-defined IDs are thus necessary. The IDs can be any value so long as they are unique among themselves. The handle to the window whose whole client area is used as the tool if the TTF_IDISHWND flag is specified. You may wonder Why this field is used to store the window handle instead of the hwnd field Above. The answer is:
the hWnd member may already be filled if the value LPSTR_TEXTCALLBACK is specified in the lpszText member and the window that is responsible for supplying the tooltip text and the window that contains the tool may NOT be the same (You can design your program so that a single window can serve both roles but this is too restrictive. In this case, Microsoft gives you more freedom. Cheers.) rectA RECT structure that specifies the dimension of the tool. This structure defines a rectangle relative to the upper left corner of the client area of the window specified by the hWnd member. In short, you must fill this structure if you want to specify a tool that covers only a part of the client area. The tooltip control will ignore this field if you specify TTF_IDISHWND flag (you choose to use a tool that covers the whole client area) hInstThe handle of the instance that contains the string resource that will be used as the tooltip text if the value in the lpszText member specifies the string reso urce identifier. This may sound confusing. Read the explanation of the lpszText member first and you will understand what this field is used for. The tooltip control ignores this field if the lpszText field does not contain a string resource identifier.lpszTextThis field can have Several VALUES:
If you specify the value LPSTR_TEXTCALLBACK in this field, the tooltip control will send TTN_NEEDTEXT notification message to the window identified by the handle in hWnd field for the text string to be displayed in the tooltip window. This is the most dynamic method of tooltip text update : you can change the tooltip text each time the tooltip window is displayed If you specify a string resource identifier in this field, when the tooltip control needs to display the tooltip text in the tooltip window, it searches for the string in the string table. of the instance specified by hInst member. The tooltip control identifies a string resource identifier by checking the high word of this field. Since a string resource identifier is a 16-bit value, the high word of this field will always be zero. This method IS Useful if you plan to port your program to other languages. Since the string resource is defined in a resource script, you do't nesed to modify the source code.you Only Have to Modify the string table and the tooltip texts will change without the risk of introducing bugs into your program. If the value in this field is not LPSTR_TEXTCALLBACK and the high word is not zero, the tooltip control interprets the value as the pointer to a text string that will be used as the tooltip text. This method is the easiest to use but the least flexible.To recapitulate, you need to fill the TOOLINFO structure prior to submitting it to the tooltip control. This structure describes the characteristics of the tool you desire.
Register the Tool with the Tooltip Controlafter You Fill THE
TOOLINFO structure, you must submit it to tooltip control. A tooltip control can service many tools so it is usually unnecessary to create more than one tooltip control for a window. To register a tool with a tooltip control, you send theTTM_ADDTOOL message to the tooltip Control. The
WPARAM IS Not Used and the
LParam Must Contain The Address of The
Toolinfo structure you want to register.
.DATA?
Ti ToolInfo <>
.......
.code
.......
.......
Invoke SendMessage, HWNDTooltip, TTM_ADDTOOL, NULL, ADDR TI
SendMessage for this Message Will Return
True if the Tool Is SuccessFully Registered with The Tooltip Control,
False Otherwise.
You can unregister the Tool by sending
TTM_DELTOOL MESSAGE TO The Tooltip Control.
Relaying Mouse Messages to the Tooltip ControlWhen the above step is completed, the tooltip control knows which area it should monitor for mouse messages and what text it should display in the tooltip window. The only thing it lacks is the * trigger * for that action. Think about it:. the area specified by the tool is on the client area of the other window How can the tooltip control intercept the mouse messages destined for that window It needs to do so in order that it can measure the amount of time the? mouse pointer hovers over a point in the tool so that when the specified amount of time elapses, the tooltip control shows the tooltip window. There are two methods of accomplishing this goal, one that requires the cooperation of the window that contains the tool and the Other without the cooperation on the part of the window.
The window that contains the tool must relay the mouse messages to the tooltip control by sending TTM_RELAYEVENT messages to the control. The lParam of this message must contain the address of a MSG structure that specifies the message to be relayed to the tooltip control. A tooltip control processes only the following mouse messages: WM_LBUTTONDOWN WM_MOUSEMOVE WM_LBUTTONUP WM_RBUTTONDOWN WM_MBUTTONDOWN WM_RBUTTONUP WM_MBUTTONUP All other messages are ignored Thus in the window procedure of the window that contains the tool, there must be a switch that does something like this:. WndProc proc hWnd: DWORD UMSG: DWORD, WPARAM: DWORD, LPARAM: DWORD ....... IF umsg == wm_create ............. elseif umsg == wm_lbuttondown || UMSG == WM_MouseMove || uMsg == WM_LBUTTONUP || uMsg == WM_RBUTTONDOWN || uMsg == WM_MBUTTONDOWN || uMsg == WM_RBUTTONUP || uMsg == WM_MBUTTONUP invoke SendMessage, hwndTooltip, TTM_RELAYEVENT, NULL, addr msg .......... You CAN Specify TTF_SUBCLASS FLAG IN the uFlags member of the TOOLINFO structure. This flag tells the tooltip control to subclass the window that contains the tool so it can intercept the mouse messages without the cooperation of the window. This method is easier to use since it does not require more coding than specifying TTF_SUBCLASS flag and the tooltip control handles all the message interception itself. That's it. At this step, your tooltip control is fully functional. There are several useful tooltip-related messages you should know about.
TTM_ACTIVATE. If you want to disable / enable the tooltip control dynamically, this message is for you. If the wParam value is TRUE, the tooltip control is enabled. If the wParam value is FALSE, the tooltip control is disabled. A tooltip control is enabled when it first created so you do not need to send this message to activate it. TTM_GETTOOLINFO and TTM_SETTOOLINFO. If you want to obtain / change the values in the TOOLINFO structure after it was submitted to the tooltip control, use these messages. you need to specify the tool you need to change with the correct uId and hWnd values. If you only want to change the rect member, use TTM_NEWTOOLRECT message. If you only want to change the tooltip text, use TTM_UPDATETIPTEXT. TTM_SETDELAYTIME. with this message, you can specify the time delay the tooltip control uses when it's displaying the tooltip text and much more.Example: The following example is a simple dialog box with two buttons The client area of the dialog box is divided into 4 ar. EAS: Upper Left, Upper Right, Lower Left and Lower Right. Each Area Is Specified As a Tool with Its Owoltip Text. The Two Buttons Also Has Their OWN Tooltip Texts.
.386
.Model flat, stdcall
Option CaseMAP: NONE
INCLUDE /MASM32/INCLUDE/Windows.inc
INCLUDE /MASM32/INCLUDE / WANEL32.INC
INCLUDE /MASM32/INCLUDE/USER32.INC
INCLUDE /MASM32/INCLUDE/ComctL32.inc
INCLUDELIB /MASM32/LIB/ComctL32.lib
INCLUDELIB /MASM32/LIB/USER32.LIB
INCLUDELIB /MASM32/LIB/kernel32.lib
DLGPROC Proto: DWORD,: DWORD,: DWORD,: DWORD
ENUMCHILD PROTO: DWORD,: DWORD
Setdlgtoolarea Proto: DWORD,: DWORD,: DWORD,: DWORD,: DWORD
.const
IDD_MAINDIALOG EQU 101
.DATA
TooltipsClassName DB "Tooltips_Class32", 0
Maindialogtext1 DB "this is the upper left area of the dialog", 0MAINDIALOGTEXT2 DB "this is the Upper right area of the dialog", 0
MaindialogText3 DB "this is the limited lying limited area of the dialog", 0
MAINDIALOGTEXT4 DB "this is the lower right area of the dialog", 0
.DATA?
HWNDTOOL DD?
Hinstance DD?
.code
Start:
Invoke getModuleHandle, NULL
Mov Hinstance, EAX
Invoke Dialogboxparam, Hinstance, IDD_MAINDIALOG, NULL, ADDR DLGPROC, NULL
Invoke EXITPROCESS, EAX DLGPROC PROC HDLG: DWORD, UMSG: DWORD, WPARAM: DWORD, LPARAM: DWORD
Local Ti: ToolInfo
Local ID: DWORD
Local Rect: RECT
.IF uMSG == WM_INITDIALOG
Invoke INITCOMMONCONTROLS
Invoke CreateWindowex, Null, Addr TooltipsclassName, NULL, /
TTS_ALWAYSTIP, CW_USEDEFAULT, /
CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, NULL, NULL, /
Hinstance, NULL
Mov hwndtool, EAX
MOV ID, 0
Mov Ti.cbsize, Sizeof ToolInfo
Mov Ti.uflags, TTF_SUBCLASS
Push HDLG
POP Ti.hwnd
Invoke GetWindowRect, HDLG, Addr Rect
Invoke setdlgtolarea, HDLG, Addr Ti, Addr MageDialogtext1, ID, AddR Rect
INC ID
Invoke setdlgtolarea, HDLG, Addr Ti, Addr MageDialogtext2, ID, AddR Rect
INC ID
Invoke Setdlgtolarea, HDLG, Addr Ti, Addr MAINDIALOGTEXT3, ID, ADDR RECT
INC ID
Invoke Setdlgtoolarea, HDLG, Addr Ti, Addr MageDialogText4, ID, Addr Rect
Invoke EnumchildWindows, HDLG, Addr Enumchild, Addr Ti
.ELSEIF uMSG == WM_Close
Invoke EndDialog, HDLG, NULL
.lse
Mov Eax, False
RET
.endif
Mov Eax, True
RET
DLGPROC ENDP ENUMCHILD PROC Uses Edi HWNDCHILD: DWORD, LPARAM: DWORD
Local buffer [256]: Byte
MOV EDI, LPARAM
Assume EDI: PTR ToolInfo
Push HWNDCHILD
POP [EDI] .UID
OR [EDI] .uflags, TTF_IDishWnd
Invoke GetWindowText, HWNDCHILD, ADDR BUFFER, 255
Lea Eax, Buffer
MOV [EDI] .lpsztext, EAX
Invoke SendMessage, Hwndtool, TTM_ADDTOOL, NULL, EDIASSUME EDI: NOTING
RET
ENUMCHILD ENDP SETDLGTOOLAREA Proc Uses Edi ESI HDLG: DWORD, LPTI: DWORD, LPTEXT: DWORD, ID: DWORD, LPRECT: DWORD
MOV EDI, LPTI
Mov ESI, LPRECT
Assume ESI: PTR Rect
Assume EDI: PTR ToolInfo
.IF id == 0
MOV [EDI] .Rect.Left, 0
MOV [EDI] .Rect.top, 0
Mov Eax, [ESI] .right
Sub Eax, [ESI] .left
SHR EAX, 1
MOV [EDI] .Rect.right, EAX
Mov Eax, [ESI] .bottom
Sub Eax, [ESI] .top
SHR EAX, 1
MOV [EDI] .Rect.Bottom, EAX
.ELSEIF ID == 1
Mov Eax, [ESI] .right
Sub Eax, [ESI] .left
SHR EAX, 1
INC EAX
MOV [EDI] .Rect.Left, EAX
MOV [EDI] .Rect.top, 0
Mov Eax, [ESI] .right
Sub Eax, [ESI] .left
MOV [EDI] .Rect.right, EAX
Mov Eax, [ESI] .bottom
Sub Eax, [ESI] .top
MOV [EDI] .Rect.Bottom, EAX
.ELSEIF ID == 2
MOV [EDI] .Rect.Left, 0
Mov Eax, [ESI] .bottom
Sub Eax, [ESI] .top
SHR EAX, 1
INC EAX
MOV [EDI] .Rect.top, EAX
Mov Eax, [ESI] .right
Sub Eax, [ESI] .left
SHR EAX, 1
MOV [EDI] .Rect.right, EAX
Mov Eax, [ESI] .bottom
Sub Eax, [ESI] .top
MOV [EDI] .Rect.Bottom, EAX
.lse
Mov Eax, [ESI] .right
Sub Eax, [ESI] .left
SHR EAX, 1
INC EAX
MOV [EDI] .Rect.Left, EAX
Mov Eax, [ESI] .bottom
Sub Eax, [ESI] .top
SHR EAX, 1
INC EAX
MOV [EDI] .Rect.top, EAX
Mov Eax, [ESI] .right
Sub Eax, [ESI] .left
MOV [EDI] .Rect.right, EAX
Mov Eax, [ESI] .bottom
Sub Eax, [ESI] .top
MOV [EDI] .Rect.Bottom, EAX
.endif
Push lptext
POP [EDI] .lpsztext
Invoke SendMessage, HwndTool, TTM_ADDTOOL, NULL, LPTI
Assume EDI: Nothing
Assume ESI: Nothing
RET
Setdlgtoolarea ENDP
End Start
Analysis: after the main dialog window is created, we create the tooltip control with createwindowex.
Invoke INITCOMMONCONTROLS
Invoke CreateWindowex, Null, Addr TooltipsclassName, NULL, /
TTS_ALWAYSTIP, CW_USEDEFAULT, /
CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, NULL, NULL, / HINSTANCE, NULL
Mov hwndtool, EAX
After That, We Proceed To Define Four Tools for Each Corner of The Dialog Box. Mov ID, 0; Used As The Tool ID
Mov Ti.cbsize, Sizeof ToolInfo
Mov Ti.uflags, TTF_SUBCLAS; Tell The Tooltip Control to Subclass The Dialog Window.
Push HDLG
Pop Ti.hWnd; Handle to the window That Contains the Tool
Invoke GetWindowRect, HDLG, Addr Rect; Obtain The Dimension of the Client Area
Invoke setdlgtolarea, HDLG, Addr Ti, Addr MageDialogtext1, ID, AddR Rect
We initialize the members of TOOLINFO structure. Note that we want to divide the client area into 4 tools so we need to know the dimension of the client area. That's why we call GetWindowRect. We do not want to relay mouse messages to the tooltip control ourselves so we specify TIF_SUBCLASS flag. SetDlgToolArea is a function that calculates the bounding rectangle of each tool and registers the tool to the tooltip control. I will not go into gory detail on the calculation, suffice to say that it divides the client area INTO 4 AREAS WITH SAME SIZES. THEN IT SENDS TTM_ADDTOOL MESSAGE TO The Tooltip Control, Passing The Address of The ToolInfo Structure In The LPARAM Parameter.
Invoke SendMessage, HwndTool, TTM_ADDTOOL, NULL, LPTI
After all 4 tools are registered, we can go on to the buttons on the dialog box. We can handle each button by its ID but this is tedious. Instead, we will use EnumChildWindows API call to enumerate all controls on the dialog box and then Registers The To The Tooltip Control. EnumchildWindows Has The Following Syntax: 0000-00-00 0000-00-00: 00_UMCHILDWINDOWS:
ENUMCHILDWINDOWS PROTO HWND: DWORD, LPENUMFUNC: DWORD, LPARAM: DWORD
hWnd is the handle to the parent window. lpEnumFunc is the address of theEnumChildProc function that will be called for each control enumerated. lParam is the application-defined value that will be passed to the
ENUMCHILDPROC FUNCTION. THE
EnumchildProc Function Has The Following Definition:
EnumchildProc Proto Hwndchild: DWORD, LPARAM: DWORD
HWNDCHILD Is The Handle To a Control Enumerated by
EnumchildWindows. LParam is The Same LParam Value You Pass To
ENUMCHILDWINDOWS.
IN Our EXAMPLE, We Call
EnumChildWindows Like this:
Invoke EnumchildWindows, HDLG, Addr Enumchild, Addr Ti
WE Pass the address of there
ToolInfo Structure In The LParam Parameter Because We Will Register Each Child Control To The Tooltip Control in The
ENUMCHILD FUNCTION. IF we don't use this method, we need to declare
Ti as a global variable which can introduce Bugs.
WHEN We Call
ENUMCHILDWINDOWS, Windows Will Enumerate The Child Controls On Our Dialog Box and Call T
ENUMCHILD FUNCE for Each Control Enumerated. Thus IF Our Dialog Box Has Two Controls,
Enumchild Will Be Called TWICE.
.
ENUMCHILD Proc Uses Edi HWNDCHILD: DWORD, LPARAM: DWORD
Local buffer [256]: Byte
MOV EDI, LPARAM
Assume EDI: PTR ToolInfo
Push HWNDCHILD
POP [EDI] .uid; We use the whole client is the Tool AS TOOL
OR [EDI] .uflags, TTF_IDishWnd
Invoke GetWindowText, HWNDCHILD, ADDR BUFFER, 255
Lea Eax, Buffer; Use the window text as the tooltip text
MOV [EDI] .lpsztext, EAX
Invoke SendMessage, Hwndtool, TTM_ADDTOOL, NULL, EDI
Assume EDI: Nothing
RET
ENUMCHILD ENDP
Note that in this case, we use a different type of tool:.. One that covers the whole client area of the window We thus need to fill theuID field with the handle to the window that contains the tool Also we must specify
TTF_IDishWnd Flag in the
Uflags member.
