Edit

CTreeCtrl Class

  • Article

Provides the functionality of the Windows common tree view control.

Syntax

class CTreeCtrl : public CWnd

Members

Public Constructors

Name Description
CTreeCtrl::CTreeCtrl Constructs a CTreeCtrl object.

Public Methods

Name Description
CTreeCtrl::Create Creates a tree view control and attaches it to a CTreeCtrl object.
CTreeCtrl::CreateDragImage Creates a dragging bitmap for the specified tree view item.
CTreeCtrl::CreateEx Creates a tree control with the specified Windows extended styles and attaches it to a CTreeCtrl object.
CTreeCtrl::DeleteAllItems Deletes all items in a tree view control.
CTreeCtrl::DeleteItem Deletes a new item in a tree view control.
CTreeCtrl::EditLabel Edits a specified tree view item in-place.
CTreeCtrl::EndEditLabelNow Cancels the edit operation on the label of a tree-view item in the current tree-view control.
CTreeCtrl::EnsureVisible Ensures that a tree view item is visible in its tree view control.
CTreeCtrl::Expand Expands, or collapses, the child items of the specified tree view item.
CTreeCtrl::GetBkColor Retrieves the current background color of the control.
CTreeCtrl::GetCheck Retrieves the check state of a tree control item.
CTreeCtrl::GetChildItem Retrieves the child of a specified tree view item.
CTreeCtrl::GetCount Retrieves the number of tree items associated with a tree view control.
CTreeCtrl::GetDropHilightItem Retrieves the target of a drag-and-drop operation.
CTreeCtrl::GetEditControl Retrieves the handle of the edit control used to edit the specified tree view item.
CTreeCtrl::GetExtendedStyle Retrieves the extended styles that the current tree-view control is using.
CTreeCtrl::GetFirstVisibleItem Retrieves the first visible item of the specified tree view item.
CTreeCtrl::GetImageList Retrieves the handle of the image list associated with a tree view control.
CTreeCtrl::GetIndent Retrieves the offset (in pixels) of a tree view item from its parent.
CTreeCtrl::GetInsertMarkColor Retrieves the color used to draw the insertion mark for the tree view.
CTreeCtrl::GetItem Retrieves the attributes of a specified tree view item.
CTreeCtrl::GetItemData Returns the application-specific value associated with an item.
CTreeCtrl::GetItemExpandedImageIndex Retrieves the index of the image to display when the specified item of the current tree-view control is in the expanded state.
CTreeCtrl::GetItemHeight Retrieves the current height of the tree view items.
CTreeCtrl::GetItemImage Retrieves the images associated with an item.
CTreeCtrl::GetItemPartRect Retrieves the bounding rectangle for a specified part of a specified item in the current tree-view control.
CTreeCtrl::GetItemRect Retrieves the bounding rectangle of a tree view item.
CTreeCtrl::GetItemState Returns the state of an item.
CTreeCtrl::GetItemStateEx Retrieves the extended state of the specified item in the current tree-view control.
CTreeCtrl::GetItemText Returns the text of an item.
CTreeCtrl::GetLastVisibleItem Retrieves the last expanded item in the current tree-view control.
CTreeCtrl::GetLineColor Retrieves the current line color for the tree view control.
CTreeCtrl::GetNextItem Retrieves the next tree view item that matches a specified relationship.
CTreeCtrl::GetNextSiblingItem Retrieves the next sibling of the specified tree view item.
CTreeCtrl::GetNextVisibleItem Retrieves the next visible item of the specified tree view item.
CTreeCtrl::GetParentItem Retrieves the parent of the specified tree view item.
CTreeCtrl::GetPrevSiblingItem Retrieves the previous sibling of the specified tree view item.
CTreeCtrl::GetPrevVisibleItem Retrieves the previous visible item of the specified tree view item.
CTreeCtrl::GetRootItem Retrieves the root of the specified tree view item.
CTreeCtrl::GetScrollTime Retrieves the maximum scroll time for the tree view control.
CTreeCtrl::GetSelectedCount Retrieves the number of selected items in the current tree-view control.
CTreeCtrl::GetSelectedItem Retrieves the currently selected tree view item.
CTreeCtrl::GetTextColor Retrieves the current text color of the control.
CTreeCtrl::GetToolTips Retrieves the handle to the child ToolTip control used by a tree view control.
CTreeCtrl::GetVisibleCount Retrieves the number of visible tree items associated with a tree view control.
CTreeCtrl::HitTest Returns the current position of the cursor related to the CTreeCtrl object.
CTreeCtrl::InsertItem Inserts a new item in a tree view control.
CTreeCtrl::ItemHasChildren Returns nonzero if the specified item has child items.
CTreeCtrl::MapAccIdToItem Maps the specified accessibility identifier to the handle to a tree-view item in the current tree-view control.
CTreeCtrl::MapItemToAccID Maps the specified handle to a tree-view item in the current tree-view control to an accessibility identifier.
CTreeCtrl::Select Selects, scrolls into view, or redraws a specified tree view item.
CTreeCtrl::SelectDropTarget Redraws the tree item as the target of a drag-and-drop operation.
CTreeCtrl::SelectItem Selects a specified tree view item.
CTreeCtrl::SelectSetFirstVisible Selects a specified tree view item as the first visible item.
CTreeCtrl::SetAutoscrollInfo Sets the autoscroll rate of the current tree-view control.
CTreeCtrl::SetBkColor Sets the background color of the control.
CTreeCtrl::SetCheck Sets the check state of a tree control item.
CTreeCtrl::SetExtendedStyle Sets the extended styles for the current tree-view control.
CTreeCtrl::SetImageList Sets the handle of the image list associated with a tree view control.
CTreeCtrl::SetIndent Sets the offset (in pixels) of a tree view item from its parent.
CTreeCtrl::SetInsertMark Sets the insertion mark in a tree view control.
CTreeCtrl::SetInsertMarkColor Sets the color used to draw the insertion mark for the tree view.
CTreeCtrl::SetItem Sets the attributes of a specified tree view item.
CTreeCtrl::SetItemData Sets the application-specific value associated with an item.
CTreeCtrl::SetItemExpandedImageIndex Sets the index of the image to display when the specified item of the current tree-view control is in the expanded state.
CTreeCtrl::SetItemHeight Sets the height of the tree view items.
CTreeCtrl::SetItemImage Associates images with an item.
CTreeCtrl::SetItemState Sets the state of an item.
CTreeCtrl::SetItemStateEx Sets the extended state of the specified item in the current tree-view control.
CTreeCtrl::SetItemText Sets the text of an item.
CTreeCtrl::SetLineColor Sets the current line color for the tree view control.
CTreeCtrl::SetScrollTime Sets the maximum scroll time for the tree view control.
CTreeCtrl::SetTextColor Sets the text color of the control.
CTreeCtrl::SetToolTips Sets a tree view control's child ToolTip control.
CTreeCtrl::ShowInfoTip Displays the infotip for the specified item in the current tree-view control.
CTreeCtrl::SortChildren Sorts the children of a given parent item.
CTreeCtrl::SortChildrenCB Sorts the children of a given parent item using an application-defined sort function.

Remarks

A "tree view control" is a window that displays a hierarchical list of items, such as the headings in a document, the entries in an index, or the files and directories on a disk. Each item consists of a label and an optional bitmapped image, and each item can have a list of subitems associated with it. By clicking an item, the user can expand and collapse the associated list of subitems.

This control (and therefore the CTreeCtrl class) is available only to programs running under Windows 98 and Windows NT version 4 and later.

For more information on using CTreeCtrl, see:

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CTreeCtrl

Requirements

Header: afxcmn.h

CTreeCtrl::Create

If you specify the tree control in a dialog box template, or if you are using CTreeView, your tree control is created automatically when the dialog box or view is created.

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parameters

dwStyle
Specifies the tree view control's style. Apply window styles, described in CreateWindow, and any combination of tree view control styles as described in the Windows SDK.

rect
Specifies the tree view control's size and position. It can be either a CRect object or a RECT structure.

pParentWnd
Specifies the tree view control's parent window, usually a CDialog. It must not be NULL.

nID
Specifies the tree view control's ID.

Return Value

Nonzero if initialization was successful; otherwise 0.

Remarks

If you want to create the tree control as a child window of some other window, use the Create member function. If you create the tree control using Create, you must pass it WS_VISIBLE, in addition to other tree view styles.

You construct a CTreeCtrl in two steps. First call the constructor, then call Create, which creates the tree view control and attaches it to the CTreeCtrl object.

To create a tree control with extended window styles, call CreateEx instead of Create.

Example

// Assuming your window has a CTreeCtrl member named m_TreeCtrl,
// you can create the tree control window with a child ID of ID_MYTREE
// using a call like this:

m_TreeCtrl.Create(WS_VISIBLE | WS_TABSTOP | WS_CHILD | WS_BORDER |
                      TVS_HASBUTTONS | TVS_LINESATROOT | TVS_HASLINES |
                      TVS_DISABLEDRAGDROP | TVS_NOTOOLTIPS | TVS_EDITLABELS,
                  CRect(10, 10, 300, 100), this, ID_MYTREE);

// The control will have the appropriate window styles, and the tree
// control styles specified are those most commonly used.

CTreeCtrl::CreateEx

Call this function to create a control (a child window) and associate it with the CTreeCtrl object.

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parameters

dwExStyle
Specifies the extended style of the control being created. For a list of extended Windows styles, see the dwExStyle parameter for CreateWindowEx in the Windows SDK.

dwStyle
Specifies the tree view control's style. Apply window styles, described in CreateWindow, and any combination of tree view control styles as described in the Windows SDK.

rect
A reference to a RECT structure describing the size and position of the window to be created, in client coordinates of pParentWnd.

pParentWnd
A pointer to the window that is the control's parent.

nID
The control's child-window ID.

Return Value

Nonzero if successful otherwise 0.

Remarks

Use CreateEx instead of Create to apply extended Windows styles, specified by the Windows extended style preface WS_EX_.

CTreeCtrl::CreateDragImage

Call this function to create a dragging bitmap for the given item in a tree view control, create an image list for the bitmap, and add the bitmap to the image list.

CImageList* CreateDragImage(HTREEITEM hItem);

Parameters

hItem
Handle of the tree item to be dragged.

Return Value

Pointer to the image list to which the dragging bitmap was added, if successful; otherwise NULL.

Remarks

An application uses the image-list functions to display the image when the item is being dragged.

The CImageList object is permanent, and you must delete it when finished. For example:

HTREEITEM hItem = m_TreeCtrl.GetSelectedItem();

CImageList *pImageList = m_TreeCtrl.CreateDragImage(hItem);

// Do something with the image list.

delete pImageList;

CTreeCtrl::CTreeCtrl

Constructs a CTreeCtrl object.

CTreeCtrl();

CTreeCtrl::DeleteAllItems

Call this function to delete all items from the tree view control.

BOOL DeleteAllItems();

Return Value

Nonzero if successful; otherwise 0.

Example

// The underlying Windows API always returns TRUE
VERIFY(m_TreeCtrl.DeleteAllItems());

CTreeCtrl::DeleteItem

Call this function to delete an item from the tree view control.

BOOL DeleteItem(HTREEITEM hItem);

Parameters

hItem
Handle of the tree item to be deleted. If hitem has the TVI_ROOT value, all items are deleted from the tree view control.

Return Value

Nonzero if successful; otherwise 0.

Example

// Look at all of the root-level items
HTREEITEM hCurrent = m_TreeCtrl.GetChildItem(TVI_ROOT);
while (hCurrent != NULL)
{
   // Get the text for the item. Notice we use TVIF_TEXT because
   // we want to retrieve only the text, but also specify TVIF_HANDLE
   // because we're getting the item by its handle.
   TVITEM item;
   TCHAR szText[1024];
   item.hItem = hCurrent;
   item.mask = TVIF_TEXT | TVIF_HANDLE;
   item.pszText = szText;
   item.cchTextMax = 1024;

   BOOL bWorked = m_TreeCtrl.GetItem(&item);

   // Try to get the next item
   hCurrent = m_TreeCtrl.GetNextItem(hCurrent, TVGN_NEXT);

   // If we successfuly retrieved an item, and the item's text
   // contains a lowercase letter 'e', delete the item.
   if (bWorked && _tcschr(item.pszText, 'e'))
      m_TreeCtrl.DeleteItem(item.hItem);
}

CTreeCtrl::EditLabel

Call this function to begin in-place editing of the specified item's text.

CEdit* EditLabel(HTREEITEM hItem);

Parameters

hItem
Handle of the tree item to be edited.

Return Value

If successful, a pointer to the CEdit object that is used to edit the item text; otherwise NULL.

Remarks

The editing is accomplished by replacing the text of the item with a single-line edit control containing the text.

Example

// Make sure the focus is set to the tree control.
m_TreeCtrl.SetFocus();

// Show the edit control on the label of the selected item.
// The tree control must have the TVS_EDITLABELS style set.
HTREEITEM hSel = m_TreeCtrl.GetSelectedItem();
CEdit *pmyEdit = m_TreeCtrl.EditLabel(hSel);
ASSERT(pmyEdit != NULL);

CTreeCtrl::EndEditLabelNow

Concludes the edit operation on the label of a tree-view item in the current tree-view control.

BOOL EndEditLabelNow(BOOL fCancelWithoutSave);

Parameters

fCancelWithoutSave
[in] TRUE to discard changes to the tree-view item before concluding the edit operation, or FALSE to save changes to the tree-view item before concluding the operation.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method sends the TVM_ENDEDITLABELNOW message, which is described in the Windows SDK.

CTreeCtrl::EnsureVisible

Call this function to ensure that a tree view item is visible.

BOOL EnsureVisible(HTREEITEM hItem);

Parameters

hItem
Handle of the tree item being made visible.

Return Value

Returns TRUE if the system scrolled the items in the tree-view control to ensure that the specified item is visible. Otherwise, the return value is FALSE.

Remarks

If necessary, the function expands the parent item or scrolls the tree view control so that the item is visible.

Example

HTREEITEM hItem = m_TreeCtrl.GetSelectedItem();
// hmyItem is the item that I want to ensure is visible.
HTREEITEM hmyItem = m_TreeCtrl.GetChildItem(hItem);

// Expand the parent, if possible.
HTREEITEM hParent = m_TreeCtrl.GetParentItem(hmyItem);
if (hParent != NULL)
   m_TreeCtrl.Expand(hParent, TVE_EXPAND);

// Ensure the item is visible.
m_TreeCtrl.EnsureVisible(hmyItem);

CTreeCtrl::Expand

Call this function to expand or collapse the list of child items, if any, associated with the given parent item.

BOOL Expand(
    HTREEITEM hItem,
    UINT nCode);

Parameters

hItem
Handle of the tree item being expanded.

nCode
A flag indicating the type of action to be taken. This flag can have one of the following values:

  • TVE_COLLAPSE Collapses the list.

  • TVE_COLLAPSERESET Collapses the list and removes the child items. The TVIS_EXPANDEDONCE state flag is reset. This flag must be used with the TVE_COLLAPSE flag.

  • TVE_EXPAND Expands the list.

  • TVE_TOGGLE Collapses the list if it is currently expanded or expands it if it is currently collapsed.

Return Value

Nonzero if successful; otherwise 0.

Example

See the example for CTreeCtrl::EnsureVisible.

CTreeCtrl::GetBkColor

This member function implements the behavior of the Win32 message TVM_GETBKCOLOR, as described in the Windows SDK.

COLORREF GetBkColor() const;

Return Value

A COLORREF value that represents the current window background color for the control. If this value is -1, the control is using the system window color. In this case, you can use ::GetSysColor(COLOR_WINDOW) to get the current system color that the control is using.

Example

See the example for CTreeCtrl::SetTextColor.

CTreeCtrl::GetCheck

Call this member function to retrieve an item's check state.

BOOL GetCheck(HTREEITEM hItem) const;

Parameters

hItem
The HTREEITEM about which to receive the state information.

Return Value

Nonzero if the tree control item is checked; otherwise 0.

Example

See the example for CTreeCtrl::SetCheck.

CTreeCtrl::GetChildItem

Call this function to retrieve the tree view item that is the child of the item specified by hItem.

HTREEITEM GetChildItem(HTREEITEM hItem) const;

Parameters

hItem
Handle of a tree item.

Return Value

The handle of the child item if successful; otherwise NULL.

Example

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Delete all of the children of hmyItem.
if (m_TreeCtrl.ItemHasChildren(hmyItem))
{
   HTREEITEM hNextItem;
   HTREEITEM hChildItem = m_TreeCtrl.GetChildItem(hmyItem);

   while (hChildItem != NULL)
   {
      hNextItem = m_TreeCtrl.GetNextItem(hChildItem, TVGN_NEXT);
      m_TreeCtrl.DeleteItem(hChildItem);
      hChildItem = hNextItem;
   }
}

CTreeCtrl::GetCount

Call this function to retrieve a count of the items in a tree view control.

UINT GetCount() const;

Return Value

The number of items in the tree view control.

Example

// Delete all of the items from the tree control.
m_TreeCtrl.DeleteAllItems();
ASSERT(m_TreeCtrl.GetCount() == 0);

CTreeCtrl::GetDropHilightItem

Call this function to retrieve the item that is the target of a drag-and-drop operation.

HTREEITEM GetDropHilightItem() const;

Return Value

The handle of the item dropped if successful; otherwise NULL.

Example

// Set the item at the point myPoint as the drop target.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectDropTarget(hItem);
   ASSERT(m_TreeCtrl.GetDropHilightItem() == hItem);
}

CTreeCtrl::GetEditControl

Call this function to retrieve the handle of the edit control being used to edit a tree view item's text.

CEdit* GetEditControl() const;

Return Value

A pointer to the edit control used to edit the item text, if successful; otherwise NULL.

Example

// The string replacing the text in the edit control.
LPCTSTR lpszmyString = _T("New text!");

// Replace the text in the label edit control, if possible.
CEdit *pEdit = m_TreeCtrl.GetEditControl();

if (pEdit != NULL)
{
   pEdit->SetWindowText(lpszmyString);
}

CTreeCtrl::GetExtendedStyle

Retrieves the extended styles that the current tree-view control is using.

DWORD GetExtendedStyle() const;

Return Value

A value that contains a bitwise combination (OR) of the current tree-view control's extended styles. For more information, see Tree-View Control Extended Styles.

Remarks

This method sends the TVM_GETEXTENDEDSTYLE message, which is described in the Windows SDK.

CTreeCtrl::GetFirstVisibleItem

Call this function to retrieve the first visible item of the tree view control.

HTREEITEM GetFirstVisibleItem() const;

Return Value

The handle of the first visible item; otherwise NULL.

Example

See the example for CTreeCtrl::SetCheck.

CTreeCtrl::GetImageList

Call this function to retrieve the handle of the normal or state image list associated with the tree view control.

CImageList* GetImageList(UINT nImageList) const;

Parameters

nImageList
Type of image list to retrieve. The image list can be one of the following values:

  • TVSIL_NORMAL Retrieves the normal image list, which contains the selected and nonselected images for the tree view item.

  • TVSIL_STATE Retrieves the state image list, which contains the images for tree view items that are in a user-defined state.

Return Value

Pointer to the control's image list if successful; otherwise NULL.

Remarks

Each item in a tree view control can have a pair of bitmapped images associated with it. One image is displayed when the item is selected, and the other is displayed when the item is not selected. For example, an item might display an open folder when it is selected and a closed folder when it is not selected.

For more information on image lists, see the CImageList class.

Example

ASSERT(m_TreeCtrl.GetImageList(TVSIL_NORMAL) == NULL);

m_TreeCtrl.SetImageList(&m_TreeImages, TVSIL_NORMAL);
ASSERT(m_TreeCtrl.GetImageList(TVSIL_NORMAL) == &m_TreeImages);

CTreeCtrl::GetIndent

Call this function to retrieve the amount, in pixels, that child items are indented relative to their parent items.

UINT GetIndent() const;

Return Value

The amount of indentation measured in pixels.

Example

// Double the indent.
UINT uIndent = m_TreeCtrl.GetIndent();
m_TreeCtrl.SetIndent(2 * uIndent);

CTreeCtrl::GetInsertMarkColor

This member function implements the behavior of the Win32 message TVM_GETINSERTMARKCOLOR, as described in the Windows SDK.

COLORREF GetInsertMarkColor() const;

Return Value

A COLORREF value that contains the current insertion mark color.

Example

// Use the highliight color for the insert mark color.
COLORREF crColor = ::GetSysColor(COLOR_HIGHLIGHT);
m_TreeCtrl.SetInsertMarkColor(crColor);
ASSERT(m_TreeCtrl.GetInsertMarkColor() == crColor);

CTreeCtrl::GetItem

Call this function to retrieve the attributes of the specified tree view item.

BOOL GetItem(TVITEM* pItem) const;

Parameters

pItem
A pointer to a TVITEM structure, as described in the Windows SDK.

Return Value

Nonzero if successful; otherwise 0.

Example

See the example for CTreeCtrl::DeleteItem.

CTreeCtrl::GetItemData

Call this function to retrieve the application-specific value associated with the specified item.

DWORD_PTR GetItemData(HTREEITEM hItem) const;

Parameters

hItem
Handle of the item whose data is to be retrieved.

Return Value

A pointer-sized application-specific value associated with the item specified by hItem.

Example

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Delete all of the children of hmyItem whose item data is
// not equal to zero.
if (m_TreeCtrl.ItemHasChildren(hmyItem))
{
   HTREEITEM hNextItem;
   HTREEITEM hChildItem = m_TreeCtrl.GetChildItem(hmyItem);

   while (hChildItem != NULL)
   {
      hNextItem = m_TreeCtrl.GetNextItem(hChildItem, TVGN_NEXT);

      if (m_TreeCtrl.GetItemData(hChildItem) != 0)
      {
         m_TreeCtrl.DeleteItem(hChildItem);
      }

      hChildItem = hNextItem;
   }
}

CTreeCtrl::GetItemExpandedImageIndex

Retrieves the index of the image to display when the specified item of the current tree-view control is in the expanded state.

int GetItemExpandedImageIndex(HTREEITEM hItem)const;

Parameters

hItem
[in] Handle to a tree-view control item.

Return Value

The index of the image to display when the specified item is in the expanded state.

Remarks

This method sends the TVM_GETITEM message, which is described in the Windows SDK. That message returns the TVITEMEX structure that describes the tree-view control item, and then this method retrieves the iExpandedImage member from that structure.

CTreeCtrl::GetItemHeight

This member function implements the behavior of the Win32 message TVM_GETITEMHEIGHT, as described in the Windows SDK.

SHORT GetItemHeight() const;

Return Value

The height of the item, in pixels.

Example

// Double the height of the items.
SHORT sHeight = m_TreeCtrl.GetItemHeight();
m_TreeCtrl.SetItemHeight(2 * sHeight);

CTreeCtrl::GetItemImage

Each item in a tree view control can have a pair of bitmapped images associated with it.

BOOL GetItemImage(
    HTREEITEM hItem,
    int& nImage,
    int& nSelectedImage) const;

Parameters

hItem
The handle of the item whose image is to be retrieved.

nImage
An integer that receives the index of the item's image within the tree view control's image list.

nSelectedImage
An integer that receives the index of the item's selected image within the tree view control's image list.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The images appear on the left side of an item's label. One image is displayed when the item is selected, and the other is displayed when the item is not selected. For example, an item might display an open folder when it is selected and a closed folder when it is not selected.

Call this function to retrieve the index of the item's image and its selected image within the tree view control's image list.

Example

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// If the selected image is the same as the nonselected image
// then make the selected image one more than the nonselected image.
if (m_TreeCtrl.ItemHasChildren(hmyItem))
{
   HTREEITEM hItem = m_TreeCtrl.GetChildItem(hmyItem);
   int nImage, nSelectedImage;

   while (hItem != NULL)
   {
      m_TreeCtrl.GetItemImage(hItem, nImage, nSelectedImage);

      if (nImage == nSelectedImage)
      {
         m_TreeCtrl.SetItemImage(hItem, nImage, nImage + 1);
      }

      hItem = m_TreeCtrl.GetNextSiblingItem(hItem);
   }
}

CTreeCtrl::GetItemPartRect

Retrieves the bounding rectangle for a specified part of a specified item in the current tree-view control.

BOOL GetItemPartRect(
    HTREEITEM hItem,
    int nPart,
    LPRECT lpRect)const;

Parameters

hItem
[in] Handle to a tree-view control item.

nPart
[in] Identifier for the part. Must be set to TVGIPR_BUTTON.

lpRect
[out] Pointer to a RECT structure. If this method is successful, the structure receives the rectangle coordinates of the part specified by hItem and nPart.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

Each tree control item is bounded by a graphics rectangle. Whenever a point in that rectangle is clicked, the item is said to be hit. This method returns the largest rectangle such that when a point in the rectangle is clicked, the item identified by the hItem parameter is hit.

This method sends the TVM_GETITEMPARTRECT message, which is described in the Windows SDK. For more information, see the TreeView_GetItemPartRect macro.

Example

The first code example defines a variable, m_treeCtrl, that is used to access the current tree-view control. The code example also defines an unsigned integer and several HTREEITEM variables. These variables are used in the next example.

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

The next code example uses an accessibility identifier and the CTreeCtrl::MapAccIdToItem method to retrieve a handle to the root tree-view item. Then the example uses the handle and the CTreeCtrl::GetItemPartRect method to draw a 3D rectangle around that item. In an earlier section of the code example, which is not shown, we created a tree-view that consists of a root country/region node for the United States, subnodes for the states of Pennsylvania and Washington, and tree items for cities in those states. We used the CTreeCtrl::MapItemToAccID method to associate the root tree-view item with an accessibility identifier.

CRect rect;
HTREEITEM hUS = m_treeCtrl.MapAccIdToItem(accIdUS);
m_treeCtrl.GetItemPartRect(hUS, TVGIPR_BUTTON, &rect);
m_treeCtrl.GetDC()->Draw3dRect(&rect, RGB(255, 0, 0), RGB(0, 0, 255));

CTreeCtrl::GetItemRect

Call this function to retrieve the bounding rectangle for hItem and determine whether it is visible or not.

BOOL GetItemRect(
    HTREEITEM hItem,
    LPRECT lpRect,
    BOOL bTextOnly) const;

Parameters

hItem
The handle of a tree view control item.

lpRect
Pointer to a RECT structure that receives the bounding rectangle. The coordinates are relative to the upper-left corner of the tree view control.

bTextOnly
If this parameter is nonzero, the bounding rectangle includes only the text of the item. Otherwise it includes the entire line that the item occupies in the tree view control.

Return Value

Nonzero if the item is visible, with the bounding rectangle contained in lpRect. Otherwise, 0 with lpRect uninitialized.

Example

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Dump the bounds of hmyItem.
if (hmyItem != NULL)
{
   RECT r;

   m_TreeCtrl.GetItemRect(hmyItem, &r, FALSE);

   TRACE(TEXT("left = %d, top = %d, right = %d, bottom = %d\r\n"),
         r.left,
         r.top,
         r.right,
         r.bottom);
}

CTreeCtrl::GetItemState

Returns the state of the item specified by hItem.

UINT GetItemState(
    HTREEITEM hItem,
    UINT nStateMask) const;

Parameters

hItem
Handle of the item whose state is to be retrieved.

nStateMask
Mask indicating one or more states to be retrieved. For more information on possible values for nStateMask, see the discussion of the state and stateMask members of the TVITEM structure in the Windows SDK.

Return Value

A UINT that holds the C++ bitwise OR operator (|) of the values specified by nStateMask. For information on possible values, see CTreeCtrl::GetItem. To find the value for a specific state, perform a C++ bitwise AND operator (&) f the state value and the return value, as shown in the following example.

Example

// Show all of the visible items in bold.
HTREEITEM hItem = m_TreeCtrl.GetFirstVisibleItem();

while (hItem != NULL)
{
   m_TreeCtrl.SetItemState(hItem, TVIS_BOLD, TVIS_BOLD);
   ASSERT(TVIS_BOLD & m_TreeCtrl.GetItemState(hItem, TVIS_BOLD));
   hItem = m_TreeCtrl.GetNextVisibleItem(hItem);
}

CTreeCtrl::GetItemStateEx

Retrieves the extended state of the specified item in the current tree-view control.

UINT GetItemStateEx(HTREEITEM hItem) const;

Parameters

hItem
[in] Handle to a tree-view control item.

Return Value

The extended state of the item. For more information, see the uStateEx member of the TVITEMEX structure.

Remarks

This method sends the TVM_GETITEM message, which is described in the Windows SDK. That message returns the TVITEMEX structure that describes the tree-view control item, and this method retrieves the uStateEx member from that structure.

CTreeCtrl::GetItemText

Returns the text of the item specified by hItem.

CString GetItemText(HTREEITEM hItem) const;

Parameters

hItem
Handle of the item whose text is to be retrieved.

Return Value

A CString object containing the item's text.

Example

See the example for CTreeCtrl::GetNextItem.

CTreeCtrl::GetLastVisibleItem

Retrieves the last unexpanded node item in the current tree-view control.

HTREEITEM GetLastVisibleItem() const;

Return Value

The handle to the last unexpanded node item if the method is successful; otherwise, NULL.

Remarks

This method sends the TVM_GETNEXTITEM message, which is described in the Windows SDK. For more information, see the TVGN_LASTVISIBLE flag in the flag parameter of that message.

Example

The first code example defines a variable, m_treeCtrl, that is used to access the current tree-view control. The code example also defines an unsigned integer and several HTREEITEM variables. One or more of these variables are used in the next example.

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

The next code example retrieves a handle to the last unexpanded tree-view node item, and then draws a 3D rectangle around that item. In an earlier section of the code example, which is not shown, we created a tree-view that consists of a root country/region node for the United States, subnodes for the states of Pennsylvania and Washington, and tree items for cities in those states.

CRect rect;
HTREEITEM hLast = m_treeCtrl.GetLastVisibleItem();
m_treeCtrl.GetItemPartRect(hLast, TVGIPR_BUTTON, &rect);
m_treeCtrl.GetDC()->Draw3dRect(&rect, RGB(255, 0, 0), RGB(0, 0, 255));

CTreeCtrl::GetLineColor

This member function implements the behavior of the Win32 message TVM_GETLINECOLOR, as described in the Windows SDK.

COLORREF GetLineColor() const;

Return Value

The current line color.

Example

COLORREF cr = m_TreeCtrl.GetLineColor();

CTreeCtrl::GetNextItem

Call this function to retrieve the tree view item that has the specified relationship, indicated by the nCode parameter, to hItem.

HTREEITEM GetNextItem(
    HTREEITEM hItem,
    UINT nCode) const;

Parameters

hItem
Handle of a tree item.

nCode
A flag indicating the type of relation to hItem. This flag can be one of the following values:

  • TVGN_CARET Retrieves the currently selected item.

  • TVGN_CHILD Retrieves the first child item of the item specified by the hItem parameter.

  • TVGN_DROPHILITE Retrieves the item that is the target of a drag-and-drop operation.

  • TVGN_FIRSTVISIBLE Retrieves the first visible item.

  • TVGN_LASTVISIBLE Retrieves the last expanded item in the tree. This does not retrieve the last item visible in the tree-view window.

  • TVGN_NEXT Retrieves the next sibling item.

  • TVGN_NEXTVISIBLE Retrieves the next visible item that follows the specified item.

  • TVGN_PARENT Retrieves the parent of the specified item.

  • TVGN_PREVIOUS Retrieves the previous sibling item.

  • TVGN_PREVIOUSVISIBLE Retrieves the first visible item that precedes the specified item.

  • TVGN_ROOT Retrieves the first child item of the root item of which the specified item is a part.

Return Value

The handle of the next item if successful; otherwise NULL.

Remarks

This function will return NULL if the item being retrieved is the root node of the tree. For example, if you use this message with the TVGN_PARENT flag on a first-level child of the tree view's root node, the message will return NULL.

Example

For an example of using GetNextItem in a loop, see CTreeCtrl::DeleteItem.

// find the currently selected item
HTREEITEM hCurSel = m_TreeCtrl.GetNextItem(TVI_ROOT, TVGN_CARET);

// report it to the user
if (hCurSel == NULL)
{
   AfxMessageBox(_T("There is no selected item"));
}
else
{
   CString str;
   str.Format(_T("The currently selected item is \"%s\""),
              (LPCTSTR)m_TreeCtrl.GetItemText(hCurSel));
   AfxMessageBox((LPCTSTR)str);
}

CTreeCtrl::GetNextSiblingItem

Call this function to retrieve the next sibling of hItem.

HTREEITEM GetNextSiblingItem(HTREEITEM hItem) const;

Parameters

hItem
Handle of a tree item.

Return Value

The handle of the next sibling item; otherwise NULL.

Example

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Show all of the children of hmyItem in bold.
if (m_TreeCtrl.ItemHasChildren(hmyItem))
{
   HTREEITEM hItem = m_TreeCtrl.GetChildItem(hmyItem);

   while (hItem != NULL)
   {
      m_TreeCtrl.SetItemState(hItem, TVIS_BOLD, TVIS_BOLD);
      hItem = m_TreeCtrl.GetNextSiblingItem(hItem);
   }
}

CTreeCtrl::GetNextVisibleItem

Call this function to retrieve the next visible item of hItem.

HTREEITEM GetNextVisibleItem(HTREEITEM hItem) const;

Parameters

hItem
Handle of a tree item.

Return Value

The handle of the next visible item; otherwise NULL.

Example

See the example for CTreeCtrl::SetCheck.

CTreeCtrl::GetParentItem

Call this function to retrieve the parent of hItem.

HTREEITEM GetParentItem(HTREEITEM hItem) const;

Parameters

hItem
Handle of a tree item.

Return Value

The handle of the parent item; otherwise NULL.

Remarks

This function will return NULL if the parent of the specified item is the root node of the tree.

Example

See the example for CTreeCtrl::EnsureVisible.

CTreeCtrl::GetPrevSiblingItem

Call this function to retrieve the previous sibling of hItem.

HTREEITEM GetPrevSiblingItem(HTREEITEM hItem) const;

Parameters

hItem
Handle of a tree item.

Return Value

The handle of the previous sibling; otherwise NULL.

Example

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Show all of the previous siblings of hmyItem in bold.
HTREEITEM hItem = hmyItem;

while (hItem != NULL)
{
   m_TreeCtrl.SetItemState(hItem, TVIS_BOLD, TVIS_BOLD);
   hItem = m_TreeCtrl.GetPrevSiblingItem(hItem);
}

CTreeCtrl::GetPrevVisibleItem

Call this function to retrieve the previous visible item of hItem.

HTREEITEM GetPrevVisibleItem(HTREEITEM hItem) const;

Parameters

hItem
Handle of a tree item.

Return Value

The handle of the previous visible item; otherwise NULL.

Example

HTREEITEM hmyItem = m_TreeCtrl.GetSelectedItem();

// Show all of the previous visible items of hmyItem in bold.
HTREEITEM hItem = hmyItem;

while (hItem != NULL)
{
   m_TreeCtrl.SetItemState(hItem, TVIS_BOLD, TVIS_BOLD);
   hItem = m_TreeCtrl.GetPrevVisibleItem(hItem);
}

CTreeCtrl::GetRootItem

Call this function to retrieve the root item of the tree view control.

HTREEITEM GetRootItem() const;

Return Value

The handle of the root item; otherwise NULL.

Example

See the example for CTreeCtrl::EditLabel.

CTreeCtrl::GetScrollTime

Call this member function to retrieve the maximum scroll time for the tree view control.

UINT GetScrollTime() const;

Return Value

The maximum scroll time, in milliseconds.

Remarks

This member function implements the behavior of the Win32 message TVM_GETSCROLLTIME, as described in the Windows SDK.

CTreeCtrl::GetSelectedCount

Retrieves the number of selected items in the current tree-view control.

UINT GetSelectedCount();

Return Value

The number of selected items.

Remarks

This method sends the TVM_GETSELECTEDCOUNT message, which is described in the Windows SDK.

CTreeCtrl::GetSelectedItem

Call this function to retrieve the currently selected item of the tree view control.

HTREEITEM GetSelectedItem() const;

Return Value

The handle of the selected item; otherwise NULL.

Example

// Expand the selected item and make it visible, if possible.
HTREEITEM hItem = m_TreeCtrl.GetSelectedItem();

if ((hItem != NULL) && m_TreeCtrl.ItemHasChildren(hItem))
{
   m_TreeCtrl.Expand(hItem, TVE_EXPAND);
   m_TreeCtrl.EnsureVisible(hItem);
}

CTreeCtrl::GetTextColor

This member function implements the behavior of the Win32 message TVM_GETTEXTCOLOR, as described in the Windows SDK.

COLORREF GetTextColor() const;

Return Value

A COLORREF value that represents the current text color. If this value is -1, the control is using the system color for the text color.

Example

See the example for CTreeCtrl::SetTextColor.

CTreeCtrl::GetToolTips

This member function implements the behavior of the Win32 message TVM_GETTOOLTIPS, as described in the Windows SDK.

CToolTipCtrl* GetToolTips() const;

Return Value

A pointer to a CToolTipCtrl object to be used by the tree control. If the Create member function uses the style TVS_NOTOOLTIPS, no tooltips are used, and NULL is returned.

Remarks

The MFC implementation of GetToolTips returns a CToolTipCtrl object, which is used by the tree control, rather than a handle to a tooltip control.

Example

// If the tree control does not have a tooltips control,
// then use m_ToolTips as the tooltips for the tree control.
if (m_TreeCtrl.GetToolTips() == NULL)
{
   m_TreeCtrl.SetToolTips(&m_ToolTips);
}

CTreeCtrl::GetVisibleCount

Call this function to retrieve a count of the visible items in a tree view control.

UINT GetVisibleCount() const;

Return Value

The number of visible items in the tree view control; otherwise - 1.

Example

See the example for CTreeCtrl::SetCheck.

CTreeCtrl::HitTest

Call this function to determine the location of the specified point relative to the client area of a tree view control.

HTREEITEM HitTest(
    CPoint pt,
    UINT* pFlags = NULL) const;

HTREEITEM HitTest(TVHITTESTINFO* pHitTestInfo) const;

Parameters

pt
Client coordinates of the point to test.

pFlags
Pointer to an integer that receives information about the results of the hit test. It can be one or more of the values listed under the flags member in the Remarks section.

pHitTestInfo
Address of a TVHITTESTINFO structure that contains the position to hit test and that receives information about the results of the hit test.

Return Value

The handle of the tree view item that occupies the specified point or NULL if no item occupies the point.

Remarks

When this function is called, the pt parameter specifies the coordinates of the point to test. The function returns the handle of the item at the specified point or NULL if no item occupies the point. In addition, the pFlags parameter contains a value that indicates the location of the specified point. Possible values are:

Value Description
TVHT_ABOVE Above the client area.
TVHT_BELOW Below the client area.
TVHT_NOWHERE In the client area, but below the last item.
TVHT_ONITEM On the bitmap or label associated with an item.
TVHT_ONITEMBUTTON On the button associated with an item.
TVHT_ONITEMICON On the bitmap associated with an item.
TVHT_ONITEMINDENT In the indentation associated with an item.
TVHT_ONITEMLABEL On the label (string) associated with an item.
TVHT_ONITEMRIGHT In the area to the right of an item.
TVHT_ONITEMSTATEICON On the state icon for a tree-view item that is in a user-defined state.
TVHT_TOLEFT To the left of the client area.
TVHT_TORIGHT To the right of the client area.

Example

// Select the item that is at the point myPoint.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectItem(hItem);
}

CTreeCtrl::InsertItem

Call this function to insert a new item in a tree view control.

HTREEITEM InsertItem(LPTVINSERTSTRUCT lpInsertStruct);

HTREEITEM InsertItem(
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    int nSelectedImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam,
    HTREEITEM hParent,
    HTREEITEM hInsertAfter);

HTREEITEM InsertItem(
    LPCTSTR lpszItem,
    HTREEITEM hParent = TVI_ROOT,
    HTREEITEM hInsertAfter = TVI_LAST);

HTREEITEM InsertItem(
    LPCTSTR lpszItem,
    int nImage,
    int nSelectedImage,
    HTREEITEM hParent = TVI_ROOT,
    HTREEITEM hInsertAfter = TVI_LAST);

Parameters

lpInsertStruct
A pointer to a TVINSERTSTRUCT that specifies the attributes of the tree view item to be inserted.

nMask
Integer specifying which attributes to set. See the TVITEM structure in the Windows SDK.

lpszItem
Address of a string containing the item's text.

nImage
Index of the item's image in the tree view control's image list.

nSelectedImage
Index of the item's selected image in the tree view control's image list.

nState
Specifies values for the item's states. See Tree View Control Item States in the Windows SDK for a list of appropriate states.

nStateMask
Specifies which states are to be set. See the TVITEM structure in the Windows SDK.

lParam
A pointer-sized application-specific value associated with the item.

hParent
Handle of the inserted item's parent.

hInsertAfter
Handle of the item after which the new item is to be inserted.

Return Value

Handle of the new item if successful; otherwise NULL.

Remarks

The example shows situations in which you might want to use each version of the function when inserting a tree control item.

Example

// Insert a root item using the structure. We must
// initialize a TVINSERTSTRUCT structure and pass its
// address to the call. 

TVINSERTSTRUCT tvInsert;
tvInsert.hParent = NULL;
tvInsert.hInsertAfter = NULL;
tvInsert.item.mask = TVIF_TEXT;
tvInsert.item.pszText = _T("United States");

HTREEITEM hCountry = m_TreeCtrl.InsertItem(&tvInsert);

// Insert subitems of that root. Pennsylvania is
// a state in the United States, so its item will be a child
// of the United States item. We won't set any image or states,
// so we supply only the TVIF_TEXT mask flag. This
// override provides nearly complete control over the
// insertion operation without the tedium of initializing
// a structure. If you're going to add lots of items
// to a tree, you might prefer the structure override
// as it affords you a performance win by allowing you
// to initialize some fields of the structure only once,
// outside of your insertion loop.

HTREEITEM hPA = m_TreeCtrl.InsertItem(TVIF_TEXT,
   _T("Pennsylvania"), 0, 0, 0, 0, 0, hCountry, NULL);

// Insert the "Washington" item and assure that it is
// inserted after the "Pennsylvania" item. This override is 
// more appropriate for conveniently inserting items with 
// images.

HTREEITEM hWA = m_TreeCtrl.InsertItem(_T("Washington"),
   0, 0, hCountry, hPA);

// We'll add some cities under each of the states.
// The override used here is most appropriate
// for inserting text-only items.

m_TreeCtrl.InsertItem(_T("Pittsburgh"), hPA, TVI_SORT);
m_TreeCtrl.InsertItem(_T("Harrisburg"), hPA, TVI_SORT);
m_TreeCtrl.InsertItem(_T("Altoona"), hPA, TVI_SORT);

m_TreeCtrl.InsertItem(_T("Seattle"), hWA, TVI_SORT);
m_TreeCtrl.InsertItem(_T("Kalaloch"), hWA, TVI_SORT);
m_TreeCtrl.InsertItem(_T("Yakima"), hWA, TVI_SORT);

CTreeCtrl::ItemHasChildren

Use this function to determine whether the tree item specified by hItem has child items.

BOOL ItemHasChildren(HTREEITEM hItem) const;

Parameters

hItem
Handle of a tree item.

Return Value

Nonzero if the tree item specified by hItem has child items; 0 if it does not.

Remarks

If so, you can then use CTreeCtrl::GetChildItem to retrieve those child items.

Example

See the example for CTreeCtrl::GetSelectedItem.

CTreeCtrl::MapAccIdToItem

Maps the specified accessibility identifier to the handle of a tree-view item in the current tree-view control.

HTREEITEM MapAccIdToItem(UINT uAccId) const;

Parameters

uAccId
[in] An accessibility identifier for an element in the tree-view item.

Return Value

The handle to a tree-view item (HTREEITEM) that corresponds to the uAccId parameter. For more information, see the hItem member of the TVITEMEX structure.

Remarks

Accessibility aids are applications that help people with disabilities use computers. An accessibility identifier is used by the IAccessible interface to uniquely specify an element in a window. For more information about the IAccessible APIs, see Microsoft Active Accessibility.

This method sends the TVM_MAPACCIDTOHTREEITEM message, which is described in the Windows SDK.

Example

The first code example defines a variable, m_treeCtrl, that is used to access the current tree-view control. The code example also defines an unsigned integer and several HTREEITEM variables. These variables are used in the next example.

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

The next code example uses an accessibility identifier and the CTreeCtrl::MapAccIdToItem method to retrieve a handle to the root tree-view item. The example uses the handle and the CTreeCtrl::GetItemPartRect method to draw a 3D rectangle around that item. In an earlier section of the code example, which is not shown, we created a tree-view that consists of a root country/region node for the United States, subnodes for the states of Pennsylvania and Washington, and tree items for cities in those states. We used the CTreeCtrl::MapItemToAccID method to associate the root tree-view item with an accessibility identifier.

CRect rect;
HTREEITEM hUS = m_treeCtrl.MapAccIdToItem(accIdUS);
m_treeCtrl.GetItemPartRect(hUS, TVGIPR_BUTTON, &rect);
m_treeCtrl.GetDC()->Draw3dRect(&rect, RGB(255, 0, 0), RGB(0, 0, 255));

CTreeCtrl::MapItemToAccID

Maps the specified handle of a tree-view item in the current tree-view control to an accessibility identifier.

UINT MapItemToAccID(HTREEITEM hItem) const;

Parameters

hItem
[in] A handle of a tree-view item in the control. For more information, see the hItem member of the TVITEMEX structure.

Return Value

The accessibility identifier that corresponds to the hItem parameter.

Remarks

Accessibility aids are applications that help people with disabilities use computers. An accessibility identifier is used by the IAccessible interface to uniquely specify an element in a window. For more information about the IAccessible APIs, see Microsoft Active Accessibility.

This method sends the TVM_MAPHTREEITEMTOACCID message, which is described in the Windows SDK.

Example

The first code example defines a variable, m_treeCtrl, that is used to access the current tree-view control. The code example also defines an unsigned integer and several HTREEITEM variables. These variables are used in the next example.

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

The next code example obtains an identification number for a tree-view control item. In an earlier section of the code example, which is not shown, we created a tree-view that consists of a root country/region node for the United States, subnodes for the states of Pennsylvania and Washington, and tree items for cities in those states. This code example obtains a unique identification number for the root country/region node.

// Map an accessibility identifier to the Pennsylvania node.
accIdUS = m_treeCtrl.MapItemToAccId(hCountry);

CTreeCtrl::Select

Call this function to select the given tree view item, scroll the item into view, or redraw the item in the style used to indicate the target of a drag-and-drop operation.

BOOL Select(
    HTREEITEM hItem,
    UINT nCode);

Parameters

hItem
Handle of a tree item.

nCode
The type of action to take. This parameter can be one of the following values:

  • TVGN_CARET Sets the selection to the given item.

  • TVGN_DROPHILITE Redraws the given item in the style used to indicate the target of a drag-and-drop operation.

  • TVGN_FIRSTVISIBLE Scrolls the tree view vertically so that the given item is the first visible item.

Return Value

Nonzero if successful; otherwise 0.

Remarks

If nCode contains the value TVGN_CARET, the parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages. In addition, if the specified item is the child of a collapsed parent item, the parent's list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Example

See the example for CTreeCtrl::HitTest.

CTreeCtrl::SelectDropTarget

Call this function to redraw the item in the style used to indicate the target of a drag-and-drop operation.

BOOL SelectDropTarget(HTREEITEM hItem);

Parameters

hItem
Handle of a tree item.

Return Value

Nonzero if successful; otherwise 0.

Example

// Set the item at the point myPoint as the drop target.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectDropTarget(hItem);
   ASSERT(m_TreeCtrl.GetDropHilightItem() == hItem);
}

CTreeCtrl::SelectItem

Call this function to select the given tree view item.

BOOL SelectItem(HTREEITEM hItem);

Parameters

hItem
Handle of a tree item.

Return Value

Nonzero if successful; otherwise 0.

Remarks

If hItem is NULL, then this function selects no item.

Example

// Select the item that is at the point myPoint.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectItem(hItem);
}

CTreeCtrl::SelectSetFirstVisible

Call this function to scroll the tree view vertically so that the given item is the first visible item.

BOOL SelectSetFirstVisible(HTREEITEM hItem);

Parameters

hItem
Handle of the tree item to be set as the first visible item.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The function sends a message to the window with the TVM_SELECTITEM and TVGN_FIRSTVISIBLE message parameters.

Example

// Select the item at the point myPoint as the first visible item.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SelectSetFirstVisible(hItem);
}

CTreeCtrl::SetAutoscrollInfo

Sets the autoscroll rate of the current tree-view control.

BOOL SetAutoscrollInfo(
    UINT uPixelsPerSec,
    UINT uUpdateTime);

Parameters

uPixelsPerSec
[in] The number of pixels per second to scroll.

uUpdateTime
[in] The time interval between updates of the control.

Return Value

Always returns TRUE.

Remarks

The autoscroll parameters are used to scroll into view an item that is currently not visible. The tree-view control must have the TVS_EX_AUTOHSCROLL extended style, which is described in Tree-View Control Extended Styles.

This method sends the TVM_SETAUTOSCROLLINFO message, which is described in the Windows SDK.

Example

The first code example defines a variable, m_treeCtrl, that is used to access the current tree-view control. The code example also defines an unsigned integer and several HTREEITEM variables. These variables are used in the next example.

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

The next code example sets the autoscroll behavior of the current tree-view control. In an earlier section of the code example, which is not shown, we created a tree-view that consists of a root country/region node for the United States, subnodes for the states of Pennsylvania and Washington, and tree items for cities in those states. We intentionally made the tree-view control narrow so that it must automatically scroll to display the tree item that has the focus. The code example sets the tree-view control to automatically scroll 30 pixels per second every 5 seconds until the tree item is in view.

// Scroll 30 pixels/sec and redraw every 5 seconds.
m_treeCtrl.SetAutoscrollInfo(30, 5);

CTreeCtrl::SetBkColor

This member function implements the behavior of the Win32 message TVM_SETBKCOLOR, as described in the Windows SDK.

COLORREF SetBkColor(COLORREF clr);

Parameters

clr
A COLORREF value that contains the new background color. If this value is -1, the control will revert to using the system color for the background color.

Return Value

A COLORREF value that represents the current text color. If this value is -1, the control is using the system color for the text color.

Example

See the example for CTreeCtrl::SetTextColor.

CTreeCtrl::SetCheck

Call this member function to set the check state for a tree control item.

BOOL SetCheck(
    HTREEITEM hItem,
    BOOL fCheck = TRUE);

Parameters

hItem
The HTREEITEM to receive the check state change.

fCheck
Indicates whether the tree control item is to be checked or unchecked. By default, SetCheck sets the item to be checked.

Return Value

Nonzero if successful; otherwise 0.

Remarks

When the tree control item is checked (fCheck set to TRUE), the item appears with an adjacent checkmark.

Example

UINT uCount = m_TreeCtrl.GetVisibleCount();
HTREEITEM hItem = m_TreeCtrl.GetFirstVisibleItem();

// Toggle the check state of all the visible items.
for (UINT i = 0; i < uCount; i++)
{
   ASSERT(hItem != NULL);
   m_TreeCtrl.SetCheck(hItem, !m_TreeCtrl.GetCheck(hItem));
   hItem = m_TreeCtrl.GetNextVisibleItem(hItem);
}

To use checkboxes, set TVS_CHECKBOXES before populating the tree control.

m_TreeCtrl.ModifyStyle(0, TVS_CHECKBOXES);

HTREEITEM aItem = m_TreeCtrl.InsertItem(_T("AAA"));
m_TreeCtrl.SetCheck(aItem);

CTreeCtrl::SetExtendedStyle

Sets the extended styles for the current tree-view control.

DWORD SetExtendedStyle(
    DWORD dwExMask,
    DWORD dwExStyles);

Parameters

dwExMask
[in] A bitmask that specifies which styles in the current tree-view control are affected by this method. If this parameter is zero, it is ignored and the value of the dwExStyles parameter is assigned to the tree-view control. Specify zero or a bitwise combination (OR) of styles described in Tree-View Control Extended Styles.

dwExStyles
[in] A bitmask that specifies which styles in the current tree-view control to set or clear. To set a combination of styles, specify a bitwise combination (OR) of styles described in Tree-View Control Extended Styles. To clear a set of styles, specify zero.

Return Value

A value that contains the previous extended control styles.

Remarks

This method clears the styles specified in the dwExMask parameter, then sets the styles specified in the dwExStyles parameter. Only the extended styles that correspond to the bits in dwExMask change.

This method sends the TVM_SETEXTENDEDSTYLE message, which is described in the Windows SDK.

Example

The first code example defines a variable, m_treeCtrl, that is used to access the current tree-view control. The code example also defines an unsigned integer and several HTREEITEM variables. These variables are used in the next example.

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

The next code example adds the TVS_EX_AUTOHSCROLL extended style to the current tree-view control. In an earlier section of the code example, which is not shown, we created a tree-view that consists of a root country/region node for the United States, subnodes for the states of Pennsylvania and Washington, and tree items for cities in those states. We intentionally made the tree-view control narrow so that it must automatically scroll to display the tree item that has the focus.

m_treeCtrl.SetExtendedStyle(TVS_EX_AUTOHSCROLL, TVS_EX_AUTOHSCROLL);

CTreeCtrl::SetImageList

Call this function to set the normal or state image list for a tree view control and redraw the control using the new images.

CImageList* SetImageList(
    CImageList* pImageList,
    int nImageListType);

Parameters

pImageList
Pointer to the image list to assign. If pImageList is NULL, all images are removed from the tree view control.

nImageListType
Type of image list to set. The image list can be one of the following values:

  • TVSIL_NORMAL Sets the normal image list, which contains the selected and nonselected images for the tree view item. You must use this state for overlay images.

  • TVSIL_STATE Sets the state image list, which contains the images for tree view items that are in a user-defined state.

Return Value

Pointer to the previous image list, if any; otherwise NULL.

Example

See the example for CTreeCtrl::GetImageList.

CTreeCtrl::SetIndent

Call this function to set the width of indentation for a tree view control and redraw the control to reflect the new width.

void SetIndent(UINT nIndent);

Parameters

nIndent
Width, in pixels, of the indentation. If nIndent is less than the system-defined minimum width, the new width is set to the system-defined minimum.

Example

See the example for CTreeCtrl::GetIndent.

CTreeCtrl::SetInsertMark

This member function implements the behavior of the Win32 message TVM_SETINSERTMARK, as described in the Windows SDK.

BOOL SetInsertMark(
    HTREEITEM hItem,
    BOOL fAfter = TRUE);

Parameters

hItem
HTREEITEM that specifies at which item the insertion mark will be placed. If this argument is NULL, the insertion mark is removed.

fAfter
BOOL value that specifies if the insertion mark is placed before or after the specified item. If this argument is nonzero, the insertion mark will be placed after the item. If this argument is zero, the insertion mark will be placed before the item.

Return Value

Nonzero if successful; otherwise 0.

Example

// Set the insert mark to be before the item at the point myPoint.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SetInsertMark(hItem, FALSE);
}

CTreeCtrl::SetInsertMarkColor

This member function implements the behavior of the Win32 message TVM_SETINSERTMARKCOLOR, as described in the Windows SDK.

COLORREF SetInsertMarkColor(COLORREF clrNew);

Parameters

clrNew
A COLORREF value that contains the new insertion mark color.

Return Value

A COLORREF value that contains the previous insertion mark color.

Example

See the example for CTreeCtrl::GetInsertMarkColor.

CTreeCtrl::SetItem

Call this function to set the attributes of the specified tree view item.

BOOL SetItem(TVITEM* pItem);

BOOL SetItem(
    HTREEITEM hItem,
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    int nSelectedImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam);

Parameters

pItem
A pointer to a TVITEM structure that contains the new item attributes, as described in the Windows SDK.

hItem
Handle of the item whose attributes are to be set. See the hItem member of the TVITEM structure in the Windows SDK.

nMask
Integer specifying which attributes to set. See the mask member of the TVITEM structure.

lpszItem
Address of a string containing the item's text.

nImage
Index of the item's image in the tree view control's image list. See the iImage member of the TVITEM structure.

nSelectedImage
Index of the item's selected image in the tree view control's image list. See the iSelectedImage member of the TVITEM structure.

nState
Specifies values for the item's states. See the State member of the TVITEM structure.

nStateMask
Specifies which states are to be set. See the stateMask member of the TVITEM structure.

lParam
A pointer-sized application-specific value associated with the item.

Return Value

Nonzero if successful; otherwise 0.

Remarks

In the TVITEM structure, the hItem member identifies the item, and the mask member specifies which attributes to set.

If the mask member or the nMask parameter specifies the TVIF_TEXT value, the pszText member or the lpszItem is the address of a null-terminated string and the cchTextMax member is ignored. If mask (or nMask) specifies the TVIF_STATE value, the stateMask member or the nStateMask parameter specifies which item states to change and the state member or nState parameter contains the values for those states.

Example

// Show the item at the point myPoint in bold.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SetItem(hItem, TVIF_STATE, NULL, 0, 0, TVIS_BOLD,
                      TVIS_BOLD, 0);
}

CTreeCtrl::SetItemData

Call this function to set the application-specific value associated with the specified item.

BOOL SetItemData(
    HTREEITEM hItem,
    DWORD_PTR dwData);

Parameters

hItem
Handle of the item whose data is to be retrieved.

dwData
A pointer-sized application-specific value associated with the item specified by hItem.

Return Value

Nonzero if successful; otherwise 0.

Example

CString str;
HTREEITEM hItem;

// Insert 20 items into the tree control making every item's
// data be the handle of the item.
for (int i = 0; i < 20; i++)
{
   str.Format(TEXT("item %d"), i);
   hItem = m_TreeCtrl.InsertItem(str);

   if (hItem != NULL)
   {
      m_TreeCtrl.SetItemData(hItem, (DWORD_PTR)hItem);
   }
}

CTreeCtrl::SetItemExpandedImageIndex

Sets the index of the image to display when the specified item of the current tree-view control is in the expanded state.

BOOL SetItemExpandedImageIndex(
    HTREEITEM hItem,
    int iExpandedImage);

Parameters

hItem
[in] Handle to a tree-view control item.

iExpandedImage
[in] The index of the image to display when the specified item is in the expanded state.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method sends the TVM_SETITEM message, which is described in the Windows SDK. This method assigns the iExpandedImage parameter to the iExpandedImage member of a TVITEMEX structure, and then uses that structure in the message.

Example

The first code example defines a variable, m_treeCtrl, that is used to access the current tree-view control. The code example also defines an unsigned integer and several HTREEITEM variables. These variables are used in the next example.

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

The next code example is a trivial test to determine whether the CTreeCtrl::GetItemExpandedImageIndex method returns the value set by the CTreeCtrl::SetItemExpandedImageIndex method. In an earlier section of the code example, which is not shown, we created a tree-view that consists of a root country/region node for the United States, subnodes for the states of Pennsylvania and Washington, and tree items for cities in those states.

CString str;
CString msg = _T("The set and retrieved item expanded image ")
              _T("indexes are%s equal.");
int nSetItem = 0;
m_treeCtrl.SetItemExpandedImageIndex(hCountry, nSetItem);
int nItem = m_treeCtrl.GetItemExpandedImageIndex(hCountry);
if (nItem == nSetItem)
   str.Format(msg, _T(""));
else
   str.Format(msg, _T(" not"));
AfxMessageBox(str, MB_ICONINFORMATION);

CTreeCtrl::SetItemHeight

This member function implements the behavior of the Win32 message TVM_SETITEMHEIGHT, as described in the Windows SDK.

SHORT SetItemHeight(SHORT cyHeight);

Parameters

cyHeight
Specifies the new height of every item in the tree view, in pixels. If this argument is less than the height of the images, then it will be set to the height of the images. If this argument is not even, it will be rounded down to the nearest even value. If this argument is -1, the control will revert to using its default item height.

Return Value

The previous height of the items, in pixels.

Example

See the example for CTreeCtrl::GetItemHeight.

CTreeCtrl::SetItemImage

Associates images with an item.

BOOL SetItemImage(
    HTREEITEM hItem,
    int nImage,
    int nSelectedImage);

Parameters

hItem
Handle of the item whose image is to be set.

nImage
Index of the item's image in the tree view control's image list.

nSelectedImage
Index of the item's selected image in the tree view control's image list.

Return Value

Nonzero if successful; otherwise 0.

Remarks

Each item in a tree view control can have a pair of bitmapped images associated with it. The images appear on the left side of an item's label. One image is displayed when the item is selected, and the other is displayed when the item is not selected. For example, an item might display an open folder when it is selected and a closed folder when it is not selected.

Call this function to set the index of the item's image and its selected image within the tree view control's image list.

For more information on images, see CImageList.

Example

See the example for CTreeCtrl::GetItemImage.

CTreeCtrl::SetItemState

Sets the state of the item specified by hItem.

BOOL SetItemState(
    HTREEITEM hItem,
    UINT nState,
    UINT nStateMask);

Parameters

hItem
Handle of the item whose state is to be set.

nState
Specifies new states for the item.

nStateMask
Specifies which states are to be changed.

Return Value

Nonzero if successful; otherwise 0.

Remarks

For information on states, see CTreeCtrl::GetItem.

Example

See the example for CTreeCtrl::GetItemState.

CTreeCtrl::SetItemStateEx

Sets the extended state of the specified item in the current tree-view control.

BOOL SetItemStateEx(
    HTREEITEM hItem,
    UINT uStateEx);

Parameters

hItem
[in] Handle to a tree-view control item.

uStateEx
[in] The extended state of the item. For more information, see the uStateEx member of the TVITEMEX structure.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method sends the TVM_SETITEM message, which is described in the Windows SDK. This method assigns the uStateEx parameter to the uStateEx member of a TVITEMEX structure, and then uses that structure in the message.

Example

The first code example defines a variable, m_treeCtrl, that is used to access the current tree-view control. The code example also defines an unsigned integer and several HTREEITEM variables. These variables are used in the next example.

public:
// Variable to access tree control.
CTreeCtrl m_treeCtrl;
// Variable to access splitbutton control.
CSplitButton m_splitbutton;
// Accessibility identifier
UINT accIdUS;
// HTREEITEMs
HTREEITEM hCountry;
HTREEITEM hPA;
HTREEITEM hWA;

The next code example sets a tree-view item to disabled state. In an earlier section of the code example, which is not shown, we created a tree-view that consists of a root country/region node for the United States, subnodes for the states of Pennsylvania and Washington, and tree items for cities in those states. This code example sets the Pennsylvania node to disabled state.

// Disable the Pennsylvania node.
m_treeCtrl.SetItemStateEx(hPA, TVIS_EX_DISABLED);

CTreeCtrl::SetItemText

Sets the text of the item specified by hItem.

BOOL SetItemText(
    HTREEITEM hItem,
    LPCTSTR lpszItem);

Parameters

hItem
Handle of the item whose text is to be set.

lpszItem
Address of a string containing the new text for the item

Return Value

Nonzero if successful; otherwise 0.

Example

// Clear the text of the item at point myPoint.
UINT uFlags;
HTREEITEM hItem = m_TreeCtrl.HitTest(myPoint, &uFlags);

if ((hItem != NULL) && (TVHT_ONITEM & uFlags))
{
   m_TreeCtrl.SetItemText(hItem, NULL);
}

CTreeCtrl::SetLineColor

Call this member function to set the current line color for the tree view control.

COLORREF SetLineColor(COLORREF clrNew = CLR_DEFAULT);

Parameters

clrNew
The new line color.

Return Value

The previous line color.

Remarks

This member function implements the behavior of the Win32 message TVM_SETLINECOLOR, as described in the Windows SDK.

Example

COLORREF clrPrev = m_TreeCtrl.SetLineColor(RGB(255, 0, 0));

CTreeCtrl::SetScrollTime

Call this member function to set the maximum scroll time for the tree view control.

UINT SetScrollTime(UINT uScrollTime);

Parameters

uScrollTime
The new maximum scroll time, in milliseconds. If this value is less than 100, it will be rounded up to 100.

Return Value

The previous maximum scroll time, in milliseconds.

Remarks

This member function implements the behavior of the Win32 message TVM_SETSCROLLTIME, as described in the Windows SDK.

CTreeCtrl::SetTextColor

This member function implements the behavior of the Win32 message TVM_SETTEXTCOLOR, as described in the Windows SDK.

COLORREF SetTextColor(COLORREF clr);

Parameters

clr
A COLORREF value that contains the new text color. If this argument is -1, the control will revert to using the system color for the text color.

Return Value

A COLORREF value that represents the previous text color. If this value is -1, the control was using the system color for the text color.

Example

// change text color to white and background to dark blue
m_TreeCtrl.SetTextColor(RGB(255, 255, 255));
ASSERT(m_TreeCtrl.GetTextColor() == RGB(255, 255, 255));
m_TreeCtrl.SetBkColor(RGB(0, 0, 128));
ASSERT(m_TreeCtrl.GetBkColor() == RGB(0, 0, 128));

// force repaint immediately
m_TreeCtrl.Invalidate();

CTreeCtrl::SetToolTips

This member function implements the behavior of the Win32 message TVM_SETTOOLTIPS, as described in the Windows SDK.

CToolTipCtrl* SetToolTips(CToolTipCtrl* pWndTip);

Parameters

pWndTip
A pointer to a CToolTipCtrl object that the tree control will use.

Return Value

A pointer to a CToolTipCtrl object containing the tooltip previously used by the control, or NULL if no tooltips were used previously.

Remarks

To use tooltips, indicate the TVS_NOTOOLTIPS style when you create the CTreeCtrl object.

Example

See the example for CTreeCtrl::GetToolTips.

CTreeCtrl::ShowInfoTip

Displays the infotip for the specified item in the current tree-view control.

void ShowInfoTip(HTREEITEM hItem);

Parameters

hItem
[in] A handle to a tree-view item in the control. For more information, see the hItem member of the TVITEMEX structure.

Remarks

For more information about the difference between tooltips and infotips, see Tooltips and Infotips.

This method sends the TVM_SHOWINFOTIP message, which is described in the Windows SDK.

CTreeCtrl::SortChildren

Call this function to alphabetically sort the child items of the given parent item in a tree view control.

BOOL SortChildren(HTREEITEM hItem);

Parameters

hItem
Handle of the parent item whose child items are to be sorted. If hItem is NULL, sorting will proceed from the root of the tree.

Return Value

Nonzero if successful; otherwise 0.

Remarks

SortChildren will not recurse through the tree; only the immediate children of hItem will be sorted.

Example

// Sort all of the items in the tree control.
m_TreeCtrl.SortChildren(TVI_ROOT);

CTreeCtrl::SortChildrenCB

Call this function to sort tree view items using an application-defined callback function that compares the items.

BOOL SortChildrenCB(LPTVSORTCB pSort);

Parameters

pSort
Pointer to a TVSORTCB structure.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The structure's comparison function, lpfnCompare, must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

The lParam1 and lParam2 parameters correspond to the lParam member of the TVITEM structure for the two items being compared. The lParamSort parameter corresponds to the lParam member of the TV_SORTCB structure.

Example

// Sort the item in reverse alphabetical order.
int CALLBACK MyCompareProc(LPARAM lParam1, LPARAM lParam2, LPARAM lParamSort)
{
   // lParamSort contains a pointer to the tree control.
   // The lParam of an item is just its handle, 
   // as specified with SetItemData
   CTreeCtrl* pmyTreeCtrl = (CTreeCtrl*)lParamSort;
   CString strItem1 = pmyTreeCtrl->GetItemText((HTREEITEM)lParam1);
   CString strItem2 = pmyTreeCtrl->GetItemText((HTREEITEM)lParam2);

   return strItem2.Compare(strItem1);
}

 

TVSORTCB tvs;

// Sort the tree control's items using my
// callback procedure.
tvs.hParent = TVI_ROOT;
tvs.lpfnCompare = MyCompareProc;
tvs.lParam = (LPARAM)&m_TreeCtrl;

m_TreeCtrl.SortChildrenCB(&tvs);

See also

MFC Sample CMNCTRL1
CWnd Class
Hierarchy Chart
CImageList Class