List-View コントロールについて
仮想リストビュー コントロールのサンプルを参照してください。
リスト ビュー コントロールは、項目のコレクションを表示するウィンドウです。 リスト ビュー コントロールは、項目を配置および表示するためのいくつかの方法を提供し、単純な リスト ボックスよりもはるかに柔軟です。 たとえば、各項目に関する追加情報は、アイコンとラベルの右側の列に表示できます。
- リスト ビューのスタイルとビュー
- 仮想List-View スタイル
- リスト ビューの作業領域
- List-View イメージ リスト
- リスト ビューアイテムとサブアイテム
- リスト ビュー列
- リスト ビューのスクロール位置
- リスト ビュー ラベルの編集
- リスト ビューの色
- グループ別のリスト アイテムの配置
- 挿入記号
スタイルとビューのList-View
リスト ビュー コントロールでは、5 つの異なるビューに項目を表示できます。 コントロールのウィンドウ スタイルは、既定のビューを指定します。 追加のウィンドウ スタイルでは、項目とコントロール固有の機能の配置を指定します。 次の表では、ビューについて説明します。
| ビュー名 | 説明 |
|---|---|
| アイコン ビュー | LVS_ICON ウィンドウ スタイルまたはLVM_SETVIEW メッセージでLV_VIEW_ICONを渡すことによって指定します。 各項目は、ラベルが下に付いているフルサイズのアイコンとして表示されます。 ユーザーは、リスト ビュー ウィンドウ内の任意の場所に項目をドラッグできます。 |
| 小さいアイコン ビュー | LVS_SMALLICON ウィンドウ スタイルで指定するか、LVM_SETVIEWでLV_VIEW_SMALLICONを渡すことによって指定します。 各項目は、ラベルが右側にある小さなアイコンとして表示されます。 ユーザーは項目を任意の場所にドラッグできます。 |
| リスト ビュー | LVS_LIST ウィンドウ スタイルで指定するか、LVM_SETVIEWでLV_VIEW_LISTを渡すことによって指定します。 各項目は、その右側にラベルが付いた小さなアイコンとして表示されます。 項目は列に配置され、ユーザーは任意の場所にドラッグすることはできません。 |
| レポート (詳細) ビュー | LVS_REPORT ウィンドウ スタイルまたはLVM_SETVIEWでLV_VIEW_DETAILSを渡すことによって指定します。 各項目は独自の行に表示され、情報は列に配置されます。 左端の列は常に左揃えで、小さなアイコンとラベルが含まれています。 後続の列には、アプリケーションで指定されたサブ項目が含まれます。 LVS_NOCOLUMNHEADER ウィンドウ スタイルも指定しない限り、各列にはヘッダーがあります。 |
| タイル ビュー | バージョン 6 以降。 LVM_SETVIEWでLV_VIEW_TILEを渡すことによって指定します。 各項目はフルサイズのアイコンとして表示され、その横に 1 行以上のラベルが付いています。 |
次のスクリーン ショットでは、ビューを使用して、7 匹のペットのそれぞれに関するさまざまな情報を表示します。 このビューは、情報が Vista でどのように表示されるかWindows示しています。 コントロールの表示スタイルは、 SetWindowTheme を使用して "エクスプローラー" テーマに設定されています。
次のスクリーン ショットは、詳細ビューを示しています。
次のスクリーン ショットは、アイコン ビューを示しています。
次のスクリーン ショットは、リスト ビューを示しています。
次のスクリーン ショットは、タイル ビューを示しています。
リスト ビュー コントロールを作成した後で、ビューの種類を変更できます。 ウィンドウ スタイルを取得して変更するには、 GetWindowLong 関数と SetWindowLong 関数を 使用します。 現在のビューのウィンドウ スタイルを確認するには、 LVS_TYPEMASK 値を使用します。
LVS_ALIGNTOP (既定) または LVS_ALIGNLEFT ウィンドウ スタイルを指定することで、アイコンまたは小さなアイコン ビューで項目を配置する方法 を 制御できます。
配置は、リスト ビュー コントロールを作成した後で変更できます。 現在の配置を確認するには、 LVS_ALIGNMASK 値を使用します。
追加のウィンドウ スタイルには、ユーザーがラベルを編集できるか、複数の項目を一度に選択できるかなど、その他のオプションが用意されています。 完全な一覧については、「 リスト ビュー ウィンドウ スタイル」を参照してください。
拡張List-View スタイル
拡張リスト ビュー コントロール スタイルには、チェック ボックス、フラット スクロール バー、グリッド線、ホットトラッキングなどのオプションが用意されています。 完全な一覧については、「 拡張List-Viewスタイル」を参照してください。 標準ウィンドウ スタイルと同じ方法で拡張リスト ビュー スタイルにアクセスすることはできません。 拡張スタイルの変更には 、GetWindowLong 関数と SetWindowLong 関数は使用しません。
拡張スタイル情報の設定と取得には、 LVM_SETEXTENDEDLISTVIEWSTYLE と LVM_GETEXTENDEDLISTVIEWSTYLEの 2 つのメッセージがあります。 メッセージを明示的に送信する代わりに、ListView_SetExtendedListViewStyle、ListView_SetExtendedListViewStyleEx、ListView_GetExtendedListViewStyleの対応するマクロを使用できます。
仮想List-View スタイル
仮想リスト ビューは、 LVS_OWNERDATA スタイルを持つリスト ビュー コントロールです。 このスタイルを使用すると、所有者がアイテム データの管理の負担を受け取るため、コントロールは数百万の項目を処理できます。 これにより、データ アクセスの特定の方法が既に配置されている大規模な情報データベースで、仮想リスト ビュー コントロールを使用できます。
仮想リスト ビュー コントロールでは、項目情報自体はほとんど保持されません。 項目の選択とフォーカスの情報を除き、コントロールの所有者はすべての項目情報を管理する必要があります。 その他のプロセスでは、LVN_GETDISPINFO通知コードを使用して所有者からアイテム情報 を 要求します。
この種類のリスト コントロールは大規模なデータ セットを対象とします。このため、取得パフォーマンスが高まるように、要求された項目データをキャッシュすることを推奨します。 リスト ビューには、キャッシュの最適化に役立つキャッシュ ヒントメカニズムが用意されています。 ヒントは、 LVN_ODCACHEHINT 通知コードの形式で実装されます。
仮想List-View コントロールの作成
CreateWindow または CreateWindowEx 関数を使用して仮想リスト ビュー コントロールを作成し、dwStyle 関数パラメーターの一部としてLVS_OWNERDATA ウィンドウ スタイルを指定します。 LVS_OWNERDATA スタイルとの動的な切り替えはサポートされていません。
LVS_OWNERDATA スタイルは、LVS_SORTASCENDINGまたはLVS_SORTDESCENDING スタイルを除く、他のほとんどのウィンドウ スタイルと組み合わせて使用できます。 すべての仮想リスト ビュー コントロールは、既定で LVS_AUTOARRANGE スタイルになります。
リストに項目を表示できるようにするには、最初に、明示的に、または ListView_SetItemCountEx マクロを使用して、 LVM_SETITEMCOUNT メッセージを送信する必要があります。
LVS_OWNERDATA スタイルでは、LVM_ENABLEGROUPVIEW、LVM_GETITEMTEXT、LVM_SETTILEINFO、LVM_MAPIDTOINDEXの各メッセージはサポートされていません。
互換性の問題
4 つのリスト ビュー スタイル (アイコン、小さいアイコン、リスト、レポート ビュー) はすべて、 LVS_OWNERDATA スタイルをサポートします。 LVS_OWNERDATA スタイルを持つリスト ビュー コントロールには、項目固有の情報は格納されません。 したがって、アイテムに適用できる唯一の有効な項目状態フラグは 、LVIS_SELECTED と LVIS_FOCUSEDです。 他の状態情報は格納されません。 特に、リスト ビュー コントロールでは、アイテムごとに状態が維持されたり、イメージがオーバーレイされたりすることはありません。 ただし、 LVM_SETCALLBACKMASK メッセージを 送信することで、リスト ビュー コントロールでアプリケーションに対してこれらのイメージのクエリを実行できます。
ほとんどのリスト ビュー コントロール メッセージと関連するマクロが完全にサポートされています。 ただし、一部のメッセージには制限があります。 また、LVS_OWNERDATA スタイルを使用する場合はサポートされていません。 次の表は、影響を受けるメッセージをまとめたものです。
| Message | 制限事項 |
|---|---|
| LVM_ARRANGE | LVA_SNAPTOGRID スタイルはサポートされていません。 |
| LVM_DELETEALLITEMS | 項目数を 0 に設定し、すべての内部選択変数をクリアしますが、実際には項目は削除されません。 通知コールバックを行います。 |
| LVM_DELETEITEM | 選択の整合性に対してのみサポートされており、実際には項目を削除しません。 |
| LVM_GETITEMSTATE | フォーカス状態と選択状態 (つまり、リスト ビュー コントロールに格納されている状態) のみを返します。 |
| LVM_GETNEXTITEM | リスト ビューの検索条件 LVNI_CUT、 LVNI_HIDDEN、または LVNI_DROPHILITEDはサポートされていません。 その他の条件はすべてサポートされています。 |
| LVM_GETWORKAREAS | サポートされません。 |
| LVM_INSERTITEM | 選択の整合性に対してのみサポートされます。 |
| LVM_SETITEM | サポートされません。 アイテムの状態を設定するには、 ListView_SetItemState メッセージを使用します。 |
| LVM_SETITEMCOUNT | リストに現在含まれている項目の数を設定します。 リスト ビュー コントロールが、最大セットまでの項目のデータを要求する通知を送信する場合は、そのデータを提供するために所有者を準備する必要があります。 メッセージ パラメーターは、仮想リスト ビュー コントロールをサポートします。 |
| LVM_SETITEMPOSITION | サポートされません。 |
| LVM_SETITEMSTATE | 項目の選択とフォーカスの状態のみを変更できます。 |
| LVM_SETITEMTEXT | サポートされません。 アイテム テキストを維持するのはアプリケーションの責任です。 |
| LVM_SETWORKAREAS | サポートされません。 |
| LVM_SORTITEMS | サポートされません。 必要な順序で項目を提示するのは、アプリケーションの責任です。 |
仮想List-Viewコントロール通知コードの処理
LVS_OWNERDATA スタイルのリスト ビュー コントロールは、他のリスト ビュー コントロールと同じ通知コードと、LVN_ODCACHEHINTとLVN_ODFINDITEMの 2 つの追加の通知コードを送信します。 LVS_OWNERDATA スタイルを持つリスト ビュー コントロールが送信する最も一般的な通知を次 に 示します。
| Notification | Description |
|---|---|
| LVN_GETDISPINFO | 仮想リスト ビュー コントロールは、項目情報をそれ自体でほとんど保持します。 その結果、多くの場合、 LVN_GETDISPINFO 通知コードが送信され、アイテム情報が要求されます。 このメッセージは、標準リスト コントロールのコールバック項目とほぼ同じ方法で処理されます。 コントロールでサポートされる項目の数は非常に大きくなる可能性があるため、項目データをキャッシュするとパフォーマンスが向上します。 LVN_GETDISPINFOを処理する場合、コントロールの所有者は最初にキャッシュから要求された項目情報を提供しようとします (詳細については、 キャッシュ管理を参照してください)。 要求された項目がキャッシュされていない場合、所有者は他の方法で情報を提供する準備をする必要があります。 |
| LVN_ODCACHEHINT | 仮想リスト ビューは 、キャッシュ の最適化に役立つLVN_ODCACHEHINT通知コードを送信します。 通知コードは、キャッシュすることをお勧めする項目の範囲に対して包括的なインデックス値を提供します。 通知コードを受信したら、要求された範囲の項目情報を含むキャッシュを読み込み、 LVN_GETDISPINFO メッセージが送信されたときに情報をすぐに使用できるように、所有者が準備する必要があります。 |
| LVN_ODFINDITEM | LVN_ODFINDITEM通知コードは、コントロールが特定のコールバック項目を検索するために所有者を必要とする場合に、仮想リスト ビュー コントロールによって送信されます。 通知コードは、リスト ビュー コントロールがクイック キー アクセスを受け取ったとき、または LVM_FINDITEM メッセージを受信したときに送信されます。 検索情報は、NMLVFINDITEM 構造体のメンバーである LVFINDINFO 構造体の形式で送信されます。 所有者は、リスト ビュー コントロールによって指定された情報と一致する項目を検索する準備をする必要があります。 所有者は、成功した場合は項目のインデックスを返し、一致する項目が見つからない場合は -1 を返します。 |
キャッシュ管理
LVS_OWNERDATA スタイルのリスト ビュー コントロールでは、多数のLVN_GETDISPINFO通知コードが生成され、キャッシュの最適化に役立つLVN_ODCACHEHINT メッセージが生成されます。 LVN_ODCACHEHINTメッセージは、キャッシュ内に含める推奨項目に関する情報を提供します。 これらのメッセージは WM_NOTIFY メッセージとして送信され、 lParam 値は NMLVCACHEHINT 構造体のアドレスとして機能します。
NMLVCACHEHINT 構造体には、最も可能性の高い項目の範囲の包括的なエンドポイントを表す 2 つの整数メンバー iFrom と iTo が含まれています。 所有者は、推奨される範囲内の各項目の項目情報を含むキャッシュを読み込む準備をする必要があります。
リスト コントロールには、多くの場合、最初の項目 (オフセット 0) の項目情報が必要です。 LVN_ODCACHEHINT通知コードにアイテム 0 が含まれているとは限りませんが、常にキャッシュに含める必要があります。
リスト内の最後の項目には、頻繁にアクセスされます。 そのため、所有者は、リストの最後に項目を含む 2 つ目のキャッシュを保持する必要がある場合があります。 LVN_ODCACHEHINTから要求された範囲をエンド キャッシュに対してチェックして、毎回同じ終了範囲を再読み込みするのではなく、自動的に使用できるようにします。
List-View作業領域
リスト ビュー コントロールは、作業領域をサポートします。これは、リスト ビュー コントロールが項目の配置に使用する四角形の仮想領域です。 作業領域はウィンドウではなく、表示される境界線を持つことはできません。 既定では、リスト ビュー コントロールには作業領域がありません。 作業領域を作成すると、項目の左、上、または右に空の罫線を作成したり、通常は表示されない場合に水平スクロール バーを表示したりできます。
作業領域が作成されると、作業領域内にある項目が作業領域のメンバーになります。 同様に、アイテムが作業領域に移動されると、その作業領域のメンバーになります。 どの作業領域内にもない項目は、自動的に最初の (インデックス 0 の) 作業領域のメンバーになります。 特定の作業領域内に新しい項目を配置するには、まず項目を作成してから、 LVM_SETITEMPOSITION または LVM_SETITEMPOSITION32 メッセージを使用して目的の作業領域に移動する必要があります。
次の図は、クライアント領域の異なる領域にある 4 つの作業領域を含むリスト ビュー コントロールの例です。
複数の作業領域を使用して、1 つのビュー内に異なる領域を作成できます。 異なる意味を持つ領域を 1 つのビューで作成できます。 たとえば、ファイル システムのビューには、読み取り/書き込みファイルの領域と、読み取り専用ファイル用の別の領域があります。 ユーザーは、アイテムを異なる作業領域に配置することで、項目を分類できます。 ファイルが読み取り専用領域に移動されると、自動的に読み取り専用になります。
複数の作業領域が交差できますが、交差部分内にある項目はすべて、下位インデックスを持つ領域のメンバーになります。したがって、この状況を避けるのが最善です。 複数の作業領域を並べ替えると、アイテムは同じ作業領域の他の項目と比較して並べ替えられます。
LVM_GETNUMBEROFWORKAREAS メッセージを使用して作業領域の数を取得できます。 作業領域は 、LVM_SETWORKAREAS メッセージで変更され、 LVM_GETWORKAREAS メッセージを使用して取得できます。 これらのメッセージはいずれも、 RECT 構造体の配列のアドレスを lParam として受け取り、 RECT 構造体の数を wParam として受け取ります。 これらの構造体の左右のメンバーは作業領域の左上隅 (原点) の座標を指定し、右と下のメンバーは作業領域の右下隅を指定します。 すべての座標は、リスト ビューのクライアント座標にあります。 許容される作業領域の最大数は、 LV_MAX_WORKAREAS 値によって定義されます。
作業領域の変更は、 LVS_LIST ビューまたは LVS_REPORT ビューを持つリスト ビュー コントロールには影響しませんが、作業領域はビューの種類が変更されたときに維持されます。 LVS_ICONビューとLVS_SMALLICONビューでは、作業領域を変更して項目の表示方法を変更できます。 作業領域の幅 (右から左) をコントロールのクライアント幅より大きくすると、項目がその幅にラップされ、水平スクロール バーが表示されます。 作業領域の幅をコントロールのクライアント領域の幅よりも狭くすると、クライアント領域ではなく作業領域内にアイテムがラップされます。 左または上のメンバーを正の値に設定すると、作業領域から項目が表示され、コントロールの端と項目の間に空のスペースが作成されます。 また、作業領域の幅をコントロールのクライアント幅よりも小さくすることで、コントロールの右端と項目の間に空の領域を作成することもできます。
イメージ リストのList-View
既定では、リスト ビュー コントロールでは項目イメージは表示されません。 項目イメージを表示するには、イメージ リストを作成し、コントロールに関連付ける必要があります。 リスト ビュー コントロールには、次の 3 つの画像リストを含めることができます。
- コントロールがアイコン ビューにあるときに表示されるフルサイズのアイコンを含む画像リスト。
- コントロールが小さいアイコン ビュー、リスト ビュー、またはレポート ビューにあるときに表示される小さいアイコンを含む画像リスト。
- フルサイズまたは小さいアイコンの左側に表示される状態イメージを含む画像リスト。 チェック ボックスやクリア チェック ボックスなどの状態イメージを使用して、アプリケーション定義の項目の状態を示すことができます。 状態イメージは、アイコン ビュー、小さいアイコン ビュー、リスト ビュー、レポート ビューに表示されます。
フルサイズと小さいアイコンの画像リストには、アイテム アイコンの上に透過的に描画するように設計された オーバーレイ イメージを含めることもできます。
リスト ビュー コントロールでオーバーレイ イメージを使用するには:
- ImageList_SetOverlayImage関数を呼び出して、フルサイズの小さいアイコン 画像リストの画像にオーバーレイ 画像インデックスを割り当てます。 オーバーレイ イメージは、1 から始まるインデックスによって識別されます。
- ListView_InsertItemまたはListView_SetItem マクロを呼び出すときに、オーバーレイ イメージ インデックスを項目に関連付けることができます。 INDEXTOOVERLAYMASK マクロを使用して、アイテムの LVITEM 構造体の状態メンバーにオーバーレイ イメージ インデックスを指定します。 stateMask メンバーのLVIS_OVERLAYMASK ビットも設定する必要があります。
状態イメージ リストが指定されている場合、リスト ビュー コントロールは、状態イメージの各項目のアイコンの左側にスペースを予約します。
状態イメージを項目に関連付けるには、INDEXTOSTATEIMAGEMASK マクロを使用して、LVITEM 構造体の状態メンバーに状態イメージ インデックスを指定します。 インデックスは、コントロールの状態イメージ リスト内のイメージを識別します。 イメージ リスト インデックスは 0 から始まりますが、コントロールは 1 から始まるインデックスを使用して状態イメージを識別します。 状態イメージ インデックスが 0 の場合、項目に状態イメージがないことを示します。
既定では、リスト ビュー コントロールが破棄されると、割り当てられたイメージ リストが破棄されます。 ただし、リスト ビュー コントロールに LVS_SHAREIMAGELISTS ウィンドウ スタイルがある場合、アプリケーションは、使用されなくなったイメージ リストを破棄する必要があります。 同じイメージ リストを複数のリスト ビュー コントロールに割り当てる場合は、このスタイルを指定する必要があります。それ以外の場合、複数のコントロールが同じイメージ リストを破棄しようとする可能性があります。
アイテムとサブアイテムのList-View
リスト ビュー コントロールの各項目には、アイコン、ラベル、現在の状態、アプリケーション定義の値があります。 リスト ビュー メッセージを使用すると、アイテムの追加、変更、削除、およびアイテムに関する情報の取得を行うことができます。
各項目には、1 つ以上の サブ項目を含めることができます。 サブアイテムは、レポート ビューで、アイテムのアイコンとラベルとは別の列に表示される文字列です。 サブ項目のテキストを指定するには、 LVM_SETITEMTEXTまたはLVM_SETITEM メッセージ を 使用します。 リスト ビュー コントロール内のすべての項目は、同じ数のサブ項目を持っています。 サブ項目の数は、リスト ビュー コントロール内の列の数によって決まります。 リスト ビュー コントロールに列を追加する場合は、関連付けられているサブ項目インデックスを指定します。
LVITEM 構造体は、リストビュー項目またはサブ項目を定義します。 iItem メンバーは、項目の 0 から始まるインデックスです。 構造体に項目に関する情報が含まれている場合、 iSubItem メンバーはサブ項目の 1 から始まるインデックス、または 0 です。 その他のメンバーでは、項目のテキスト、アイコン、状態、項目データを指定します。 項目データ は、リスト ビュー項目に関連付けられたアプリケーション定義の値です。
リスト ビュー コントロールに項目を追加するには、LVITEM 構造体のアドレスを指定して、LVM_INSERTITEM メッセージを使用します。 複数の項目を追加する前に、コントロールに 最終的に 含まれる項目の数を指定して、LVM_SETITEMCOUNTメッセージをコントロールに送信できます。 このメッセージにより、リスト ビュー コントロールは、項目を追加するたびにではなく、内部データ構造を 1 回だけ再割り当てできます。 リスト ビュー コントロール内の項目の数は、 LVM_GETITEMCOUNT メッセージを使用して決定できます。 リスト ビュー コントロールに多数の項目を追加する場合は、項目を追加する前に再描画を無効にしてから、項目が追加された後に再描画を有効にすることで、プロセスを高速化できます。 再描画を有効または無効にするには、 WM_SETREDRAW メッセージを使用します。
リスト ビュー項目の属性を変更するには、LVITEM 構造体のアドレスを指定して、LVM_SETITEM メッセージを使用します。 この構造体の マスク メンバーは、変更する項目属性を指定します。 たとえば、アイテムまたはサブアイテムのテキストのみを変更するには、 LVM_SETITEMTEXT メッセージを使用します。
リスト ビュー項目に関する情報を取得するには、 LVM_GETITEM メッセージを使用して、入力する LVITEM 構造体のアドレスを指定します。 この構造体の マスク メンバーは、取得する項目属性を指定します。 アイテムまたはサブアイテムのテキストのみを取得するには、 LVM_GETITEMTEXT メッセージを使用します。
リスト ビュー項目を削除するには、 LVM_DELETEITEM メッセージを使用します。 LVM_DELETEALLITEMS メッセージを使用して、リスト ビュー コントロール内のすべての項目を削除できます。
List-View項目の状態
アイテムの状態は、アイテムの可用性を指定する値、ユーザー アクションを示す値、またはアイテムの状態を反映する値です。 リスト ビュー コントロールは、ユーザーが項目を選択するときなど、一部の状態ビットを変更します。 アプリケーションは、アイテムを無効または非表示にしたり、オーバーレイ イメージまたは状態イメージを指定したりするために、他の状態ビットを変更する場合があります。 オーバーレイ イメージと状態イメージの詳細については、「 リスト ビュー イメージ リスト」を参照してください。
項目の状態は、LVITEM 構造体の状態メンバーによって指定されます。 項目の状態を指定または変更すると、 stateMask メンバーは、変更する必要がある状態ビットを指定します。 アイテムの状態は、 LVM_SETITEMSTATE メッセージを使用して変更できます。 アイテムの状態は、アイテムを作成するとき、または LVM_SETITEM メッセージを使用して属性を変更するときに指定できます。 アイテムの現在の状態を確認するには、LVM_GETITEMSTATEまたは LVM_GETITEM メッセージ を 使用します。
項目のオーバーレイ イメージを設定するには、LVITEM 構造体の stateMask メンバーにLVIS_OVERLAYMASK値を含める必要があります。また、STATE メンバーには、INDEXTOOVERLAYMASK マクロを使用して、8 ビット左にシフトされたオーバーレイ イメージの 1 から始まるインデックスを含める必要があります。 オーバーレイ イメージを指定しない場合は、インデックスを 0 にできます。
項目の状態イメージを設定するには、LVITEM 構造体の stateMask メンバーにLVIS_STATEIMAGEMASK値を含める必要があります。また、STATE メンバーには、INDEXTOSTATEIMAGEMASK マクロを使用して 12 ビット左にシフトされた状態イメージの 1 から始まるインデックスを含める必要があります。 状態イメージを指定しない場合は、インデックスを 0 にすることができます。
コールバック項目とコールバック マスク
リスト ビュー コントロールは、通常、各アイテムについて、ラベル テキスト、項目のアイコンの画像リスト インデックス、および項目の状態に対するビット フラグのセットを格納します。 コールバック項目を定義したり、コントロールのコールバック マスクを変更して、コントロールではなくアプリケーションがこの情報の一部またはすべてを格納することを示すことができます。 アプリケーションでこの情報の一部が格納されている場合は、コールバックを使用できます。
リスト ビュー コントロール内の コールバック項目 は、アプリケーションがテキストインデックスまたはアイコンインデックス、またはその両方を格納するアイテムです。 LVM_INSERTITEM メッセージを送信してリスト ビュー コントロールに項目を追加するときに、コールバック項目を定義できます。 アプリケーションが項目またはサブ項目のテキストを格納する場合は、項目の LVITEM 構造体の pszText メンバーをLPSTR_TEXTCALLBACKに設定します。 アプリケーションが項目のアイコン インデックスを格納する場合は、項目の LVITEM 構造体の iImage メンバーをI_IMAGECALLBACKに設定します。
リスト ビュー コントロールの コールバック マスク は、コントロールではなく、アプリケーションが現在のデータを格納する項目の状態を指定するビット フラグのセットです。 コールバック項目の指定が個別の項目に適用されるのに対し、コールバック マスクは、コントロールのすべての項目に適用されます。 コールバック マスクは既定では 0 です。つまり、リスト ビュー コントロールはすべての項目の状態情報を格納します。 リスト ビュー コントロールを作成し、その項目を初期化したら、 LVM_SETCALLBACKMASK メッセージを送信してコールバック マスクを変更できます。 現在のコールバック マスクを取得するには、 LVM_GETCALLBACKMASK メッセージを送信します。
リスト ビュー コントロールで、アプリケーションがコールバック情報を格納するリスト ビュー項目を表示または並べ替える必要がある場合、コントロールは LVN_GETDISPINFO 通知コードをコントロールの親ウィンドウに送信します。 このメッセージは、必要な情報のタイプを含む NMLVDISPINFO 構造体を指定し、取得する項目またはサブ項目を識別します。 要求されたデータを提供するには、親ウィンドウでLVN_GETDISPINFOを処理する必要があります。
リスト ビュー コントロールは、テキスト、アイコン、状態情報の変更など、項目のコールバック情報の変更を検出した場合、変更を通知する LVN_SETDISPINFO 通知コードを送信します。
コールバック 項目の属性または状態ビットを変更する場合は、 LVM_UPDATE メッセージを使用して、コントロールに項目の再描画を強制します。 このメッセージは、コントロールが LVS_AUTOARRANGE スタイルを持っている場合にも、その項目を配置します。 リスト ビュー コントロールのクライアント領域の対応する部分を無効にすることで、 LVM_REDRAWITEMS メッセージを使用して項目の範囲を再描画できます。
コールバック項目とコールバック マスクを効果的に使用することで、各アイテム属性が 1 つの場所でのみ維持されるようにすることができます。 これを行うと、アプリケーションを簡略化できますが、保存される領域は、項目ラベルとサブ項目テキストを格納するために必要なメモリだけです。
List-View項目の位置
すべてのリスト ビュー項目には、メッセージを使用して取得および設定できる位置とサイズがあります。 また、指定した位置にある項目 (存在する場合) を決定することもできます。 リスト ビュー項目の位置は、スクロール位置によってオフセットされたクライアント 座標であるビュー座標で指定されます。
項目の位置を取得して設定するには、 メッセージのLVM_GETITEMPOSITION と LVM_SETITEMPOSITION を使用します。 LVM_GETITEMPOSITION はすべてのビューに対して機能しますが、 LVM_SETITEMPOSITION はアイコン ビューと小さいアイコン ビューでのみ機能します。
特定の場所にある項目がある場合は、 LVM_HITTEST メッセージを使用して判断できます。
リスト アイテムの外接する四角形、またはそのアイコンまたはラベルの外接する四角形のみを取得するには、 LVM_GETITEMRECT メッセージを使用します。
アイテムの配置、並べ替え、検索
リスト ビュー メッセージを使用すると、アイテムを並べ替えたり、属性や位置に基づいてアイテムを検索したりできます。 配置すると、項目がグリッド上に配置されるように再配置されますが、項目のインデックスは変更されません。 並べ替えにより、項目のシーケンス (および対応するインデックス) が変更され、それに応じて位置が変更されます。 アイコン ビューと小さなアイコン ビューでのみ項目を並べ替えることができますが、任意のビューでアイテムを並べ替えることができます。 アイテムを検索するには、アイテムの場所またはプロパティを指定するリスト ビュー メッセージを送信します。
アイテムを配置するには、 LVM_ARRANGE メッセージを使用します。 LVS_AUTOARRANGE ウィンドウ スタイルを指定することで、アイテムが常に配置されるようにすることができます。
アイテムを並べ替えるには、 LVM_SORTITEMS メッセージを使用します。 このメッセージを使用して並べ替える場合は、2 つの項目の相対順序を比較するためにリスト ビュー コントロールが呼び出すアプリケーション定義のコールバック関数を指定します。 コントロールは、2 つの項目のそれぞれに関連付けられている項目データを比較関数に渡します。 項目データは、項目の LVITEM 構造体の lParam メンバーがリストに挿入されたときに指定された値です。 適切な項目データを指定し、適切な比較関数を指定することで、ラベル、任意のサブ項目、またはその他のプロパティで項目を並べ替えることができます。 項目の並べ替えは、対応するサブ項目の順序を変更しないことに注意してください。 項目を並べ替えると、対応するサブ項目が持ち込まれます。つまり、行全体が一緒に保持されます。 列を互いに個別に並べ替えるには、サブ項目を項目からデタッチし、 LVM_SETITEMを使用して並べ替え後に列を再生成する必要があります。
LVS_SORTASCENDING またはLVS_SORTDESCENDING ウィンドウ スタイルを指定することで、リスト ビュー コントロールを常 に 並べ替えることができます。 これらのスタイルを持つコントロールは、項目のラベル テキストを使用して、昇順または降順で並べ替えます。 これらのウィンドウ スタイルを使用する場合、比較関数を指定することはできません。 リスト ビュー コントロールにこれらのスタイルのいずれかが含まれている場合、LVITEM 構造体の pszText メンバーとしてLPSTR_TEXTCALLBACK項目を挿入しようとすると、LVM_INSERTITEM メッセージは失敗します。
LVM_FINDITEM メッセージを使用して、特定のプロパティを持つリスト ビュー 項目を見つけることができます。 LVM_GETNEXTITEM メッセージを 使用して、指定した状態で、特定のアイテムに対して指定されたリレーションシップを持つリスト ビュー アイテムを見つけることができます。 たとえば、指定した項目の右側にある次に選択した項目を取得できます。
列のList-View
列は、アイテムとそのサブ項目をレポート ビューに表示する方法を制御します。 各列にはタイトルと幅があり、特定のサブ項目に関連付けられています。サブ項目 0 は、項目のアイコンとラベルです。 列の属性は 、LVCOLUMN 構造体によって定義されます。
リスト ビュー コントロールに列を追加するには、 LVM_INSERTCOLUMN メッセージを使用します。 列を削除するには、 LVM_DELETECOLUMN メッセージを使用します。
注意
リスト ビュー コントロールの列 0 の削除は、バージョン 6 以降ComCtl32.dllでのみサポートされています。 バージョン 5 では列 0 の削除もサポートされていますが、 CCM_SETVERSION を使用してバージョンを 5 以降に設定した後にのみサポートされます。 バージョン 5 より前のバージョンでは、列 0 の削除はサポートされていません。
LVM_GETCOLUMNメッセージとLVM_SETCOLUMNメッセージを使用して、既存の列のプロパティを取得および変更できます。 列の幅を取得または変更するには、 メッセージのLVM_GETCOLUMNWIDTH と LVM_SETCOLUMNWIDTH を使用します。
LVS_NOCOLUMNHEADER ウィンドウ スタイルを指定しない限り、レポート ビューに列ヘッダーが表示されます。 ユーザーが列ヘッダーをクリックすると、 LVN_COLUMNCLICK 通知コードが親ウィンドウに送信されます。 通常、親ウィンドウでは、このクリックが発生したときに、指定した列でリスト ビュー コントロールが並べ替えられます。 ユーザーは、ヘッダー間で列ガイドをドラッグして列のサイズを設定することもできます。
リスト ビュー コントロールでは、列タイトルの横に画像を表示できます。 この機能を実装するには、LVCF_IMAGE値を指定し、LVCOLUMN 構造体の iImage メンバーにイメージのインデックスを割り当てます。
リスト ビュー コントロールでは、列の表示順序を設定できます。 この機能を実装するには、LVCF_ORDER値を指定し、LVCOLUMN 構造体の iOrder メンバーに列の順序を割り当てます。 列の順序は 0 から始まる順で、左から右の順序です。 たとえば、0 は左端の列を示します。
List-Viewスクロール位置
LVS_NOSCROLL ウィンドウ スタイルを指定しない限り、リスト ビュー コントロールをスクロールして、コントロールのクライアント領域に収まらない項目を表示できます。 リスト ビュー コントロールのスクロール位置と関連情報を取得したり、リスト ビュー コントロールを指定した量でスクロールしたり、リスト ビュー コントロールをスクロールして指定したリスト アイテムを表示したりすることができます。
アイコン ビューまたは小さいアイコン ビューでは、現在のスクロール位置はビューの 原点によって定義されます。 ビューの原点は、リスト ビュー コントロールの表示領域を基準とした、ビュー座標 (0,0) に対応する座標のセットです。 現在のビューの配信元を取得するには、 LVM_GETORIGIN メッセージを使用します。 このメッセージは、アイコンまたは小さなアイコン ビューでのみ使用する必要があります。リスト ビューまたはレポート ビューでエラーが返されます。
リスト ビューまたはレポート ビューでは、現在のスクロール位置は上部の インデックスによって定義されます。 一番上のインデックスは、リスト ビュー コントロール内の最初に表示される項目のインデックスです。 現在の最上位インデックスを取得するには、 LVM_GETTOPINDEX メッセージを使用します。 このメッセージは、リスト ビューまたはレポート ビューでのみ有効な結果を返します。アイコンまたは小さいアイコン ビューで 0 を返します。
LVM_GETVIEWRECT メッセージを使用すると、コントロールの表示領域を基準にして、リスト ビュー コントロール内のすべての項目の外接する四角形を取得できます。
LVM_GETCOUNTPERPAGE メッセージは、リスト ビュー コントロールの 1 ページに収まる項目の数を返します。 このメッセージは、リスト ビューとレポート ビューでのみ有効な結果を返します。アイコンビューと小さなアイコンビューでは、アイテムの合計数が返されます。
リスト ビュー コントロールを特定の量までスクロールするには、 LVM_SCROLL メッセージを使用します。 LVM_ENSUREVISIBLE メッセージを使用すると、必要に応じてリスト ビュー コントロールをスクロールして、指定した項目が確実に表示されるようにすることができます。
List-Viewラベル編集
LVS_EDITLABELS ウィンドウ スタイルを持つリスト ビュー コントロールを使用すると、ユーザーはアイテム ラベルを適切に編集できます。 ユーザーは、フォーカスがある項目のラベルをクリックして編集を開始します。 または、アプリケーションは、 LVM_EDITLABEL メッセージを使用して自動的に編集を開始できます。 リスト ビュー コントロールは、編集の開始時と、編集がキャンセルまたは完了したときに親ウィンドウに通知します。 編集が完了すると、必要に応じて、親ウィンドウがアイテムのラベルを更新します。
ラベルの編集が開始されると、 編集コントロール が作成、配置、初期化されます。 表示される前に、リスト ビュー コントロールは親ウィンドウ にLVN_BEGINLABELEDIT 通知コードを送信します。 ラベル編集プロセスを変更する必要がある場合は、この通知のハンドラーを実装できます。
LVN_BEGINLABELEDIT通知ハンドラーの 1 つの用途は、ユーザーが編集できるラベルを制御することです。 ラベルの編集を防ぐには、0 以外の値を返します。 ラベルの編集をカスタマイズするには、通知ハンドラーに、 LVM_GETEDITCONTROL メッセージを リスト ビュー コントロールに送信することで、編集コントロールへのハンドルを取得します。 そのハンドルを取得したら、通常のEM_XXX メッセージを送信して編集コントロールをカスタマイズできます。 たとえば、ユーザーが入力できるテキストの量を制限するには、編集コントロールに EM_LIMITTEXT メッセージを送信します。 SetWindowText を使用して、編集コントロールの既定のテキストを変更できます。 編集コントロールをサブクラス化して、無効な文字をインターセプトして破棄することもできます。
ラベルの編集が取り消されるか完了すると、リスト ビュー コントロールは親ウィンドウ にLVN_ENDLABELEDIT 通知コードを送信します。 lParam パラメーターは、NMLVDISPINFO 構造体のアドレスです。 この構造体の 項目 メンバーは、 iItem メンバーが項目を識別する LVITEM 構造体です。 編集が取り消された場合、LVITEM 構造体の pszText メンバーは NULL になります。それ以外の場合、pszText は編集されたテキストのアドレスです。 新しいラベルを保持する場合は、親ウィンドウで項目のラベルを更新します。
List-View色
アプリケーションは、リスト ビュー コントロールの 3 つの色を取得して設定できます。
| Color | 色の取得と設定に使用されるメッセージ |
|---|---|
| テキストの色 | LVM_GETTEXTCOLOR、 LVM_SETTEXTCOLOR |
| テキストの背景色 | LVM_GETTEXTBKCOLOR、 LVM_SETTEXTBKCOLOR |
| ウィンドウの背景色 | LVM_GETBKCOLOR、 LVM_SETBKCOLOR |
リスト ビュー コントロールの外観をより大幅にカスタマイズするには、 NM_CUSTOMDRAW (リスト ビュー) を使用するか、表示スタイルを使用します (「 表示スタイル 」と「 表示スタイルの有効化」を参照)。
グループ別のリスト アイテムの配置
リスト ビュー コントロールのグループ化機能を使用すると、論理的に関連する項目のセットを視覚的にグループ化できます。 グループは、項目のプロパティ、属性、またはその他の特性に基づいて作成できます。 通常、これらのグループは、グループの名前を含む水平ヘッダーによって画面上で区切られます。 次のスクリーン ショットは、グループ化された項目を示しています。
LVGROUP 構造体を使用して、ヘッダーやフッターのテキスト、グループの現在の状態など、グループに関する情報を格納します。 グループ化 API には、グループへの項目の追加、ビューへのグループの追加、グループ 項目の並べ替え、項目のサイズやその他の情報に関するグループのクエリを実行することで、グループとグループ要素を管理できるメッセージが含まれています。 たとえば、ListView_SetGroupMetricsマクロと ListView_GetGroupMetricsマクロを 使用して、各グループの表示パラメーターを設定および取得できます。
グループ化は、リスト ビューを除くすべてのビューで使用できます。 LVS_OWNERDATA スタイルを持つコントロールでは使用できません。
詳細については、「 List-View コントロールの使用」を参照してください。
挿入マーク
挿入マークは、ドラッグされた項目が配置される場所をユーザーに示します。 現在、ユーザーが項目を [スタート] メニューまたはサイド リンク バーにドラッグすると、挿入マークが表示されます。 挿入マークは、オートアレンジに設定されているリストにも使用できます。 ユーザーが項目をその他の 2 つの項目の間のポイントにドラッグすると、項目の予期される新しい場所に挿入マークが表示されます。 次のスクリーン ショットは、挿入マークを示しています。
挿入マーク API 要素を使用すると、ヒット検出を実行するメッセージとフラグを指定し、項目ごとに挿入マークの位置と外観を指定し、挿入マークの現在のサイズと外観に関する情報をクエリすることで、挿入マークの配置を可能にします。