リスト ビュー コントロールについて
「Virtual listview コントロールのサンプル」を参照してください。
リストビュー コントロールは、アイテムのコレクションを表示するウィンドウです。 リストビュー コントロールは、アイテムを配置および表示するためのいくつかの方法を提供し、単純なリスト ボックスよりもはるかに柔軟です。 たとえば、各アイテムに関する追加情報は、アイコンとラベルの右側の列に表示できます。
- リストビュー スタイルとビュー
- 仮想リストビュー スタイル
- リスト ビューの作業領域
- リストビュー イメージ リスト
- リストビュー アイテムとサブアイテム
- リストビュー列
- リストビューのスクロール位置
- リスト ビュー ラベルの編集
- リストビューの色
- グループ別のリスト アイテムの配置
- 挿入マーク
リストビュー スタイルとビュー
リストビュー コントロールは、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 匹のペットのそれぞれに関するさまざまな情報を表示します。 このビューは、Windows Vista での情報の表示方法を示しています。 コントロールのビジュアル スタイルは、SetWindowTheme を使用して「Explorer」のテーマに設定されます。
次のスクリーンショットは、詳細ビューを示しています。
次のスクリーンショットは、アイコン ビューを示しています。
次のスクリーンショットは、リスト ビューを示しています。
次のスクリーンショットは、タイル ビューを示しています。
リストビュー コントロールを作成した後で、ビューの種類を変更できます。 ウィンドウ スタイルを取得および変更するには、GetWindowLong および SetWindowLong 関数を使用します。 現在のビューのウィンドウ スタイルを確認するには、LVS_TYPEMASK 値を使用します。
LVS_ALIGNTOP (既定) または LVS_ALIGNLEFT ウィンドウ スタイルを指定することで、アイテムをアイコンビューまたは小さなアイコンビューに配置する方法を制御できます。
リストビュー コントロールを作成した後で、配置を変更できます。 現在の配置を確認するには、LVS_ALIGNMASK 値を使用します。
追加のウィンドウ スタイルには、ユーザーがラベルを編集できるか、一度に複数のアイテムを選択できるかなど、その他のオプションが用意されています。 完全な一覧については、「リストビュー ウィンドウ スタイル」を参照してください。
拡張 List-View スタイル
拡張リストビュー コントロール スタイルには、チェック ボックス、フラット スクロール バー、グリッド線、ホット トラッキングなどのオプションが用意されています。 完全な一覧については、「拡張リストビュー スタイル」を参照してください。 標準のウィンドウ スタイルと同じ方法で拡張リスト ビュー スタイルにアクセスすることはできません。 拡張スタイルの変更には、GetWindowLong および SetWindowLong 関数は使用しません。
拡張スタイル情報を設定および取得するメッセージは、LVM_SETEXTENDEDLISTVIEWSTYLE および LVM_GETEXTENDEDLISTVIEWSTYLE メッセージの 2 つがあります。 メッセージを明示的に送信する代わりに、対応するマクロである ListView_SetExtendedListViewStyle、ListView_SetExtendedListViewStyleEx および ListView_GetExtendedListViewStyle を使用できます。
仮想リストビュー スタイル
仮想リスト ビューは、LVS_OWNERDATA スタイルを持つ リストビュー コントロールです。 このスタイルを使用すると、所有者がアイテム データの管理負担を負うため、コントロールは何百万ものアイテムを処理できます。 これにより、特定のデータ アクセス方法が既に導入されている大規模な情報データベースで仮想リストビュー コントロールを使用できます。
仮想リストビュー コントロールは、それ自体のアイテム情報をほとんど保持しません。 アイテムの選択とフォーカスの情報を除き、コントロールの所有者はすべてのアイテム情報を管理する必要があります。 その他のプロセスでは、LVN_GETDISPINFO 通知コードを使用して所有者にアイテム情報を要求します。
この種類のリスト コントロールは大規模なデータ セットを対象とします。このため、取得パフォーマンスが高まるように、要求された項目データをキャッシュすることを推奨します。 リスト ビューには、キャッシュの最適化に役立つキャッシュ ヒントメカニズムが用意されています。 ヒントは、LVN_ODCACHEHINT 通知コードの形式で実装されます。
仮想リストビュー コントロールの作成
仮想リストビュー コントロールは、CreateWindow または CreateWindowEx 関数を使用して作成し、dwStyle 関数パラメーターの一部として LVS_OWNERDATA ウィンドウ スタイルを指定します。 LVS_OWNERDATA との動的な切り替えはサポートされていません。
LVS_OWNERDATA スタイルは、LVS_SORTASCENDING または LVS_SORTDESCENDING スタイルを除く他のほとんどのウィンドウ スタイルと組み合わせて使用できます。 すべての仮想リストビュー コントロールは、既定で LVS_AUTOARRANGE スタイルに設定されます。
リストにアイテムを表示できるようにするには、最初に明示的に LVM_SETITEMCOUNT メッセージを送信するか、ListView_SetItemCountEx マクロを使用して送信します。
LVS_OWNERDATA スタイルでは、LVM_ENABLEGROUPVIEW、LVM_GETITEMTEXT、LVM_SETTILEINFO、LVM_MAPIDTOINDEX の各メッセージはサポートされていません。
互換性の問題
アイコン、小さなアイコン、リストおよびレポート ビューの 4 つすべてのリストビュー スタイルは、LVS_OWNERDATA スタイルをサポートします。 LVS_OWNERDATA スタイルがあるリストビュー コントロールは、アイテム固有情報を格納しません。 した場って、アイテムに適用できる有効なアイテム状態フラグは、LVIS_SELECTED および LVIS_FOCUSED のみです。 その他の状態情報は保存されません。 特に、リストビュー コントロールでは、各アイテムの状態やオーバーレイ イメージは維持されません。 ただし、LVM_SETCALLBACKMASK メッセージを送信することで、リストビュー コントロールがアプリケーションに対してこれらのイメージをクエリするようにできます。
ほとんどのリストビュー コントロール メッセージと関連するマクロは完全にサポートされています。 ただし、一部のメッセージには制限がある場合や、LVS_OWNERDATA スタイルを使用する場合はサポートされないメッセージがあります。 次の表は、影響を受けるメッセージをまとめたものです。
| メッセージ | 制限事項 |
|---|---|
| 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 | サポートされません。 アプリケーションが希望の順番でアイテムを表示します。 |
仮想リストビュー コントロール通知コードの処理
LVS_OWNERDATA スタイルのリストビュー コントロールは、他のリストビュー コントロールと同じ通知コードと、LVN_ODCACHEHINT と LVN_ODFINDITEM の 2 つの追加通知コードを送信します。 LVS_OWNERDATA スタイルがあるリストビュー アイテムが送信する最も一般的な通知は以下のとおりです。
| Notification | 説明 |
|---|---|
| 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 構造体には、最も必要とされる可能性の高いアイテムの範囲の包括的な終点を表す iFrom と iTo の 2 つの整数メンバーが含まれます。 所有者は、推奨される範囲内の各アイテムのアイテム情報と共にキャッシュを読み込む準備をする必要があります。
リスト コントロールには、多くの場合、最初のアイテム (オフセット 0) のアイテム情報が必要です。 LVN_ODCACHEHINT 通知コードにアイテム 0 が常に含まれているとは限りませんが、常にキャッシュに含める必要があります。
リスト内の最後のアイテムは、頻繁にアクセスされます。 そのため、所有者は、リストの末尾にアイテムを含む 2 つ目のキャッシュを保持することが必要になる場合があります。 LVN_ODCACHEHINT から要求された範囲をエンド キャッシュに対してチェックして、毎回同じ終了範囲を再読み込みするのではなく、自動的に使用できるようにすることができます。
リスト ビューの作業領域
リストビュー コントロールは作業領域をサポートします。これは、リストビュー コントロールがそのアイテムを配置するために使用する四角形の仮想領域です。 作業領域はウィンドウではなく、表示される境界線を持つことはできません。 既定では、リストビュー コントロールには作業領域がありません。 作業領域を作成することで、アイテムの左、上、または右に空の境界線を作成したり、通常は水平スクロール バーがないときに水平スクロール バーを表示したりできます。
作業領域が作成されると、作業領域内にあるアイテムが作業領域のメンバーになります。 同様に、アイテムが作業領域に移動すると、そのアイテムはその作業領域のメンバーになります。 どの作業領域内にもない項目は、自動的に最初の (インデックス 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 を使用すると、アイテムの表示方法を変更するように作業領域が修正されます。 作業領域の幅 (右から左) をコントロールのクライアント幅より大きくすると、アイテムがその幅でラップされ、水平スクロール バーが表示されます。 作業領域の幅をコントロールのクライアント領域の幅よりも狭くすると、クライアント領域ではなく作業領域内にアイテムがラップされます。 左または上のメンバーを正の値に設定すると、作業領域からアイテムが表示され、コントロールの端とアイテムの間に空のスペースが作成されます。 また、作業領域の幅をコントロールのクライアント幅よりも小さくすることで、コントロールの右端とアイテムの間に空の領域を作成することもできます。
リストビュー イメージ リスト
既定では、リストビュー コントロールにはアイテム イメージは表示されません。 アイテムイメージを表示するには、イメージ リストを作成し、コントロールに関連付ける必要があります。 リストビュー コントロールには、次の 3 つのイメージ リストを含めることができます。
- コントロールがアイコン ビューにあるときに表示されるフルサイズのアイコンを含む画像リスト。
- コントロールが小さいアイコン ビュー、リスト ビュー、またはレポート ビューにあるときに表示される小さなアイコンを含む画像リスト。
- フルサイズまたは小さいアイコンの左側に表示される状態イメージを含む画像リスト。 オンになっているチェックボックスやオフになっているチェックボックスなどの状態イメージを使用して、アプリケーション定義のアイテム状態を示します。 状態イメージは、アイコン ビュー、小さいアイコン ビュー、リスト ビュー、レポート ビューに表示されます。
フルサイズおよび小さいアイコン イメージ リストには、アイテム アイコンの上に透過的に描画されるように設計されたオーバーレイ画像を含めることもできます。
リストビュー コントロールでオーバーレイ イメージを使用するには:
- ImageList_SetOverlayImage 関数を呼び出して、フルサイズおよび小さいアイコン イメージ リストの画像にオーバーレイ画像インデックスを割り当てます。 オーバーレイ イメージは、1 から始まるインデックスによって識別されます。
- ListView_InsertItem または ListView_SetItem マクロを呼び出す際は、アイテムがあるオーバーレイ イメージ インデックスを関連付けることができます。 INDEXTOOVERLAYMASK を指定してアイテムの LVITEM 構造体の状態メンバー内のオーバーレイ イメージ インデックスを指定します。 stateMask メンバーに LVIS_OVERLAYMASK ビットも設定する必要があります。
状態イメージ リストが指定されている場合、リストビュー コントロールは、状態イメージ用の各アイテムのアイコンの左に領域を予約します。
状態イメージをアイテムに関連付けるには、INDEXTOSTATEIMAGEMASK マクロを使用して、LVITEM 構造体の状態メンバーの状態イメージ インデックスを指定します。 インデックスは、コントロールの状態イメージ リスト内のイメージを識別します。 イメージ リスト インデックスは 0 から始まりますが、コントロールは 1 から始まるインデックスを使用して状態イメージを識別します。 状態イメージのインデックスが 0 の場合は、アイテムに状態イメージがないことを示します。
既定では、リストビュー コントロールが破棄されると、割り当てられたイメージ リストが破棄されます。 ただし、リストビュー コントロール に LVS_SHAREIMAGELISTS ウィンドウ スタイルがある場合、アプリケーションは、使用されなくなったイメージ リストを破棄する役割を担います。 このスタイルは、同じイメージ リストを複数のリストビュー コントロールに割り当てる場合に指定する必要があります。そうしないと、複数のコントロールが同じイメージ リストを破棄しようとする場合があります。
リストビュー アイテムとサブアイテム
リストビュー コントロールの各アイテムには、アイコン、ラベル、現在の状態、アプリケーション定義の値があります。 リスト ビュー メッセージを使用すると、アイテムを追加、変更、削除したり、アイテムに関する情報を取得したりできます。
各アイテムには、1 つ以上のサブアイテムを含めることができます。 サブアイテムは、レポート ビューで、アイテムのアイコンとラベルとは別の列に表示される文字列です。 サブアイテムのテキストを指定するには、LVM_SETITEMTEXT または LVM_SETITEM メッセージを使用します。 リストビュー コントロール内のすべてのアイテムには、同じ数のサブアイテムがあります。 サブアイテムの数は、リストビュー コントロールの列数によって決まります。 リストビュー コントロールに列を追加する場合は、関連付けられているサブアイテム インデックスを指定します。
LVITEM 構造体は、リストビュー アイテムまたはサブアイテムを定義します。 iItem メンバーは、アイテムの 0 から始まるインデックスです。 iSubItem メンバーは、サブアイテムの 1 から始まるインデックスで、構造体にアイテムに関する情報が含まれている場合は 0 です。 その他のメンバーでは、項目のテキスト、アイコン、状態、項目データを指定します。 アイテム データは、リストビュー アイテムに関連するアプリケーション定義値です。
リストビュー コントロールにアイテムを追加するには、LVM_INSERTITEM を使用して、LVITEM 構造体のアドレスを指定します。 複数のアイテムを追加する前に、コントロールに最終的に含まれるアイテムの数を指定して、LVM_SETITEMCOUNT メッセージをコントロールに送信します。 このメッセージにより、リストビュー コントロールは、アイテムを毎回追加しなくても、内部データ構造を 1 回だけ再割り当てできます。 LVM_GETITEMCOUNT メッセージを使用すると、リストビュー コントロール内のアイテムの数を確認できます。 リストビュー コントロールに多数のアイテムを追加する場合は、アイテムを追加する前に再描画を無効にしてから、アイテムが追加された後に再描画を有効にすることで、プロセスを高速化できます。 再描画を有効または無効にするには、WM_SETREDRAW メッセージを使用します。
リストビュー アイテムの属性を変更するには、LVM_SETITEM を使用して、LVITEM 構造体のアドレスを指定します。 この構造体の mask メンバーは、変更するアイテム属性を指定します。 たとえば、アイテムまたはサブアイテムのテキストのみを変更するには、LVM_SETITEMTEXT メッセージを使用します。
リストビュー アイテムの情報を取得するには、LVM_GETITEM メッセージを使用して、入力する LVITEM 構造体のアドレスを指定します。 この構造体の mask メンバーは、取得するアイテム属性を指定します。 アイテムまたはサブアイテムのテキストのみを取得するには、LVM_GETITEMTEXT メッセージを使用します。
リストビュー アイテムを削除するには、LVM_DELETEITEM メッセージを使用します。 LVM_DELETEALLITEMS メッセージを使用すると、リストビュー コントロール内のすべてのアイテムを削除できます。
List-View 項目の状態
アイテムの状態は、アイテムの可用性を指定する値、ユーザー アクションを示す値、またはアイテムの状態を反映する値です。 リストビュー コントロールは、ユーザーがアイテムを選択したときなど、一部の状態ビットを変更します。 アプリケーションは、他の状態ビットを変更して、アイテムを無効または非表示にしたり、オーバーレイ イメージまたは状態イメージを指定したりする場合があります。 オーバーレイ イメージと状態イメージの詳細については、「リストビュー イメージ リスト」を参照してください。
アイテムの状態は、LVITEM構造体の状態メンバーが指定します。 アイテムの状態を指定または変更すると、stateMask メンバーは、変更する必要がある状態ビットを指定します。 LVM_SETITEMSTATE メッセージを使用すると、アイテムの状態を変更できます。 アイテムの状態は、アイテムを作成するとき、または LVM_SETITEM メッセージを使用して属性を変更するときに指定できます。 アイテムの現在の状態を確認するには、LVM_GETITEMSTATE または LVM_GETITEM メッセージを使用します。
アイテムのオーバーレイ イメージを設定するには、LVITEM 構造体の stateMask メンバーにLVIS_OVERLAYMASK 値を含める必要があります。また、状態メンバーには、INDEXTOOVERLAYMASK マクロを使用して、左に 8 ビットシフトされたオーバーレイ イメージの 1 から始まるインデックスを含める必要があります。 インデックスを 0 にすると、オーバーレイ イメージを指定できません。
アイテム状態のオーバーレイ イメージを設定するには、LVITEM 構造体の stateMask メンバーにLVIS_STATEIMAGEMASK 値を含める必要があります。また、状態メンバーには、INDEXTOSTATEIMAGEMASKマクロを使用して、左に 12 ビットシフトされた状態イメージの 1 から始まるインデックスを含める必要があります。 インデックスを 0 にすると、状態イメージを指定できません。
コールバック項目とコールバック マスク
通常、リストビュー コントロールはその各アイテムについて、ラベル テキスト、アイテムのアイコン画像のリスト インデックス、アイテムの状態の一連のビット フラグを格納します。 コールバックアイテムを定義したり、コントロールのコールバック マスクを変更して、コントロールではなくアプリケーションがこの情報の一部またはすべてを格納することを示すことができます。 アプリケーションにこの情報の一部が格納されている場合は、コールバックを使用できます。
リストビュー コントロールのコールバック アイテムは、アプリケーションがテキストまたはアイコンインデックス、またはその両方を格納するアイテムです。 LVM_INSERTITEM メッセージを送信してリストビュー コントロールにアイテムを追加するときに、コールバック アイテムを定義できます。 アプリケーションがアイテムまたはサブアイテムのテキストを格納する場合は、アイテムの LVITEM 構造体の pszText メンバーを LPSTR_TEXTCALLBACK に設定します。 アプリケーションがアイテムのアイコン インデックスを格納する場合は、アイテムの LVITEM 構造体の iImage メンバーを I_IMAGECALLBACK に設定します。
リストビュー コントロールのコールバック マスクは、アプリケーションが点在のデータを格納するアイテムの状態を指定するビット フラグ一式です。 コールバック項目の指定が個別の項目に適用されるのに対し、コールバック マスクは、コントロールのすべての項目に適用されます。 コールバック マスクの既定値は 0 で、0 の場合、リストビュー コントロールはすべてのアイテム状態情報を格納します。 リストビュー コントロールを作成してそのアイテムを初期化した後は、LVM_SETCALLBACKMASK メッセージを送信すると、コールバック マスクを変更できます。 現在のコールバック マスクを取得するには、LVM_GETCALLBACKMASK メッセージを送信します。
アプリケーションがコールバック情報を格納するリストビュー アイテムをリストビュー コントロールが表示または並べ替える必要がある場合、コントロールは、コントロールの親ウィンドウに LVN_GETDISPINFO 通知コードを送信します。 このメッセージは、必要な情報のタイプを 含む NMLVDISPINFO 構造体を指定し、取得するアイテムまたはサブアイテムを識別します。 親ウィンドウは、要求されたデータを提供するために LVN_GETDISPINFO を処理する必要があります。
リストビュー コントロールが、テキスト、アイコン、状態情報の変更など、アイテムのコールバック情報の変更を検出した場合、コントロールは LVN_SETDISPINFO 通知コードを送信して変更を通知します。
コールバック アイテムの属性または状態ビットを変更する場合は、LVM_UPDATE メッセージを使用して、コントロールにアイテムの再描画を強制します。 このメッセージは、コントロールに LVS_AUTOARRANGE スタイルがある場合、そのアイテムを配置します。 LVM_REDRAWITEMS メッセージを使用すると、リストビュー コントロールのクライアント領域の対応する部分を無効にすることで、アイテムの範囲を再描画できます。
コールバック アイテムとコールバック マスクを効果的に使用することで、各アイテム属性が 1 つの場所のみで維持されるようにできます。 これを行うと、アプリケーションを簡略化できますが、保存される唯一の領域は、アイテム ラベルとサブアイテム テキストを格納するために必要なメモリです。
リストビュー アイテムの位置
すべてのリスト ビュー アイテムには、メッセージを使用して取得および設定できる位置とサイズがあります。 また、指定した位置にあるアイテム (ある場合) を確認することもできます。 リストビュー アイテムの位置は、スクロール位置によってオフセットされたクライアント座標であるビュー座標で指定されます。
アイテムの位置を取得して設定するには、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 メッセージを使用すると、指定した状態と指定したアイテムへの指定したリレーションシップのあるリストビュー アイテムを検索でいます。 たとえば、指定したアイテムの右側にある次に選択したアイテムを取得できます。
リストビュー列
列は、アイテムとそのサブアイテムをレポート ビューに表示する方法を制御します。 各列にはタイトルと幅があり、特定のサブアイテムに関連付けられています。サブアイテム 0 は、アイテムのアイコンとラベルです。 列の属性は、LVCOLUMN 構造体によって定義されます。
リストビュー コントロールに列を追加するには、LVM_INSERTCOLUMN メッセージを使用します。 列を削除するには、LVM_DELETECOLUMN メッセージを使用します。
Note
リストビュー コントロールの列 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 は左端の列を示します。
リストビューのスクロール位置
LVS_NOSCROLL ウィンドウ スタイルを指定しない限り、リストビュー コントロールをスクロールして、コントロールのクライアント領域に収まらないアイテムを表示できます。 リストビュー コントロールのスクロール位置と関連情報を取得したり、リストビュー コントロールを指定した量でスクロールしたり、リストビュー コントロールをスクロールして指定したリスト アイテムを表示したりすることができます。
アイコン ビューまたは小さいアイコン ビューでは、現在のスクロール位置は、ビューの原点によって定義されます。 ビューの原点は、ビュー座標 (0, 0) に対応するリストビュー コントロールの表示領域を基準とした座標一式です。 現在のビューの原点を取得するには、LVM_GETORIGIN メッセージを使用します。 このメッセージは、アイコンまたは小さなアイコン ビューでのみ使用する必要があります。リスト ビューまたはレポート ビューでエラーが返されます。
リスト ビューまたはレポート ビューでは、現在のスクロール位置は上部のインデックスによって定義されます。 一番上のインデックスは、リストビュー コントロール内の最初に表示されるアイテムのインデックスです。 現在の一番上のインデックスを取得するには、LVM_GETTOPINDEX メッセージを使用します。 このメッセージは、リスト ビューまたはレポート ビューでのみ有効な結果を返します。アイコンビューまたは小さなアイコンビューでゼロを返します。
LVM_GETVIEWRECT メッセージを使用すると、コントロールの表示領域を基準にすると、リストビュー コントロール内のすべてのアイテムの外接矩形を取得できます。
LVM_GETCOUNTPERPAGE メッセージは、リストビュー コントロールの 1 ページに収まるアイテム数を返します。 このメッセージは、リスト ビューとレポート ビューでのみ有効な結果を返します。アイコン ビューと小さいアイコン ビューでは、アイテムの合計数が返されます。
リストビュー コントロールを特定の量スクロールするには、LVM_SCROLL メッセージを使用します。 LVM_ENSUREVISIBLE メッセージを使用すると、必要に応じてリストビュー コントロールをスクロールして、指定したアイテムが確実に表示されるようにすることができます。
リスト ビュー ラベルの編集
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 は編集されたテキストのアドレスです。 新しいラベルを保持する場合は、親ウィンドウがアイテムのラベルを更新する必要があります。
リストビューの色
アプリケーションは、リストビュー コントロールの 3 つの色を取得して設定できます。
| 色 | 色の取得と設定に使用されるメッセージ |
|---|---|
| テキストの色 | LVM_GETTEXTCOLOR、LVM_SETTEXTCOLOR |
| テキストの背景色 | LVM_GETTEXTBKCOLOR、LVM_SETTEXTBKCOLOR |
| ウィンドウの背景色 | LVM_GETBKCOLOR、LVM_SETBKCOLOR |
リストビュー コントロールの外観をより大幅にカスタマイズするには、NM_CUSTOMDRAW (リスト ビュー) を使用するか、ビジュアル スタイルを使用します (「ビジュアル スタイル」および「ビジュアル スタイルの有効化」を参照)。
グループ別のリスト アイテムの配置
リストビュー コントロールのグループ化機能を使用すると、論理的に関連するアイテム一式を視覚的にグループ化できます。 グループは、アイテムのプロパティ、属性、またはその他の特性に基づいて作成できます。 これらのグループは、通常、グループの名前を含む水平ヘッダーによって画面上で区切られます。 次のスクリーン ショットは、グループ化されたアイテムを示しています。
LVGROUP 構造体を使用して、ヘッダーとフッターのテキスト、グループの現在の状態などのグループに関する情報を格納します。 grouping API には、アイテムをグループに追加、ビューにグループを追加、グループ アイテムの並び替え、アイテム サイズやその他情報のグループをクエリすることでグループとグループ要素を管理するメッセージが含まれます。 ListView_SetGroupMetrics と ListView_GetGroupMetrics マクロを使用すると、各グループの表示パラメーターを設定および取得できます。
グループ化は、リスト ビューを除くすべてのビューで使用できます。 LVS_OWNERDATA スタイルを持つコントロールでは使用できません。
詳細については、「リストビュー コントロールの使用」を参照してください。
挿入マーク
挿入マークは、ドラッグされたアイテムが配置される場所をユーザーに示します。 現在、ユーザーがアイテムを [スタート] メニューまたは [Quick Launch] バーにドラッグすると、挿入マークが表示されます。 挿入マークは、オートアレンジに設定されているリストに対しても機能します。 ユーザーが項目をその他の 2 つの項目の間のポイントにドラッグすると、項目の予期される新しい場所に挿入マークが表示されます。 次のスクリーン ショットは、挿入マークを示しています。
insertion mark API 要素を使用すると、ヒット検出を実行するメッセージとフラグを提供し、アイテムごとに挿入マークの場所と外観を指定し、挿入マークの現在のサイズと外観に関する情報をクエリすることで、挿入マークを配置できます。
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示