Tree View Control Reference

Tree View Control Reference


This section contains information about the following new or updated API elements used with tree view controls.

Tree View Control Window Styles

Tree View Control Item States

Messages
TVM_CREATEDRAGIMAGE
TVM_DELETEITEM
TVM_EDITLABEL
TVM_ENDEDITLABELNOW
TVM_ENSUREVISIBLE
TVM_EXPAND
TVM_GETBKCOLOR
TVM_GETCOUNT
TVM_GETEDITCONTROL
TVM_GETIMAGELIST
TVM_GETINDENT
TVM_GETINSERTMARKCOLOR
TVM_GETISEARCHSTRING
TVM_GETITEM
TVM_GETITEMHEIGHT
TVM_GETITEMRECT
TVM_GETNEXTITEM
TVM_GETSCROLLTIME
TVM_GETTEXTCOLOR
TVM_GETTOOLTIPS
TVM_GETUNICODEFORMAT
TVM_GETVISIBLECOUNT
TVM_HITTEST
TVM_INSERTITEM
TVM_SELECTITEM
TVM_SETBKCOLOR
TVM_SETIMAGELIST
TVM_SETINDENT
TVM_SETINSERTMARK
TVM_SETINSERTMARKCOLOR
TVM_SETITEM
TVM_SETITEMHEIGHT
TVM_SETSCROLLTIME
TVM_SETTEXTCOLOR
TVM_SETTOOLTIPS
TVM_SETUNICODEFORMAT
TVM_SORTCHILDREN
TVM_SORTCHILDRENCB

Utility Macros
TreeView_CreateDragImage
TreeView_DeleteAllItems
TreeView_DeleteItem
TreeView_EditLabel
TreeView_EndEditLabelNow
TreeView_EnsureVisible
TreeView_Expand
TreeView_GetBkColor
TreeView_GetChild
TreeView_GetCount
TreeView_GetDropHilight
TreeView_GetEditControl
TreeView_GetFirstVisible
TreeView_GetImageList
TreeView_GetIndent
TreeView_GetInsertMarkColor
TreeView_GetISearchString
TreeView_GetItem
TreeView_GetItemHeight
TreeView_GetItemRect
TreeView_GetLastVisible
TreeView_GetNextItem
TreeView_GetNextSibling
TreeView_GetNextVisible
TreeView_GetParent
TreeView_GetPrevSibling
TreeView_GetPrevVisible
TreeView_GetRoot
TreeView_GetScrollTime
TreeView_GetSelection
TreeView_GetTextColor
TreeView_GetToolTips
TreeView_GetUnicodeFormat
TreeView_GetVisibleCount
TreeView_HitTest
TreeView_InsertItem
TreeView_Select
TreeView_SelectDropTarget
TreeView_SelectItem
TreeView_SelectSetFirstVisible
TreeView_SetBkColor
TreeView_SetImageList
TreeView_SetIndent
TreeView_SetInsertMark
TreeView_SetInsertMarkColor
TreeView_SetItem
TreeView_SetItemHeight
TreeView_SetScrollTime
TreeView_SetTextColor
TreeView_SetToolTips
TreeView_SetUnicodeFormat
TreeView_SortChildren
TreeView_SortChildrenCB

Notifications
NM_CLICK (tree view)
NM_CUSTOMDRAW (tree view)
NM_DBLCLK (tree view)
NM_KILLFOCUS (tree view)
NM_RCLICK (tree view)
NM_RETURN (tree view)
NM_SETFOCUS (tree view)
TVN_BEGINDRAG
TVN_BEGINLABELEDIT
TVN_BEGINRDRAG
TVN_DELETEITEM
TVN_ENDLABELEDIT
TVN_GETDISPINFO
TVN_GETINFOTIP
TVN_ITEMEXPANDED
TVN_ITEMEXPANDING
TVN_KEYDOWN
TVN_SELCHANGED
TVN_SELCHANGING
TVN_SETDISPINFO
TVN_SINGLEEXPAND

Structures
NM_TREEVIEW
NMTREEVIEW
NMTVCUSTOMDRAW
NMTVDISPINFO
NMTVGETINFOTIP
NMTVKEYDOWN
TV_DISPINFO
TV_HITTESTINFO
TV_INSERTSTRUCT
TV_ITEM
TV_KEYDOWN
TV_SORTCB
TVHITTESTINFO
TVINSERTSTRUCT
TVITEM
TVITEMEX
TVSORTCB

Tree View Control Window Styles

The following window styles are used when creating tree view controls.
TVS_CHECKBOXES Version 4.70. Enables check boxes for items in a tree view control. Effectively, when set to this style, the control creates and sets a state image list using DrawFrameControl. For more information, see Working with state image indexes. Once the control is created with this style, it cannot be removed. If it is necessary to remove this style, the control must be destroyed and a new one created in its place.
TVS_DISABLEDRAGDROP Prevents the tree view control from sending TVN_BEGINDRAG notification messages.
TVS_EDITLABELS Allows the user to edit the labels of tree view items.
TVS_FULLROWSELECT Version 4.71. Enables full-row selection in the tree view. The entire row of the selected item is highlighted, and clicking anywhere on an item's row will cause it to be selected. This style cannot be used in conjunction with the TVS_HASLINES style.
TVS_HASBUTTONS Displays plus (+) and minus (-) buttons next to parent items. The user clicks the buttons to expand or collapse a parent item's list of child items. To include buttons with items at the root of the tree view, TVS_LINESATROOT must also be specified.
TVS_HASLINES Uses lines to show the hierarchy of items.
TVS_INFOTIP Version 4.71. The tree view control will send the TVN_GETINFOTIP notification to obtain tooltip information.
TVS_LINESATROOT Uses lines to link items at the root of the tree view control. This value is ignored if TVS_HASLINES is not also specified.
TVS_NONEVENHEIGHT Version 4.71. The height of the items can be set to an odd height with the TVM_SETITEMHEIGHT message. By default, the height of items must be an even value.
TVS_NOSCROLL Version 4.71. Disables both horizontal and vertical scrolling in the control. The control will not display any scroll bars.
TVS_NOTOOLTIPS Version 4.70. The tree view control does not support tooltips.
TVS_RTLREADING Version 4.70. Displays text using right-to-left reading order on Hebrew or Arabic systems.
TVS_SHOWSELALWAYS Causes a selected item to remain selected when the tree view control loses focus.
TVS_SINGLEEXPAND Version 4.71. When this style is enabled, changing the selection in the tree view will automatically cause the item being selected to expand and the item being unselected to collapse. If the mouse is used to single-click the selected item and that item is closed, it will be expanded. If the selected item is single-clicked when it is open, it will be collapsed.
TVS_TRACKSELECT Version 4.70. Enables hot tracking in a tree view control.

Tree View Control Item States

The following item state flags are used to indicate the state of an item in a tree view control.
TVIS_BOLD The item is bold.
TVIS_CUT 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 Version 4.70. 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.

When you set or retrieve an item's overlay image index or state image index, you must specify the following masks in the stateMask member of the TVITEM structure. These values can also be used to mask off the state bits that are not of interest.
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.
TVIS_USERMASK Same as TVIS_STATEIMAGEMASK.

Tree View Control Messages

This section contains information about the messages used with tree view controls.

TVM_CREATEDRAGIMAGE

TVM_CREATEDRAGIMAGE 
    wParam = 0; 
    lParam = (LPARAM) (HTREEITEM) hitem; 

Creates a dragging bitmap for the specified item in a tree view control. The message also creates an image list for the bitmap and adds the bitmap to the image list. An application can display the image when dragging the item by using the image list functions. You can send this message explicitly or by using the TreeView_CreateDragImage macro.

hitem
Handle to the item that receives the new dragging bitmap.

If you create a tree view control without an associated image list, you cannot use the TVM_CREATEDRAGIMAGE message to create the image to display during a drag operation. You must implement your own method of creating a drag cursor.

TVM_DELETEITEM

TVM_DELETEITEM 
    wParam = 0; 
    lParam = (LPARAM) (HTREEITEM) hitem; 

Removes an item from a tree view control. You can send this message explicitly or by using the TreeView_DeleteItem or TreeView_DeleteAllItems macro.

hitem
Handle to the item to delete. If hitem is the TVI_ROOT value, all items are deleted from the tree view control.

If the item label is being edited, the edit operation is canceled and the parent window receives the TVN_ENDLABELEDIT notification message. The parent window receives a TVN_DELETEITEM notification message when the item is removed.

TVM_EDITLABEL

TVM_EDITLABEL 
    wParam = 0; 
    lParam = (LPARAM) (HTREEITEM) hitem; 

Begins in-place editing of the specified item's text, replacing the text of the item with a single-line edit control containing the text. This message implicitly selects and focuses the specified item. You can send this message explicitly or by using the TreeView_EditLabel macro.

hitem
Handle to the item to edit.

This message sends a TVN_BEGINLABELEDIT notification message to the parent of the tree view control.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but do not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

TVM_ENDEDITLABELNOW

TVM_ENDEDITLABELNOW 
    wParam = (WPARAM) (BOOL) fCancel; 
    lParam = 0; 

Ends the editing of a tree view item's label. You can send this message explicitly or by using the TreeView_EndEditLabelNow macro.

fCancel
Variable that indicates whether the editing is canceled without being saved to the label. If this parameter is TRUE, the system cancels editing without saving the changes. Otherwise, the system saves the changes to the label.

This message causes the TVN_ENDLABELEDIT notification message to be sent to the parent window of the tree view control.

TVM_ENSUREVISIBLE

TVM_ENSUREVISIBLE 
    wParam = 0; 
    lParam = (LPARAM) (HTREEITEM) hitem; 

Ensures that a tree view item is visible, expanding the parent item or scrolling the tree view control, if necessary. You can send this message explicitly or by using the TreeView_EnsureVisible macro.

hitem
Handle to the item.

If the TVM_ENSUREVISIBLE message expands the parent item, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

TVM_EXPAND

TVM_EXPAND
    wParam = (WPARAM) (UINT) flag; 
    lParam = (LPARAM) (HTREEITEM) hItem; 

Expands or collapses the list of child items associated with the specified parent item, if any. You can send this message explicitly or by using the TreeView_Expand macro.

flag
Action flag. This parameter can be one or more of the following values:
TVE_COLLAPSE Collapses the list.
TVE_COLLAPSERESET Collapses the list and removes the child items. This flag must be used with the TVE_COLLAPSE flag.
TVE_EXPAND Expands the list.
TVE_EXPANDPARTIAL Version 4.70. Partially expands the list. In this state, the child items are visible and the parent item's plus symbol is displayed. This flag must be used in combination with the TVE_EXPAND flag.
TVE_TOGGLE Collapses the list if it is expanded or expands it if it is collapsed.
hItem
Handle to the parent item to expand or collapse.

The TVM_EXPAND message will cause the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages to be generated if the item being expanded does not have the TVIS_EXPANDEDONCE state bit set. This state gets set when a parent item is expanded for the first time. Using TVE_COLLAPSE and TVE_COLLAPSERESET with TVM_EXPAND will cause the TVIS_EXPANDEDONCE state to be reset.

If the item already has the TVIS_EXPANDEDONCE state set, the TVM_EXPAND message will not cause the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages to be generated.

TVM_GETBKCOLOR

TVM_GETBKCOLOR
    wParam = 0;
    lParam = 0;

Retrieves the current background color of the control. You can send this message explicitly or by using the TreeView_GetBkColor macro.

Version 4.71

See also TVM_SETBKCOLOR

TVM_GETCOUNT

TVM_GETCOUNT 
    wParam = 0; 
    lParam = 0; 

Retrieves a count of the items in a tree view control. You can send this message explicitly or by using the TreeView_GetCount macro.

TVM_GETEDITCONTROL

TVM_GETEDITCONTROL 
    wParam = 0; 
    lParam = 0; 

Retrieves the handle to the edit control being used to edit a tree view item's text. You can send this message explicitly or by using the TreeView_GetEditControl macro.

TVM_GETIMAGELIST

TVM_GETIMAGELIST 
    wParam = (WPARAM) iImage; 
    lParam = 0; 

Retrieves the handle to the normal or state image list associated with a tree view control. You can send this message explicitly or by using the TreeView_GetImageList macro.

iImage
Type of image list to retrieve. This parameter can be one of the following values:
TVSIL_NORMAL Indicates the normal image list, which contains selected, nonselected, and overlay images for the items of a tree view control.
TVSIL_STATE Indicates the state image list. You can use state images to indicate application-defined item states. A state image is displayed to the left of an item's selected or nonselected image.

See also TVM_SETIMAGELIST

TVM_GETINDENT

TVM_GETINDENT 
    wParam = 0; 
    lParam = 0; 

Retrieves the amount, in pixels, that child items are indented relative to their parent items. You can send this message explicitly or by using the TreeView_GetIndent macro.

TVM_GETINSERTMARKCOLOR

TVM_GETINSERTMARKCOLOR
    wParam = 0;
    lParam = 0;

Retrieves the color used to draw the insertion mark for the tree view. You can send this message explicitly or by using the TreeView_GetInsertMarkColor macro.

Version 4.71

See also TVM_SETINSERTMARKCOLOR

TVM_GETISEARCHSTRING

TVM_GETISEARCHSTRING 
    wParam = 0; 
    lParam = (LPARAM) (LPSTR) lpsz; 

Retrieves the incremental search string for a tree view control. The tree view control uses the incremental search string to select an item based on characters typed by the user. You can send this message explicitly or by using the TreeView_GetISearchString macro.

lpsz
Address of the buffer that receives the incremental search string.

If the tree view control is not in incremental search mode, the return value is zero.

TVM_GETITEM

TVM_GETITEM 
    wParam = 0; 
    lParam = (LPARAM) (LPTVITEM) pitem; 

Retrieves some or all of a tree view item's attributes. You can send this message explicitly or by using the TreeView_GetItem macro.

pitem
Address of a TVITEM structure that specifies the information to retrieve and receives information about the item. When the message is sent, the hItem member identifies the item to retrieve information about and the mask member specifies the attributes to retrieve.
If the mask member specifies the TVIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.
If the mask member specifies the TVIF_STATE value, the stateMask member must specify the item state bits to retrieve. On output, the state member contains the values of the specified state bits.

TVM_GETITEMHEIGHT

TVM_GETITEMHEIGHT
    wParam = 0;
    lParam = 0;

Retrieves the current height of the tree view items. You can send this message explicitly or by using the TreeView_GetItemHeight macro.

Version 4.71

See also TVM_SETITEMHEIGHT

TVM_GETITEMRECT

TVM_GETITEMRECT 
    wParam = (WPARAM) (BOOL) fItemRect; 
    lParam = (LPARAM) (LPRECT) prc; 

Retrieves the bounding rectangle for a tree view item and indicates whether the item is visible. You can send this message explicitly or by using the TreeView_GetItemRect macro.

fItemRect
Value specifying the portion of the item for which to retrieve the bounding rectangle. If this parameter is TRUE, 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.
prc
Address of a RECT structure that receives the bounding rectangle. The coordinates are relative to the upper-left corner of the tree view control.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.