CToolTipCtrl
類別
封裝「工具提示控件」的功能,這個小型彈出視窗會顯示描述應用程式中工具用途的單行文字。
語法
class CToolTipCtrl : public CWnd
成員
公用建構函式
名稱 | 描述 |
---|---|
CToolTipCtrl::CToolTipCtrl |
建構 CToolTipCtrl 物件。 |
公用方法
備註
「工具」是視窗,例如子視窗或控件,或視窗工作區內應用程式定義的矩形區域。 大部分時候,工具提示都會隱藏,只有在使用者將游標放在工具上,並將它留在那裡大約一半秒時才會顯示。 當使用者按下滑鼠按鈕或將游標移離工具時,工具提示會出現在游標附近並消失。
CToolTipCtrl
提供功能來控制工具提示的初始時間和持續時間、工具提示文字周圍的邊界寬度、工具提示視窗本身的寬度,以及工具提示的背景和文字色彩。 單一工具提示控件可以提供多個工具的資訊。
類別 CToolTipCtrl
提供 Windows 通用工具提示控制件的功能。 此控件(因此類別 CToolTipCtrl
)僅適用於在 Windows 95/98 和 Windows NT 3.51 版和更新版本下執行的程式。
如需啟用工具提示的詳細資訊,請參閱 Windows 中未衍生自 CFrameWnd
的工具提示。
如需使用CToolTipCtrl
的詳細資訊,請參閱 控制項和使用 CToolTipCtrl
。
繼承階層架構
CToolTipCtrl
需求
標頭: afxcmn.h
CToolTipCtrl::Activate
呼叫此函式以啟動或停用工具提示控制件。
void Activate(BOOL bActivate);
參數
bActivate
指定要啟動或停用工具提示控件。
備註
如果 bActivate
為 TRUE
,則會啟動 控件;如果 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_TEXTCALLBACK
, TTN_NEEDTEXT
通知訊息會移至指向之視窗的父系 pWnd
。
傳回值
如果成功則為非零;否則為 0。
備註
lpRectTool
和 nIDTool
參數都必須有效,如果 lpRectTool
為 NULL
nIDTool
,則必須是 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_ALWAYSTIP
和 TTS_NOPREFIX
。
樣式 | 意義 |
---|---|
TTS_ALWAYSTIP |
指定不論工具提示控件的擁有者視窗為使用中或非使用中,當游標位於工具上時,工具提示就會顯示。 如果沒有此樣式,工具提示控件就會在工具的擁有者視窗處於使用中狀態時顯示,但不會在非使用中時顯示。 |
TTS_NOPREFIX |
此樣式可防止系統從字串中去除連字元和 (& ) 字元。 如果工具提示控件沒有 TTS_NOPREFIX 樣式,系統會自動移除連字元,讓應用程式使用與功能表項和工具提示控制件中的文字相同的字串。 |
不論您是否在建立控制項時指定工具提示控制項,工具提示控制件都有 WS_POPUP
和 WS_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
工具的識別碼。
備註
pWnd
和 nIDTool
參數會識別工具。 如果此工具先前已透過先前的呼叫 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
工具所參考CToolInfo
之TOOLINFO
結構的和 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 中所述。
CToolTipCtrl::Popup
導致目前的工具提示控件顯示在最後一個滑鼠訊息的座標上。
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
包含工具文字的字串資源識別碼。