TVITEMEX structure

Specifies or receives attributes of a tree-view item. This structure is an enhancement to the TVITEM structure. New applications should use this structure where appropriate.

Syntax

typedef struct tagTVITEMEX {
  UINT      mask;
  HTREEITEM hItem;
  UINT      state;
  UINT      stateMask;
  LPTSTR    pszText;
  int       cchTextMax;
  int       iImage;
  int       iSelectedImage;
  int       cChildren;
  LPARAM    lParam;
  int       iIntegral;
#if (_WIN32_IE >= 0x0600)
  UINT      uStateEx;
  HWND      hwnd;
  int       iExpandedImage;
#endif 
#if (NTDDI_VERSION >= NTDDI_WIN7)
  int       iReserved;
#endif 
} TVITEMEX, *LPTVITEMEX;

Members

mask

Type: UINT

Array of flags that indicate which of the other structure members contain valid data. When this structure is used with the TVM_GETITEM message, the mask member indicates the item attributes to retrieve. If used with the TVM_SETITEM message, the mask indicates the attributes to set. This member can be one or more of the following values:

Value	Meaning
TVIF_CHILDREN	The cChildren member is valid.
TVIF_DI_SETITEM	The tree-view control will retain the supplied information and will not request it again. This flag is valid only when processing the TVN_GETDISPINFO notification.
TVIF_EXPANDEDIMAGE	Version 6.00 and Windows Vista. The iExpandedImage member is valid.
TVIF_HANDLE	The hItem member is valid.
TVIF_IMAGE	The iImage member is valid.
TVIF_INTEGRAL	The iIntegral member is valid.
TVIF_PARAM	The lParam member is valid.
TVIF_SELECTEDIMAGE	The iSelectedImage member is valid.
TVIF_STATE	The state and stateMask members are valid.
TVIF_STATEEX	Version 6.00 and Windows Vista. The uStateEx member is valid.
TVIF_TEXT	The pszText and cchTextMax members are valid.

 

hItem

Type: HTREEITEM

Handle to the item.

state

Type: UINT

Set of bit flags and image list indexes that indicate the item's state. When setting the state of an item, the stateMask member indicates the valid bits of this member. When retrieving the state of an item, this member returns the current state for the bits indicated in the stateMask member. For more information regarding this member, see remarks section.

Bits 0 through 7 of this member contain the item state flags. For a list of possible item state flags, see Tree-View Control Item States.

Bits 8 through 11 of this member specify the one-based overlay image index. The overlay image is superimposed over the item's icon image. If these bits are zero, the item has no overlay image. To isolate these bits, use the TVIS_OVERLAYMASK mask. To set the overlay image index in this member, use the INDEXTOOVERLAYMASK macro. The image list's overlay images are set with the ImageList_SetOverlayImage function.

A state image is displayed next to an item's icon to indicate an application-defined state. Specify the state image list by sending a TVM_SETIMAGELIST message. To set an item's state image, include the TVIS_STATEIMAGEMASK value in The stateMask member of the TVITEM structure. Bits 12 through 15 of the structure's state member specify the index in the state image list of the image to be drawn.

To set the state image index, use INDEXTOSTATEIMAGEMASK. This macro takes an index and sets bits 12 through 15 appropriately. To indicate that the item has no state image, set the index to zero. This convention means that image zero in the state image list cannot be used as a state image. To isolate bits 12 through 15 of The state member, use the TVIS_STATEIMAGEMASK mask.

stateMask

Type: UINT

Bits of the state member that are valid. If you are retrieving an item's state, set the bits of the stateMask member to indicate the bits to be returned in the state member. If you are setting an item's state, set the bits of the stateMask member to indicate the bits of the state member that you want to set. To set or retrieve an item's overlay image index, set the TVIS_OVERLAYMASK bits. To set or retrieve an item's state image index, set the TVIS_STATEIMAGEMASK bits.

pszText

Type: LPTSTR

Pointer to a null-terminated string that contains the item text if the structure specifies item attributes. If this member is the LPSTR_TEXTCALLBACK value, the parent window is responsible for storing the name. In this case, the tree-view control sends the parent window a TVN_GETDISPINFO notification code when it needs the item text for displaying, sorting, or editing and a TVN_SETDISPINFO notification code when the item text changes. If the structure is receiving item attributes, this member is the address of the buffer that receives the item text. Note that although the tree-view control allows any length string to be stored as item text, only the first 260 characters are displayed.

cchTextMax

Type: int

Size of the buffer pointed to by the pszText member, in characters. If this structure is being used to set item attributes, this member is ignored.

iImage

Type: int

Index in the tree-view control's image list of the icon image to use when the item is in the nonselected state. If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the tree-view control sends the parent a TVN_GETDISPINFO notification code to retrieve the index when it needs to display the image.

iSelectedImage

Type: int

Index in the tree-view control's image list of the icon image to use when the item is in the selected state. If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the tree-view control sends the parent a TVN_GETDISPINFO notification code to retrieve the index when it needs to display the image.

cChildren

Type: int

Flag that indicates whether the item has associated child items. This member can be one of the following values:

Value	Meaning
zero	The item has no child items.
one	The item has one or more child items.
I_CHILDRENCALLBACK	The parent window keeps track of whether the item has child items. In this case, when the tree-view control needs to display the item, the control sends the parent a TVN_GETDISPINFO notification code to determine whether the item has child items. If the tree-view control has the TVS_HASBUTTONS style, it uses this member to determine whether to display the button indicating the presence of child items. You can use this member to force the control to display the button even though the item does not have any child items inserted. This allows you to display the button while minimizing the control's memory usage by inserting child items only when the item is visible or expanded.
I_CHILDRENAUTO	Version 6.0 Intended for internal use; not recommended for use in applications. The tree-view control automatically determines whether the item has child items. Note  This flag may not be supported in future versions of Comctl32.dll. Also, this flag is not defined in commctrl.h. Add the following definition to the source files of your application to use the flag: Copy #define I_CHILDRENAUTO (-2)

 

lParam

Type: LPARAM

A value to associate with the item.

iIntegral

Type: int

Height of the item, in multiples of the standard item height (see TVM_SETITEMHEIGHT). For example, setting this member to 2 will give the item twice the standard height. The tree-view control does not draw in the extra area, which appears below the item content, but this space can be used by the application for drawing when using custom draw. Applications that are not using custom draw should set this value to 1, as otherwise the behavior is undefined.

uStateEx

Type: UINT

Internet Explorer 6 and later. One or more (as a bitwise combination) of the following extended states.

Value	Meaning
TVIS_EX_DISABLED	Windows Vista and later. Creates a control that is drawn in gray, that the user cannot interact with.
TVIS_EX_FLAT	Creates a flat item—the item is virtual and is not visible in the tree; instead, its children take its place in the tree hierarchy. This state is valid only when adding an item to the tree-view control.
TVIS_EX_HWND	Creates a separate HWND for the item. This state is valid only when adding an item to the tree-view control.

 

hwnd

Type: HWND

Internet Explorer 6 and later. Not used; must be NULL.

iExpandedImage

Type: int

Internet Explorer 6 and later. Index of the image in the control's image list to display when the item is in the expanded state.

iReserved

Type: int

Reserved member. Do not use.

Requirements

See also

Adding Tree-View Items