TreeView

The TreeView control displays a hierarchical data set graphically, as shown in Figure G-30.

The TreeView control uses TreeNode objects to represent the items it contains. The control’s Nodes collection contains references to the top-level objects called its root nodes. In Figure G-30, the R & D and Sales & Support items are the root nodes.

Figure G-30: The TreeView control displays hierarchical data graphically.

Each TreeNode object has a Nodes collection of its own that contains references to its child nodes. For example, in Figure G-30 the R & D root node has children labeled Engineering and Test. Each of those nodes has child nodes representing employees.

You can assign each of the TreeNode objects icons to display. In Figure G-30, the nodes display images representing factories, workgroups, and people.

Your program can manipulate the TreeNode objects at runtime, but you can also edit the tree data at design time. Select the TreeView control, select its Nodes property in the Properties window, and click the ellipsis to the right to make Visual Basic display the TreeNode Editor shown in Figure G-31.

Figure G-31: The TreeNode Editor lets you edit a TreeView control’s data at design time.

Click Add Root to add a new root node to the tree. Select a node and click Add Child to give the node a new child. Select a node and click Delete to remove the node and any descendants it contains.

If the TreeView control’s ImageList property is set to an ImageList control, then you can set a node’s ImageIndex property to the index of the image in the ImageList that the node should display. Set the node’s SelectedImageIndex to the index of the image that the control should display when the node is selected.

The following table describes the TreeView control’s most useful properties.

Open table as spreadsheet

Property	Purpose
BorderStyle	Determines the control’s border style.
CheckBoxes	Determines whether the control displays check boxes next to the nodes.
DrawMode	Determines whether your code draws nothing (the default), the nodes’ text, or the nodes’ text and lines.
FullRowSelect	Determines whether selection highlights span the whole width of the control.
HideSelection	Determines whether the selected node remains visibly highlighted even when the TreeView control loses the focus.
HotTracking	Determines whether node labels look like hyperlinks when the mouse moves over them.
ImageIndex	Determines the default image index for the nodes.
ImageList	Determines the ImageList control that contains the images used by the nodes.
Indent	Determines the indentation distance for each level in the tree.
ItemHeight	Determines the height of each node.
LabelEdit	Determines whether the user can edit the nodes’ labels.
LineColor	Determines the color of the lines connecting the nodes.
Nodes	Returns the collection of tree nodes.
PathSeparator	Determines the delimiter string used to represent paths in the tree. For example, using the default separator \, the path to the first person in Figure G-31 is R & D\Engineering\Cameron, Charlie.
Scrollable	Determines whether the control displays scroll bars when necessary.
SelectedImageIndex	Determines the default image index for the selected nodes.
SelectedNode	Determines the currently selected node.
ShowLines	Determines whether the control draws lines connecting the nodes.
ShowNodeToolTips	Determines whether the control displays tooltips when the mouse hovers over a node. Use the TreeNode objects’ ToolTipText properties to set the tooltip text.
ShowPlusMinus	Determines whether the control displays plus and minus signs next to tree nodes. The user can click the plus and minus signs or double-click the nodes to expand and collapse them.
ShowRootLines	Determines whether the control draws lines between the root nodes. In Figure G-31, ShowRootLines is True.
Sorted	Determines whether the control displays the nodes in sorted order.
TopNode	Returns the first node that is currently completely visible.
VisibleCount	Returns the number of nodes that could be fully visible. Fewer nodes may actually be visible if some are collapsed.

The TreeView control provides several methods that let your code manage the data at runtime. The fol-lowing table describes the most useful of these methods.

Open table as spreadsheet

Method	Purpose
CollapseAll	Collapses all of the control’s nodes.
ExpandAll	Expands all of the control’s nodes. In the process, the control scrolls down, so the last node is visible and selects the topmost visible control. To select some other control, such as the topmost root node, set the control’s SelectedNode property as in trvOrgChart.SelectedNode = trvOrg.Nodes(0).
GetNodeAt	Returns the TreeNode object at a specific (X, Y) location.
GetNodeCount	Returns the number of the tree’s nodes. If the method’s includeSubTrees parameter is False, the routine returns only the number of root nodes. If includeSubTrees is True, then the routine returns the total number of nodes in the tree.

The control provides a series of events that fire before and after the user takes certain actions. For example, when the user clicks a node’s check box, the control raises its BeforeCheck event, changes the node’s checked state, and then raises its AfterCheck event. The other actions that have similar Before and After event handlers are Collapse, Expand, LabelEdit, and Select.

Each of the Before event handlers provides a parameter that the code can set to cancel the event. For example, the following code shows how a program can prevent the user from editing the labels of the tree’s root nodes. When the user tries to edit a node’s label, the BeforeLabelEdit event fires. The value e.Node represents the node that the user is about to edit. Its FullPath property returns a delimited path showing the node’s position in the tree.

The code searches this path for the path separator character (normally \). If the node is a root node, then the separator is not in the path so the IndexOf method returns -1 and the code sets e.CancelEdit to True so the edit never occurs. If IndexOf finds the path separator in the node’s FullPath, the code leaves e.CancelEdit equal to False so the edit takes place as usual.

  Private Sub trvOrgChart_BeforeLabelEdit(ByVal sender As Object, _  ByVal e As System.Windows.Forms.NodeLabelEditEventArgs) _  Handles trvOrgChart.BeforeLabelEdit     e.CancelEdit = (e.Node.FullPath.IndexOf(trvOrgChart.PathSeparator) = -1) End Sub 

The TreeNode object also provides properties and methods if its own. The following table describes the TreeNode object’s most useful properties.

Open table as spreadsheet

Property	Purpose
Checked	Determines whether the node is checked, assuming that the TreeView control’s CheckBoxes property is True.
FirstNode	Returns the node’s first child node.
FullPath	Returns a string representing the node and its ancestors in the tree, delimited by the character specified by the TreeView control’s PathSeparator property.
ImageIndex	Determines the index of the node’s image in the ImageList control specified by the TreeView control’s ImageList property.
Index	Returns the node’s index within its parent node’s collection of children.
IsEditing	Indicates whether the user is editing the node’s label.
IsExpanded	Indicates whether the node is expanded.
IsSelected	Indicates whether the node is selected.
IsVisible	Indicates whether the node is at least partly visible.
LastNode	Returns the node’s last child node.
Level	Returns the node’s level in the tree. Root nodes have level 0, their children have level 1, the children of those nodes have level 2, and so forth.
NextNode	Returns the node’s next sibling node.
NextVisibleNode	Returns the next node that is not hidden because of a collapse. This may be a sibling, child, or some other node, depending on which nodes are expanded at the time. Note that this node may lie below the visible scrolling area, so it may not really be visible.
NodeFont	The font used to draw the node’s text. If the node’s font makes the text bigger than the TreeView control’s Font property does, then the text is clipped.
Nodes	The collection of this node’s child nodes.
Parent	Returns a reference to the node’s parent node in the tree.
PrevNode	Returns the node’s previous sibling node.
PrevVisibleNode	Returns the previous node that is not hidden because of a collapse. This may be a sibling, parent, or some other node, depending on which nodes are expanded at the time. Note that this node may be above the visible scrolling area, so it may not really be visible.
SelectedImageIndex	Determines the index of the node’s selected image in the ImageList control specified by the TreeView control’s ImageList property. The node displays this image while it is selected.
Text	Determines the text displayed in the node’s label.
ToolTipText	Determines the node’s tooltip text.
TreeView	Returns a reference to the TreeView control that contains the node.

The TreeNode object also provides several methods. The following table describes the most useful of these.

Open table as spreadsheet

Method	Purpose
BeginEdit	Begins editing of the node’s label. This raises an error if the TreeView control’s LabelEdit property is False.
Clone	Copies the node and its entire subtree.
Collapse	Collapses the node’s subtree.
EndEdit	Ends editing of the node’s label.
EnsureVisible	Expands nodes and scrolls the TreeView as necessary to ensure that the node is visible.
Expand	Expands the node to display its children.
ExpandAll	Expands the node’s whole subtree.
GetNodeCount	Returns the number of child nodes.
Remove	Removes the node and its subtree.
Toggle	Toggles the node between expanded and collapsed.