共用方式為

關於工具提示控件

當使用者將滑鼠指標停在工具或其他 UI 元素上時，工具提示會自動顯示或快顯。 工具提示會出現在指標附近，當用戶按兩下滑鼠按鈕、將指標從工具移開，或只是等候幾秒鐘時消失。

下圖中的工具提示控件會顯示 Windows 桌面上檔案的相關信息。 當您將滑鼠移至圖例上方時，也應該會看到包含描述性文字的即時工具提示。

螢幕快照，顯示在桌面的檔案上出現的工具提示中的文字

本節說明工具提示控制項的運作方式，以及如何建立工具提示。

工具提示的行為和外觀

工具提示控件可以顯示單行文字或多行。 其角落可以是圓角或正方形。 他們可能有，也可能沒有如卡通語音氣球般指向工具的線。 工具提示文字可以是靜止的，也可以使用滑鼠指標移動，稱為追蹤。 固定文字可以與工具相鄰顯示，或在工具上方顯示，也就是就地顯示。 標準工具提示框是靜止的，顯示單行文字，角是方的，而且沒有指向工具的箭頭。

受 4.70 版 通用控件支持的追蹤工具提示會在螢幕上動態地改變位置。 藉由快速更新位置，這些工具提示控件似乎會順暢地移動，或「追蹤」。當您想要工具提示文字在移動時追蹤滑鼠指標的位置時，這些會很有用。 如需追蹤工具提示的詳細資訊，以及示範如何建立工具提示的程式代碼範例，請參閱 追蹤工具提示。

通用控件的 4.70 版也支援多行的工具提示，能顯示一行以上的文字。 這些適用於顯示冗長的訊息。 如需詳細資訊和示範如何建立多行工具提示的範例，請參閱 多行工具提示。

氣球狀提示會顯示於圓角方框中，且有一個指向工具的尾端。 它們可以是單行或多行。 以下插圖顯示了一個氣球工具提示，其中莖和矩形處於它們的預設位置。 如需了解有關氣球工具提示的詳細資訊，並查看如何建立它們的範例，請參閱使用工具提示控制項 。

螢幕快照顯示一個工具提示，其中包含一行文字，位於對話框按鈕的上方

工具提示也可以有標題文字和圖示，如下圖所示。 請注意，工具提示必須有文字;如果只有標題文字，工具提示就不會顯示。 此外，除非有標題，否則不會顯示圖示。

顯示工具提示的螢幕快照，其中包含位於對話框按鈕下方的圖示、標題和文字

有時候會裁剪文字字串，因為它們太長而無法完全顯示在小型視窗中。 就地工具提示可用來顯示已截斷物件的文字字串，例如下圖中的檔案名稱。 若要查看有關如何建立就地工具提示的範例，請參閱 In-Place 工具提示。

螢幕快照顯示工具提示，其中包含位於樹狀控制中檔案圖示旁的檔名

游標必須停留在工具上一段時間，才能顯示工具提示。 此超時的預設持續時間由使用者的雙擊速度控制，通常大約是半秒。 若要指定非預設逾時值，請傳送工具提示控制 TTM_SETDELAYTIME 訊息。

建立工具提示控件

若要建立工具提示控件，請呼叫 CreateWindowEx 並指定 TOOLTIPS_CLASS 視窗類別。 載入通用控件 DLL 時，會註冊這個類別。 若要確保載入此 DLL，請在應用程式中包含 InitCommonControlsEx 函式。 您必須明確地將工具提示控件定義為最上層。 否則，主視窗可能會涵蓋它。 下列代碼段示範如何建立工具提示控件。

HWND hwndTip = CreateWindowEx(NULL, TOOLTIPS_CLASS, NULL,
                            WS_POPUP | TTS_NOPREFIX | TTS_ALWAYSTIP,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            hwndParent, NULL, hinstMyDll,
                            NULL);

SetWindowPos(hwndTip, HWND_TOPMOST,0, 0, 0, 0,
             SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);

工具提示控件的視窗程式會自動設定控制元件的大小、位置和可見性。 工具提示視窗的高度是根據目前在工具提示控制項裝置內容中選取的字型高度。 寬度會根據工具提示視窗中目前字串的長度而有所不同。

啟用工具提示控制件

工具提示框可以是啟用或停用狀態。 使用中時，當滑鼠指標位於工具上時，工具提示文字就會顯示。 當它處於非使用中狀態時，即使指標位於工具上，工具提示文字也不會顯示。 TTM_ACTIVATE 訊息會啟動並停用工具提示控制件。

支援工具

工具提示控制項可以支援任意數目的工具。 若要支援特定工具，您必須向工具提示控件註冊此工具，方法是向控件傳送 TTM_ADDTOOL 訊息。 訊息包含結構 的 TOOLINFO 位址，提供工具提示控制項顯示工具文字所需的資訊。 應用程式會定義 TOOLINFO 結構的 uID 成員。 每次新增工具時，您的應用程式都會提供唯一標識碼。 cbSize 成員是 TOOLINFO 結構體中必須的，並且必須指定結構體的大小。

工具提示控制支援實作為視窗的工具（例如子視窗或控制視窗），以及視窗用戶區域內的矩形區域。 當您新增實作為矩形區域的工具時，TOOLINFO 結構的 hwnd 成員必須指定包含區域的視窗句柄，而 rect 成員必須指定區域邊界矩形的用戶端座標。 此外，uID 成員必須指定工具的應用程式定義識別碼。

當您新增一個實作為視窗的工具時，uID 成員中的 TOOLINFO 結構必須包含工具的窗口句柄。 此外，uFlags 成員必須指定 TTF_IDISHWND 值，這個值會指示工具提示控件將 uID 成員解譯為視窗句柄。

顯示文字

當您將工具新增至工具提示控件時，TOOLINFO 結構的 lpszText 成員必須指定要顯示的字串位址，以提供此工具使用。 新增工具之後，您可以使用 TTM_UPDATETIPTEXT 訊息來變更文字。

如果 lpszText 的高順序單字為零，則低序字必須是字串資源的標識符。 當工具提示控件需要文字時，系統會從由 hinst 成員識別的應用程式實例中，載入指定的字串資源到 TOOLINFO 結構。

如果您在 lpszText 成員中指定 LPSTR_TEXTCALLBACK 值，當工具提示控件需要顯示工具文字時，工具提示控件會通知在 hwnd 成員中指定的視窗，這是 TOOLINFO結構的一部分。 工具提示控制項會將 TTN_GETDISPINFO 通知碼傳送至視窗。 訊息包含 NMTTDISPINFO 結構的位址，其中包含視窗句柄，以及工具的應用程式定義標識符。 視窗會檢查 結構，以判斷需要文字的工具，並填入適當的結構成員，其中包含工具提示控件為了顯示字串所需的資訊。

注意

標準工具提示文字的最大長度為80個字元。 如需詳細資訊，請參閱 NMTTDISPINFO 結構。 多行工具提示文字可能更長。

 

許多應用程式都會建立工具列，其中包含對應至功能表命令的工具。 針對這類工具，工具提示控件可方便顯示與對應功能表項相同的文字。 除非控件具有 TTS_NOPREFIX 樣式，否則系統會自動從傳遞至工具提示控件的所有字元串中移除和號（&）加速器字元，並在第一個製表字元（\t）終止字元串。

若要擷取工具的文字，請使用 TTM_GETTEXT 訊息。

傳訊和通知

當滑鼠指標停留在區域上方時，通常會顯示工具提示文字，通常是由按鈕控件之類的工具所定義的矩形。 不過，Microsoft Windows 只會將滑鼠相關的訊息傳送至包含指標的視窗，而不是工具提示控制件本身。 滑鼠相關信息必須轉接至工具提示控件，才能在適當的時間和地點顯示工具提示文字。

如果滿足以下條件，則可以自動轉發消息：

  • 此工具是控件，或定義為工具 TOOLINFO 結構中的矩形。
  • 與工具相關聯的視窗位於與工具提示控件相同的線程中。

如果符合這兩個條件，請在工具的 TOOLINFO 結構 uFlags uFlags 中設定 TTF_SUBCLASS 旗標，當您使用 TTM_ADDTOOL將工具新增至工具提示控件。 接著，必要的滑鼠訊息會自動轉譯至工具提示控件。

將 TTF_SUBCLASS 設定為將滑鼠訊息轉寄至控件就足以用於大部分用途。 不過，在工具提示控件與工具視窗之間沒有直接連線的情況下，它將無法運作。 例如，如果工具實作為應用程式定義視窗中的矩形區域，則視窗程式會接收滑鼠訊息。 設定 TTF_SUBCLASS 足以確保它們被傳遞至控制項。 不過，如果工具實作為系統定義的視窗，則滑鼠訊息會傳送至該視窗，而且無法直接供應用程式使用。 在此情況下，您必須將視窗子類別化，或使用訊息攔截來存取滑鼠訊息。 然後，您必須使用 TTM_RELAYEVENT明確地將滑鼠訊息轉寄至工具提示控件。 如需如何使用 TTM_RELAYEVENT的範例，請參閱 追蹤工具提示。

當工具提示控件收到 WM_MOUSEMOVE 訊息時，它會判斷滑鼠指標是否位於工具的周框中。 如果是，工具提示控件會設定定時器。 在超時時間間隔結束時，工具提示控件會檢查指標的位置，以查看指標是否已移動。 如果沒有，工具提示控制項會擷取工具的提示文字，並顯示工具提示。 工具提示控件會繼續顯示視窗，直到它收到轉送的按鈕向上或按鈕向下訊息，或直到 WM_MOUSEMOVE 訊息指出指標已移至工具周框外為止。

工具提示控件實際上有三個與其相關聯的逾時持續時間。 初始持續時間是滑鼠指標在工具提示窗口顯示之前，必須在工具周框內保持靜止的時間。 重新顯示持續時間是當指標從某個工具移至另一個工具時，顯示後續工具提示視窗之前的延遲長度。 快顯持續時間是指工具提示窗口在隱藏之前保持彈出顯示的時間。 也就是說，如果在顯示工具提示窗口之後，指標會保持固定在周框內，工具提示視窗就會在快顯持續時間結束時自動隱藏。 您可以使用 TTM_SETDELAYTIME 訊息來調整所有逾時持續時間。

如果應用程式中包含一個以矩形區域實作的工具，而該工具的控件大小或位置發生變更，則應用程式可以使用 TTM_NEWTOOLRECT 訊息來向工具提示控件報告變更。 應用程式不需要報告實作為視窗之工具的大小和位置變更，因為工具提示控件會使用工具的視窗句柄來判斷滑鼠指標是否位於工具上，而不是工具的周框矩形。

當工具提示即將顯示時，工具提示控件會將 TTN_SHOW 通知碼傳送給擁有者視窗。 當工具提示即將隱藏時，擁有者視窗會收到 TTN_POP 通知碼。 每個通知碼都會在 WM_NOTIFY 訊息的內容中傳送。

命中測試

TTM_HITTEST 訊息允許您擷取工具提示控制保留的關於佔用特定點的工具的資訊。 訊息包含 TTHITTESTINFO 結構，其中包含視窗句柄、點座標，以及 TOOLINFO結構的位址。 工具提示控件會判斷工具是否佔用點，如果這樣做，則會填入 TOOLINFO 工具的相關信息。

默認訊息處理

下表描述工具提示控件之視窗程式所處理的訊息。

消息 描述
WM_CREATE 確保工具提示控制項具有 WS_EX_TOOLWINDOW 和 WS_POPUP 視窗樣式。 它也會配置記憶體並初始化內部變數。
WM_DESTROY 釋放為工具提示控件配置的資源。
WM_GETFONT 傳回工具提示控件將用來繪製文字之字型的句柄。
WM_MOUSEMOVE 隱藏工具提示視窗。
WM_PAINT 繪製工具提示視窗。
WM_SETFONT 設定工具提示控件用來繪製文字的字型句柄。
WM_TIMER 如果工具已變更位置，或滑鼠指標已移至工具外部，則隱藏工具提示視窗。 否則，它會顯示工具提示視窗。
WM_WININICHANGE 重設以系統計量為基礎的內部變數。

 

 

 

  • Last updated on