
This section contains information about the following new or updated API elements used with tree view controls.
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. |
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. |
This section contains information about the messages used with tree view controls.
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.
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
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.
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
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.
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
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.
This message causes the TVN_ENDLABELEDIT notification message to be sent to the parent window of the tree view control.
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.
If the TVM_ENSUREVISIBLE message expands the parent item, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.
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.
| 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. |
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
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
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
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
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.
| 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
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
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
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.
If the tree view control is not in incremental search mode, the return value is zero.
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.
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
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.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.