Tree-View コントロールについて

ツリー ビュー コントロールは、ドキュメント内の見出し、インデックス内のエントリ、ディスク上のファイルとディレクトリなどの項目の階層リストを表示するウィンドウです。 各項目はラベルとオプションのビットマップイメージで構成され、各項目にはサブ項目のリストを関連付けることができます。 アイテムをクリックすると、ユーザーは関連するサブ項目の一覧を展開または折りたたみることができます。

次の図は、ルート ノード、展開されたノード、および折りたたまれたノードを含む単純なツリー ビュー コントロールを示しています。 コントロールは、選択した項目に 1 つのビットマップを使用し、他の項目には別のビットマップを使用します。

ツリー ビュー コントロールを作成した後、コントロールにメッセージを送信することで、項目を追加、削除、配置、またはその他の操作を行います。 各メッセージには、メッセージを明示的に送信する代わりに使用できる 1 つ以上の対応するマクロがあります。

Tree-View スタイル

ツリー ビュー スタイルは、ツリー ビュー コントロールの外観の側面を制御します。 初期スタイルは、ツリー ビュー コントロールを作成するときに設定します。 GetWindowLong 関数と SetWindowLong 関数を使用して、ツリー ビュー コントロールを作成した後でスタイルを取得および変更できます。

TVS_HASLINES スタイルは、次の図に示すように、子項目を親項目にリンクする線を描画することで、ツリー ビュー コントロールの階層のグラフィック表現を強化します。

このスタイル自体では、階層のルートに線は描画されません。 そのためには、 TVS_HASLINES スタイルと TVS_LINESATROOT スタイルを組み合わせる必要があります。 結果を次の図に示します。

ユーザーは、親アイテムをダブルクリックすることで、親アイテムの子項目の一覧を展開または折りたたむことができます。 TVS_HASBUTTONS スタイルを持つツリー ビュー コントロールは、各親項目の左側にボタンを追加します。 ユーザーは、親項目をダブルクリックして子を展開または折りたたむ代わりに、ボタンを 1 回クリックできます。 TVS_HASBUTTONS は、階層のルートにある項目にボタンを追加しません。 そのためには、TVS_HASLINES、TVS_LINESATROOT、およびTVS_HASBUTTONSを組み合わせる必要があります。 このスタイルの組み合わせを次の図に示します。

TVS_CHECKBOXES スタイルでは、各項目の横にチェック ボックスが作成されます。 チェックボックス スタイルを使用する場合は、ツリー ビュー コントロールを作成した後、およびツリーを設定する前に、 TVS_CHECKBOXES スタイル ( SetWindowLong を使用) を設定する必要があります。 そうしないと、タイミングの問題に応じて、チェック ボックスがオフに表示されることがあります。 次の図は、チェック ボックスのスタイルを示しています。

TVS_FULLROWSELECT スタイルを使用すると、選択範囲の強調表示は、項目自体だけでなく、コントロールの全幅にわたって拡張されます。 次の図は、このスタイルを示しています。

TVS_EDITLABELS スタイルを使用すると、ユーザーはツリー ビュー項目のラベルを編集できます。 ラベルの編集の詳細については、「 Tree-View ラベルの編集」を参照してください。

これらのスタイルとその他のスタイルの詳細については、「 コントロール ウィンドウのスタイルTree-View」を参照してください。

親アイテムと子アイテム

ツリー ビュー コントロール内の項目には、 子項目と呼ばれるサブ項目の一覧を関連付けることができます。 1 つ以上の子項目を持つ項目を 親項目と呼びます。 子項目は親項目の下に表示され、親に従属していることを示すためにインデントされます。 親を持たない項目は、階層の上部に表示され、 ルート項目と呼ばれます。

ツリー ビュー コントロールに項目を追加するには、 TVM_INSERTITEM メッセージをコントロールに送信します。 このメッセージは、項目を一意に識別する HTREEITEM 型へのハンドルを返します。 項目を追加するときは、新しい項目の親項目へのハンドルを指定する必要があります。 TVINSERTSTRUCT 構造体で親項目ハンドルの代わりに NULL またはTVI_ROOT値を指定した場合、項目はルート項目として追加されます。

いつでも、親項目の子項目のリストの状態を展開または折りたたみにすることができます。 状態が展開されると、親項目の下に子項目が表示されます。 それが折りたたみの場合、子項目は表示されません。 リストは、ユーザーが親アイテムをダブルクリックしたときに展開された状態と折りたたまれた状態を自動的に切り替えます。親が TVS_HASBUTTONS スタイルを持っている場合は、ユーザーが親アイテムに関連付けられているボタンをクリックしたときに切り替わります。 アプリケーションは、 TVM_EXPAND メッセージを使用して子項目を展開または折りたたむことができます。

ツリー ビュー コントロールは、親アイテムの子項目のリストが展開または折りたたまれるときに、親ウィンドウに TVN_ITEMEXPANDING 通知メッセージを送信します。 この通知により、アプリケーションは変更を防いだり、子項目のリストの状態に依存する親アイテムの属性を設定したりできます。 リストの状態を変更すると、ツリー ビュー コントロールは親ウィンドウに TVN_ITEMEXPANDED 通知メッセージを送信します。

子項目のリストが展開されると、親項目を基準にインデントされます。 TVM_SETINDENT メッセージを使用してインデントの量を設定したり、TVM_GETINDENT メッセージを使用して現在の量を取得したりできます。

ツリー ビュー コントロールは、ツリー ビュー コントロールを作成するプロセスのヒープから割り当てられたメモリを使用します。 ツリー ビューの項目の最大数は、ヒープで使用可能なメモリの量に基づきます。

項目ラベル

通常、ツリー ビュー コントロールに項目を追加するときに、項目のラベルのテキストを指定します。 TVM_INSERTITEM メッセージには、ラベルのテキストを含む文字列など、項目のプロパティを定義する TVITEM 構造体が含まれています。

ツリー ビュー コントロールは、各項目を格納するためのメモリを割り当てます。項目ラベルのテキストは、このメモリのかなりの部分を占めます。 アプリケーションがツリー ビュー コントロール内の文字列のコピーを保持している場合は、ツリー ビューに実際の文字列を渡す代わりに、TVITEM の pszText メンバーでLPSTR_TEXTCALLBACK値を指定することで、コントロールのメモリ要件を減らすことができます。 LPSTR_TEXTCALLBACKを使用すると、項目を再描画する必要があるときに、ツリー ビュー コントロールは親ウィンドウから項目のラベルのテキストを取得します。 テキストを取得するために、ツリー ビュー コントロールは、NMTVDISPINFO 構造体のアドレスを含むTVN_GETDISPINFO通知メッセージを送信します。 親ウィンドウは、含まれる構造体の適切なメンバーを埋める必要があります。

Tree-View ラベルの編集

ユーザーは、 TVS_EDITLABELS スタイルを持つツリー ビュー コントロール内の項目のラベルを直接編集できます。 ユーザーは、フォーカスがある項目のラベルをクリックして編集を開始します。 アプリケーションは、 TVM_EDITLABEL メッセージを使用して編集を開始します。 ツリー ビュー コントロールは、編集の開始時およびキャンセルまたは完了時に親ウィンドウに通知します。 編集が完了すると、必要に応じて、親ウィンドウがアイテムのラベルを更新します。

ラベルの編集が開始されると、ツリー ビュー コントロールは親ウィンドウ にTVN_BEGINLABELEDIT 通知メッセージを送信します。 この通知を処理することで、アプリケーションは一部のラベルの編集を許可し、他のラベルの編集を防止できます。 0 を返す場合は編集が可能で、0 以外の値を返しても編集できません。

ラベルの編集が取り消されるか完了すると、ツリー ビュー コントロールは親ウィンドウ にTVN_ENDLABELEDIT 通知メッセージを送信します。 lParam パラメーターは、NMTVDISPINFO 構造体のアドレスです。 item パラメーターは、 アイテム を識別し、編集されたテキストを含む TVITEM 構造体です。 新しいラベルを保持する場合は、親ウィンドウがアイテムのラベルを更新する必要があります。 編集が取り消された場合、TVITEM の pszText メンバーは 0 です。

ラベルの編集中、通常は TVN_BEGINLABELEDIT 通知メッセージに応答して、 TVM_GETEDITCONTROL メッセージを使用してラベル編集に使用される編集コントロールへのハンドルを取得できます。 編集コントロールに EM_SETLIMITTEXT メッセージを送信して、ユーザーが編集コントロールに入力またはサブクラス化して無効な文字をインターセプトして破棄できるテキストの量を制限できます。 ただし、編集コントロールは、TVN_BEGINLABELEDITが送信された 後 にのみ表示されることに注意してください。

Tree-View 項目の位置

項目の初期位置は、 TVM_INSERTITEM メッセージを使用して項目がツリー ビュー コントロールに追加されるときに設定されます。 メッセージには、親項目へのハンドルと、新しい項目の挿入後の項目へのハンドルを指定する TVINSERTSTRUCT 構造体が含まれています。 2 番目のハンドルは、指定された親の子項目、または TVI_FIRST、TVI_LAST、またはTVI_SORTのいずれかの値を識別する必要があります。

TVI_FIRSTまたはTVI_LASTを指定すると、ツリー ビュー コントロールは、指定された親項目の子項目のリストの先頭または末尾に新しい項目を配置します。 TVI_SORTを指定すると、ツリー ビュー コントロールは、項目ラベルのテキストに基づいて、子項目の一覧に新しい項目をアルファベット順に挿入します。

TVM_SORTCHILDREN メッセージを使用して、親アイテムの子項目の一覧をアルファベット順 に 配置できます。 メッセージには、指定された親項目から降順のすべての子項目をアルファベット順に並べ替えるかどうかを指定するパラメーターが含まれています。

TVM_SORTCHILDRENCB メッセージを使用すると、定義した条件に基づいて子項目を並べ替えることができます。 このメッセージを使用する場合は、2 つの子項目の相対順序を決定する必要があるときに、ツリー ビュー コントロールが呼び出すことができるアプリケーション定義のコールバック関数を指定します。 コールバック関数は、比較対象の項目に対して 2 つの 32 ビット アプリケーション定義値と、 TVM_SORTCHILDRENCBを送信するときに指定する 3 番目の 32 ビット値を受け取ります。

Tree-View 項目の状態の概要

ツリー ビュー コントロールの各項目は、現在の状態です。 各項目の状態情報には、一連のビット フラグと、アイテムの状態イメージとオーバーレイ イメージを示すイメージ リスト インデックスが含まれます。 ビット フラグは、項目が選択されているかどうか、無効になっているか、展開されているかなどを示します。 ほとんどの場合、ツリー ビュー コントロールは、項目の選択などのユーザー アクションを反映するように項目の状態を自動的に設定します。 ただし、 TVM_SETITEM メッセージを使用してアイテムの状態を設定したり、 TVM_GETITEM メッセージを使用してアイテムの現在の状態を取得したりすることもできます。 項目の状態の完全な一覧については、「 Tree-View コントロール項目の状態」を参照してください。

項目の現在の状態は、TVITEM 構造体の状態メンバーによって指定されます。 ツリー ビュー コントロールは、項目の選択や項目へのフォーカスの設定などのユーザー アクションを反映するように項目の状態を変更する場合があります。 さらに、アプリケーションはアイテムの状態を変更して、アイテムを無効または非表示にしたり、オーバーレイ イメージまたは状態イメージを指定したりすることがあります。

項目の状態を指定または変更すると、TVITEM の statemask メンバーは設定する状態ビットを指定し、状態メンバーにはそれらのビットの新しい値が含まれます。

アイテムのオーバーレイ イメージを設定するには、 statemask に TVIS_OVERLAYMASK 値を含める必要があります。また、 STATE には 、INDEXTOOVERLAYMASK マクロを使用して、左 8 ビットシフトされたオーバーレイ イメージの 1 から始まるインデックスを含める必要があります。 オーバーレイ イメージを指定しない場合は、インデックスを 0 にできます。

状態イメージは、アプリケーション定義の状態を示す項目のアイコンの横に表示されます。 状態イメージは、TVM_SETIMAGELIST メッセージを送信することによって指定された状態イメージ リストに含まれます。 項目の状態イメージを設定するには、TVITEM 構造体の statemask メンバーにTVIS_STATEIMAGEMASK値を含めます。 構造体の 状態 メンバーのビット 12 から 15 は、描画するイメージの状態イメージ リストのインデックスを指定します。

状態イメージのインデックスを設定するには、 INDEXTOSTATEIMAGEMASK を使用します。 このマクロはインデックスを受け取り、ビット 12 から 15 を適切に設定します。 アイテムに状態イメージがないことを示すには、インデックスを 0 に設定します。 この規則は、状態イメージ リストのイメージ ゼロを状態イメージとして使用できないことを意味します。 状態メンバーのビット 12 から 15 を分離するには、TVIS_STATEIMAGEMASK マスクを使用します。 オーバーレイイメージと状態イメージの詳細については、「 Tree-View イメージリスト」を参照してください。

項目の選択

ツリー ビュー コントロールは、 TVN_SELCHANGINGとTVN_SELCHANGED 通知メッセージを送信して、選択項目が別の項目に変更されたときに親ウィンドウ に 通知します。 どちらの通知にも、変更がマウス クリックの結果かキーストロークかを指定する値が含まれます。 通知には、選択範囲を取得している項目と、選択を失っている項目に関する情報も含まれます。 この情報を使用して、項目の選択状態に依存する項目属性を設定できます。 TVN_SELCHANGINGに応答して TRUE を返した場合、選択内容が変更されるのを防ぎ、 FALSE を 返す場合は変更が許可されます。

アプリケーションは、 TVM_SELECTITEM メッセージを送信することによって選択を変更できます。

アイテム情報

ツリー ビュー コントロールは、コントロール内の項目に関する情報を取得する多数のメッセージをサポートします。

TVM_GETITEM メッセージは、項目のハンドルと属性を取得できます。 項目の属性には、現在の状態、項目の選択されたイメージと選択されていないビットマップイメージのコントロールのイメージ リスト内のインデックス、項目に子項目があるかどうかを示すフラグ、項目のラベル文字列のアドレス、およびアイテムのアプリケーション定義の 32 ビット値が含まれます。

TVM_GETNEXTITEM メッセージは、現在のアイテムに対して指定されたリレーションシップを持つツリー ビュー項目を取得します。 メッセージは、項目の親、次または前に表示される項目、最初の子項目などを取得できます。

TVM_GETITEMRECT メッセージは、ツリー ビュー項目の外接する四角形を取得します。 TVM_GETCOUNTメッセージとTVM_GETVISIBLECOUNT メッセージは、ツリー ビュー コントロール内の項目の数と、ツリー ビュー コントロールのウィンドウに完全に表示できる項目の数をそれぞれ取得します。 TVM_ENSUREVISIBLE メッセージを使用して、特定の項目が確実 に 表示されるようにすることができます。

Tree-View イメージ リスト

ツリー ビュー コントロールの各項目には、4 つのビットマップイメージを関連付けることができます。

• アイテムを選択すると、開いているフォルダーなどの画像が表示されます。
• アイテムが選択されていない場合に表示される閉じたフォルダーなどの画像。
• 選択したイメージまたは選択されていないイメージの上に透過的に描画されるオーバーレイ イメージ。
• 状態イメージ。選択されたイメージまたは選択されていないイメージの左側に表示される追加の画像です。 チェック ボックスやクリアチェック ボックスなどの状態イメージを使用して、アプリケーション定義の項目の状態を示すことができます。

既定では、ツリー ビュー コントロールには項目イメージは表示されません。 項目イメージを表示するには、イメージ リストを作成し、コントロールに関連付ける必要があります。 イメージ リストの詳細については、「 イメージ リスト」を参照してください。

ツリー ビュー コントロールには、通常のイメージ リストと状態イメージ リストという 2 つのイメージ リストを含めることができます。 通常のイメージ リストには、選択したイメージ、選択されていないイメージ、オーバーレイ イメージが格納されます。 状態イメージ リストには、状態イメージが格納されます。 ImageList_Create関数を使用してイメージ リストを作成し、他のイメージ リスト関数を使用してビットマップをイメージ リストに追加します。 次に、イメージ リストをツリー ビュー コントロールに関連付けるには、 TVM_SETIMAGELIST メッセージを使用します。 TVM_GETIMAGELIST メッセージは、ツリー ビュー コントロールのイメージ リストのいずれかに対するハンドルを取得します。 このメッセージは、一覧に画像を追加する必要がある場合に便利です。

選択したイメージと選択されていないイメージに加えて、ツリー ビュー コントロールの通常のイメージ リストには、最大 4 つのオーバーレイ イメージを含めることができます。 オーバーレイ イメージは 1 から始まるインデックスによって識別され、選択したイメージと選択されていないイメージの上に透過的に描画されるように設計されています。 オーバーレイ マスク インデックスを通常のイメージ リスト内のイメージに割り当てるには、 ImageList_SetOverlayImage 関数を呼び出します。

既定では、選択した状態と選択されていない状態の両方について、すべての項目が通常のイメージ リストの最初の画像を表示します。 また、既定では、アイテムにはオーバーレイ イメージや状態イメージは表示されません。 TVM_INSERTITEMまたはTVM_SETITEM メッセージを送信することで、アイテムの既定の動作を変更できます。 これらのメッセージは 、TVITEM 構造体を使用して、項目のイメージ リスト インデックスを指定します。

項目の選択されたイメージと選択されていないイメージを指定するには、TVITEM 構造体のマスク メンバーにTVIF_SELECTEDIMAGEビットとTVIF_IMAGE ビットを設定し、iSelectImage および iImage メンバーのコントロールの通常のイメージ リストのインデックスを指定します。 または、インデックスを指定する代わりに 、iSelectImage と iImage でI_IMAGECALLBACK値を指定することもできます。 これにより、項目が再描画されるたびに、コントロールはイメージ リスト インデックスの親ウィンドウに対してクエリを実行します。 コントロールは、インデックスを取得するために TVN_GETDISPINFO 通知メッセージを送信します。

オーバーレイ イメージをアイテムに関連付けるには、INDEXTOOVERLAYMASK マクロを使用して、アイテムの TVITEM 構造体の状態メンバーにオーバーレイ マスク インデックスを指定します。 stateMask メンバーのTVIS_OVERLAYMASK ビットも設定する必要があります。 オーバーレイ マスク インデックスは 1 から始まります。インデックスが 0 の場合は、オーバーレイ イメージが指定されていないことを示します。

状態イメージは別の状態イメージ リストに格納され、インデックスによって識別されます。 状態イメージの一覧を指定するには、 TVM_SETIMAGELIST メッセージを送信します。 1 から始まるインデックスを使用して状態イメージを識別するリスト ビュー コントロールとは異なり、ツリー ビュー コントロールの状態イメージは 0 から始まるインデックスによって識別されます。 ただし、インデックスが 0 の場合は、アイテムに状態イメージがないことを示します。 そのため、イメージ ゼロを状態イメージとして使用することはできません。 項目の状態と状態イメージの詳細については、「 Tree-View 項目の状態の概要」を参照してください。

ドラッグ アンド ドロップ操作

ツリー ビュー コントロールは、ユーザーが項目のドラッグを開始したときに親ウィンドウに通知します。 親ウィンドウは、ユーザーがマウスの左ボタンで項目のドラッグを開始すると TVN_BEGINDRAG 通知メッセージを受け取り、ユーザーが右ボタンでドラッグを開始したときに TVN_BEGINRDRAG 通知メッセージを受け取ります。 ツリー ビュー コントロールに TVS_DISABLEDRAGDROP スタイルを指定することで、ツリー ビュー コントロールがこれらの通知を送信できないようにすることができます。

TVM_CREATEDRAGIMAGE メッセージを使用して、ドラッグ操作中に表示する画像を取得します。 ツリー ビュー コントロールは、ドラッグする項目のラベルに基づいてドラッグ ビットマップを作成します。 次に、ツリー ビュー コントロールによってイメージ リストが作成され、ビットマップが追加され、イメージ リストにハンドルが返されます。

項目を実際にドラッグするコードを指定する必要があります。 通常、これは、イメージ リスト関数のドラッグ機能を使用し、ドラッグ操作の開始後に親ウィンドウに送信される WM_MOUSEMOVE メッセージと WM_LBUTTONUP メッセージ (または WM_RBUTTONUP) を処理する必要があります。

ツリー ビュー コントロール内の項目をドラッグ アンド ドロップ操作のターゲットにする場合は、マウス ポインターがターゲット項目上にあるタイミングを把握する必要があります。 TVM_HITTEST メッセージを使用して確認できます。 マウス ポインターの現在の座標を含む TVHITTESTINFO 構造体のアドレスを指定します。 SendMessage 関数から制御が戻ると、ツリー ビュー コントロールに対するマウス ポインターの位置を示すフラグが構造体に含まれます。 ポインターがツリー ビュー コントロール内の項目の上にある場合、構造体には項目へのハンドルも含まれます。

項目がドラッグ アンド ドロップ操作のターゲットであることを示すには、 TVM_SETITEM メッセージを使用して状態を TVIS_DROPHILITED 値に設定します。 この状態の項目は、ドラッグ アンド ドロップ ターゲットを示すために使用されるスタイルで描画されます。

Tree-View コントロールの通知メッセージ

ツリー ビュー コントロールは、次の通知メッセージを WM_NOTIFYメッセージの 形式で親ウィンドウに送信します。

既定の Tree-View 制御メッセージ処理

このセクションでは、ツリー ビュー コントロールによって実行されるウィンドウ メッセージ処理について説明します。 ツリー ビュー コントロールに固有のメッセージについては、このドキュメントの他のセクションで説明します。そのため、ここには含まれません。