LVITEMA 構造体 (commctrl.h)

[アーティクル]
08/22/2023

リストビューアイテムの属性を指定または受信します。この構造体は、項目のインデントを有効にする新しいマスク値 (LVIF_INDENT) をサポートするように更新されました。この構造体は 、LV_ITEM 構造体よりも優先されます。

構文

typedef struct tagLVITEMA {
  UINT   mask;
  int    iItem;
  int    iSubItem;
  UINT   state;
  UINT   stateMask;
  LPSTR  pszText;
  int    cchTextMax;
  int    iImage;
  LPARAM lParam;
  int    iIndent;
  int    iGroupId;
  UINT   cColumns;
  PUINT  puColumns;
  int    *piColFmt;
  int    iGroup;
} LVITEMA, *LPLVITEMA;

メンバー

mask

型: UINT

設定するデータを含むこの構造体のメンバー、または要求するメンバーを指定するフラグのセット。このメンバーには、次のフラグを 1 つ以上設定できます。

値	意味
LVIF_COLFMT	Windows Vista 以降。 piColFmt メンバーが有効であるか、設定する必要があります。このフラグを使用する場合、 cColumns メンバーは有効であるか、設定する必要があります。
LVIF_COLUMNS	cColumns メンバーは有効であるか、設定する必要があります。
LVIF_DI_SETITEM	オペレーティングシステムは、要求されたリストアイテム情報を格納し、もう一度要求しないようにする必要があります。このフラグは、 LVN_GETDISPINFO 通知コードでのみ使用されます。
LVIF_GROUPID	iGroupId メンバーが有効であるか、設定する必要があります。 LVM_INSERTITEM メッセージの送信時にこのフラグが設定されていない場合、iGroupId の値はI_GROUPIDCALLBACKと見なされます。
LVIF_IMAGE	iImage メンバーが有効であるか、設定されている必要があります。
LVIF_INDENT	iIndent メンバーは有効であるか、設定する必要があります。
LVIF_NORECOMPUTE	コントロールは、 LVM_GETITEM メッセージを受信した場合、テキスト情報を取得する LVN_GETDISPINFO を生成しません。代わりに、 pszText メンバーには LPSTR_TEXTCALLBACKが含まれます。
LVIF_PARAM	lParam メンバーは有効であるか、設定する必要があります。
LVIF_STATE	状態メンバーが有効であるか、設定する必要があります。
LVIF_TEXT	pszText メンバーが有効であるか、設定する必要があります。

iItem

型: int

この構造体が参照する項目の 0 から始まるインデックス。

iSubItem

型: int

この構造体が参照するサブ項目の 1 から始まるインデックス。この構造体がサブ項目ではなく項目を参照する場合は 0。

state

型: UINT

アイテムの状態、状態イメージ、オーバーレイイメージを示します。 stateMask メンバーは、このメンバーの有効なビットを示します。

このメンバーのビット 0 から 7 には、項目の状態フラグが含まれています。アイテムの状態値を 1 つ以上指定できます。

このメンバーのビット 8 から 11 は、1 ベースのオーバーレイイメージインデックスを指定します。フルサイズのアイコンイメージリストと小さなアイコン画像リストの両方にオーバーレイ画像を含めることができます。オーバーレイ画像は、アイテムのアイコン画像に重ね合わされます。これらのビットが 0 の場合、アイテムにはオーバーレイイメージがありません。これらのビットを分離するには、 LVIS_OVERLAYMASK マスクを使用します。このメンバーのオーバーレイイメージインデックスを設定するには、 INDEXTOOVERLAYMASK マクロを使用する必要があります。イメージリストのオーバーレイイメージは、ImageList_SetOverlayImage 関数で設定されます。

このメンバーのビット 12 から 15 は、状態イメージのインデックスを指定します。状態イメージは、アプリケーション定義の状態を示す項目のアイコンの横に表示されます。これらのビットが 0 の場合、項目には状態イメージがありません。これらのビットを分離するには、 LVIS_STATEIMAGEMASK マスクを使用します。状態イメージインデックスを設定するには、 INDEXTOSTATEIMAGEMASK マクロを使用します。状態イメージインデックスは、描画する必要がある状態イメージリスト内のイメージのインデックスを指定します。状態イメージリストは、LVM_SETIMAGELIST メッセージと共に指定されます。

stateMask

型: UINT

取得または変更する状態メンバーのビットを指定する値。たとえば、このメンバーを LVIS_SELECTED に設定すると、アイテムの選択状態のみが取得されます。

このメンバーを使用すると、最初にすべてのアイテムの状態を取得することなく、1 つ以上のアイテムの状態を変更できます。たとえば、このメンバーを LVIS_SELECTED に設定し 、state を 0 に設定すると、アイテムの選択状態はクリアされますが、他のどの状態も影響を受けなくなります。

すべての状態を取得または変更するには、このメンバーを (UINT)-1 に設定します。

マクロ ListView_SetItemState を使用して、ビットの設定とクリアの両方を行うことができます。

pszText

種類: LPTSTR

構造体で項目属性が指定されている場合、 pszText は、アイテムテキストを含む null で終わる文字列へのポインターです。 LVN_GETDISPINFO通知に応答するときは、次の通知が受信されるまで、このポインターが有効なままであることを確認してください。

構造体が項目属性を受け取る場合、 pszText は項目テキストを受け取るバッファーへのポインターです。リストビューコントロールでは、任意の長さの文字列をアイテムテキストとして格納できますが、最初の 259 TCHARのみが表示されることに注意してください。

pszText の値がLPSTR_TEXTCALLBACK場合、項目はコールバック項目です。コールバックテキストが変更された場合は、 pszText を LPSTR_TEXTCALLBACK に明示的に設定し、 LVM_SETITEMまたはLVM_SETITEMTEXT メッセージを送信して、変更をリストビューコントロールに通知する必要があります。

リストビューコントロールにLVS_SORTASCENDINGまたはLVS_SORTDESCENDINGスタイルがある場合は、pszText をLPSTR_TEXTCALLBACKに設定しないでください。

cchTextMax

型: int

pszText が指すバッファー内の TCHARの数 (終端の NULL を含む)。

このメンバーは、構造体が項目属性を受け取る場合にのみ使用されます。構造体が項目属性を指定する場合は無視されます。たとえば、 cchTextMax は、LVM_SETITEM および LVM_INSERTITEM中は無視されます。 LVN_GETDISPINFOおよびその他の LVN_ 通知中は読み取り専用です。

メモcchTextMax に終端の NULL が含まれる cchTextMaxTCHARを、LVN_通知中に pszText にコピーしないでください。そうしないと、プログラムが失敗する可能性があります。

iImage

型: int

コントロールのイメージリスト内の項目のアイコンのインデックス。これは、大小の両方のイメージリストに適用されます。このメンバーがI_IMAGECALLBACK値の場合、親ウィンドウはインデックスの格納を担当します。この場合、リストビューコントロールは親に LVN_GETDISPINFO 通知コードを送信し、イメージを表示する必要があるときにインデックスを取得します。

lParam

型: LPARAM

アイテムに固有の値。 LVM_SORTITEMS メッセージを使用すると、リストビューコントロールはこの値をアプリケーション定義の比較関数に渡します。また、LVM_FINDITEM メッセージを使用して、指定した lParam 値を持つアイテムのリストビューコントロールを検索することもできます。

iIndent

型: int

バージョン 4.70。アイテムをインデントする画像の幅の数。 1 つのインデントは、項目イメージの幅と等しくなります。そのため、値 1 は 1 つの画像の幅で項目をインデントし、値 2 は 2 つの画像でインデントします。などです。このフィールドはアイテムに対してのみサポートされていることに注意してください。サブ項目のインデントを設定しようとすると、呼び出し元の関数が失敗します。

iGroupId

型: int

バージョン 6.0 項目が属するグループの識別子、または次のいずれかの値。

値	意味
I_GROUPIDCALLBACK	listview コントロールは、親に LVN_GETDISPINFO 通知コードを送信して、グループのインデックスを取得します。
I_GROUPIDNONE	アイテムはグループに属していません。

cColumns

型: UINT

バージョン 6.0 タイルビューでこのアイテムに表示するデータ列 (サブ項目) の数。最大値は 20 です。この値がI_COLUMNSCALLBACK場合、列配列と配列自体 (puColumns) のサイズは、 LVN_GETDISPINFO 通知を送信することによって取得されます。

puColumns

型: PUINT

バージョン 6.0 列インデックスの配列へのポインター。この項目に表示する列と、それらの列の順序を指定します。

piColFmt

型: int*

Windows Vista: 実装されていません。 Windows 7 以降: 拡張タイルビューの各サブ項目の形式を指定する、次のフラグ (単独または組み合わせ) の配列へのポインター。

値	意味
LVCFMT_LINE_BREAK	列を強制的に折り返し、列の次の一覧の先頭に移動します。
LVCFMT_FILL	タイル領域の残りの部分を塗りつぶします。タイトルがある可能性があります。
LVCFMT_WRAP	列の一覧の残りのスペース内で列を折り返すことができます。
LVCFMT_NO_TITLE	サブ項目からタイトルを削除します。
LVCFMT_TILE_PLACEMENTMASK	LVCFMT_LINE_BREAKとLVCFMT_FILLの組み合わせと同じです。

iGroup

型: int

Windows Vista: 項目のグループインデックス。所有者データ/コールバック (複数のグループ内の 1 つの項目) に対してのみ有効です。

解説

LVITEM 構造体は、LVM_GETITEM、LVM_SETITEM、LVM_INSERTITEM、LVM_DELETEITEMなど、複数のメッセージで使用されます。

タイルビューでは、アイコンの右側にアイテム名が表示されます。項目名の下の行に表示する追加のサブ項目 (詳細ビューの列に対応) を指定できます。 puColumns 配列には、表示するサブ項目のインデックスが含まれています。項目名であるサブ項目 0 が既に表示されているため、インデックスは 0 より大きくする必要があります。列情報は、リストアイテムを変更するときに LVTILEINFO 構造体で設定することもできます。

コード例については、「 List-View コントロールの使用」を参照してください。

バージョン 6 Comctl32.dll 再頒布可能ではありませんが、Windows 以降に含まれていることに注意してください。バージョン 6 Comctl32.dll 使用するには、マニフェストで指定します。マニフェストの詳細については、「ビジュアルスタイルの有効化」を参照してください。

注意

commctrl.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして LVITEM を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイルエラーまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件


サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2003 (デスクトップアプリのみ)
Header	commctrl.h

次の方法で共有

LVITEMA 構造体 (commctrl.h)

構文

メンバー

解説

要件

フィードバック

その他のリソース