TVITEMEXW 结构 (commctrl.h)

项目
08/22/2023

指定或接收树视图项的属性。此结构是 TVITEM 结构的增强。新应用程序应在适当的情况下使用此结构。

语法

typedef struct tagTVITEMEXW {
  UINT      mask;
  HTREEITEM hItem;
  UINT      state;
  UINT      stateMask;
  LPWSTR    pszText;
  int       cchTextMax;
  int       iImage;
  int       iSelectedImage;
  int       cChildren;
  LPARAM    lParam;
  int       iIntegral;
  UINT      uStateEx;
  HWND      hwnd;
  int       iExpandedImage;
  int       iReserved;
} TVITEMEXW, *LPTVITEMEXW;

成员

mask

类型： UINT

标志数组，指示哪些其他结构成员包含有效数据。将此结构与 TVM_GETITEM 消息一起使用时，掩码成员指示要检索的项属性。如果与 TVM_SETITEM 消息一起使用， 则掩码 指示要设置的属性。此成员可以是以下一个或多个值：

值	含义
TVIF_CHILDREN	cChildren 成员有效。
TVIF_DI_SETITEM	树视图控件将保留提供的信息，并且不会再次请求它。仅当处理 TVN_GETDISPINFO 通知时，此标志才有效。
TVIF_EXPANDEDIMAGE	版本 6.00 和 Windows Vista。iExpandedImage 成员有效。
TVIF_HANDLE	hItem 成员有效。
TVIF_IMAGE	iImage 成员有效。
TVIF_INTEGRAL	iIntegral 成员有效。
TVIF_PARAM	lParam 成员有效。
TVIF_SELECTEDIMAGE	iSelectedImage 成员有效。
TVIF_STATE	state 和 stateMask 成员有效。
TVIF_STATEEX	版本 6.00 和 Windows Vista。uStateEx 成员有效。
TVIF_TEXT	pszText 和 cchTextMax 成员有效。

hItem

类型： HTREEITEM

项的句柄。

state

类型： UINT

一组指示项状态的位标志和图像列表索引。设置项的状态时， stateMask 成员指示此成员的有效位。检索项的状态时，此成员返回 stateMask 成员中指示的位的当前状态。有关此成员的详细信息，请参阅备注部分。

此成员的位 0 到 7 包含项状态标志。有关可能的项状态标志的列表，请参阅树视图控件项状态。

此成员的位 8 到 11 指定从 1 开始的覆盖图像索引。覆盖图像叠加在项的图标图像上。如果这些位为零，则该项没有覆盖图像。若要隔离这些位，请使用 TVIS_OVERLAYMASK 掩码。若要在此成员中设置覆盖图像索引，请使用 INDEXTOOVERLAYMASK 宏。图像列表的覆盖图像是使用 ImageList_SetOverlayImage 函数设置的。

状态图像显示在项的图标旁边，以指示应用程序定义的状态。通过发送 TVM_SETIMAGELIST 消息指定状态图像列表。若要设置项的状态图像，请在 TVITEM 结构的 stateMask 成员中包含TVIS_STATEIMAGEMASK值。结构的状态成员的第 12 位到第 15 位指定要绘制的图像的状态图像列表中的索引。

若要设置状态图像索引，请使用 INDEXTOSTATEIMAGEMASK。此宏采用索引并相应地设置位 12 到 15。若要指示该项没有状态图像，请将索引设置为零。此约定意味着状态映像列表中的图像零不能用作状态映像。若要隔离状态成员的位 12 到 15，请使用 TVIS_STATEIMAGEMASK 掩码。

stateMask

类型： UINT

有效的状态成员的位。如果要检索项的状态，请设置 stateMask 成员的位，以指示将在状态成员中返回的位。如果要设置项的状态，请设置 stateMask 成员的位，以指示要设置 的状态 成员的位。若要设置或检索项的覆盖图像索引，请设置 TVIS_OVERLAYMASK 位。若要设置或检索项的状态图像索引，请设置 TVIS_STATEIMAGEMASK 位。

pszText

类型： LPTSTR

指向以 null 结尾的字符串的指针，如果结构指定项属性，则该字符串包含项文本。如果此成员是LPSTR_TEXTCALLBACK值，则父窗口负责存储名称。在这种情况下，树视图控件在需要项文本用于显示、排序或编辑时向父窗口发送 TVN_GETDISPINFO 通知代码，并在项目文本更改时向TVN_SETDISPINFO 通知代码。如果结构正在接收项属性，则此成员是接收项文本的缓冲区的地址。请注意，尽管树视图控件允许将任何长度字符串存储为项文本，但仅显示前 260 个字符。

cchTextMax

类型： int

pszText 成员指向的缓冲区的大小（以字符为单位）。如果使用此结构设置项属性，则忽略此成员。

iImage

类型： int

当项处于未选择状态时要使用的图标图像的树视图控件的图像列表中的索引。如果此成员是I_IMAGECALLBACK值，则父窗口负责存储索引。在这种情况下，树视图控件向父级发送 TVN_GETDISPINFO 通知代码，以在需要显示图像时检索索引。

iSelectedImage

类型： int

树视图控件的图像列表中的索引，该图标图像在项处于选定状态时使用。如果此成员是I_IMAGECALLBACK值，则父窗口负责存储索引。在这种情况下，树视图控件向父级发送 TVN_GETDISPINFO 通知代码，以在需要显示图像时检索索引。

cChildren

类型： int

指示项是否具有关联的子项的标志。此成员可以是以下值之一：

值	含义
零	该项没有子项。
一个	该项具有一个或多个子项。
I_CHILDRENCALLBACK	父窗口跟踪项是否具有子项。在这种情况下，当树视图控件需要显示项时，控件会向父级发送 TVN_GETDISPINFO 通知代码，以确定该项是否具有子项。如果树视图控件具有 TVS_HASBUTTONS 样式，它将使用此成员确定是否显示指示是否存在子项的按钮。可以使用此成员强制控件显示按钮，即使该项未插入任何子项。这允许你显示按钮，同时通过仅在项可见或展开时插入子项来最大程度地减少控件的内存使用量。
I_CHILDRENAUTO	版本 6.0供内部使用;不建议在应用程序中使用。树视图控件自动确定项是否具有子项。注意 Comctl32.dll 的未来版本可能不支持此标志。此外，commctrl.h 中未定义此标志。将以下定义添加到应用程序的源文件以使用标志： `#define I_CHILDRENAUTO (-2)`

lParam

类型： LPARAM

要与项关联的值。

iIntegral

类型： int

项的高度，以标准项高度的倍数 (查看 TVM_SETITEMHEIGHT) 。例如，将此成员设置为 2 将为该项提供两倍的标准高度。树视图控件不会在项目内容下方显示的额外区域进行绘制，但在使用自定义绘图时，应用程序可以使用此空间进行绘制。未使用自定义绘制的应用程序应将此值设置为 1，否则行为未定义。

uStateEx

类型： UINT

Internet Explorer 6 及更高版本。一个或多个 (作为以下扩展状态) 按位组合。

值	含义
TVIS_EX_DISABLED	Windows Vista 及更高版本。创建一个以灰色绘制的控件，用户无法与之交互。
TVIS_EX_FLAT	创建平面项 - 该项是虚拟的，在树中不可见;相反，其子级在树层次结构中占据其位置。仅当将项添加到树视图控件时，此状态才有效。
TVIS_EX_HWND	为项创建单独的 HWND。仅当将项添加到树视图控件时，此状态才有效。

hwnd

类型： HWND

Internet Explorer 6 及更高版本。未使用;必须为 NULL。

iExpandedImage

类型： int

Internet Explorer 6 及更高版本。控件的图像列表中的图像的索引，当项处于展开状态时显示。

iReserved

类型： int

保留成员。请勿使用。

注解

注意

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

要求

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

另请参阅

添加 Tree-View 项

通过

TVITEMEXW 结构 (commctrl.h)

语法

成员

注解

要求

另请参阅

反馈

其他资源