The Spotlight on Controls series describes the controls, that is, the objects in the System.Windows.Forms namespace, so you can use them effectively when building GUI apps in PowerShell Studio and PrimalScript.

Each post focuses on one control and lists its most important properties, methods, and events, including the default event that PowerShell Studio adds to your script when you double-click the control. The posts include many examples written in Windows PowerShell, so you can use them right away.

Read more: Spotlight on Controls: Common properties and methods

This two-part post describes the TreeView control.

• Part 1: TreeView Overview
• Part 2: TreeNode Overview

TreeView [System.Windows.Forms.TreeView]

Displays a hierarchical collection of labeled items, each of which is represented by a TreeNode.

• MSDN Page: System.Windows.Forms.TreeView
• Default Event: AfterSelect

 

Default Event: AfterSelect

Why use a TreeView control?

When it comes to displaying hierarchical information such as a folder structure, the TreeView control is a perfect choice. In addition, the TreeView allows users to rename tree nodes which can be useful in many instances. The TreeView also serves as a good navigation tool.

Important Properties:

CheckBoxes

This property indicates whether check boxes are displayed next to the tree nodes in the tree view control.

This property can be useful if you want the user to pick multiple nodes by checking them. Note: Checked nodes are not treated as if they are “selected”. We will cover how to determine which nodes are checked by the user in Part 2.

Default Value: False

ContextMenuStrip

This property sets the shortcut menu associated with the control.

Use this property to select an existing ContextMenuStrip.The ContextMenuStrip will be featured in a future Spotlight on Control article. The context menu will appear when TreeView is right clicked. Part 2 will cover how to add specific context menus for nodes.

HideSelection

This property indicates whether the selected tree node remains highlighted even when the tree view has lost the focus such as when another control is selected.

Default Value: True

Selection with Focus:

Selection without Focus and HideSelection is set to False:

 

ImageList

This property  sets the ImageList that contains the Image objects that are used by the tree nodes. (See the Spotlight on the ImageList Control blog article for more details.)

ImageIndex

This property indicates the default image index value that is displayed by the tree nodes.

SelectedImageIndex

This property indicates the default image index value that is displayed when a tree node is selected.

StateImageList

This property sets the ImageList that is used to indicate the state of the TreeView and its nodes.  This image is displayed next to the imaged specified by the ImageIndex and SelectedImageIndex. See Part 2 for more details.

 

LabelEdit

This property indicates whether the label text of the tree nodes can be edited. This can be useful when you wish to allow the user to rename an object such as a file.

Default Value: False

When a user edits a label, various events are called that allow you to prevent or reject the changed label. See the BeforeLabeEdit and AfterLabelEdit events before for more details.

ShowLines

This property indicates whether lines are drawn between tree nodes in the tree view control.

Default Value: True

The lines are hidden when ShowLines is set to False:

ShowNodeToolTips

This property indicates whether ToolTips are shown when the mouse pointer hovers over a TreeNode. Displaying tooltips can be helpful in providing users with hints about what the node represents.

Default Value: False

Refer to Part 2 to see how to set a node’s tooltip.

ShowPlusMinus

This property indicates whether plus-sign (+) and minus-sign (-) buttons are displayed next to tree nodes that contain child tree nodes.

Default Value: True

When ShowPlusMinus is set to False, the plus/minus buttons are hidden but you can still expand and collapse the node by double clicking on it. To disable this behavior please refer to the BeforeExpand / BeforeCollapse events below.

ShowRootLines

This property indicates whether lines are drawn between the tree nodes that are at the root of the tree view.

Default Value: True

When the ShowRootLines is set to False, the root node does not display either a line or the plus or minus button.

 

Nodes

This property contains the collection of tree nodes that are assigned to the tree view control.

Use this property to add or remove nodes. Part 2 will examine this property in more detail.

SelectedNode

This property get or sets the tree node that is currently selected in the tree view control.

Example of how to select the first root node via Script Editor:

$treeview1.SelectedNode = $treeview1.Nodes[0]

 

Important Methods:

CollapseAll

This method collapses all the tree nodes.

$treeview1.CollapseAll()

ExpandAll

This method expands all the tree nodes.

$treeview1.ExpandAll()

Sort

This method sorts all the nodes in TreeView control.

$treeview1.Sort()

Before Sort:

After Sort:

Important Events:

After Events:

The ‘After’ events listed below, except AfterLabelEdit, have the following as an argument that is accessible via the $_ variable:

[System.Windows.Forms.TreeViewEventArgs]

Properties
Action	Gets the type of action that raised the event. Values: Unknown The action that caused the event is unknown. ByKeyboard The event was caused by a keystroke. ByMouse The event was caused by a mouse operation. Collapse The event was caused by the TreeNode collapsing. Expand The event was caused by the TreeNode expanding.
Node	Gets the tree node that has been checked, expanded, collapsed, or selected.

 

AfterCheck

This event occurs after the tree node check box is checked or unchecked.

AfterCollapse

This event occurs after the tree node is collapsed.

AfterExpand

This event occurs after the tree node is expanded.

AfterLabelEdit

This event occurs after the tree node label text is edited. Label editing must be enabled for this event to be called (See LabelEdit property).

AfterLabelEdit event uses the following argument:

[System.Windows.Forms.NodeLabelEditEventArgs]

Properties
CancelEdit	Gets or sets a value indicating whether the edit has been canceled.
Label	Gets the new text to associate with the tree node.
Node	Gets the tree node that has been checked, expanded, collapsed, or selected.

 

Use this event to react to name changes. For example if the Node represents a file, you can use this event as a trigger for renaming the file. You should also perform any validation and reject the name change if there is a failure.

$treeview1_AfterLabelEdit=[System.Windows.Forms.NodeLabelEditEventHandler]{
#Event Argument: $_ = [System.Windows.Forms.NodeLabelEditEventArgs]
    if(-not (Validate-FileName $_.Label))
    {
        $_.CancelEdit = $true
    }
    else
    {
        #Rename the file
    }
}

 

AfterSelect

This event occurs after the tree node is selected.

This event is useful if you are using the TreeView as a form of navigation.

$treeview1_AfterSelect=[System.Windows.Forms.TreeViewEventHandler]{
#Event Argument: $_ = [System.Windows.Forms.TreeViewEventArgs]
    Write-Host 'Node Selected: ' $_.Node.Text
}

 

Before Events:

The  ‘Before’ events listed below, except BeforeLabelEdit, have the following as an argument that is accessible via the $_ variable:

[System.Windows.Forms.TreeViewCancelEventArgs]

Properties
Action	Gets the type of action that raised the event. Values: Unknown The action that caused the event is unknown. ByKeyboard The event was caused by a keystroke. ByMouse The event was caused by a mouse operation. Collapse The event was caused by the TreeNode collapsing. Expand The event was caused by the TreeNode expanding.
Cancel	Gets or sets a value indicating whether the event should be canceled. To cancel the event, set this property to True.
Node	Gets the tree node that has been checked, expanded, collapsed, or selected.

 

BeforeCheck

This event occurs before the tree node check box is checked.

Use this event to cancel the check action:

$treeview1_BeforeCheck=[System.Windows.Forms.TreeViewCancelEventHandler]{
#Event Argument: $_ = [System.Windows.Forms.TreeViewCancelEventArgs]
    if($_.Node.Checked)
    { # Prevent node from unchecking
        $_.Cancel = $true
    }
}

 

BeforeCollapse

This event occurs before the tree node is collapsed.

Use this event to cancel the action.

BeforeExpand

This event occurs before the tree node is expanded.

Use this event to cancel the action.

BeforeLabelEdit

This event occurs before the tree node label text is edited. Label editing must be enabled for this event to be called (See LabelEdit property).

This event uses the [System.Windows.Forms.NodeLabelEditEventArgs] argument. See AfterLabelEdit for more information about this argument.

Use this event to prevent users from renaming specific nodes.

BeforeSelect

This event occurs before the tree node is selected.

You can use this event to prevent specific nodes from being selected.

Click Events:

The ‘Click’ events have the following as an argument that is accessible via the $_ variable:

[System.Windows.Forms.TreeNodeMouseClickEventArgs]

Properties
Button	Gets which mouse button was pressed. Values: Left The left mouse button was pressed. None No mouse button was pressed. Right The right mouse button was pressed. Middle The middle mouse button was pressed.
Clicks	Gets the number of times the mouse button was pressed and released.
Location	Gets the location of the mouse during the generating mouse event.
Node	Gets the node that was clicked.

 

NodeMouseClick

This event occurs when the user clicks a TreeNode with the mouse.

Example:

$treeview1_NodeMouseClick=[System.Windows.Forms.TreeNodeMouseClickEventHandler]{
#Event Argument: $_ = [System.Windows.Forms.TreeNodeMouseClickEventArgs]
    if($_.Button -eq 'Right')
    {
        Write-Host "Right Click Node: " $_.Node.Text
        $this.SelectedNode = $_.Node #Select the node (Helpful when using a ContextMenuStrip)
    }
}

 

NodeMouseDoubleClick

Occurs when the user double-clicks a TreeNode with the mouse.

$treeview1_NodeMouseDoubleClick=[System.Windows.Forms.TreeNodeMouseClickEventHandler]{
#Event Argument: $_ = [System.Windows.Forms.TreeNodeMouseClickEventArgs]
    Write-Host "Double Click " $_.Node.Text
}

 

Next: Spotlight on the TreeView Control – Part 2