通过

LVITEMA 结构 （commctrl.h）

  • 项目

指定或接收列表视图项的属性。 此结构已更新，以支持启用项缩进的新掩码值（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

一组标志，指定此结构的成员包含要设置的数据或要请求的成员。 此成员可以设置一个或多个以下标志：

价值 意义
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

此结构引用的项的从零开始的索引。

iSubItem

类型：int

此结构引用的子项的基于一个索引，如果此结构引用项而不是子项，则为零。

state

类型：UINT

指示项的状态、状态图像和覆盖图像。 stateMask 成员指示此成员的有效位。

此成员的位 0 到 7 包含项状态标志。 这可以是一个或多个 项状态 值。

此成员的位 8 到 11 指定基于一个的覆盖图像索引。 全尺寸图标图像列表和小型图标图像列表都可以具有覆盖图像。 覆盖图像叠加在项的图标图像上。 如果这些位为零，则该项没有覆盖图像。 若要隔离这些位，请使用 LVIS_OVERLAYMASK 掩码。 若要在此成员中设置覆盖图像索引，应使用 INDEXTOOVERLAYMASK 宏。 使用 ImageList_SetOverlayImage 函数设置图像列表的覆盖图像。

此成员的位 12 到 15 位指定状态映像索引。 状态图像显示在项的图标旁边，以指示应用程序定义的状态。 如果这些位为零，则该项没有状态图像。 若要隔离这些位，请使用 LVIS_STATEIMAGEMASK 掩码。 若要设置状态图像索引，请使用 INDEXTOSTATEIMAGEMASK 宏。 状态图像索引指定应绘制的状态图像列表中的图像的索引。 状态图像列表使用 LVM_SETIMAGELIST 消息指定。

stateMask

类型：UINT

指定将检索或修改成员 状态 位的值。 例如，将此成员设置为 LVIS_SELECTED 将导致仅检索项目的选择状态。

此成员允许你修改一个或多个项状态，而无需先检索所有项状态。 例如，将此成员设置为 LVIS_SELECTED，将 状态 为零将导致清除项的选择状态，但其他任何状态都不会受到影响。

若要检索或修改所有状态，请将此成员设置为 （UINT）-1。

可以使用宏 ListView_SetItemState 来设置和清除位。

pszText

类型：LPTSTR

如果结构指定项属性，pszText 是指向包含项文本的 null 终止字符串的指针。 响应 LVN_GETDISPINFO 通知时，请确保此指针在收到下一个通知之前保持有效。

如果结构接收项属性，pszText 是指向接收项文本的缓冲区的指针。 请注意，尽管列表视图控件允许将任何长度字符串存储为项文本，但仅显示前 259 TCHAR。

如果LPSTR_TEXTCALLBACK pszText 的值，则该项是 回调项。 如果回调文本发生更改，则必须将 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_通知期间是只读的。

注释 从不复制超过 cchTextMaxTCHARs（其中 cchTextMax 包括终止 NULL）复制到 LVN_pszText 中，否则程序可能会失败。
 

iImage

类型：int

控件图像列表中的项图标的索引。 这同时适用于大型和小型图像列表。 如果此成员是I_IMAGECALLBACK值，则父窗口负责存储索引。 在这种情况下，列表视图控件会向父级发送一个 LVN_GETDISPINFO 通知代码，以在需要显示图像时检索索引。

lParam

类型：LPARAM

特定于项的值。 如果使用 LVM_SORTITEMS 消息，列表视图控件会将此值传递给应用程序定义的比较函数。 还可以使用 LVM_FINDITEM 消息搜索具有指定 lParam 值的项的列表视图控件。

iIndent

类型：int

版本 4.70。 要缩进项的图像宽度数。 单个缩进等于项图像的宽度。 因此，值 1 按一个图像的宽度缩进项，值 2 缩进两个图像等。 请注意，此字段仅支持项。 尝试设置子项缩进将导致调用函数失败。

iGroupId

类型：int

版本 6.0 项所属组的标识符，或以下值之一。

价值 意义
I_GROUPIDCALLBACK
 listview 控件向父级发送 LVN_GETDISPINFO 通知代码，以检索组的索引。
I_GROUPIDNONE
 该项不属于组。

cColumns

类型：UINT

版本 6.0 要在磁贴视图中显示此项的数据列数（子项）。 最大值为 20。 如果此值I_COLUMNSCALLBACK，则通过发送 LVN_GETDISPINFO 通知来获取列数组的大小和数组本身（puColumns）。

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：项的组索引。 仅适用于所有者数据/回调（多个组中的单个项）。

言论

LVITEM 结构用于多个消息，包括 LVM_GETITEM、LVM_SETITEM、LVM_INSERTITEM和 LVM_DELETEITEM。

在磁贴视图中，项名称显示在图标右侧。 可以指定其他子项（对应于详细信息视图中的列），以显示在项名称下方的行上。 puColumns 数组包含要显示的子项的索引。 索引应大于 0，因为已显示项名称的子项 0。 修改列表项时，还可以在 LVTILEINFO 结构中设置列信息。

有关示例代码，请参阅 使用 List-View 控件。

注释 Comctl32.dll 版本 6 不可再发行，但它包含在 Windows 或更高版本中。 若要使用 Comctl32.dll 版本 6，请在清单中指定它。 有关清单的详细信息，请参阅 启用视觉样式。
 

注意

commctrl.h 标头将 LVITEM 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Windows Vista [仅限桌面应用]
支持的最低服务器 Windows Server 2003 [仅限桌面应用]
标头 commctrl.h