ツールヒントコントロールの概要

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

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

デスクトップ上のファイルに表示されるツールヒントのテキストを示すスクリーンショット

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

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

ツールヒントコントロールでは、1行のテキストまたは複数の行を表示できます。 角は、丸みのある、または正方形にすることができます。 これらのツールは、漫画音声バルーンのようなツールを指しているかもしれません。 ツールヒントテキストは、[追跡] というマウスポインターを使用して、静止したり、移動したりすることができます。 固定テキストは、ツールの横に表示することも、ツールを使用して表示することもできます。このツールは、インプレースと呼ばれます。 標準のツールヒントは固定されており、1行のテキストを表示し、角が直角で、ツールを指していません。

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

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

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

ダイアログボックスのボタンの上に配置された1行のテキストを含むツールヒントを示すスクリーンショット

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

ダイアログボックスのボタンの下に配置されたアイコン、タイトル、テキストを含むツールヒントを示すスクリーンショット

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

ツリーコントロール内のファイルアイコンの横に配置されたファイル名を含むツールヒントを示すスクリーンショット

ツールヒントが表示されるまで、カーソルはツールの上に一定の時間だけポインターを合わせる必要があります。 このタイムアウトの既定の期間は、ユーザーのダブルクリック時間によって制御され、通常は約0.5 秒です。 既定以外のタイムアウト値を指定するには、ツールヒントコントロールに Ttm _ setdelaytime メッセージを送信します。

ツールヒントコントロールの作成

ツールヒントコントロールを作成するには、 CreateWindowEx を呼び出し、 ツールヒント _ クラス ウィンドウクラスを指定します。 このクラスは、コモンコントロール 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 メンバーは、 _ IDISHWND 値を指定する必要があります。これは、 uID メンバーをウィンドウハンドルとして解釈するようにツールヒントコントロールに指示します。

テキストを表示する

ツールヒントコントロールにツールを追加する場合、 TOOLINFO構造体の lpszText メンバーは、ツールで表示する文字列のアドレスを指定する必要があります。 ツールを追加した後は、 Ttm _ UPDATETIPTEXT メッセージを使用してテキストを変更できます。

LpszText の上位ワードが0の場合、下位ワードは文字列リソースの識別子である必要があります。 ツールヒントコントロールにテキストが必要な場合、システムは、 TOOLINFO構造体の hinst メンバーによって識別されるアプリケーションインスタンスから、指定された文字列リソースを読み込みます。

LpszText メンバーに LPSTR の textcallback 値を指定すると、ツールヒントコントロールが _ ツールのテキストを表示する必要があるときに、ツールヒントコントロールによって、 TOOLINFO構造体の hwnd メンバーで指定されたウィンドウが通知されます。 ツールヒントコントロールは、 TTN _ getdispinfo 通知コードをウィンドウに送信します。 このメッセージには、 Nmttdispinfo 構造体のアドレスが含まれます。これには、ウィンドウハンドルだけでなく、ツールのアプリケーション定義の識別子も含まれます。 ウィンドウは、テキストが必要なツールを決定するために構造体を調べ、適切な構造体のメンバーに、文字列を表示するために必要なツールヒントコントロールの情報を格納します。

注意

標準のツールヒントテキストの最大長は80文字です。 詳細については、 Nmttdispinfo 構造体を参照してください。 複数行のツールヒントテキストが長くなる可能性があります。

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

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

メッセージングと通知

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

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

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

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

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

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

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

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

ツールヒントを表示しようとしているときに、ツールヒントコントロールは、 TTN _ SHOW 通知コードをオーナーウィンドウに送信します。 ツールヒントを非表示にしようとすると、オーナーウィンドウは TTN _ POP 通知コードを受け取ります。 各通知コードは、 WM _ 通知 メッセージのコンテキストで送信されます。

ヒット テスト

Ttm _ system.windows.media.visualtreehelper.hittestメッセージを使用すると、特定のポイントを占有するツールについて、ツールヒントコントロールによって保持される情報を取得できます。 このメッセージには、ウィンドウハンドル、点の座標、および TOOLINFO構造体のアドレスを含む Tthittestinfo構造体が含まれています。 ツールヒントコントロールは、ツールがポイントを占有するかどうかを判断し、設定されている場合は、 TOOLINFO にツールに関する情報を入力します。

既定のメッセージ処理

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

Message 説明
WM の _ 作成 ツールヒントコントロールに ws _ EX _ TOOLWINDOWws _ ポップアップ ウィンドウスタイルがあることを確認します。 また、メモリを割り当て、内部変数を初期化します。
WM _ 破棄 ツールヒントコントロールに割り当てられたリソースを解放します。
WM _ GETFONT ツールヒントコントロールがテキストの描画に使用するフォントのハンドルを返します。
WM の _ MOUSEMOVE ツールヒントウィンドウを非表示にします。
WM _ ペイント ツールヒントウィンドウを描画します。
WM _ SETFONT ツールヒントコントロールがテキストの描画に使用するフォントのハンドルを設定します。
WM _ タイマー ツールが位置を変更した場合、またはマウスポインターがツールの外に移動した場合は、ツールヒントウィンドウを非表示にします。 それ以外の場合は、ツールヒントウィンドウが表示されます。
WM _ WININICHANGE システムメトリックに基づく内部変数をリセットします。