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.
Warning 1.8.141.0
Root returns the first node of the root level, whichever node it is asked of. For a node in the first branch that is the right node, and for a node in any later branch it is the wrong one. A program that needs the top of a branch goes up with Parent until it is Nothing.
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.
Warning 1.8.141.0
The property returns at most 259 characters of a longer text, with no error. The same holds for the node’s part of FullPath and for the texts the sorting compares. A program that keeps longer texts keeps them itself, for instance in Tag.
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
- TreeView class
- TvwNodes class – the collection of the nodes
- TvwSelectedNodes class – the selected nodes of a tree that allows several