Using CToolTipCtrl study

Waterathena Statement: This document is from MSDN document 2005

The CToolTipCtrl class encapsulates the functionality of a tool tip control, a small pop-up window that displays a single line of text describing the purpose of a tool in an application. A tool tip is hidden most of the time, appearing only when the user puts the cursor on a tool and leaves it there for approximately one-half second. The tool tip appears near the cursor and disappears when the user clicks a mouse button or moves the cursor off of the tool.

What do you want to know more about?

• Methods of Creating Tool Tips
• Settings for the Tool Tip Control
• Using CToolTipCtrl to Create and Manipulate a CToolTipCtrl Object
• Manipulating the Tool Tip Control

 

Methods of Creating Tool Tips

MFC provides three classes to create and manage the tool tip control: CWnd, CToolBarCtrl, and CToolTipCtrl. The tool tip member functions in these classes wrap the Windows common control API. Class CToolBarCtrl and class CToolTipCtrl are derived from class CWnd.

CWnd provides four member functions to create and manage tool tips: EnableToolTips, CancelToolTips, FilterToolTipMessage, and OnToolHitTest. See these individual member functions for more information about how they implement tool tips.

If you create a toolbar using CToolBarCtrl, you can implement tool tips for that toolbar directly using the following member functions: GetToolTips and SetToolTips. See these individual member functions and CToolBarCtrl: Handling Tool Tip Notifications in the Class Library Reference for more information about how they implement tool tips.

The CToolTipCtrl class provides the functionality of the Windows common tool tip control. A single tool tip control can provide information for more than one tool. A tool is either a window, such as a child window or control, or an application-defined rectangular area within a window's client area.

Settings for the Tool Tip Control

You can set the tool tip control ( CToolTipCtrl) to be either active or inactive. When you set it to be active, the tool tip control appears when the cursor is on a tool. When you set it to be inactive, the tool tip control does not appear, even if the cursor is on a tool. Call Activate to activate or deactivate a tool tip control.

You can set an active tool tip to display the tool tip when the cursor is on a tool, whether or not the tool tip control's owner window is active or inactive, by using the TTS_ALWAYSTIP style. If you do not use this style, the tool tip control appears when the tool's owner window is active, but not when it is inactive.

（你可以设置Style为TTS_ALWYSTIP，这样不管tooltip control的owner窗口是否是active/deactive, tool tip都会显示）

Most applications contain toolbars with tools that correspond to menu commands. For such tools, it is convenient for the tool tip control to display the same text as the corresponding menu item. The system automatically strips the ampersand (&) accelerator characters from all strings passed to a tool tip control, unless the control has the TTS_NOPREFIX style.

ampersand

['æmpəsænd]

＆(=and)号

Strip v 剥夺、剥去

Using CToolTipCtrl to Create and Manipulate a CToolTipCtrl Object

To create and manipulate a CToolTipCtrl

1. Construct the CToolTipCtrl object.
2. Call Create to create the Windows tool tip common control and attach it to the CToolTipCtrl object.
3. Call AddTool to register a tool with the tool tip control, so that the information stored in the tool tip is displayed when the cursor is on the tool.
4. Call SetToolInfo to set the information that a tool tip maintains for a tool.
5. Call SetToolRect to set a new bounding rectangle for a tool.
6. Call HitTest to test a point to determine whether it is within the bounding rectangle of the given tool and, if so, retrieve information about the tool.
7. Call GetToolCount to retrieve a count of the tools registered with the tool tip control.

Manipulating the Tool Tip Control

Class CToolTipCtrl provides a group of member functions that control the various attributes of the CToolTipCtrl object and the tool tip window.

The initial, pop-up, and reshow durations for the tool tip windows can be set and retrieved with calls to GetDelayTime and SetDelayTime.

Change the appearance of the tool tip windows with the following functions:

• GetMargin and SetMargin    Retrieves and sets the width between the tool tip border and the tool tip text.
• GetMaxTipWidth and SetMaxTipWidth   Retrieves and sets the maximum width of the tool tip window.
• GetTipBkColor and SetTipBkColor   Retrieves and sets the background color of the tool tip window.
• GetTipTextColor and SetTipTextColor   Retrieves and sets the text color of the tool tip window.

In order for the tooltip control to be notified of important messages, such as WM_LBUTTONXXX messages, you must relay the messages to your tooltip control. The best method for this relay is to make a call to CToolTipCtrl::RelayEvent, in the PreTranslateMessage function of the owner window. The following example illustrates one possible method (assuming the tooltip control is called m_ToolTip):

if(pMsg->message== WM_LBUTTONDOWN ||        pMsg->message== WM_LBUTTONUP ||        pMsg->message== WM_MOUSEMOVE)
m_ToolTip.RelayEvent(pMsg);

return CMyView::PreTranslateMessage(pMsg);

To immediately remove a tool tip window, call the Pop member function.

CToolTipCtrl::GetDelayTime

Retrieves the initial, pop-up, and reshow durations currently set for a tool tip control.

int GetDelayTime(
   DWORD dwDuration 
) const;

Parameters

dwDuration

Flag that specifies which duration value will be retrieved. This parameter can be one of the following values:

• TTDT_AUTOPOP   Retrieve the length of time the tool tip window remains visible if the pointer is stationary within a tool's bounding rectangle.
• TTDT_INITIAL   Retrieve the length of time the pointer must remain stationary within a tool's bounding rectangle before the tool tip window appears.
• TTDT_RESHOW   Retrieve the length of time it takes for subsequent tool tip windows to appear as the pointer moves from one tool to another.

Return Value

The specified delay time, in milliseconds

Remarks

This member function implements the behavior of the Win32 message TTM_GETDELAYTIME, as described in the Platform SDK.

CToolTipCtrl::SetDelayTime

Sets the delay time for a tool tip control.

void SetDelayTime(
   UINT nDelay 
);
void SetDelayTime(
   DWORD dwDuration,
   int iTime 
);

Parameters

nDelay

Specifies the new delay time, in milliseconds.

dwDuration [flag]

Flag that specifies which duration value will be retrieved. See CToolTipCtrl::GetDelayTime for a description of the valid values.

iTime

The specified delay time, in milliseconds.

Remarks

The delay time is the length of time the cursor must remain on a tool before the tool tip window appears. The default delay time is 500 milliseconds.

CToolTipCtrl::Create

Creates a tool tip control and attaches it to a CToolTipCtrl object.

virtual BOOL Create(
   CWnd* pParentWnd,
      DWORD dwStyle = 0 
);

Parameters

pParentWnd

Specifies the tool tip control's parent window, usually a CDialog. It must not be NULL.（父窗口不能为空）

dwStyle

Specifies the tool tip control's style. See the Remarks section for more information.

Return Value

Nonzero if the CToolTipCtrl object is successfully created; otherwise 0.

Remarks

You construct a CToolTipCtrl in two steps. First, call the constructor to construct the CToolTipCtrl object, and then call Create to create the tool tip control and attach it to the CToolTipCtrl object.（先声明调用了默认构造函数，再调用Create真正生成一个ToolTip Object）

The dwStyle parameter can be any combination of Window Styles. In addition, a tool tip control has two class-specific styles: TTS_ALWAYSTIP and TTS_NOPREFIX.

/* ToolTip的是Style可以设置为Window Styles中任意一个值，当然有自己特定的风格值 */

Style	Meaning
TTS_ALWAYSTIP	Specifies that the tool tip will appear when the cursor is on a tool, regardless of whether the tool tip control's owner window is active or inactive. Without this style, the tool tip control appears when the tool's owner window is active, but not when it is inactive.（默认状态是当它的ONWER WINDOW Active才显示出来，否则tool tip不会显示）
TTS_NOPREFIX	This style prevents the system from stripping the ampersand (&) character from a string. If a tool tip control does not have the TTS_NOPREFIX style, the system automatically strips ampersand characters, allowing an application to use the same string as both a menu item and as text in a tool tip control.（默认状态，对于菜单SUB ITEM字符串中&字符，系统在生成TOOL TIP的时候会自动过滤掉）

A tool tip control has the WS_POPUP and WS_EX_TOOLWINDOW window styles, regardless of whether you specify them when creating the control.

（一个tool tip control拥有WS_POPUP 和 WS_EX_TOOLWINDOW 的窗口特性，WS_EX_WINDOW表示窗口不会在TaskBar上产生一个小Table停靠在TaskBar上）

To create a tool tip control with extended windows styles, call CToolTipCtrl::CreateEx instead of Create.

CToolTipCtrl::AddTool

Registers a tool with the tool tip control.

BOOL AddTool(
   CWnd* pWnd,
   UINT nIDText,
   LPCRECT lpRectTool = NULL,
   UINT_PTR nIDTool = 0 
);
BOOL AddTool(
   CWnd* pWnd,
   LPCTSTR lpszText = LPSTR_TEXTCALLBACK,
   LPCRECT lpRectTool = NULL,
   UINT_PTR nIDTool = 0 
);

Parameters

pWnd

Pointer to the window that contains the tool.

nIDText

ID of the string resource that contains the text for the tool.

lpRectTool

Pointer to a RECT structure containing coordinates of the tool's bounding rectangle. The coordinates are relative to the upper-left corner of the client area of the window identified by pWnd.

nIDTool

ID of the tool.

lpszText

Pointer to the text for the tool. If this parameter contains the value LPSTR_TEXTCALLBACK, TTN_NEEDTEXT notification messages go to the parent of the window that pWnd points to.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The lpRectTool and nIDTool parameters must both be valid, or if lpRectTool is NULL, nIDTool must be 0.

lpRectTool 和 nIDTool 参数要同时为空，或者同时不为空。

A tool tip control can be associated with more than one tool. Call this function to register a tool with the tool tip control, so that the information stored in the tool tip is displayed when the cursor is on the tool.

一个Tool tip control能和多个tool绑定，只要给每个TOOL对应的TIPSTRING分配不同的ID和STRING.

/* 在我的工程中我曾经试过一个Dialog只创建一个CToolTip，然后用它来处理我Dialog里面所有buttons的Tips显示。Dialog里面的所有Button不是继承CButon类。*/

Note

You cannot set a tool tip to a static control using AddTool.

/*静态控件不能使用该函数添加TOOL TIP*/

Example:

// Create and associate a tooltip control to the tab control of 
// CMyPropertySheet.  CMyPropertySheet is a CPropertySheet-derived
// class.
BOOL CMyPropertySheet::OnInitDialog() 
{
   BOOL bResult = CPropertySheet::OnInitDialog();
   
   // Create a tooltip control.  m_ToolTipCtrl is a member variable
   // of type CToolTipCtrl* in CMyPropertySheet class.  It is 
   // initialized to NULL in the constructor, and destroyed in the 
   // destructor of CMyPropertySheet class.

   m_ToolTipCtrl = new CToolTipCtrl;

   if (!m_ToolTipCtrl->Create(this))
   {
      TRACE("Unable To create ToolTip/n");           
      return bResult;
   }

   // Associate the tooltip control to the tab control
   // of CMyPropertySheet.
   CTabCtrl* tab = GetTabControl();
   tab->SetToolTips(m_ToolTipCtrl);

   // Get the bounding rectangle of each tab in the tab control of the
   // property sheet. Use this rectangle when registering a tool with 
   // the tool tip control.  IDS_FIRST_TOOLTIP is the first ID string 
   // resource that contains the text for the tool.
   int count = tab->GetItemCount();
   int id = IDS_FIRST_TOOLTIP;

   for (int i = 0; i < count; i++)
   {
      id += i;
      CRect r;
      tab->GetItemRect(i, &r);
      VERIFY(m_ToolTipCtrl->AddTool(tab, id, &r, id));
   }

   // Activate the tooltip control.
   m_ToolTipCtrl->Activate(TRUE);

   return bResult;
}

// Override PreTranslateMessage() so RelayEvent() can be 
// called to pass a mouse message to CMyPropertySheet's 
// tooltip control for processing.
BOOL CMyPropertySheet::PreTranslateMessage(MSG* pMsg) 
{
   if (NULL != m_ToolTipCtrl)            
      m_ToolTipCtrl->RelayEvent(pMsg);
   
   return CPropertySheet::PreTranslateMessage(pMsg);
}

HOWTO: How to Add Tooltips for Controls to an MFC Modal Dialog Box

statement: this digest is from MSND 2001.

SUMMARY

To make the CToolTipCtrl class work correctly, you must call the CToolTipCtrl::RelayEvent() function. This makes it possible for the mouse messages to be passed to the tooltip control.
For a non-modal dialog box window in an MFC application, use the window's CWnd::PreTranslateMessage() function to call CToolTipsCtrl::RelayEvent(). However, for a modal dialog box in MFC versions prior to 4.0, the CDialog::PreTranslateMessage() function is not called because modal dialog boxes have their own message loops.
In versions of MFC 4.0 and later, this is not a problem because of changes to the implementation of DoModal.

Step-by-Step Examples

The following procedures generate a default MFC skeleton application and add tooltips to the OK button on the About dialog box and the dialog box itself.
For Versions of MFC 4.0 or Later Use These Steps:

1. Use the Appwizard in Visual C++ to generate an MFC application. Call it Tooltips, and use all the Appwizard default settings.

2. Use ClassWizard to add a PreTranslateMessage override to CAboutDialog as follows:

   CAboutDialog::PreTranslateMessage(MSG* pMsg)
   {
        if (NULL != m_pToolTip)
            m_pToolTip->RelayEvent(pMsg);

        return CDialog::PreTranslateMessage(pMsg);
   } 

3.Use ClassWizard to add a member variable for the OK button in the CAboutDlg class, and call it m_btOK. Also, add a m_pToolTip pointer to a CToolTipCtrl object: 

   class CAboutDlg : public CDialog
   {
   public:
       CAboutDlg();

       // Dialog Data
       //{{AFX_DATA(CAboutDlg)
       enum { IDD = IDD_ABOUTBOX };
       CButton   m_btOK;
       //}}AFX_DATA

       CToolTipCtrl* m_pToolTip;

       //...
   }; 

4. Add code to the CAboutDlg class constructor and destructor to initialize and release the tooltip object. You might also need to add a default destructor first:

   CAboutDlg::CAboutDlg() : CDialog(CAboutDlg::IDD)
   {
       m_pToolTip = NULL;
   }

   CAboutDlg::~CAboutDlg()
   {
       delete m_pToolTip;
   } 

5. Override the OnInitDialog() function of the CAboutDlg class to set up the tooltip control.

   BOOL CAboutDlg::OnInitDialog()
   {
      CDialog::OnInitDialog();

       //Set up the tooltip
       m_pToolTip = new CToolTipCtrl;
       if(!m_pToolTip->Create(this))
       {
           TRACE("Unable To create ToolTip/n");
           return TRUE;
       }

       if(m_pToolTip->AddTool(this, "About Box"))
       {
           TRACE("Unable to add Dialog to the tooltip/n");
       }

       if (m_pToolTip->AddTool(&m_btOK,"OK Button"))
       {
           TRACE("Unable to add OK button to the tooltip/n");
       }

       m_pToolTip->Activate(TRUE);

       return TRUE;
   } 

6. Rebuild the application, and bring up the About dialog box, you will see the tooltips.