共用方式為


CToolTipCtrl 類別

封裝「工具提示控件」的功能,這個小型彈出視窗會顯示描述應用程式中工具用途的單行文字。

語法

class CToolTipCtrl : public CWnd

成員

公用建構函式

名稱 描述
CToolTipCtrl::CToolTipCtrl 建構 CToolTipCtrl 物件。

公用方法

名稱 描述
CToolTipCtrl::Activate 啟動並停用工具提示控件。
CToolTipCtrl::AddTool 向工具提示控件註冊工具。
CToolTipCtrl::AdjustRect 在工具提示控件的文字顯示矩形與其視窗矩形之間轉換。
CToolTipCtrl::Create 建立工具提示控件,並將它附加至 CToolTipCtrl 物件。
CToolTipCtrl::CreateEx 使用指定的 Windows 擴充樣式建立工具提示控件,並將它附加至 CToolTipCtrl 物件。
CToolTipCtrl::DelTool 從工具提示控件移除工具。
CToolTipCtrl::GetBubbleSize 擷取工具提示的大小。
CToolTipCtrl::GetCurrentTool 擷取目前工具提示控件顯示之工具提示視窗的大小、位置和文字等資訊。
CToolTipCtrl::GetDelayTime 擷取目前為工具提示控制項設定的初始、快顯和重新顯示持續時間。
CToolTipCtrl::GetMargin 擷取工具提示視窗所設定的上、左、下和右邊界。
CToolTipCtrl::GetMaxTipWidth 擷取工具提示視窗的最大寬度。
CToolTipCtrl::GetText 擷取工具提示控件為工具維護的文字。
CToolTipCtrl::GetTipBkColor 擷取工具提示視窗中的背景色彩。
CToolTipCtrl::GetTipTextColor 擷取工具提示視窗中的文字色彩。
CToolTipCtrl::GetTitle 擷取目前工具提示控件的標題。
CToolTipCtrl::GetToolCount 擷取工具提示控件維護的工具計數。
CToolTipCtrl::GetToolInfo 擷取工具提示控件維護工具的相關信息。
CToolTipCtrl::HitTest 測試某個點,以判斷它是否位於指定工具的周框內。 如果是,則擷取工具的相關信息。
CToolTipCtrl::Pop 從檢視中移除顯示的工具提示視窗。
CToolTipCtrl::Popup 導致目前的工具提示控件顯示在最後一個滑鼠訊息的座標上。
CToolTipCtrl::RelayEvent 將滑鼠訊息傳遞至工具提示控件以進行處理。
CToolTipCtrl::SetDelayTime 設定工具提示控件的初始、快顯和重新顯示持續時間。
CToolTipCtrl::SetMargin 設定工具提示視窗的上、左、下和右邊界。
CToolTipCtrl::SetMaxTipWidth 設定工具提示視窗的最大寬度。
CToolTipCtrl::SetTipBkColor 設定工具提示視窗中的背景色彩。
CToolTipCtrl::SetTipTextColor 設定工具提示視窗中的文字色彩。
CToolTipCtrl::SetTitle 將標準圖示和標題字串新增至工具提示。
CToolTipCtrl::SetToolInfo 設定工具提示為工具維護的資訊。
CToolTipCtrl::SetToolRect 設定工具的新周框。
CToolTipCtrl::SetWindowTheme 設定工具提示視窗的視覺化樣式。
CToolTipCtrl::Update 強制重新繪製目前的工具。
CToolTipCtrl::UpdateTipText 設定工具的工具提示文字。

備註

「工具」是視窗,例如子視窗或控件,或視窗工作區內應用程式定義的矩形區域。 大部分時候,工具提示都會隱藏,只有在使用者將游標放在工具上,並將它留在那裡大約一半秒時才會顯示。 當使用者按下滑鼠按鈕或將游標移離工具時,工具提示會出現在游標附近並消失。

CToolTipCtrl 提供功能來控制工具提示的初始時間和持續時間、工具提示文字周圍的邊界寬度、工具提示視窗本身的寬度,以及工具提示的背景和文字色彩。 單一工具提示控件可以提供多個工具的資訊。

類別 CToolTipCtrl 提供 Windows 通用工具提示控制件的功能。 此控件(因此類別 CToolTipCtrl )僅適用於在 Windows 95/98 和 Windows NT 3.51 版和更新版本下執行的程式。

如需啟用工具提示的詳細資訊,請參閱 Windows 中未衍生自 CFrameWnd的工具提示。

如需使用CToolTipCtrl的詳細資訊,請參閱 控制項和使用 CToolTipCtrl

繼承階層架構

CObject

CCmdTarget

CWnd

CToolTipCtrl

需求

標頭: afxcmn.h

CToolTipCtrl::Activate

呼叫此函式以啟動或停用工具提示控制件。

void Activate(BOOL bActivate);

參數

bActivate
指定要啟動或停用工具提示控件。

備註

如果 bActivateTRUE,則會啟動 控件;如果 FALSE為 ,則會停用。

當工具提示控件為使用中時,當游標位於向控件註冊的工具時,工具提示資訊就會顯示;當它處於非使用中狀態時,即使游標位於工具上,工具提示資訊也不會顯示。

範例

請參閱 CPropertySheet::GetTabControl 的範例。

CToolTipCtrl::AddTool

向工具提示控件註冊工具。

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);

參數

pWnd
包含工具之視窗的指標。

nIDText
包含工具文字的字串資源識別碼。

lpRectTool
RECT結構的指標,其中包含工具周框的座標。 座標相對於 所 pWnd識別視窗工作區的左上角。

nIDTool
工具的識別碼。

lpszText
工具文字的指標。 如果此參數包含 值 LPSTR_TEXTCALLBACKTTN_NEEDTEXT 通知訊息會移至指向之視窗的父系 pWnd

傳回值

如果成功則為非零;否則為 0。

備註

lpRectToolnIDTool 參數都必須有效,如果 lpRectToolNULLnIDTool ,則必須是 0。

工具提示控制件可以與多個工具相關聯。 呼叫此函式以向工具提示控件註冊工具,以便在工具指標位於工具上時顯示儲存在工具提示中的資訊。

注意

您無法使用 AddTool將工具提示設定為靜態控制項。

範例

請參閱 CPropertySheet::GetTabControl 的範例。

CToolTipCtrl::AdjustRect

在工具提示控件的文字顯示矩形與其視窗矩形之間轉換。

BOOL AdjustRect(
    LPRECT lprc,
    BOOL bLarger = TRUE);

參數

lprc
RECT保留工具提示視窗矩形或文字顯示矩形之結構的指標。

bLarger
如果 TRUE為 , lprc 則用來指定文字顯示矩形,並接收對應的視窗矩形。 如果 FALSE為 , lprc 則用來指定視窗矩形,而且會接收對應的文字顯示矩形。

傳回值

如果矩形已成功調整,則為非零;否則為 0。

備註

這個成員函式會從其視窗矩形計算工具提示控件的文字顯示矩形,或顯示指定文字顯示矩形所需的工具提示視窗矩形。

此成員函式會實作 Win32 訊息 TTM_ADJUSTRECT 的行為,如 Windows SDK 中所述。

CToolTipCtrl::Create

建立工具提示控件,並將它附加至 CToolTipCtrl 物件。

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

參數

pParentWnd
指定工具提示控制件的父視窗,通常是 CDialog。 它不得為 NULL

dwStyle
指定工具提示控制件的樣式。 如需詳細資訊,請參閱一節。

傳回值

如果成功建立物件,則為 CToolTipCtrl 非零,否則為 0。

備註

您會在兩個步驟中建構 CToolTipCtrl 。 首先,呼叫 建構函式來建構 CToolTipCtrl 物件,然後呼叫 Create 以建立工具提示控件,並將它附加至 CToolTipCtrl 物件。

參數dwStyle可以是窗口樣式的任何組合。 此外,工具提示控制件有兩個類別特定的樣式: TTS_ALWAYSTIPTTS_NOPREFIX

樣式 意義
TTS_ALWAYSTIP 指定不論工具提示控件的擁有者視窗為使用中或非使用中,當游標位於工具上時,工具提示就會顯示。 如果沒有此樣式,工具提示控件就會在工具的擁有者視窗處於使用中狀態時顯示,但不會在非使用中時顯示。
TTS_NOPREFIX 此樣式可防止系統從字串中去除連字元和 (&) 字元。 如果工具提示控件沒有 TTS_NOPREFIX 樣式,系統會自動移除連字元,讓應用程式使用與功能表項和工具提示控制件中的文字相同的字串。

不論您是否在建立控制項時指定工具提示控制項,工具提示控制件都有 WS_POPUPWS_EX_TOOLWINDOW 視窗樣式。

若要建立具有擴充視窗樣式的工具提示控制項,請呼叫 CToolTipCtrl::CreateEx 而非 Create

範例

請參閱 CPropertySheet::GetTabControl 的範例。

CToolTipCtrl::CreateEx

建立控件(子視窗),並將它與 CToolTipCtrl 對象產生關聯。

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

參數

pParentWnd
控件父系之視窗的指標。

dwStyle
指定工具提示控制件的樣式。 如需詳細資訊,請參閱的Create一節。

dwStyleEx
指定要建立之控件的擴充樣式。 如需擴充 Windows 樣式的清單,請參閱 dwExStyle Windows SDK 中的 參數 CreateWindowEx

傳回值

如果成功則為非零,否則為 0。

備註

使用 CreateEx 而不是 Create 套用延伸的 Windows 樣式,由 Windows 擴充樣式前置詞 WS_EX_所指定。

CToolTipCtrl::CToolTipCtrl

建構 CToolTipCtrl 物件。

CToolTipCtrl();

備註

建構 物件之後,您必須呼叫 Create

範例

// Declare a CToolTipCtrl object.
CToolTipCtrl m_ToolTipCtrl;

CToolTipCtrl::DelTool

從工具提示控制項所支援的工具集合中移除 和 nIDTool 所指定的pWnd工具。

void DelTool(
    CWnd* pWnd,
    UINT_PTR nIDTool = 0);

參數

pWnd
包含工具之視窗的指標。

nIDTool
工具的識別碼。

CToolTipCtrl::GetBubbleSize

擷取工具提示的大小。

CSize GetBubbleSize(LPTOOLINFO lpToolInfo) const;

參數

lpToolInfo
工具提示 TOOLINFO 結構的指標。

傳回值

工具提示的大小。

備註

此成員函式會實作 Win32 訊息 TTM_GETBUBBLESIZE 的行為,如 Windows SDK 中所述。

CToolTipCtrl::GetCurrentTool

擷取目前工具提示控制項所顯示之工具提示視窗的大小、位置和文字等資訊。

BOOL GetCurrentTool(LPTOOLINFO lpToolInfo) const;

參數

lpToolInfo
[out] TOOLINFO 接收目前工具提示視窗相關信息之結構的指標。

傳回值

TRUE 如果成功擷取資訊,則為 ;否則為 FALSE

備註

這個方法會傳送 TTM_GETCURRENTTOOL 訊息,如 Windows SDK 中所述。

範例

下列程式代碼範例會擷取目前工具提示視窗的相關信息。

{
    //Get information about the current tooltip. 
    TOOLINFO tInfo = {0};
    tInfo.cbSize = sizeof(TOOLINFO);
    CToolBarCtrl& m_toolBarCtrl = m_wndToolBar.GetToolBarCtrl();
    CToolTipCtrl* m_toolTip = m_toolBarCtrl.GetToolTips();
    BOOL bRet = m_toolTip->GetCurrentTool( &tInfo );
}

CToolTipCtrl::GetDelayTime

擷取工具提示控制項目前設定的初始、快顯和重新顯示持續時間。

int GetDelayTime(DWORD dwDuration) const;

參數

dwDuration
旗標,指定要擷取的持續時間值。 這個參數可以是下列其中一個 值:

  • TTDT_AUTOPOP 如果指標固定在工具周框內,擷取工具提示視窗保持可見的時間長度。

  • TTDT_INITIAL 擷取指標在工具提示窗口出現之前,必須保持固定在工具周框內的時間長度。

  • TTDT_RESHOW 擷取後續工具提示視窗在指標從某個工具移至另一個工具時所花費的時間長度。

傳回值

指定的延遲時間,以毫秒為單位

備註

此成員函式會實作 Win32 訊息 TTM_GETDELAYTIME 的行為,如 Windows SDK 中所述。

CToolTipCtrl::GetMargin

擷取工具提示視窗所設定的上、左、下和右邊界。

void GetMargin(LPRECT lprc) const;

參數

lprc
RECT將接收邊界資訊的結構位址。 結構的成員 RECT 不會定義周框。 針對此訊息的目的,結構成員會解譯如下:

member 表示法
top 頂端框線與工具提示文字頂端之間的距離,以像素為單位。
left 左框線與小費文字左端之間的距離,以像素為單位。
bottom 底框線與小費文字底部之間的距離,以像素為單位。
right 右框線與小費文字右端之間的距離,以像素為單位。

備註

此成員函式會實作 Win32 訊息 TTM_GETMARGIN 的行為,如 Windows SDK 中所述。

CToolTipCtrl::GetMaxTipWidth

擷取工具提示視窗的最大寬度。

int GetMaxTipWidth() const;

傳回值

工具提示視窗的最大寬度。

備註

此成員函式會實作 Win32 訊息 TTM_GETMAXTIPWIDTH 的行為,如 Windows SDK 中所述。

CToolTipCtrl::GetText

擷取工具提示控件為工具維護的文字。

void GetText(
    CString& str,
    CWnd* pWnd,
    UINT_PTR nIDTool = 0) const;

參數

str
CString接收工具文字的對象參考。

pWnd
包含工具之視窗的指標。

nIDTool
工具的識別碼。

備註

pWndnIDTool 參數會識別工具。 如果此工具先前已透過先前的呼叫 CToolTipCtrl::AddTool向工具提示控件註冊,則會將參數所 str 參考的物件指派給工具的文字。

CToolTipCtrl::GetTipBkColor

擷取工具提示視窗中的背景色彩。

COLORREF GetTipBkColor() const;

傳回值

COLORREF值,表示背景色彩。

備註

此成員函式會實作 Win32 訊息 TTM_GETTIPBKCOLOR 的行為,如 Windows SDK 中所述。

CToolTipCtrl::GetTipTextColor

擷取工具提示視窗中的文字色彩。

COLORREF GetTipTextColor() const;

傳回值

COLORREF值,表示文字色彩。

備註

此成員函式會實作 Win32 訊息 TTM_GETTIPTEXTCOLOR 的行為,如 Windows SDK 中所述。

CToolTipCtrl::GetTitle

擷取目前工具提示控件的標題。

void GetTitle(PTTGETTITLE pttgt) const;

參數

pttgt
[out] TTGETTITLE 結構指標,其中包含工具提示控件的相關信息。 當這個方法傳回時, pszTitle 結構的成員 TTGETTITLE 會指向標題的文字。

備註

這個方法會傳送 TTM_GETTITLE 訊息,如 Windows SDK 中所述。

CToolTipCtrl::GetToolCount

擷取向工具提示控件註冊的工具計數。

int GetToolCount() const;

傳回值

向工具提示控件註冊的工具計數。

CToolTipCtrl::GetToolInfo

擷取工具提示控件維護工具的相關信息。

BOOL GetToolInfo(
    CToolInfo& ToolInfo,
    CWnd* pWnd,
    UINT_PTR nIDTool = 0) const;

參數

ToolInfo
TOOLINFO接收工具文字的對象參考。

pWnd
包含工具之視窗的指標。

nIDTool
工具的識別碼。

傳回值

如果成功則為非零;否則為 0。

備註

識別hwnd工具所參考CToolInfoTOOLINFO結構的和 uId 成員。 如果此工具已透過先前的呼叫 AddTool向工具提示控件註冊,則 TOOLINFO 結構會填入工具的相關信息。

CToolTipCtrl::HitTest

測試某個點,以判斷它是否位於指定工具的周框內,如果是的話,請擷取工具的相關信息。

BOOL HitTest(
    CWnd* pWnd,
    CPoint pt,
    LPTOOLINFO lpToolInfo) const;

參數

pWnd
包含工具之視窗的指標。

pt
CPoint物件的指標,其中包含要測試之點的座標。

lpToolInfo
TOOLINFO包含工具相關信息之結構的指標。

傳回值

如果點擊測試資訊所指定的點位於工具周框內,則為非零;否則為 0。

備註

如果此函式傳回非零值,所指向 lpToolInfo 的結構會填入其矩形所在工具上的資訊。

結構 TTHITTESTINFO 的定義如下:

typedef struct _TT_HITTESTINFO { // tthti
    HWND hwnd;   // handle of tool or window with tool
    POINT pt;    // client coordinates of point to test
    TOOLINFO ti; // receives information about the tool
} TTHITTESTINFO, FAR * LPHITTESTINFO;
  • hwnd

    指定工具的句柄。

  • pt

    如果點位於工具周框內,則指定點的座標。

  • ti

    工具的相關信息。 如需 結構的詳細資訊 TOOLINFO ,請參閱 CToolTipCtrl::GetToolInfo

CToolTipCtrl::Pop

從檢視中移除顯示的工具提示視窗。

void Pop();

備註

此成員函式會實作 Win32 訊息 TTM_POP 的行為,如 Windows SDK 中所述。

導致目前的工具提示控件顯示在最後一個滑鼠訊息的座標上。

void Popup();

備註

這個方法會傳送 TTM_POPUP 訊息,如 Windows SDK 中所述。

範例

下列程式代碼範例會顯示工具提示視窗。

{
   // Display the most recent tooltip.
   CToolBarCtrl &m_toolBarCtrl = m_wndToolBar.GetToolBarCtrl();
   CToolTipCtrl *m_toolTip = m_toolBarCtrl.GetToolTips();
   m_toolTip->Popup();
}

CToolTipCtrl::RelayEvent

將滑鼠訊息傳遞至工具提示控件以進行處理。

void RelayEvent(LPMSG lpMsg);

參數

lpMsg
MSG包含要轉送之訊息的結構指標。

備註

工具提示控制項只會處理下列訊息,這些訊息會由 RelayEvent傳送給它:

WM_LBUTTONDOWN WM_MOUSEMOVE
WM_LBUTTONUP WM_RBUTTONDOWN
WM_MBUTTONDOWN WM_RBUTTONUP
WM_MBUTTONUP

範例

請參閱 CPropertySheet::GetTabControl 的範例。

CToolTipCtrl::SetDelayTime

設定工具提示控制件的延遲時間。

void SetDelayTime(UINT nDelay);

void SetDelayTime(
    DWORD dwDuration,
    int iTime);

參數

nDelay
指定新的延遲時間,以毫秒為單位。

dwDuration
旗標,指定要擷取的持續時間值。 如需有效值的描述,請參閱 CToolTipCtrl::GetDelayTime

iTime
指定的延遲時間,以毫秒為單位。

備註

延遲時間是數據指標在工具提示窗口出現之前,必須保留在工具上的時間長度。 默認延遲時間為500毫秒。

CToolTipCtrl::SetMargin

設定工具提示視窗的上、左、下和右邊界。

void SetMargin(LPRECT lprc);

參數

lprc
RECT結構位址,其中包含要設定的邊界資訊。 結構的成員 RECT 不會定義周框。 如需邊界資訊的描述,請參閱 CToolTipCtrl::GetMargin

備註

此成員函式會實作 Win32 訊息 TTM_SETMARGIN 的行為,如 Windows SDK 中所述。

CToolTipCtrl::SetMaxTipWidth

設定工具提示視窗的最大寬度。

int SetMaxTipWidth(int iWidth);

參數

iWidth
要設定的最大工具提示視窗寬度。

傳回值

前一個小費寬度上限。

備註

此成員函式會實作 Win32 訊息 TTM_SETMAXTIPWIDTH 的行為,如 Windows SDK 中所述。

CToolTipCtrl::SetTipBkColor

設定工具提示視窗中的背景色彩。

void SetTipBkColor(COLORREF clr);

參數

clr
新的背景色彩。

備註

此成員函式會實作 Win32 訊息 TTM_SETTIPBKCOLOR 的行為,如 Windows SDK 中所述。

CToolTipCtrl::SetTipTextColor

設定工具提示視窗中的文字色彩。

void SetTipTextColor(COLORREF clr);

參數

clr
新的文字色彩。

備註

此成員函式會實作 Win32 訊息 TTM_SETTIPTEXTCOLOR 的行為,如 Windows SDK 中所述。

CToolTipCtrl::SetTitle

將標準圖示和標題字串新增至工具提示。

BOOL SetTitle(
    UINT uIcon,
    LPCTSTR lpstrTitle);

參數

uIcon
TTM_SETTITLE請參閱 icon Windows SDK 中的 。

lpstrTitle
標題字串的指標。

傳回值

如果成功則為非零;否則為 0。

備註

此成員函式會實作 Win32 訊息 TTM_SETTITLE 的行為,如 Windows SDK 中所述。

CToolTipCtrl::SetToolInfo

設定工具提示為工具維護的資訊。

void SetToolInfo(LPTOOLINFO lpToolInfo);

參數

lpToolInfo
結構的指標 TOOLINFO ,指定要設定的資訊。

CToolTipCtrl::SetToolRect

設定工具的新周框。

void SetToolRect(
    CWnd* pWnd,
    UINT_PTR nIDTool,
    LPCRECT lpRect);

參數

pWnd
包含工具之視窗的指標。

nIDTool
工具的識別碼。

lpRect
RECT指定新周框之結構的指標。

CToolTipCtrl::SetWindowTheme

設定工具提示視窗的視覺化樣式。

HRESULT SetWindowTheme(LPCWSTR pszSubAppName);

參數

pszSubAppName
Unicode 字串的指標,其中包含要設定的可視化樣式。

傳回值

不會使用傳回值。

備註

此成員函式會模擬訊息的功能 TTM_SETWINDOWTHEME ,如 Windows SDK 中所述。

CToolTipCtrl::Update

強制重新繪製目前的工具。

void Update();

CToolTipCtrl::UpdateTipText

更新此控制項工具的工具提示文字。

void UpdateTipText(
    LPCTSTR lpszText,
    CWnd* pWnd,
    UINT_PTR nIDTool = 0);

void UpdateTipText(
    UINT nIDText,
    CWnd* pWnd,
    UINT_PTR nIDTool = 0);

參數

lpszText
工具文字的指標。

pWnd
包含工具之視窗的指標。

nIDTool
工具的識別碼。

nIDText
包含工具文字的字串資源識別碼。

另請參閱

CWnd
階層架構圖表
CToolBar