ツールヒント コントロールについて

ツールまたはその他の UI 要素の上にマウス ポインターを置くと、ツールヒントが自動的に表示されるか、ポップアップ表示されます。 ツールヒントはポインターの近くに表示され、ユーザーがマウス ボタンをクリックしたり、ツールからポインターを離したり、数秒待ったりすると消えます。

次の図のツールヒント コントロールには、Windows デスクトップ上のファイルに関する情報が表示されます。 図の上にマウスを移動すると、説明テキストを含むライブ ツールヒントも表示されます。

このセクションでは、ツールヒント コントロールの動作と作成方法について説明します。

• ツールヒントの動作と外観
• ツールヒント コントロールの作成
• ツールヒント コントロールのアクティブ化
• サポート ツール
• テキストを表示する
• メッセージングと通知
• ヒット テスト
• デフォルトのメッセージ処理

ツールヒントの動作と外観

ツールヒント コントロールでは、1 行のテキストまたは複数行を表示できます。 角は丸くすることも四角にすることもできます。 漫画の吹き出しのようなツールを指すステムを持っている場合もあれば、持っていない場合もあります。 ツールヒント テキストは固定することも、追跡と呼ばれるマウス ポインターで移動することもできます。 固定テキストは、ツールの横に表示することも、インプレースと呼ばれるツール上に表示することもできます。 標準のツールヒントは固定され、1 行のテキストが表示され、角が四角形になり、ツールを指すステムがありません。

共通コントロールのバージョン 4.70 でサポートされているツールヒントの追跡は、画面上の位置を動的に変更します。 位置を迅速に更新することで、これらのツールヒント コントロールはスムーズに移動するか、「追跡」するように見えます。これらは、マウス ポインターの移動に合わせてツールヒント テキストを移動させたい場合に便利です。 ツールヒントの追跡の詳細と、ツールヒントの作成方法を示すコードの例については、「ツールヒントの追跡」を参照してください。

共通コントロールのバージョン 4.70 でもサポートされている複数行のツールヒントは、複数の行にテキストを表示します。 これらは、長いメッセージを表示する場合に便利です。 詳細と複数行のツールヒントを作成する方法を示す例については、「複数行のツールヒント」を参照してください。

バルーン ヒントは、角が丸く、ツールを指すステムが付いたボックスに表示されます。 単一行でも複数行でもかまいません。 次の図は、既定の位置にステムと四角形を含むバルーン ヒントを示しています。 吹き出しのヒントとその作成方法を示す例の詳細については、「ツールヒント コントロールの使用」を参照してください。

次の図に示すように、ツールヒントにはタイトル テキストとアイコンを含めることもできます。 ツールヒントにはテキストが必要です。タイトル テキストのみが含まれている場合、ツールヒントは表示されません。 また、タイトルがない限り、アイコンは表示されません。

テキスト文字列が長すぎて小さなウィンドウに完全に表示できないため、テキスト文字列がクリップされることがあります。 インプレース ツールヒントは、次の図のファイル名など、クリップされたオブジェクトのテキスト文字列を表示するために使用されます。 インプレース ツールヒントを作成する方法を示す例については、「インプレース ツールヒント」を参照してください。

ツールヒントが表示されるまで、カーソルをツールの上に置く必要があります。 このタイムアウトの既定の期間は、ユーザーのダブルクリック時間によって制御され、通常は約 5 分の 1 秒です。 既定以外のタイムアウト値を指定するには、ツールヒント コントロールに 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 の上位ワードが 0 の場合、下位ワードは文字列リソースの識別子である必要があります。 ツールヒント コントロールにテキストが必要な場合、TOOLINFO 構造体の hinst メンバーによって識別されるアプリケーション インスタンスから、指定された文字列リソースが読み込まれます。

lpszText メンバーの LPSTR_TEXTCALLBACK 値を指定する場合、ツールヒント コントロールは、ツールヒント コントロールがツールのテキストを表示する必要があると、TOOLINFO 構造体の hwnd メンバーで指定されたウィンドウに通知します。 ツールヒント コントロールは、TTN_GETDISPINFO 通知コードをウィンドウに送信します。 メッセージには、ウィンドウ ハンドルとツールの アプリケーション定義識別子を含む NMTTDISPINFO 構造体のアドレスが含まれています。 このウィンドウは、必要なテキストのツールを決定する構造体を調べ、文字列を表示するためにツールヒント コントロールに必要な情報を適切な構造体メンバーに入力します。

多くのアプリケーションは、メニュー コマンドに対応するツールを組み込んだツールバーを作成します。 このようなツールには、対応するメニュー項目と同じテキストのツールヒント コントロールを表示すると便利です。 システムは、ツールヒント コントロールに渡されるすべての文字列からアンパサンド (&) アクセラレータ文字を自動的に削除し、コントロールに TTS_NOPREFIX スタイルがない限り、最初のタブ文字 (\t) で文字列を終了します。

ツールのテキストを取得するには、TTM_GETTEXT メッセージを使用します。

メッセージングと通知

ツールヒント テキストは、通常、マウス ポインターが領域 (通常はボタン コントロールなどのツールによって定義された四角形) の上に置いたときに表示されます。 ただし、Microsoft Windows はマウス関連のメッセージのみを、ツールヒント コントロール自体ではなく、ポインターを含むウィンドウに送信します。 マウス関連の情報は、ツールヒント テキストを適切なタイミングと場所に表示するために、ツールヒント コントロールにリレーする必要があります。

次の場合は、メッセージを自動的にリレーできます。

• ツールはコントロールであるか、ツール の TOOLINFO 構造体の四角形として定義されます。
• ツールに関連付けられているウィンドウは、ツールヒント コントロールと同じスレッド内にあります。

これら 2 つの条件が満たされている場合は、TTM_ADDTOOL を使用してツールをツールヒント コントロールに追加するときに、ツールの TOOLINFO 構造体の uFlags メンバーで TTF_SUBCLASS フラグを設定します。 その後、必要なマウス メッセージがツールヒント コントロールに自動的にリレーされます。

ほとんどの場合、マウス メッセージをコントロールにリレーするように TTF_SUBCLASS を設定するだけで十分です。 ただし、ツールヒント コントロールとツールのウィンドウの間に直接接続がない場合は機能しません。 たとえば、ツールがアプリケーション定義ウィンドウの四角形領域として実装されている場合、ウィンドウ プロシージャはマウス メッセージを受け取ります。 TTF_SUBCLASS を設定するだけで、コントロールに確実に渡すことができます。 ただし、ツールがシステム定義ウィンドウとして実装されている場合、マウス メッセージはそのウィンドウに送信され、アプリケーションで直接使用することはできません。 この場合、ウィンドウをサブクラス化するか、メッセージ フックを使用してマウス メッセージにアクセスする必要があります。 その後、TTM_RELAYEVENT を使用してマウス メッセージをツールヒント コントロールに明示的にリレーする必要があります。 TTM_RELAYEVENT の使用方法の例については、「ツールヒントの追跡」を参照してください。

ツールヒント コントロールは、WM_MOUSEMOVE メッセージを受け取ると、マウス ポインターがツールの外接矩形内にあるかどうかを判断します。 その場合、ツールヒント コントロールによってタイマーが設定されます。 タイムアウト間隔の終了時に、ツールヒント コントロールはポインターの位置をチェックして移動したかどうかを確認します。 表示されていない場合、ツールヒント コントロールはツールのテキストを取得し、ツールヒントを表示します。 ツールヒント コントロールは、リレーされたボタンアップまたはボタンダウン メッセージを受け取るか、WM_MOUSEMOVE メッセージがポインターがツールの外接矩形外に移動したことを示すまで、ウィンドウを表示し続けます。

ツールヒント コントロールには、実際には 3 つのタイムアウト期間が関連付けられています。 最初の期間は、ツールヒント ウィンドウが表示される前に、ツールの外接矩形内にマウス ポインターが固定され続ける時間です。 再表示期間は、ポインターがツール間を移動したときに後続のツールヒント ウィンドウが表示されるまでの遅延の長さです。 ポップアップ期間は、ツールヒント ウィンドウが非表示になる前に、表示され続ける時間です。 つまり、ツールヒント ウィンドウが表示された後、ポインターが外接矩形内で固定され続ける場合、ツールヒント ウィンドウは、ポップアップ期間の終了時に自動的に非表示になります。 TTM_SETDELAYTIME メッセージをつかうとすべてのタイムアウト機関を調整できます。

アプリケーションに、四角形領域として実装されたツールを含み、コントロールのサイズや位置が変更された場合、アプリケーションは、TTM_NEWTOOLRECT メッセージを使用して、ツールヒント コントロールへの変更を報告します。 アプリケーションは、ウィンドウとして実装されたツールに対してサイズや位置の変更を報告する必要はありません。これは、ツールヒント コントロールは、マウス ポインターが、ツールの外接矩形ではなく、ツールの上にあるかどうかを判断するツールのウィンドウ ハンドルを使用するためです。

ツールヒントが表示されようとしている場合、ツールヒント コントロールは所有者ウィンドウに TTN_SHOW 通知コードを送信します。 ツールヒントが非表示になろうとしている場合、所有者ウィンドウは、TTN_POP 通知コードを受信します。 各通知コードは、WM_NOTIFY メッセージのコンテキストで送信されます。

ヒット テスト

TTM_HITTEST メッセージを使用すると、ツールヒント コントロールが特定のポイントを占有するツールを維持します。 メッセージには、ウィンドウ ハンドル、ポイントの座標、および TOOLINFO 構造体のアドレスを含む TTHITTESTINFO 構造体が含まれています。 ツールヒント コントロールは、ツールがポイントを占有するかどうかを決定し、占有する場合、ツールに関する情報を TOOLINFO に入力します。

デフォルトのメッセージ処理

次の表では、ツールヒント コントロールのウィンドウ プロシージャによって処理されるメッセージについて説明します。