TVITEMA 结构 (commctrl.h)

  • 项目

指定或接收树视图项的属性。 此结构与 TV_ITEM 结构相同，但已重命名为遵循当前命名约定。 新应用程序应使用此结构。

语法

typedef struct tagTVITEMA {
  UINT      mask;
  HTREEITEM hItem;
  UINT      state;
  UINT      stateMask;
  LPSTR     pszText;
  int       cchTextMax;
  int       iImage;
  int       iSelectedImage;
  int       cChildren;
  LPARAM    lParam;
} TVITEMA, *LPTVITEMA;

成员

mask

类型： UINT

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

值 含义
TVIF_CHILDREN
 cChildren 成员有效。
TVIF_DI_SETITEM
 树视图控件将保留提供的信息，并且不会再次请求它。 仅当处理 TVN_GETDISPINFO 通知时，此标志才有效。
TVIF_HANDLE
 hItem 成员有效。
TVIF_IMAGE
 iImage 成员有效。
TVIF_PARAM
 lParam 成员有效。
TVIF_SELECTEDIMAGE
 iSelectedImage 成员有效。
TVIF_STATE
 state 和 stateMask 成员有效。
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

要与项关联的值。

注解

注意

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

要求

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