リストビューのアイテムの属性を格納します。アイテムの追加や変更、情報の取得などに使用されます。
typedef struct _LVITEM {
UINT mask; // 有効メンバを示すフラグ
int iItem; // アイテムのインデックス
int iSubItem; // サブアイテムインデックス
UINT state; // アイテムの状態・イメージ
UINT stateMask; // state のフラグ
LPTSTR pszText; // アイテムの文字列
int cchTextMax; // pszTextのサイズ
int iImage; // イメージのインデックス
LPARAM lParam; // アイテムの持つ32ビット値
#if (_WIN32_IE >= 0x0300)
int iIndent; // インデント
#endif
#if (_WIN32_IE >= 0x560)
int iGroupId; //
UINT cColumns; // tile view columns
PUINT puColumns; //
#endif
} LVITEM, FAR *LPLVITEM;
※ (_WIN32_IE >= 0x0300) は comctl32.dll Version4.70 以降、 (_WIN32_IE >= 0x560) は comctl32.dll Version 6.0 以降で有効
どのメンバが有効かを表すフラグを指定します。以下の値の組み合わせで指定します。
| 値 | 有効なメンバ |
|---|---|
| 0x0001 (LVIF_TEXT) | pszText |
| 0x0002 (LVIF_IMAGE) | iImage |
| 0x0004 (LVIF_PARAM) | lParam |
| 0x0008 (LVIF_STATE) | state |
| 0x0010 (LVIF_INDENT) | Version 4.70 以降： iIndent |
| 0x0100 (LVIF_GROUPID) | Version 6.0 以降： iGroupID |
| 0x0200 (LVIF_COLUMNS) | Version 6.0 以降： cColumns |
| 0x0800 (LVIF_NORECOMPUTE) | Version 4.70 以降： コントロールは LVM_GETITEM メッセージを受け取ったときに、テキスト情報を取得するのに LVN_GETDISPINFO 通知メッセージを発生させません。代わりに、 pszText メンバに -1 (LPSTR_TEXTCALLBACK) を格納します。 |
| 0x1000 (LVIF_DI_SETITEM) | システムは、要求されたリストアイテムの情報を格納しておき、後で再び情報を求めません。このフラグは LVN_GETDISPINFO 通知メッセージでのみ使用されます。 |
0 から始まるアイテムのインデックスを指定します。
サブアイテムを参照する場合は、 1 から始まるサブアイテムのインデックスを指定します。サブアイテムではなく、アイテムを参照する場合は 0 を指定します。
アイテムの状態、状態イメージ、オーバーレイイメージが格納されます。 stateMask メンバは、このメンバの有効なビットを示します。
ビット 0 〜 7 は、アイテムの状態のフラグを示します。これは以下の値の組み合わせです。
| 値 | 意味 |
|---|---|
| 0x0001 (LVIS_FOCUSED) | アイテムがフォーカスを持ちます。フォーカスを持ったアイテムは周囲が点線で囲まれます。フォーカスを持つことができるアイテムは1つだけです。 |
| 0x0002 (LVIS_SELECTED) | アイテムが選択されています。表示のされ方はシステムカラーに依存します。複数のアイテムが同時に選択されることができます。 |
| 0x0004 (LVIS_CUT) | アイテムはカット・アンド・ペーストの対象としてマークされています。 |
| 0x0008 (LVIS_DROPHILITED) | ドラッグ・アンド・ドロップのターゲットとしてハイライト表示されています。 |
| 0x0020 (LVIS_ACTIVATING) | 現在はサポートされていません。 |
ビット 8 〜 11 は、1から始まるオーバーレイイメージのインデックスを示します。0 のときはオーバーレイイメージを持ちません。大きいアイコンイメージのリストと小さいアイコンイメージのリストはオーバーレイイメージを持つことができます。オーバーレイイメージはアイコンイメージの上に重ねて表示されます。このビットを取り出すには、このメンバの値に 0x0F00 (LVIS_OVERLAYMASK) をAND結合します。オーバーレイイメージを設定するには、インデックスを8ビット左シフトしてからOR結合します。
ビット 12 〜 15 は、状態イメージのインデックスを示します。0 のときは状態イメージを持ちません。状態イメージは、アプリケーション定義の状態を示すのにアイテムアイコンの横に表示されます。このビットを取り出すには、このメンバの値に 0xF000 (LVIS_STATEIMAGEMASK) をAND結合します。状態イメージを設定するには、インデックスを12ビット左シフトしてからOR結合します。
state メンバのどのビットを検索または変更するのかを指定します。（state メンバの説明を参照）
アイテムの状態を操作するにはそれぞれ対応するビットフラグを、オーバーレイイメージのインデックスを操作するには 0x0F00 (LVIS_OVERLAYMASK) を、状態イメージのインデックスを操作するには 0xF000 (LVIS_STATEIMAGEMASK) を組み合わせて指定します。
このメンバは、アイテム状態のすべてを検索することなく1つ以上のアイテムの状態を変更できるようにします。例えば、このメンバに LVIS_SELECTED を指定して state メンバに 0 を指定すると、アイテムは選択されていない状態になりますが、他の状態は変化しません。
すべての状態を検索または変更するには、このメンバに -1 を指定します。
アイテム情報を設定する場合は、アイテムの文字列のアドレスを指定します。アイテム情報を取得する場合は、文字列を受け取るためのバッファのアドレスを指定します。
このメンバの値が -1 (LPSTR_TEXTCALLBACK) である場合は、アイテムはコールバックアイテムです。コールバックテキストが変化する場合には、明示的にこのメンバに -1 (LPSTR_TEXTCALLBACK) を設定して LVM_SETITEM または LVM_SETITEMTEXT メッセージを送信してリストビューコントロールに変化を通知しなければなりません。
リストビューコントロールが LVS_SORTASCENDING または LVS_SORTDESCENDING スタイルを持つ場合は、このメンバに -1 (LPSTR_TEXTCALLBACK) を指定してはいけません。
アイテム情報を取得する場合は、 pszText メンバで示されるバッファのアドレスを指定します。それ以外の場合は、このメンバは無視されます。
イメージリスト中のイメージのインデックスを示します。大きいアイコンイメージのリストと小さいアイコンイメージのリストの両方に対して適用されます。
このメンバに -1 (I_IMAGECALLBACK) を指定した場合は、親ウィンドウにはインデックスを格納しておく責任があります。この場合、コントロールがイメージを表示する必要がある場合には、イメージのインデックスを取得するために、親ウィンドウに LVN_GETDISPINFO 通知メッセージが送られます。
アイテム固有の32ビット値を示します。
Version 4.70 以降： インデントの幅をイメージ幅の数で示します。すなわち、 1 を指定するとアイテムイメージ1つ分の幅でインデントされます。アイテムを設定する場合のみに使用します。サブアイテム設定時にインデントを指定すると失敗します。
Version 6.0 以降： アイテムを受け取るタイルビューの ID が格納されます。
Version 6.0 以降： このアイテムに対して表示されるタイルビューのカラムの数が格納されます。
Version 6.0 以降： カラムのインデックスリストの配列のアドレスを指定します。この配列には cColumns メンバで指定される数のタイルビューのカラムの幅が格納されます。
Windows 95 以降 / Windows NT 3.51 以降
| HSP 変数 | メンバ | ||
|---|---|---|---|
| メンバ名 | オフセット | サイズ | |
| lvitem.0 | mask | 0 | 4 |
| lvitem.1 | iItem | 4 | 4 |
| lvitem.2 | iSubItem | 8 | 4 |
| lvitem.3 | state | 12 | 4 |
| lvitem.4 | stateMask | 16 | 4 |
| lvitem.5 | pszText | 20 | 4 |
| lvitem.6 | cchTextMax | 24 | 4 |
| lvitem.7 | iImage | 28 | 4 |
| lvitem.8 | lParam | 32 | 4 |
| lvitem.9 | iIndent | 36 | 4 |
| lvitem.10 | iGroupId | 40 | 4 |
| lvitem.11 | cColumns | 44 | 4 |
| lvitem.12 | puColumns | 48 | 4 |
state メンバを格納するには
itemstate = (アイテムの状態) iOverlay = (オーバーレイイメージのインデックス) iState = (状態イメージのインデックス) lvitem.3 = itemstate | (iOverlay << 8) | (iState << 12)
state メンバから各値を取り出すには
itemstate = lvitem.3 & 0x00FF iOverlay = (lvitem.3 & 0x0F00) >> 8 iState = (lvitem.3 & 0xF000) >> 12