TvwNode class

One node of a TreeView: its text and key, its place in the tree, the pictures and colors it is drawn with, and its state: open or closed, selected, checked. A program gets a node from the TvwNodes collection, from its Add method, from a property of the tree such as SelectedItem, and from the properties of another node. It cannot make a TvwNode object with New.

Dim Root As TvwNode, Leaf As TvwNode
Set Root = TreeView1.Nodes.Add(, , "r", "Root")
Set Leaf = TreeView1.Nodes.Add(Root, TvwNodeRelationshipChild, "m", "Middle")
Set Leaf = TreeView1.Nodes.Add(Leaf, TvwNodeRelationshipChild, "l", "Leaf")
Debug.Print Leaf.FullPath
Debug.Print Leaf.Level
Debug.Print Leaf.Parent.Text
Debug.Print Root.Children
' Output:
'  Root\Middle\Leaf
'  2
'  Middle
'  1

A TvwNode refers to its node in the tree. When the program removes the node, with Remove or Clear, the object stays but refers to nothing.

Moving around the tree

Parent, Child, NextSibling, PreviousSibling, FirstSibling and LastSibling return the nodes around this one, or Nothing where there is none. The siblings of a node are the nodes that have the same parent, or the nodes of the root level. A node is its own first and last sibling when it is the only one. Level is how deep the node is: 0 at the root level.

A Set of one of these properties other than Parent raises run-time error 383, Property is read-only.

Dim Node As TvwNode
Set Node = TreeView1.Nodes.Add(, , "a", "A")
TreeView1.Nodes.Add Node, TvwNodeRelationshipChild, "a1", "A1"
TreeView1.Nodes.Add Node, TvwNodeRelationshipChild, "a2", "A2"
TreeView1.Nodes.Add , , "b", "B"
Set Node = TreeView1.Nodes("a1")
Debug.Print Node.NextSibling.Text
Debug.Print TypeName(Node.PreviousSibling)
Debug.Print Node.LastSibling.Text
Debug.Print TreeView1.Nodes("b").FirstSibling.Text
' Output:
'  A2
'  Nothing
'  A2
'  A

Root is meant to return the root-level node a node hangs from, but it does not.

FirstVisible, LastVisible, NextVisible and PreviousVisible go through the nodes that are shown, which are all those that are not inside a closed branch, in the order of the tree.

Moving a node

Move takes the node, with all its children, to another place, and assigning a node to Parent makes the node the first child of that node. The node keeps its number in the collection, its key, its text, and its open, selected and checked state. It gets a new Handle.

A move into the node’s own branch, which would make a loop, raises run-time error 35614. Assigning Nothing to Parent raises run-time error 35610.

Dim Folder As TvwNode, File As TvwNode
Set Folder = TreeView1.Nodes.Add(, , "d", "Folder")
Set File = TreeView1.Nodes.Add(, , "f", "File")
Set File.Parent = Folder
Debug.Print File.FullPath
File.Move
Debug.Print File.Level
On Error Resume Next
Folder.Move File, TvwNodeRelationshipChild
Debug.Print Err.Number
Folder.Move Folder.Child, TvwNodeRelationshipNext
Debug.Print Err.Number
' Output:
'  Folder\File
'  0
'  0
'  0

Pictures

A node shows the picture Image names. While it is selected it shows SelectedImage instead, or its Image if that is 0. While its branch is open and it has an ExpandedImage, it shows that in place of Image, and in place of SelectedImage too if that is 0. NoImages draws a node without a picture. All of them name a picture of the tree’s image list, by number from 1 or, when the tree holds the ImageList control, by key.

Dim Folder As TvwNode
Set Folder = TreeView1.Nodes.Add(, , "docs", "Documents")
Folder.Image = "folder"
Folder.ExpandedImage = "open"
Folder.SelectedImage = 3

Properties

BackColor

The background color of the node’s label. OLE_COLOR. A node that has no color of its own has the tree’s BackColor, and a node assigned -1 has it again. It does not show while the node is selected or has the focus.

The property returns the tree’s color for a node that has none of its own.

Bold

Whether the label is drawn in bold. Boolean. Default: False.

CheckBox

Whether the node has a check box, while the tree’s Checkboxes is True. Boolean. A new node has one.

Assigning False takes the box away, and the node reads False for Checked from then on. A node whose box was taken away ignores an assignment to Checked, and assigning True to CheckBox gives it a box again.

Checked

Whether the node’s check box is checked. Boolean. Default: False. See Check boxes for the events a change raises.

Child

The first child of the node, or Nothing when it has none. A TvwNode, read-only: an assignment raises run-time error 383.

Children

The number of children of the node, not counting their children. Long, read-only.

Enabled

Whether the label is drawn in the normal color or in gray. Boolean. Default: True. It only changes the drawing: the user can still select the node. It has an effect when the program has visual styles; without them the node is always enabled and an assignment does nothing.

With visual styles a node assigned False reads False.

Expanded

Whether the branch of the node is open. Boolean. Default: False. See Opening and closing branches for the events a change raises.

ExpandedImage

The picture the node shows while its branch is open. The number of a picture of the tree’s image list, from 1, or its key as a String. Variant. Default: 0, with which the node shows its Image. A key the list does not have raises run-time error 35601, and a negative number 35600.

ExpandedImageIndex

The number of the picture ExpandedImage names, whether it was assigned as a number or as a key. Long, read-only.

FirstSibling

The first node of the branch the node is in. A TvwNode, read-only. A node that is the first returns itself.

FirstVisible

The node at the top of the visible part of the tree, as TopItem is, whichever node it is asked of. A TvwNode, read-only.

ForeColor

The color of the node’s text. OLE_COLOR. A node that has no color of its own has the tree’s ForeColor, and a node assigned -1 has it again, as the tree’s ResetForeColors does for every node. It does not show while the node is selected or has the focus.

FullPath

The texts of the node and of all the nodes above it, from the top, with the tree’s PathSeparator between them. String, read-only. At the root level it is the node’s own text.

The separator is read when the path is asked for, so a change of PathSeparator shows at once.

Ghosted

Whether the node is drawn as if it had been cut: its picture lighter. Boolean. Default: False.

Handle

The handle of the node in the tree view window of Windows, for a program that sends the window its own messages. LongPtr, read-only. It changes when Move or Parent moves the node.

Image

The picture the node shows. The number of a picture of the tree’s image list, from 1, or its key as a String. Variant. Default: 0, no picture. A key the list does not have, or any key while the tree holds no ImageList control, raises run-time error 35601. A negative number raises 35600. A number is not checked against the size of the list. See Pictures.

ImageIndex

The number of the picture Image names, whether it was assigned as a number or as a key. Long, read-only.

Index

The number of the node in the TvwNodes collection. Long, read-only. It is the order in which the nodes were added, not their place in the tree. See Numbers and keys.

Key

The key of the node in the collection. String. An assignment changes the key, and an empty string takes it away.

A key that another node has raises run-time error 457 and leaves the key as it was.

LastSibling

The last node of the branch the node is in. A TvwNode, read-only. A node that is the last returns itself.

LastVisible

The last node of the tree that is shown, that is the last one that is not inside a closed branch, whichever node it is asked of. A TvwNode, read-only.

Level

How deep the node is in the tree: 0 for a node of the root level, 1 for its children. Long, read-only.

NextSibling

The next node of the branch, or Nothing for the last. A TvwNode, read-only.

NextVisible

The next node that is shown, after this one in the order of the tree, or Nothing. A TvwNode, read-only.

NoImages

Whether the node is drawn without a picture. Boolean. Default: False.

Parent

The node above this one, or Nothing at the root level. A TvwNode. Assigned with Set, it moves the node, with its children, to be the first child of the new parent. See Moving a node.

PreviousSibling

The previous node of the branch, or Nothing for the first. A TvwNode, read-only.

PreviousVisible

The previous node that is shown, before this one in the order of the tree, or Nothing. A TvwNode, read-only.

Root

The node of the root level above this one. A TvwNode, read-only. See Moving around the tree for what it really returns.

Selected

Whether the node is selected. Boolean. Assigning True selects it, with the events described under Selecting nodes, and opens the branches above it. In a tree that allows several selected nodes it adds the node to the selection.

Selecting a node in a closed branch opens the branch.

SelectedImage

The picture the node shows while it is selected. The number of a picture of the tree’s image list, from 1, or its key as a String. Variant. Default: 0, with which the node shows its Image. A key the list does not have raises run-time error 35601, and a negative number 35600.

SelectedImageIndex

The number of the picture SelectedImage names. Long, read-only.

Sorted

Whether the children of the node are kept sorted. Boolean. Default: False. Assigning True sorts them at once, and a child added later goes to its sorted place. The sorting follows the node’s SortOrder and SortType, and not the tree’s.

SortOrder

The direction in which the children are sorted. A member of TvwSortOrderConstants. Default: TvwSortOrderAscending.

Another value raises run-time error 380.

SortType

How the texts of the children are compared. A member of TvwSortTypeConstants. Default: TvwSortTypeBinary.

Another value raises run-time error 380.

Tag

A value of the program’s own, which the node does not use. Variant. A new node has an empty string. Assigned with Set, it holds an object.

Text

The label of the node. String. It is the default member, so Node = "New" sets the text.

ToolTipText

The text shown in a small window when the pointer rests on the node, while the tree’s ShowTips is True. String. Default: empty, with which the node shows none.

Visible

Whether the node is shown: it is not inside a closed branch. Boolean, read-only. A node that is scrolled out of the window is still True.

The children of a node whose branch is closed read False; they read True once the branch is opened.

Methods

CreateDragImage

Returns the handle of an image list of Windows that holds a picture of the node, for a drag with the Windows API. LongPtr. The program owns the image list and destroys it when it no longer needs it, with ImageList_Destroy.

Syntax: object.CreateDragImage

EnsureVisible

Scrolls the tree, and opens the branches above the node if they are closed, so that the node is shown.

Syntax: object.EnsureVisible

Move

Takes the node, with all its children, to another place in the tree. See Moving a node.

Syntax: object.Move [ Relative ] [, Relationship ]

Relative
optional The node that the moved one is placed by: a TvwNode, or the number or the key of one. Without it the node goes to the root level, and TvwNodeRelationshipFirst puts it before every other node of the root level and every other relationship after the last.
Relationship
optional A member of TvwNodeRelationshipConstants. The default is TvwNodeRelationshipNext.

A Relative that is a key no node has raises run-time error 5, and one that is not a node, a string or a whole number raises 13.

SelectedIndex

Returns the place of the node in the tree’s SelectedNodes, counted from 1, or 0 when the node is not selected. Long.

Syntax: object.SelectedIndex

See Also