TVITEM

This structure specifies or receives attributes of a tree view item.

At a Glance

Syntax

typedef struct _TVITEM { tvi
UINT mask;
HTREEITEM hItem;
UINT state;
UINT stateMask;
LPSTR pszText;
int cchTextMax;
int iImage;
int iSelectedImage;
int cChildren;
LPARAM lParam;
} TVITEM, FAR *LPTVITEM;

Members

mask

Indicates 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. This member can be one or more of the following values:

hItem

Handle to the item to which this structure refers.

state

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 bits of this member that are valid. When retrieving the state of an item, this member returns the current state for the bits indicated in the stateMask member.

Bits 0 through 7 of this member contain the item state flags.

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, you should use the INDEXTOOVERLAYMASK macro. The image list’s overlay images are set with the ImageList_SetOverlayImage function.

Bits 12 through 15 of this member specify the state image index. The state image is displayed next to an item’s icon to indicate an application-defined state. If these bits are zero, the item has no state image. To isolate these bits, use the TVIS_STATEIMAGEMASK mask. To set the state image index, you should use the INDEXTOSTATEIMAGEMASK macro. The state image index specifies the index of the image in the state image list that should be drawn. The state image list is specified with the TVM_SETIMAGELIST message.

stateMask

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

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 message when it needs the item text for displaying, sorting, or editing and a TVN_SETDISPINFO notification message 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.

cchTextMax

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

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 message to get the index when it needs to display the image.

iSelectedImage

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 message to get the index when it needs to display the image.

cChildren

Indicates whether the item has associated child items. It is one of the following values:

lParam

Specifies a 32-bit value to associate with the item.

See Also

TVM_INSERTITEM, TVM_SETITEM