Win32 API 日本語リファレンス
ホームUI.Controls › LVITEMW

LVITEMW

構造体
サイズx64: 88 バイト / x86: 60 バイト

サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。

フィールド

フィールドサイズx64x86説明
maskLIST_VIEW_ITEM_FLAGS4+0+0

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

意味
LVIF_COLFMT
Windows Vista 以降。 piColFmt メンバーが有効であるか、設定する必要があります。このフラグを使用する場合、cColumns メンバーが有効であるか、設定する必要があります。
LVIF_COLUMNS
cColumns メンバーが有効であるか、設定する必要があります。
LVIF_DI_SETITEM
オペレーティングシステムは、要求されたリスト項目の情報を保存し、再度要求しないようにします。このフラグは LVN_GETDISPINFO 通知コードでのみ使用されます。
LVIF_GROUPID
                    <b>iGroupId</b> メンバーが有効であるか、設定する必要があります。<a href="/windows/desktop/Controls/lvm-insertitem">LVM_INSERTITEM</a> メッセージが送信されたときにこのフラグが設定されていない場合、<b>iGroupId</b> の値は I_GROUPIDCALLBACK と見なされます。
LVIF_IMAGE
iImage メンバーが有効であるか、設定する必要があります。
LVIF_INDENT
iIndent メンバーが有効であるか、設定する必要があります。
LVIF_NORECOMPUTE
コントロールは、LVM_GETITEM メッセージを受け取っても、テキスト情報を取得するための LVN_GETDISPINFO を生成しません。代わりに、pszText メンバーには LPSTR_TEXTCALLBACK が格納されます。
LVIF_PARAM
                    <b>lParam</b> メンバーが有効であるか、設定する必要があります。
LVIF_STATE
state メンバーが有効であるか、設定する必要があります。
LVIF_TEXT
pszText メンバーが有効であるか、設定する必要があります。
iItemINT4+4+4この構造体が参照する項目の、0 から始まるインデックスです。
iSubItemINT4+8+8この構造体が参照するサブ項目の、1 から始まるインデックスです。この構造体がサブ項目ではなく項目を参照する場合は 0 です。
stateLIST_VIEW_ITEM_STATE_FLAGS4+12+12

項目の状態、状態イメージ、およびオーバーレイイメージを示します。 stateMask メンバーは、このメンバーの有効なビットを示します。

このメンバーのビット 0 から 7 には、項目の状態フラグが格納されます。これには、1 つ以上の 項目の状態 の値を指定できます。

このメンバーのビット 8 から 11 は、1 から始まるオーバーレイイメージのインデックスを指定します。フルサイズのアイコンイメージリストと小さいアイコンイメージリストの両方が、オーバーレイイメージを持つことができます。オーバーレイイメージは、項目のアイコンイメージの上に重ねて表示されます。これらのビットが 0 の場合、項目にはオーバーレイイメージがありません。これらのビットを取り出すには、LVIS_OVERLAYMASK マスクを使用します。このメンバーにオーバーレイイメージのインデックスを設定するには、INDEXTOOVERLAYMASK マクロを使用してください。イメージリストのオーバーレイイメージは、ImageList_SetOverlayImage 関数で設定します。

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

stateMaskLIST_VIEW_ITEM_STATE_FLAGS4+16+16
                <b>state</b> メンバーのどのビットを取得または変更するかを指定する値です。たとえば、このメンバーに <a href="/windows/desktop/Controls/list-view-item-states">LVIS_SELECTED</a> を設定すると、項目の選択状態のみが取得されます。 

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

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

ビットの設定とクリアのどちらにも、ListView_SetItemState マクロを使用できます。

pszTextLPWSTR8/4+24+20

この構造体が項目の属性を指定する場合、pszText は項目のテキストを格納した null 終端文字列へのポインターです。LVN_GETDISPINFO 通知に応答するときは、次の通知を受け取るまでこのポインターが有効であり続けるようにしてください。

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

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

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

cchTextMaxINT4+32+24

pszText が指すバッファー内の TCHAR の数です。終端の NULL を含みます。

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

メモ LVN_ 通知の実行中に、cchTextMax 個の TCHAR を超える量を pszText にコピーしないでください (cchTextMax は終端の NULL を含みます)。超えた場合、プログラムが失敗する可能性があります。
iImageINT4+36+28コントロールのイメージリスト内での、項目のアイコンのインデックスです。これは大きいイメージリストと小さいイメージリストの両方に適用されます。このメンバーが I_IMAGECALLBACK 値の場合、インデックスの保持は親ウィンドウが担当します。この場合、リストビューコントロールはイメージを表示する必要が生じたときに、インデックスを取得するために親へ LVN_GETDISPINFO 通知コードを送信します。
lParamLPARAM8/4+40+32項目に固有の値です。LVM_SORTITEMS メッセージを使用する場合、リストビューコントロールはこの値をアプリケーション定義の比較関数に渡します。また、LVM_FINDITEM メッセージを使用して、指定した lParam 値を持つ項目をリストビューコントロールから検索することもできます。
iIndentINT4+48+36バージョン 4.70。項目をインデントするイメージ幅の数です。1 段のインデントは、項目イメージの幅に相当します。したがって、値 1 は項目をイメージ 1 個分の幅だけインデントし、値 2 はイメージ 2 個分インデントします (以下同様)。このフィールドは項目に対してのみサポートされる点に注意してください。サブ項目のインデントを設定しようとすると、呼び出した関数は失敗します。
iGroupIdINT4+52+40

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

意味
I_GROUPIDCALLBACK
リストビューコントロールは、グループのインデックスを取得するために、親へ LVN_GETDISPINFO 通知コードを送信します。
I_GROUPIDNONE
項目はどのグループにも属しません。
cColumnsDWORD4+56+44バージョン 6.0 タイルビューでこの項目に表示するデータ列 (サブ項目) の数です。最大値は 20 です。この値が I_COLUMNSCALLBACK の場合、列配列のサイズと配列そのもの (puColumns) は、LVN_GETDISPINFO 通知を送信することで取得されます。
puColumnsDWORD*8/4+64+48バージョン 6.0 列インデックスの配列へのポインターで、この項目に対してどの列を表示するか、およびそれらの列の順序を指定します。
piColFmtLIST_VIEW_ITEM_COLUMN_FORMAT_FLAGS*8/4+72+52

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

意味
LVCFMT_LINE_BREAK
列を強制的に次の列リストの先頭へ折り返します。
LVCFMT_FILL
タイル領域の残りを埋めます。タイトルを持つ場合があります。
LVCFMT_WRAP
列が属する列リスト内の残りのスペースで、列を折り返せるようにします。
LVCFMT_NO_TITLE
サブ項目からタイトルを削除します。
LVCFMT_TILE_PLACEMENTMASK
LVCFMT_LINE_BREAKLVCFMT_FILL を組み合わせたものと同等です。
iGroupINT4+80+56Windows Vista: 項目のグループインデックスです。オーナーデータ/コールバック (1 つの項目が複数のグループに属する場合) でのみ有効です。

公式ドキュメント

リストビュー項目の属性を指定または受け取ります。この構造体は、項目のインデントを可能にする新しいマスク値 (LVIF_INDENT) をサポートするように更新されました。この構造体は LV_ITEM 構造体に代わるものです。

解説(Remarks)

LVITEM 構造体は、LVM_GETITEMLVM_SETITEMLVM_INSERTITEMLVM_DELETEITEM をはじめとする複数のメッセージで使用されます。

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

コード例については、リストビューコントロールの使用 を参照してください。

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

commctrl.h ヘッダーは、UNICODE プリプロセッサ定数の定義に応じて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして LVITEM を定義します。エンコード中立のエイリアスの使用と、エンコード中立でないコードを混在させると、不一致が生じてコンパイルエラーや実行時エラーの原因となることがあります。詳細については、関数プロトタイプの規則 を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での定義

#include <windows.h>

// LVITEMW  (x64 88 / x86 60 バイト)
typedef struct LVITEMW {
    LIST_VIEW_ITEM_FLAGS mask;
    INT iItem;
    INT iSubItem;
    LIST_VIEW_ITEM_STATE_FLAGS state;
    LIST_VIEW_ITEM_STATE_FLAGS stateMask;
    LPWSTR pszText;
    INT cchTextMax;
    INT iImage;
    LPARAM lParam;
    INT iIndent;
    INT iGroupId;
    DWORD cColumns;
    DWORD* puColumns;
    LIST_VIEW_ITEM_COLUMN_FORMAT_FLAGS* piColFmt;
    INT iGroup;
} LVITEMW;
using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct LVITEMW
{
    public uint mask;
    public int iItem;
    public int iSubItem;
    public uint state;
    public uint stateMask;
    public IntPtr pszText;
    public int cchTextMax;
    public int iImage;
    public IntPtr lParam;
    public int iIndent;
    public int iGroupId;
    public uint cColumns;
    public IntPtr puColumns;
    public IntPtr piColFmt;
    public int iGroup;
}
Imports System.Runtime.InteropServices

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure LVITEMW
    Public mask As UInteger
    Public iItem As Integer
    Public iSubItem As Integer
    Public state As UInteger
    Public stateMask As UInteger
    Public pszText As IntPtr
    Public cchTextMax As Integer
    Public iImage As Integer
    Public lParam As IntPtr
    Public iIndent As Integer
    Public iGroupId As Integer
    Public cColumns As UInteger
    Public puColumns As IntPtr
    Public piColFmt As IntPtr
    Public iGroup As Integer
End Structure
import ctypes
from ctypes import wintypes

class LVITEMW(ctypes.Structure):
    _fields_ = [
        ("mask", wintypes.DWORD),
        ("iItem", ctypes.c_int),
        ("iSubItem", ctypes.c_int),
        ("state", wintypes.DWORD),
        ("stateMask", wintypes.DWORD),
        ("pszText", ctypes.c_void_p),
        ("cchTextMax", ctypes.c_int),
        ("iImage", ctypes.c_int),
        ("lParam", ctypes.c_ssize_t),
        ("iIndent", ctypes.c_int),
        ("iGroupId", ctypes.c_int),
        ("cColumns", wintypes.DWORD),
        ("puColumns", ctypes.c_void_p),
        ("piColFmt", ctypes.c_void_p),
        ("iGroup", ctypes.c_int),
    ]
#[repr(C)]
pub struct LVITEMW {
    pub mask: u32,
    pub iItem: i32,
    pub iSubItem: i32,
    pub state: u32,
    pub stateMask: u32,
    pub pszText: *mut core::ffi::c_void,
    pub cchTextMax: i32,
    pub iImage: i32,
    pub lParam: isize,
    pub iIndent: i32,
    pub iGroupId: i32,
    pub cColumns: u32,
    pub puColumns: *mut core::ffi::c_void,
    pub piColFmt: *mut core::ffi::c_void,
    pub iGroup: i32,
}
import "golang.org/x/sys/windows"

type LVITEMW struct {
	mask uint32
	iItem int32
	iSubItem int32
	state uint32
	stateMask uint32
	pszText uintptr
	cchTextMax int32
	iImage int32
	lParam uintptr
	iIndent int32
	iGroupId int32
	cColumns uint32
	puColumns uintptr
	piColFmt uintptr
	iGroup int32
}
type
  LVITEMW = record
    mask: DWORD;
    iItem: Integer;
    iSubItem: Integer;
    state: DWORD;
    stateMask: DWORD;
    pszText: Pointer;
    cchTextMax: Integer;
    iImage: Integer;
    lParam: NativeInt;
    iIndent: Integer;
    iGroupId: Integer;
    cColumns: DWORD;
    puColumns: Pointer;
    piColFmt: Pointer;
    iGroup: Integer;
  end;
const LVITEMW = extern struct {
    mask: u32,
    iItem: i32,
    iSubItem: i32,
    state: u32,
    stateMask: u32,
    pszText: ?*anyopaque,
    cchTextMax: i32,
    iImage: i32,
    lParam: isize,
    iIndent: i32,
    iGroupId: i32,
    cColumns: u32,
    puColumns: ?*anyopaque,
    piColFmt: ?*anyopaque,
    iGroup: i32,
};
type
  LVITEMW {.bycopy.} = object
    mask: uint32
    iItem: int32
    iSubItem: int32
    state: uint32
    stateMask: uint32
    pszText: pointer
    cchTextMax: int32
    iImage: int32
    lParam: int
    iIndent: int32
    iGroupId: int32
    cColumns: uint32
    puColumns: pointer
    piColFmt: pointer
    iGroup: int32
struct LVITEMW
{
    uint mask;
    int iItem;
    int iSubItem;
    uint state;
    uint stateMask;
    void* pszText;
    int cchTextMax;
    int iImage;
    ptrdiff_t lParam;
    int iIndent;
    int iGroupId;
    uint cColumns;
    void* puColumns;
    void* piColFmt;
    int iGroup;
}

HSP用 定義

HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; LVITEMW サイズ: 60 バイト(x86)
dim st, 15    ; 4byte整数×15(構造体サイズ 60 / 4 切り上げ)
; mask : LIST_VIEW_ITEM_FLAGS (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; iItem : INT (+4, 4byte)  st.1 = 値  /  値 = st.1   (lpoke/lpeek も可)
; iSubItem : INT (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; state : LIST_VIEW_ITEM_STATE_FLAGS (+12, 4byte)  st.3 = 値  /  値 = st.3   (lpoke/lpeek も可)
; stateMask : LIST_VIEW_ITEM_STATE_FLAGS (+16, 4byte)  st.4 = 値  /  値 = st.4   (lpoke/lpeek も可)
; pszText : LPWSTR (+20, 4byte)  st.5 = 値  /  値 = st.5   (lpoke/lpeek も可)
; cchTextMax : INT (+24, 4byte)  st.6 = 値  /  値 = st.6   (lpoke/lpeek も可)
; iImage : INT (+28, 4byte)  st.7 = 値  /  値 = st.7   (lpoke/lpeek も可)
; lParam : LPARAM (+32, 4byte)  st.8 = 値  /  値 = st.8   (lpoke/lpeek も可)
; iIndent : INT (+36, 4byte)  st.9 = 値  /  値 = st.9   (lpoke/lpeek も可)
; iGroupId : INT (+40, 4byte)  st.10 = 値  /  値 = st.10   (lpoke/lpeek も可)
; cColumns : DWORD (+44, 4byte)  st.11 = 値  /  値 = st.11   (lpoke/lpeek も可)
; puColumns : DWORD* (+48, 4byte)  st.12 = 値  /  値 = st.12   (lpoke/lpeek も可)
; piColFmt : LIST_VIEW_ITEM_COLUMN_FORMAT_FLAGS* (+52, 4byte)  st.13 = 値  /  値 = st.13   (lpoke/lpeek も可)
; iGroup : INT (+56, 4byte)  st.14 = 値  /  値 = st.14   (lpoke/lpeek も可)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; LVITEMW サイズ: 88 バイト(x64)
dim st, 22    ; 4byte整数×22(構造体サイズ 88 / 4 切り上げ)
; mask : LIST_VIEW_ITEM_FLAGS (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; iItem : INT (+4, 4byte)  st.1 = 値  /  値 = st.1   (lpoke/lpeek も可)
; iSubItem : INT (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; state : LIST_VIEW_ITEM_STATE_FLAGS (+12, 4byte)  st.3 = 値  /  値 = st.3   (lpoke/lpeek も可)
; stateMask : LIST_VIEW_ITEM_STATE_FLAGS (+16, 4byte)  st.4 = 値  /  値 = st.4   (lpoke/lpeek も可)
; pszText : LPWSTR (+24, 8byte)  qpoke st,24,値 / qpeek(st,24)  ※IronHSPのみ。3.7/3.8は lpoke st,24,下位 : lpoke st,28,上位
; cchTextMax : INT (+32, 4byte)  st.8 = 値  /  値 = st.8   (lpoke/lpeek も可)
; iImage : INT (+36, 4byte)  st.9 = 値  /  値 = st.9   (lpoke/lpeek も可)
; lParam : LPARAM (+40, 8byte)  qpoke st,40,値 / qpeek(st,40)  ※IronHSPのみ。3.7/3.8は lpoke st,40,下位 : lpoke st,44,上位
; iIndent : INT (+48, 4byte)  st.12 = 値  /  値 = st.12   (lpoke/lpeek も可)
; iGroupId : INT (+52, 4byte)  st.13 = 値  /  値 = st.13   (lpoke/lpeek も可)
; cColumns : DWORD (+56, 4byte)  st.14 = 値  /  値 = st.14   (lpoke/lpeek も可)
; puColumns : DWORD* (+64, 8byte)  qpoke st,64,値 / qpeek(st,64)  ※IronHSPのみ。3.7/3.8は lpoke st,64,下位 : lpoke st,68,上位
; piColFmt : LIST_VIEW_ITEM_COLUMN_FORMAT_FLAGS* (+72, 8byte)  qpoke st,72,値 / qpeek(st,72)  ※IronHSPのみ。3.7/3.8は lpoke st,72,下位 : lpoke st,76,上位
; iGroup : INT (+80, 4byte)  st.20 = 値  /  値 = st.20   (lpoke/lpeek も可)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global LVITEMW
    #field int mask
    #field int iItem
    #field int iSubItem
    #field int state
    #field int stateMask
    #field intptr pszText
    #field int cchTextMax
    #field int iImage
    #field intptr lParam
    #field int iIndent
    #field int iGroupId
    #field int cColumns
    #field intptr puColumns
    #field intptr piColFmt
    #field int iGroup
#endstruct

stdim st, LVITEMW        ; NSTRUCT 変数を確保
st->mask = 100
mes "mask=" + st->mask