共用方式為

關於工具提示控件

  • 發行項

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

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

screen shot showing text in a tooltip that appears over a file on the desktop

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

工具提示行為和外觀

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

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

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

氣球工具提示會顯示在圓角的方塊中，以及指向工具的字幹。 它們可以是單行或多行。 下圖顯示具有其預設位置之莖和矩形的氣球工具提示。 如需氣球工具提示的詳細資訊，以及示範如何建立工具提示的範例，請參閱 使用工具提示控件。

screen shot showing a tooltip containing one line of text, positioned above a button on a dialog box

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

screen shot showing a tooltip with an icon, title, and text, positioned below a button on a dialog box

有時候會裁剪文字字串，因為它們太長而無法完全顯示在小型視窗中。 就地工具提示可用來顯示已裁剪之物件的文字字串，例如下圖中的檔名。 如需示範如何建立就地工具提示的範例，請參閱 就地工具提示。

screen shot showing a tooltip containing a file name positioned next to a file icon in a tree control

游標必須停留在工具上一段時間，才能顯示工具提示。 此逾時的默認持續時間是由使用者的按兩下時間所控制，通常大約是半秒。 若要指定非預設的逾時值，請傳送工具提示控制 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 成員是由應用程式所定義。 每次新增工具時，您的應用程式都會提供唯一標識碼。 TOOLINFO 結構的 cbSize 成員是必要的，而且必須指定結構的大小。

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

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

顯示文字

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

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

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

注意

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

 

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

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

傳訊和通知

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

如果：

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

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

將 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 重設以系統計量為基礎的內部變數。