TreeView class

A TreeView is a hierarchical display of Node objects organized into a tree. Each node can be expanded or collapsed, optionally has a checkbox, and references an icon from an associated ImageList. The collection of nodes is reached through Nodes; each Node has its own siblings, parent, and child navigation properties.

Private Sub Form_Load()
    Set TreeView1.ImageList = ImageList1
    TreeView1.Style = tvwTreelinesPlusMinusPictureText

    Dim root As Node
    Set root = TreeView1.Nodes.Add(, , "root", "My Computer", "computer")
    TreeView1.Nodes.Add root, tvwChild, "c", "C: drive", "disk"
    TreeView1.Nodes.Add root, tvwChild, "d", "D: drive", "disk"
    root.Expanded = True
End Sub

Private Sub TreeView1_NodeClick(ByVal Node As Node)
    Debug.Print "Clicked: " & Node.FullPath
End Sub

The control inherits the focusable rect-dockable members from BaseControlFocusable — size, position, Anchors, Dock, Font, Appearance, MousePointer / MouseIcon, ToolTipText, DragMode / DragIcon, Drag, Refresh, SetFocus, TabIndex / TabStop, ZOrder, CausesValidation, VisualStyles, hWnd, HelpContextID / WhatsThisHelpID.

Style: a composite of buttons / lines / icons / text

Style is the most-clicked property on this control. It is a single enum value but the eight choices encode a 3-bit combination of which visual elements appear:

Style Buttons Lines Icons
tvwTextOnly — — —
tvwPictureText — — yes
tvwPlusMinusText yes — —
tvwPlusMinusPictureText yes — yes
tvwTreelinesText — yes —
tvwTreelinesPictureText — yes yes
tvwTreelinesPlusMinusText yes yes —
tvwTreelinesPlusMinusPictureText (default) yes yes yes

The values are decoded internally into the Win32 TVS_HASBUTTONS / TVS_HASLINES style bits.

Sorting

Sorting is configured at two levels:

  • The TreeView as a whole sorts its root-level nodes when Sorted is True, using SortOrder and SortType to control direction and comparison.
  • Each individual Node has its own Sorted / SortOrder / SortType properties, which control how its children are sorted, independently of the tree-level setting.

Toggling either flag triggers an immediate sort. New nodes added after a node has been sorted are inserted into the correct sorted position.

Image lists and image references

Bind an ImageList through ImageList. Each Node references icons through Image (rendered when the node is not selected) and SelectedImage (rendered when the node is selected); either accepts a 1-based Long index or a String key into the bound image list. Omitting SelectedImage defaults the selected icon to the same as Image.

Checkboxes

Setting CheckBoxes to True adds a leading checkbox to every node. The user can click the checkbox or press Space while a node is focused to toggle; the NodeCheck event then fires. Node.Checked reads and writes the check state programmatically.

Properties

Appearance

How the control’s border is drawn. A AppearanceConstants member. Default: vbAppear3d. Inherited.

BorderStyle

The control’s border style. A member of TreeBorderStyleConstants: ccNone or ccFixedSingle. Default: ccFixedSingle.

CheckBoxes

Whether each node has a leading checkbox. Boolean. Default: False.

DropHighlight

The Node currently highlighted as a drag-drop target, or Nothing. Node, read/write.

FullRowSelect

Whether clicking on the indentation area of a row selects the node (instead of only clicking on its icon or label). Boolean. Default: False.

HideSelection

Whether the selection highlight is hidden when the control does not have focus. Boolean. Default: True.

HotTracking

Whether nodes are highlighted as the mouse hovers over them. Boolean. Default: False.

hWnd

The Win32 handle of the treeview window. LongPtr, read-only.

hWndLabelEdit

The Win32 handle of the currently editing label’s textbox window, or 0. LongPtr, read-only.

ImageList

The ImageList used for node icons. Assignment increments the ImageList’s bound-count.

Indentation

The horizontal pixel indent per level of node depth. Double, read/write. Default: 20.

LabelEdit

How inline label editing is triggered. A member of TreeLabelEditConstants: tvwAutomatic, tvwManual, or tvwDisabled. Default: tvwAutomatic.

LineStyle

Whether tree lines are drawn from root nodes or only from child nodes. A member of TreeLineStyleConstants: tvwTreeLines or tvwRootLines. Default: tvwRootLines.

Nodes

The Nodes collection. Read-only.

PathSeparator

The string inserted between node texts in Node.FullPath. String. Default: "\".

Scroll

Whether the treeview has scrollbars (when its content extends beyond the visible area). Boolean. Default: True.

SelectedItem

The currently selected Node, or Nothing. Read/write.

SingleSel

Whether only a single node can be expanded at any time (any other expansion automatically collapses sibling subtrees). Boolean. Default: False.

Sorted

Whether root-level nodes are sorted. Boolean. Default: False. Per-subtree sorting is controlled through Node.Sorted on individual nodes.

SortOrder

The sort direction at the root level. A member of TreeSortOrderConstants. Default: tvwAscending.

SortType

The string comparison used for sorting at the root level. A member of TreeSortTypeConstants: tvwBinary (case-sensitive) or tvwText (case-insensitive). Default: tvwText.

Style

The composite visual style — see the Style table above. A member of TreeStyleConstants. Default: tvwTreelinesPlusMinusPictureText.

WheelScrollEvent

Whether mouse-wheel events trigger Scroll. Boolean. Default: True.

Methods

GetVisibleCount

Returns the maximum number of fully-visible nodes the current viewport can show. Long.

Syntax: object.GetVisibleCount As Long

HitTest

Returns the Node at the given point, or Nothing if no node lies under it. Useful for drag-drop hover effects, custom context menus, and right-click handling.

Syntax: object.HitTest ( x, y ) As Node

x
A Single horizontal coordinate in the control’s coordinate system (twips by default).
y
A Single vertical coordinate.

StartLabelEdit

Opens the inline editor on the currently selected node. Used when LabelEdit is tvwManual.

Syntax: object.StartLabelEdit

Events

AfterLabelEdit

Raised when an inline label edit completes. Set Cancel to True to revert the change.

Syntax: object_AfterLabelEdit( Cancel As Boolean, NewString As String )

BeforeCollapse

Raised before a node is collapsed. Set Cancel to True to prevent the collapse.

Syntax: object_BeforeCollapse( ByVal Node As Node, ByRef Cancel As Boolean )

BeforeExpand

Raised before a node is expanded. Set Cancel to True to prevent the expansion.

Syntax: object_BeforeExpand( ByVal Node As Node, ByRef Cancel As Boolean )

BeforeLabelEdit

Raised when an inline label edit is about to start. Set Cancel to True to block the edit.

Syntax: object_BeforeLabelEdit( Cancel As Boolean )

Click

Raised on a mouse click inside the control. Distinct from NodeClick, which fires when the click hits a node.

Syntax: object_Click( )

Collapse

Raised after a node has been collapsed.

Syntax: object_Collapse( ByVal Node As Node )

DblClick

Raised on a double-click inside the control.

Syntax: object_DblClick( )

DragDrop, DragOver

Inherited drag-drop events.

Expand

Raised after a node has been expanded.

Syntax: object_Expand( ByVal Node As Node )

Initialize

Raised after the control’s window has been created.

KeyDown, KeyPress, KeyUp

Inherited keyboard events. Pressing Space while CheckBoxes is True toggles the focused node’s check state and fires NodeCheck.

MouseDown, MouseMove, MouseUp

Inherited mouse events.

NodeCheck

Raised when a node’s checkbox is toggled — either by the user clicking it, by Space keypress, or by code assigning Node.Checked.

Syntax: object_NodeCheck( ByVal Node As Node )

NodeClick

Raised when a node is clicked. Distinct from Click, which fires on any mouse click in the control regardless of where it lands.

Syntax: object_NodeClick( ByVal Node As Node )

NodeSelect

Raised when a node becomes the selected node — either by user click, by keyboard arrow navigation, or by code assigning SelectedItem.

Syntax: object_NodeSelect( ByVal Node As Node )

OLECompleteDrag, OLEDragDrop, OLEDragOver, OLEGiveFeedback, OLESetData, OLEStartDrag

Inherited OLE drag-and-drop events.

Scroll

Raised when the treeview scrolls. New to this twinBASIC implementation; the original VB6 control did not expose this event. Set WheelScrollEvent to False to suppress firing on mouse-wheel input.

Syntax: object_Scroll( )

Validate

Inherited validation event.

See Also