This documentation is archived and is not being maintained.

TreeView.CheckBoxes Property

Gets or sets a value indicating whether check boxes are displayed next to the tree nodes in the tree view control.

Namespace: System.Windows.Forms
Assembly: System.Windows.Forms (in system.windows.forms.dll)

'Declaration
Public Property CheckBoxes As Boolean
'Usage
Dim instance As TreeView
Dim value As Boolean

value = instance.CheckBoxes

instance.CheckBoxes = value
/** @property */
public boolean get_CheckBoxes ()

/** @property */
public void set_CheckBoxes (boolean value)

public function get CheckBoxes () : boolean

public function set CheckBoxes (value : boolean)

Property Value

true if a check box is displayed next to each tree node in the tree view control; otherwise, false. The default is false.

A check box is displayed to the left of both the tree node label and tree node Image, if any. Check boxes allow the user to select more than one tree node at a time.

When the CheckBoxes property of a TreeView is set to true, and the StateImageList property is set, each TreeNode contained in the TreeView will display the first and second images from the StateImageList to indicate an unchecked or checked state, respectively. However, the displayed images may be different if the following situation occurs: If the SelectedImageIndex of the node is set to a value other than 0 or 1, and the CheckBoxes property of the parent TreeView is set to false, the SelectedImageIndex will not automatically reset to -1 to indicate it is not set. In this case, the state image at the indicated index position is shown. If CheckBoxes is set to true again, the first and second images of the StateImageList are shown to indicate a checked or unchecked state, respectively.

NoteNote

When setting the CheckBoxes property at run time, the TreeView handle is recreated (see Control.RecreateHandle) to update the control's appearance. This causes all tree nodes to be collapsed, with the exception of the selected TreeNode.

The following code example demonstrates how to change the collapse state of a TreeView so that all the checked nodes are visible. First, all the nodes are collapsed, and a handler is added for the BeforeExpand event. Next, all the nodes are expanded. The BeforeExpand event handler determines whether a given node has child nodes that are checked. If a node does not have checked children, the expansion is canceled for that node. In order to allow standard node expansion when the plus sign next to a node is clicked, the BeforeExpand event handler is then removed.

This behavior can also be implemented by handling the BeforeCollapse event, as illustrated in the example for that topic.

Imports System
Imports System.Drawing
Imports System.Windows.Forms

Public Class Form1
    Inherits Form
    Private treeView1 As TreeView
    Private showCheckedNodesButton As Button

    Public Sub New()
        treeView1 = New TreeView
        showCheckedNodesButton = New Button

        Me.SuspendLayout()

        ' Initialize treeView1.
        treeView1.Location = New Point(0, 25)
        treeView1.Size = New Size(292, 248)
        treeView1.Anchor = AnchorStyles.Top Or AnchorStyles.Left Or AnchorStyles.Bottom Or AnchorStyles.Right
        treeView1.CheckBoxes = True

        ' Add nodes to treeView1.
        Dim node As TreeNode
        Dim x As Integer
        For x = 0 To 3
            ' Add a root node.
            node = treeView1.Nodes.Add(String.Format("Node{0}", x * 4))
            Dim y As Integer
            For y = 1 To 4
                ' Add a node as a child of the previously added node.
                node = node.Nodes.Add(String.Format("Node{0}", x * 4 + y))
            Next y
        Next x

        ' Set the checked state of one of the nodes to
        ' demonstrate the showCheckedNodesButton button behavior.
        treeView1.Nodes(1).Nodes(0).Nodes(0).Checked = True

        ' Initialize showCheckedNodesButton.
        showCheckedNodesButton.Size = New Size(144, 24)
        showCheckedNodesButton.Text = "Show Checked Nodes"
        AddHandler showCheckedNodesButton.Click, AddressOf showCheckedNodesButton_Click

        ' Initialize the form.
        Me.ClientSize = New Size(292, 273)
        Me.Controls.AddRange(New Control() {showCheckedNodesButton, treeView1})

        Me.ResumeLayout(False)
    End Sub 'New

    <STAThreadAttribute()> _
    Shared Sub Main()
        Application.Run(New Form1)
    End Sub 'Main

    Private Sub showCheckedNodesButton_Click(ByVal sender As Object, ByVal e As EventArgs)
        ' Disable redrawing of treeView1 to prevent flickering 
        ' while changes are made.
        treeView1.BeginUpdate()

        ' Collapse all nodes of treeView1.
        treeView1.CollapseAll()

        ' Add the CheckForCheckedChildren event handler to the BeforeExpand event.
        AddHandler treeView1.BeforeExpand, AddressOf CheckForCheckedChildren

        ' Expand all nodes of treeView1. Nodes without checked children are 
        ' prevented from expanding by the checkForCheckedChildren event handler.
        treeView1.ExpandAll()

        ' Remove the checkForCheckedChildren event handler from the BeforeExpand 
        ' event so manual node expansion will work correctly.
        RemoveHandler treeView1.BeforeExpand, AddressOf CheckForCheckedChildren

        ' Enable redrawing of treeView1.
        treeView1.EndUpdate()
    End Sub 'showCheckedNodesButton_Click

    ' Prevent expansion of a node that does not have any checked child nodes.
    Private Sub CheckForCheckedChildren(ByVal sender As Object, ByVal e As TreeViewCancelEventArgs)
        If Not HasCheckedChildNodes(e.Node) Then
            e.Cancel = True
        End If
    End Sub 'CheckForCheckedChildren

    ' Returns a value indicating whether the specified 
    ' TreeNode has checked child nodes.
    Private Function HasCheckedChildNodes(ByVal node As TreeNode) As Boolean
        If node.Nodes.Count = 0 Then
            Return False
        End If
        Dim childNode As TreeNode
        For Each childNode In node.Nodes
            If childNode.Checked Then
                Return True
            End If
            ' Recursively check the children of the current child node.
            If HasCheckedChildNodes(childNode) Then
                Return True
            End If
        Next childNode
        Return False
    End Function 'HasCheckedChildNodes

End Class 'Form1 

import System.*;
import System.Drawing.*;
import System.Windows.Forms.*;

public class Form1 extends Form
{
    private TreeView treeView1;
    private Button showCheckedNodesButton;
    private TreeViewCancelEventHandler checkForCheckedChildren;

    public Form1()
    {
        treeView1 = new TreeView();
        showCheckedNodesButton = new Button();
        checkForCheckedChildren =
            new TreeViewCancelEventHandler(CheckForCheckedChildrenHandler);

        this.SuspendLayout();
        // Initialize treeView1.
        treeView1.set_Location(new Point(0, 25));
        treeView1.set_Size(new Size(292, 248));
        treeView1.set_Anchor(AnchorStyles.Top | AnchorStyles.Left
            | AnchorStyles.Bottom | AnchorStyles.Right);
        treeView1.set_CheckBoxes(true);
        // Add nodes to treeView1.
        TreeNode node;
        for (int x = 0; x < 3; ++x) {
            // Add a root node.
            node = treeView1.get_Nodes().Add(String.Format
                ("Node{0}", (Int32)(x * 4)));
            for (int y = 1; y < 4; ++y) {
                // Add a node as a child of the previously added node.
                node = node.get_Nodes().Add(String.Format
                    ("Node{0}", (Int32)(x * 4 + y)));
            }
        }
        // Set the checked state of one of the nodes to
        // demonstrate the showCheckedNodesButton button behavior.
        treeView1.get_Nodes().get_Item(1).get_Nodes().get_Item(0).
            get_Nodes().get_Item(0).set_Checked(true);
        // Initialize showCheckedNodesButton.
        showCheckedNodesButton.set_Size(new Size(144, 24));
        showCheckedNodesButton.set_Text("Show Checked Nodes");
        showCheckedNodesButton.add_Click(
            new EventHandler(showCheckedNodesButton_Click));
        // Initialize the form.
        this.set_ClientSize(new Size(292, 273));
        this.get_Controls().AddRange(new Control[]
            { showCheckedNodesButton, treeView1 });

        this.ResumeLayout(false);
    } //Form1

    public static void main(String[] args)
    {
        Application.Run(new Form1());
    } //main

    private void showCheckedNodesButton_Click(Object sender, EventArgs e)
    {
        // Disable redrawing of treeView1 to prevent flickering 
        // while changes are made.
        treeView1.BeginUpdate();
        // Collapse all nodes of treeView1.
        treeView1.CollapseAll();
        // Add the checkForCheckedChildren event handler to the
        // BeforeExpand event.
        treeView1.add_BeforeExpand(checkForCheckedChildren);
        // Expand all nodes of treeView1. Nodes without checked children are 
        // prevented from expanding by the checkForCheckedChildren event handler.
        treeView1.ExpandAll();
        // Remove the checkForCheckedChildren event handler from
        // the BeforeExpand 
        // event so manual node expansion will work correctly.
        treeView1.remove_BeforeExpand(checkForCheckedChildren);
        // Enable redrawing of treeView1.
        treeView1.EndUpdate();
    } //showCheckedNodesButton_Click

    // Prevent expansion of a node that does not have any checked child nodes.
    private void CheckForCheckedChildrenHandler(Object sender,
        TreeViewCancelEventArgs e)
    {
        if (!(HasCheckedChildNodes(e.get_Node()))) {
            e.set_Cancel(true);
        }
    } //CheckForCheckedChildrenHandler

    // Returns a value indicating whether the specified 
    // TreeNode has checked child nodes.
    private boolean HasCheckedChildNodes(TreeNode node)
    {
        if (node.get_Nodes().get_Count() == 0) {
            return false;
        }
        for (int iCtr = 0; iCtr < node.get_Nodes().get_Count(); iCtr++) {
            TreeNode childNode = node.get_Nodes().get_Item(iCtr);
            if (childNode.get_Checked()) {
                return true;
            }
            // Recursively check the children of the current child node.
            if (HasCheckedChildNodes(childNode)) {
                return true;
            }
        }
        return false;
    } //HasCheckedChildNodes
} //Form1

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0
Show: