Tree Control Item States Overview
The latest version of this topic can be found at Tree Control Item States Overview.
Each item in a tree control (CTreeCtrl) has a current state. For example, an item can be selected, disabled, expanded, and so on. For the most part, the tree control automatically sets an item's state to reflect user actions, such as selection of an item. However, you can also set an item's state by using the SetItemState member function and retrieve the current state of an item by using the GetItemState member function. For a complete list of item states, see Tree-View Control Constants in the Windows SDK.
An item's current state is specified by the nState parameter. A tree control might change an item's state to reflect a user action, such as selecting the item or setting the focus to the item. In addition, an application might change an item's state to disable or hide the item or to specify an overlay image or state image.
When you specify or change an item's state, the nStateMask parameter specifies which state bits to set, and the nState parameter contains the new values for those bits. For example, the following example changes the current state of a parent item (specified by hParentItem) in a CTreeCtrl object (m_treeCtrl) to TVIS_EXPANDPARTIAL:
TVITEM curItem;
HTREEITEM hParentItem;
hParentItem = m_TreeCtrl.GetSelectedItem();
//modify the parent item to keep the '+' sign
curItem.mask = TVIF_STATE | TVIF_HANDLE;
curItem.hItem = hParentItem;
curItem.state = TVIS_EXPANDPARTIAL;
curItem.stateMask = TVIS_EXPANDPARTIAL;
m_TreeCtrl.SetItem(&curItem);
Another example of changing the state would be to set an item's overlay image. To accomplish this, nStateMask must include the TVIS_OVERLAYMASK value, and nState must include the one-based index of the overlay image shifted left eight bits by using the INDEXTOOVERLAYMASK macro. The index can be 0 to specify no overlay image. The overlay image must have been added to the tree control's list of overlay images by a previous call to the CImageList::SetOverlayImage function. The function specifies the one-based index of the image to add; this is the index used with the INDEXTOOVERLAYMASK macro. A tree control can have up to four overlay images.
To set an item's state image, nStateMask must include the TVIS_STATEIMAGEMASK value, and nState must include the one-based index of the state image shifted left 12 bits by using the INDEXTOSTATEIMAGEMASK macro. The index can be 0 to specify no state image. For more information about overlay and state images, see Tree Control Image Lists.