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

此结构引用的子项的从 1 开始的索引;如果此结构引用项而不是子项，则为零。

state

类型： UINT

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

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

此成员的位 8 到 11 指定基于 1 的覆盖图像索引。 全尺寸图标图像列表和小图标图像列表都可以有覆盖图像。 覆盖图像叠加在项的图标图像上。 如果这些位为零，则该项没有覆盖图像。 若要隔离这些位，请使用 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。

如果 pszText 的值LPSTR_TEXTCALLBACK，则该项是 回调项。 如果回调文本发生更改，则必须将 pszText 显式设置为 LPSTR_TEXTCALLBACK，并通过发送 LVM_SETITEM 或 LVM_SETITEMTEXT 消息通知列表视图控件更改。

如果列表视图控件具有LVS_SORTASCENDING或LVS_SORTDESCENDING样式，请不要将 pszText 设置为 LPSTR_TEXTCALLBACK。

cchTextMax

类型： int

pszText 指向的缓冲区中的TCHAR 数，包括终止 NULL。

仅当结构接收项属性时，才使用此成员。 当结构指定项属性时，将忽略它。 例如，在LVM_SETITEM和LVM_INSERTITEM期间忽略 cchTextMax。 在 LVN_GETDISPINFO和其他LVN_ 通知期间，它是只读的。

注意 在LVN_通知期间，切勿将超过 cchTextMaxTCHAR（其中 cchTextMax 包含终止 NULL）复制到 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