TreeView_GetNextItem
Tree View Control Reference

TreeView_GetNextItem


HTREEITEM TreeView_GetNextItem(
    HWND hwndTV,
    HTREEITEM hitem,
    UINT flag
);		

Retrieves the tree view item that bears the specified relationship to a specified item. You can use this macro, use one of the TreeView_Get macros described below, or send the TVM_GETNEXTITEM message explicitly.

hwndTV
Handle to the tree view control.
hitem
Handle to an item.
flag
Flag specifying the item to retrieve. This parameter can be one of the following values:
TVGN_CARET Retrieves the currently selected item. You can use the TreeView_GetSelection macro to send this message.
TVGN_CHILD Retrieves the first child item of the item specified by the hitem parameter. You can use the TreeView_GetChild macro to send this message.
TVGN_DROPHILITE Retrieves the item that is the target of a drag-and-drop operation. You can use the TreeView_GetDropHilight macro to send this message.
TVGN_FIRSTVISIBLE Retrieves the first visible item. You can use the TreeView_GetFirstVisible macro to send this message.
TVGN_NEXT Retrieves the next sibling item. You can use the TreeView_GetNextSibling macro to send this message.
TVGN_NEXTVISIBLE Retrieves the next visible item that follows the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetNextVisible macro to send this message.
TVGN_PARENT Retrieves the parent of the specified item. You can use the TreeView_GetParent macro to send this message.
TVGN_PREVIOUS Retrieves the previous sibling item. You can use the TreeView_GetPrevSibling macro to send this message.
TVGN_PREVIOUSVISIBLE Retrieves the first visible item that precedes the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetPrevVisible macro to send this message.
TVGN_ROOT Retrieves the topmost or very first item of the tree view control. You can use the TreeView_GetRoot macro to send this message.

TreeView_GetNextSibling

HTREEITEM TreeView_GetNextSibling(
    HWND hwndTV,
    HTREEITEM hitem
);		

Retrieves the next sibling item of a specified item in a tree view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_NEXT flag.

hwndTV
Handle to the tree view control.
hitem
Handle to an item.

See also TreeView_GetChild, TreeView_GetNextItem, TreeView_GetParent, TreeView_GetPrevSibling

TreeView_GetNextVisible

HTREEITEM TreeView_GetNextVisible(
    HWND hwndTV,
    HTREEITEM hitem
);		

Retrieves the next visible item that follows a specified item in a tree view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_NEXTVISIBLE flag.

hwndTV
Handle to the tree view control.
hitem
Handle to an item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible.

See also TreeView_GetFirstVisible, TreeView_GetNextItem, TreeView_GetPrevVisible

TreeView_GetParent

HTREEITEM TreeView_GetParent(
    HWND hwndTV,
    HTREEITEM hitem
);		

Retrieves the parent item of the specified tree view item. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_PARENT flag.

hwndTV
Handle to the tree view control.
hitem
Handle to an item.

See also TreeView_GetChild, TreeView_GetNextItem, TreeView_GetNextSibling, TreeView_GetPrevSibling

TreeView_GetPrevSibling

HTREEITEM TreeView_GetPrevSibling(
    HWND hwndTV,
    HTREEITEM hitem
);		

Retrieves the previous sibling item of a specified item in a tree view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_PREVIOUS flag.

hwndTV
Handle to the tree view control.
hitem
Handle to an item.

See also TreeView_GetChild, TreeView_GetNextItem, TreeView_GetNextSibling, TreeView_GetParent

TreeView_GetPrevVisible

HTREEITEM TreeView_GetPrevVisible(
    HWND hwndTV,
    HTREEITEM hitem
);		

Retrieves the first visible item that precedes a specified item in a tree view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_PREVIOUSVISIBLE flag.

hwndTV
Handle to the tree view control.
hitem
Handle to an item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible.

See also TreeView_GetFirstVisible, TreeView_GetNextItem, TreeView_GetNextVisible

TreeView_GetRoot

HTREEITEM TreeView_GetRoot(
    HWND hwndTV
);		

Retrieves the topmost or very first item of the tree view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_ROOT flag.

hwndTV
Handle to the tree view control.

See also TreeView_GetNextItem

TreeView_GetScrollTime

UINT TreeView_GetScrollTime(
    HWND hwndTV
);

Retrieves the maximum scroll time for the tree view control. You can use this macro or send the TVM_GETSCROLLTIME message explicitly.

hwndTV
Handle to the tree view control.

The maximum scroll time is the longest amount of time that a scroll operation can take. Scrolling will be adjusted so that the scroll will take place within the maximum scroll time. A scroll operation may take less time than the maximum.

See also TreeView_SetScrollTime

TreeView_GetSelection

HTREEITEM TreeView_GetSelection(
    HWND hwndTV
);		

Retrieves the currently selected item in a tree view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_CARET flag.

hwndTV
Handle to the tree view control.

See also TreeView_GetNextItem

TreeView_GetTextColor

COLORREF TreeView_GetTextColor(
    HWND hwndTV 
);

Retrieves the current text color of the control. You can use this macro or send the TVM_GETTEXTCOLOR message explicitly.

hwndTV
Handle to a tree view control.

Version 4.71

See also TreeView_SetTextColor

TreeView_GetToolTips

HWND TreeView_GetToolTips(
    HWND hwndTV 
);

Retrieves the handle to the child tooltip control used by a tree view control. You can use this macro or send the TVM_GETTOOLTIPS message explicitly.

hwndTV
Handle to a tree view control.

When created, tree view controls automatically create a child tooltip control. To prevent a tree view control from using tooltips, create the control with the TVS_NOTOOLTIPS style.

Version 4.70

See also TreeView_SetToolTips

TreeView_GetUnicodeFormat

BOOL TreeView_GetUnicodeFormat(
    HWND hwnd
);

Retrieves the UNICODE character format flag for the control. You can use this macro or send the TVM_GETUNICODEFORMAT message explicitly.

hwnd
Handle to the control.

See also TreeView_SetUnicodeFormat

TreeView_GetVisibleCount

UINT TreeView_GetVisibleCount(
    HWND hwndTV
);		

Obtains the number of items that can be fully visible in the client window of a tree view control. You can use this macro or send the TVM_GETVISIBLECOUNT message explicitly.

hwndTV
Handle to the tree view control.

The number of items that can be fully visible may be greater than the number of items in the control. The control calculates this value by dividing the height of the client window by the height of an item.

Note that the return value is the number of items that can be fully visible. If you can see all of 20 items and part of one more item, the return value is 20.

TreeView_HitTest

HTREEITEM TreeView_HitTest(
    HWND hwndTV,
    LPTVHITTESTINFO lpht
);		

Determines the location of the specified point relative to the client area of a tree view control. You can use this macro or send the TVM_HITTEST message explicitly.

hwndTV
Handle to the tree view control.
lpht
Address of a TVHITTESTINFO structure. When the message is sent, the pt member specifies the coordinates of the point to test. When the message returns, the hItem member is the handle to the item at the specified point or NULL if no item occupies the point. Also, when the message returns, the flags member is a hit test value that indicates the location of the specified point. For a list of hit test values, see the description of the TVHITTESTINFO structure.

TreeView_InsertItem

HTREEITEM TreeView_InsertItem(
    HWND hwndTV,
    LPTVINSERTSTRUCT lpis
);		

Inserts a new item in a tree view control. You can use this macro or send the TVM_INSERTITEM message explicitly.

hwndTV
Handle to the tree view control.
lpis
Address of a TVINSERTSTRUCT structure that specifies the attributes of the tree view item.

See also TVN_ENDLABELEDIT

TreeView_Select

BOOL TreeView_Select(
    HWND hwndTV,
    HTREEITEM hitem,
    UINT flag
);		

Selects the specified tree view item, scrolls the item into view, or redraws the item in the style used to indicate the target of a drag-and-drop operation. You can use this macro or the TreeView_SelectItem, TreeView_SelectSetFirstVisible, or TreeView_SelectDropTarget macros, or you can send the TVM_SELECTITEM message explicitly.

hwndTV
Handle to the tree view control.
hitem
Handle to an item. If the hitem parameter is NULL, the control is set to have no selected item.
flag
Action flag. This parameter can be one of the following values:
TVGN_CARET Sets the selection to the given item. The control's parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages.
TVGN_DROPHILITE Redraws the given item in the style used to indicate the target of a drag-and-drop operation.
TVGN_FIRSTVISIBLE Ensures that the specified item is visible, and, if possible, displays it at the top of the control's window. Tree view controls display as many items as will fit in the window. If the specified item is near the bottom of the control's hierarchy of items, it might not become the first visible item, depending on how many items fit in the window.

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.

TreeView_SelectDropTarget

BOOL TreeView_SelectDropTarget(
    HWND hwndTV,
    HTREEITEM hitem
);		

Redraws a specified tree view control item in the style used to indicate the target of a drag-and-drop operation. You can use this macro or the TreeView_Select macro, or you can send the TVM_SELECTITEM message explicitly.

hwndTV
Handle to the tree view control.
hitem
Handle to an item. If the hitem parameter is NULL, the control is set to have no selected item.

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.

Using the TreeView_SelectDropTarget macro is equivalent to sending the TVM_SELECTITEM message with its flag parameter set to the TVGN_DROPHILITE value.

TreeView_SelectItem

BOOL TreeView_SelectItem(
    HWND hwndTV,
    HTREEITEM hitem
);		

Selects the specified tree view item. You can use this macro or the TreeView_Select macro, or you can send the TVM_SELECTITEM message explicitly.

hwndTV
Handle to the tree view control.
hitem
Handle to an item. If the hitem parameter is NULL, the control is set to have no selected item.

When you call the TreeView_SelectItem macro, the control's parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages. Also, 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.

Using the TreeView_SelectItem macro is equivalent to sending the TVM_SELECTITEM message with its flag parameter set to the TVGN_CARET value.

TreeView_SetBkColor

COLORREF TreeView_SetBkColor(
    HWND hwndTV 
    COLORREF clrBk;
); 

Sets the background color of the control. You can use this macro or send the TVM_SETBKCOLOR message explicitly.

hwndTV
Handle to a tree view control.
clrBk
COLORREF value that contains the new background color. If this argument is -1, the control will revert to using the system color for the background color.

Version 4.71

See also TreeView_GetBkColor

TreeView_SelectSetFirstVisible

BOOL TreeView_SelectSetFirstVisible(
    HWND hwndTV,
    HTREEITEM hitem
);		

Scrolls the tree view control vertically to ensure that the specified item is visible. If possible, the specified item becomes the first visible item at the top of the control's window. You can use this macro or the TreeView_Select macro, or you can send the TVM_SELECTITEM message explicitly.

hwndTV
Handle to the tree view control.
hitem
Handle to an item. If the hitem parameter is NULL, the control is set to have no selected item.

Tree view controls display as many items as will fit in the window. If the specified item is near the bottom of the control's hierarchy of items, it might not become the first visible item, depending on how many items fit in the window.

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.

Using the TreeView_SelectSetFirstVisible macro is equivalent to sending the TVM_SELECTITEM message with its flag parameter set to the TVGN_FIRSTVISIBLE value.

TreeView_SetImageList

HIMAGELIST TreeView_SetImageList(
    HWND hwndTV,
    HIMAGELIST himl,
    INT iImage
   );		

Sets the normal or state image list for a tree view control and redraws the control using the new images. You can use this macro or send the TVM_SETIMAGELIST message explicitly.

hwndTV
Handle to the tree view control.
himl
The HIMAGELIST handle to the image list. If himl is NULL, the message removes the specified image list from the tree view control.
iImage
Type of image list to set. 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 TreeView_GetImageList, TVM_GETIMAGELIST

TreeView_SetIndent

BOOL TreeView_SetIndent(
    HWND hwndTV,
    INT indent
   );		

Sets the width of indentation for a tree view control and redraws the control to reflect the new width. You can use this macro or send the TVM_SETINDENT message explicitly.

hwndTV
Handle to the tree view control.
indent
Width, in pixels, of the indentation. If this parameter is less than the system-defined minimum width, the new width is set to the system-defined minimum.

TreeView_SetInsertMark

BOOL TreeView_SetInsertMark(
    HWND hwndTV,
    HTREEITEM htiInsert,
    BOOL fAfter
);

Sets the insertion mark in a tree view control. You can use this macro or send the TVM_SETINSERTMARK message explicitly.

hwndTV
Handle to a tree view control.
htiInsert
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.

Version 4.71

TreeView_SetInsertMarkColor

COLORREF TreeView_SetInsertMarkColor(
    HWND hwndTV,
    COLORREF clrInsertMark
);

Sets the color used to draw the insertion mark for the tree view. You can use this macro or send the TVM_SETINSERTMARKCOLOR message explicitly.

hwndTV
Handle to a tree view control.
clrInsertMark
COLORREF value that contains the new insertion mark color.

Version 4.71

See also TreeView_GetInsertMarkColor

TreeView_SetItem

BOOL TreeView_SetItem(
    HWND hwndTV,
    LPTVITEM pitem
);		

Sets some or all of a tree view item's attributes. You can use this macro or send the TVM_SETITEM message explicitly.

hwndTV
Handle to the tree view control.
pitem
Address of a TVITEM structure that contains the new item attributes. The hItem member identifies the item, and the mask member specifies which attributes to set.
If mask specifies the TVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.
If mask specifies the TVIF_STATE value, the stateMask member indicates which item states to change and the state member contains the values for those states.

TreeView_SetItemHeight

int TreeView_SetItemHeight(
    HWND hwndTV,
    SHORT cyItem
);

Sets the height of the tree view items. You can use this macro or send the TVM_SETITEMHEIGHT message explicitly.

hwndTV
Handle to a tree view control.
cyItem
Specifies the new height of every item in the tree view, in pixels. If this value 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.

The tree view control uses this value for the height of all items. To modify the height of individual items, see the description of the iIntegral member of the TVITEMEX structure.

Version 4.71

See also TreeView_GetItemHeight

TreeView_SetScrollTime

UINT TreeView_SetScrollTime(
    HWND hwndTV,
    UINT uMaxScrollTime
);

Sets the maximum scroll time for the tree view control. You can use this macro or send the TVM_SETSCROLLTIME message explicitly.

hwndTV
Handle to a tree view control.
uMaxScrollTime
Specifies the new maximum scroll time, in milliseconds. If this value is less than 100, it will be rounded up to 100.

The maximum scroll time is the longest amount of time that a scroll operation can take. Scrolling will be adjusted so that the scroll will take place within the maximum scroll time. A scroll operation may take less time than the maximum.

See also TVM_GETSCROLLTIME

TreeView_SetTextColor

COLORREF TreeView_SetTextColor(
    HWND hwndTV 
    COLORREF clrText;
); 

Sets the text color of the control. You can use this macro or send the TVM_SETTEXTCOLOR message explicitly.

hwndTV
Handle to a tree view control.
clrText
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.

Version 4.71

See also TreeView_GetTextColor

TreeView_SetToolTips

HWND TreeView_SetToolTips(
    HWND hwndTV,
    HWND hwndTooltip
);

Sets a tree view control's child tooltip control. You can use this macro or send the TVM_SETTOOLTIPS message explicitly.

hwndTV
Handle to a tree view control.
hwndTooltip
Handle to a tooltip control.

When created, tree view controls automatically create a child tooltip control. To prevent a tree view control from using tooltips, create the control with the TVS_NOTOOLTIPS style.

Version 4.70

See also TreeView_GetToolTips

TreeView_SetUnicodeFormat

BOOL TreeView_SetUnicodeFormat(
    HWND hwnd,
    BOOL fUnicode
);

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can use this macro or send the TVM_SETUNICODEFORMAT message explicitly.

hwnd
Handle to the control.
fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

See also TreeView_GetUnicodeFormat

TreeView_SortChildren

BOOL TreeView_SortChildren(
    HWND hwndTV,
    HTREEITEM hitem,
    BOOL fRecurse
);		

Sorts the child items of the specified parent item in a tree view control. You can use this macro or send the TVM_SORTCHILDREN message explicitly.

hwndTV
Handle to the tree view control.
hitem
Handle to the parent item whose child items are to be sorted.
fRecurse
Reserved for future use. Must be zero.

TreeView_SortChildrenCB

BOOL TreeView_SortChildrenCB(
    HWND hwndTV,
    LPTVSORTCB psort,
    BOOL fRecurse
);		

Sorts tree view items using an application-defined callback function that compares the items. You can use this macro or send the TVM_SORTCHILDRENCB message explicitly.

hwndTV
Handle to the tree view control.
psort
Address of a TVSORTCB structure. The lpfnCompare member is the address of the application-defined callback function, which is called during the sort operation each time the relative order of two list items needs to be compared. For more information about the callback function, see the description of TVSORTCB.
fRecurse
Reserved for future use. Must be zero.

Tree View Notification Messages

This section contains information about the notification messages that are sent by tree view controls.

NM_CLICK (tree view)

NM_CLICK 
    lpnmh = (LPNMHDR) lParam; 

Notifies a tree view control's parent window that the user has clicked the left mouse button within the control. This notification is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

NM_CUSTOMDRAW (tree view)

NM_CUSTOMDRAW
    lpNMCustomDraw = (LPNMTVCUSTOMDRAW) lParam;

Sent by a tree view control to notify its parent window about drawing operations. This notification is sent in the form of a WM_NOTIFY message.

lpNMCustomDraw
Address of a NMTVCUSTOMDRAW structure that contains information about the drawing operation.

Version 4.70

See also Using Custom Draw

NM_DBLCLK (tree view)

NM_DBLCLK 
    lpnmh = (LPNMHDR) lParam; 

Notifies a tree view control's parent window that the user has double-clicked the left mouse button within the control. This notification is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

NM_KILLFOCUS (tree view)

NM_KILLFOCUS 
    lpnmh = (LPNMHDR) lParam; 

Notifies a tree view control's parent window that the control has lost the input focus. This notification is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

NM_RCLICK (tree view)

NM_RCLICK 
    lpnmh = (LPNMHDR) lParam; 

Notifies a tree view control's parent window that the user has clicked the right mouse button within the control. This notification is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

NM_RETURN (tree view)

NM_RETURN
    lpnmh = (LPNMHDR) lParam; 

Notifies a tree view control's parent window that the control has the input focus and that the user has pressed the ENTER key. This notification is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

NM_SETCURSOR (tree view)

NM_SETCURSOR
    lpnmm = (LPNMMOUSE) lParam; 

Notifies a tree view control's parent window that the control is setting the cursor in response to a WM_SETCURSOR message. This notification is sent in the form of a WM_NOTIFY message.

lpnmm
Address of an NMMOUSE structure that contains additional information about this notification message.

Version 4.71.

NM_SETFOCUS (tree view)

NM_SETFOCUS 
    lpnmh = (LPNMHDR) lParam; 

Notifies a tree view control's parent window that the control has received the input focus. This notification is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

TVN_BEGINDRAG

TVN_BEGINDRAG 
    pnmtv = (LPNMTREEVIEW) lParam 

Notifies a tree view control's parent window that a drag-and-drop operation involving the left mouse button is being initiated. This notification message is sent in the form of a WM_NOTIFY message.

pnmtv
Address of an NMTREEVIEW structure. The itemNew member is a TVITEM structure that contains valid information about the item being dragged in the hItem, state, and lParam members. The ptDrag member specifies the current screen coordinates of the mouse.

A tree view control that has the TVS_DISABLEDRAGDROP style does not send this notification message.

TVN_BEGINLABELEDIT

TVN_BEGINLABELEDIT 
    ptvdi = (LPNMTVDISPINFO) lParam 

Notifies a tree view control's parent window about the start of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

ptvdi
Address of an NMTVDISPINFO structure. The item member is a TVITEM structure that contains valid information about the item being edited in the hItem, state, lParam, and pszText members.

TVN_BEGINRDRAG

TVN_BEGINRDRAG 
    pnmtv = (LPNMTREEVIEW) lParam 

Notifies a tree view control's parent window about the initiation of a drag-and-drop operation involving the right mouse button. This notification message is sent in the form of a WM_NOTIFY message.

pnmtv
Address of an NMTREEVIEW structure. The itemNew member is a TVITEM structure that contains valid information in the hItem, state, and lParam members about the item to be dragged. The ptDrag member specifies the current screen coordinates of the mouse.

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