Tuesday, January 29, 2013

[ MFC ] - CTooltipCtrl Example - Explains you creating control tooltip


1. Introduction


A tool tip is a flashing window that shows helpful information about the control in which the cursor is resting for some time. In this article, we will see how can we create a reusable helper class for displaying the tooltip text for the MFC dialog controls.



2. About the sample


The below-given screenshot shows the sample that we are going to develop to demonstrate the display of the tooltip using the helper class that we are going to write.



In our example, the dialog is the parent for the tool. A tool is nothing but the controls like a push button, edit box, combo box etc. A tip is a small rectangle (the yellow colored rectangle in the sample) that shows a descriptive message to the user about the tool (i.e.) the control. In the above screenshot, the tip text for the tool (Last name edit box control) is displayed when the mouse cursor enters the tool and stays at one position for some time. This means that tooltip control should track the mouse movement and display the text in the yellow background when the mouse move stops inside the tool.

MFC framework provides CToolTipCtrl class for displaying the tooltip for any controls. We are going to extend this class, to make the display of tooltip with a single simple function call. OK, let us start.



3. Extend the CToolTipCtrl


Create a dialog-based application by accepting all the defaults and name the application as TooltipExp. Once the application is created, add a class to the project and name the class as CToolTipCtrlExt. This class should derive from the MFC class CToolTipCtrl. In this tutorial, we are going to see displaying the standard tooltip, using the derived class. However, you can add more functionality to it like setting a border, displaying the hyperlink within the tooltip etc.,

To see how this new class added to the project, have a look at the below video:


Once the class is added, using the Visual Studio IDE, the dialog for this example is designed to have two textboxes and one button. From the default dialog, the ok and cancel buttons are removed and a new button is added. When the dialog is ready, control variables are added to the dialog class. Adding the control variables are shown in the below video.

4. Code Explanation for CToolTipCtrlExt

1) A public function is declared by taking two parameters. The first parameter is the tooltip text that we want to display as a helper text for the window which passed as a second parameter. The declaration can be found in the header file of the class.

//Sample 01: Declare a function to display tooltip text for a control
void Display_tooltip_text(LPCTSTR display_text, CWnd* pWnd);

2) In the implementation, the TOOLTIP info structure is populated and sent to the window procedure while sending the message TTM_ADDTOOL. The window procedure responds to this message TTM_ADDTOOL by registering the tip text with the tool.  The implementation is given below:

//Sample 02: Display the tooltip text for a given window
void CToolTipCtrlExt::Display_tooltip_text(LPCTSTR display_text, CWnd* pWnd)
{
       //2.1: Declare the Structure
       TOOLINFO ti;
       //2.2: Specify the tooltip text and window handle to the tool
       //             that requires tooltip
       ti.cbSize = sizeof(TOOLINFO);
       ti.lpszText = (LPSTR) display_text;
       ti.hwnd = pWnd->GetParent()->GetSafeHwnd();
       ti.uFlags = TTF_IDISHWND | TTF_SUBCLASS;
       ti.uId = (unsigned int) pWnd->GetSafeHwnd();
       //2.3: Send a window message to the control's window procedure (CToolTipCtrl will take care)
       SendMessage(TTM_ADDTOOL, 0, (LPARAM) &ti);
}

Note that the hwnd member is supplied with the parent of the tool, which is the dialog box in our case. The TTF_IDISHWND and TTF_SUBCLASS flags are set through the uFlags member. The flag TTF_IDISHWND specifies that uId member of the structure will hold the window handle to the tool. The flag TTF_SUBCLASS informs the window procedure (Window procedure of the CToolTipCtrl) that it should sub-class the tool window (In the picture at section 2 the textboxes and the button are the tool windows). What is the benefit? When we set this flag, the CToolTipCtrl will take care of tracking the WM_MOUSEMOVE on the sub-classed tool window, and displays the tooltip text when MOUSE_MOVE is stopped (Pointer stays at the control).

5. Add tool tip to the dialog controls

1) The class derived from the CToolTipCtrl is ready now. First, the header file for the extended control (Actually nothing is extended, we just display tooltip by single method call) is included in the dialog class.

//Sample 03: Include the extended tooltip
#include "TooltipCtrlExt.h"

2) A public data member of the extended CToolTipCtrl control class is declared in the dialog class. This is shown below:

//Sample 04: Declare a member of our extended tooltip control
CToolTipCtrlExt m_ctrl_tooltip_ext;

3) In the OnInitDialog(), the Display_tooltip_text function is called to register the tooltip text with the tools (Dialog controls) and this done after calling the Create method of the CToolTipCtrl by supplying the dialog window.

//Sample 05: Register the controls for tooltip display
m_ctrl_tooltip_ext.Create(this);
m_ctrl_tooltip_ext.Display_tooltip_text("Saves the Data", &m_ctrl_btn_save);
m_ctrl_tooltip_ext.Display_tooltip_text("First Name of the Person", &m_ctrl_edit_fname);
m_ctrl_tooltip_ext.Display_tooltip_text("Last Name of the Person", &m_ctrl_edit_lname);

Now run the application and place the mouse cursor over the textboxes or the button control. This will show the tool tip near the control. As we extended the MFC class, you can add additional functionality to the class to improve the tooltip display. Say for example, alternating between two texts when the mouse pointer stays on the control, providing a border around the tooltip text etc.,
The sample is generated in visual studio 2005.

Source Code : Download

No comments:

Post a Comment

Leave your comment(s) here.

Like this site? Tell it to your Firend :)