TVITEM

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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

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.

    Value Description

    TVIF_CHILDREN

    The cChildren member is valid.

    TVIF_HANDLE

    The hItem member is valid.

    TVIF_IMAGE

    The iImage 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_TEXT

    The pszText and cchTextMax members are valid.
  • 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, as shown in the following table.

    Flag Description

    TVIS_BOLD

    The item is bold.

    TVIS_CUT

    The item is selected as part of a cut-and-paste operation. The item is selected as part of a cut-and-paste operation.

    TVIS_DROPHILITED

    The item is selected as a drag-and-drop target.

    TVIS_EXPANDED

    The item's list of child items is currently expanded; that is, the child items are visible. This value applies only to parent items.

    TVIS_EXPANDEDONCE

    The item's list of child items has been expanded at least once. The TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages are not generated for parent items that have this state set in response to a TVM_EXPAND message. Using TVE_COLLAPSE and TVE_COLLAPSERESET with TVM_EXPAND will cause this state to be reset. This value applies only to parent items.

    TVIS_EXPANDPARTIAL

    A partially expanded tree-view item. In this state, some, but not all, of the child items are visible and the parent item's plus symbol is displayed.

    TVIS_SELECTED

    The item is selected. Its appearance depends on whether it has the focus. The item will be drawn using the system colors for selection.

    The following table shows the masks that you must specify in the stateMask member when you set or retrieve an item's overlay image index or state image index. These values can also be used to mask off the state bits that are not of interest.

    Mask Description

    TVIS_OVERLAYMASK

    Mask for the bits used to specify the item's overlay image index.

    TVIS_STATEIMAGEMASK

    Mask for the bits used to specify the item's state image index.

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

    Value Description

    0

    The item has no child items.

    1

    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 message 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.
  • lParam
    Specifies a 32-bit value to associate with the item.

Requirements

Header commctrl.h
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

ImageList_SetOverlayImage
INDEXTOOVERLAYMASK
INDEXTOSTATEIMAGEMASK
TVM_GETITEM
TVM_INSERTITEM
TVM_SETITEM
TVN_GETDISPINFO
TVN_SETDISPINFO
TV_ITEM