Version

IncludeCollapsedDescendantsOnRangeSelection Property (UltraTree)

Gets/sets a value which determines whether the descendants of collapsed nodes are selected when those collapsed nodes lie between the first and last node in a range selection. Applicable only when the SelectionBehavior property is set to a value other than 'UseOverride'.
Syntax
'Declaration
 
Public Property IncludeCollapsedDescendantsOnRangeSelection As Infragistics.Win.DefaultableBoolean
public Infragistics.Win.DefaultableBoolean IncludeCollapsedDescendantsOnRangeSelection {get; set;}
Remarks

The value of the IncludeCollapsedDescendantsOnRangeSelection property is only applicable to range (a.k.a., contiguous) selection, i.e., when the user selects by clicking a node while pressing the System.Windows.Forms.Keys.Shift key, or dragging the mouse.

In the case where a data bound node is part of the range selection, and IncludeCollapsedDescendantsOnRangeSelection is set to true, the act of selecting that node can trigger the population of its Nodes collection, as well as those of its descendants.

By default, nodes which are not visible in the user interface because an ancestor node is collapsed are not included in a range selection. Setting the IncludeCollapsedDescendantsOnRangeSelection property to true changes this behavior, so that all descendants of each node in a range selection (except for the last one) are selected along with their ancestors.

In the case where the user creates a range selection by clicking a node while pressing the Shift key, descendants of the node that was clicked are not selected, i.e., the clicked-on node is always the last node in the selection range. This is also true for the last node that is dragged to in a drag selection operation.

Listeners of the BeforeSelect event can override the behavior caused by the IncludeCollapsedDescendantsOnRangeSelection property by setting the BeforeSelectEventArgs.IncludeCollapsedDescendantsOnRangeSelection property. Note that the BeforeSelectEventArgs.NewSelections collection passed to the event handler only contain descendants of collapsed nodes when the control-level IncludeCollapsedDescendantsOnRangeSelection property is set to true.

Example
The following code sample demonstrates how to use the IncludeCollapsedDescendantsOnRangeSelection property to allow or prevent descendants of collapsed nodes to be selected when their ancesrots fall between the first and last nodes of a range selection:

Imports System.Collections.Generic
Imports Infragistics.Win
Imports Infragistics.Win.Misc.UltraWinTree

    Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
        '  Set the SelectionBehavior property to 'ExtendedAcrossCollections'
        '  to allow nodes from different collections to be selected concurrently.
        Me.ultraTree1.SelectionBehavior = SelectionBehavior.ExtendedAcrossCollections

        '  Add nodes to the tree
        Me.PopulateTree(Me.ultraTree1)

        '  Determine the deepest level 
        Dim deepestLevel As Integer = Me.GetDeepestLevel(Me.ultraTree1)

        '  Only allow selection of leaf nodes
        Me.AllowSelectionOnLevel(Me.ultraTree1, deepestLevel)
    End Sub

    Private Sub PopulateTree(ByVal treeControl As UltraTree)
        Try

            treeControl.BeginUpdate()
            treeControl.Nodes.Clear()

            Dim i As Integer
            For i = 0 To 2

                Dim text As String = String.Format("Root {0}", i)
                Dim rootNode As UltraTreeNode = treeControl.Nodes.Add(Nothing, text)
                Me.PopulateNodes(rootNode.Nodes, 1)
            Next

        Finally
            treeControl.EndUpdate()
        End Try

        treeControl.ExpandAll()

    End Sub

    Private Sub PopulateNodes(ByVal nodesCollection As TreeNodesCollection, ByVal level As Integer)

        If (level > 3) Then Return

        Dim parentNode As UltraTreeNode = nodesCollection.ParentNode

        Dim i As Integer
        For i = 0 To 2

            Dim text As String = String.Format("{0}\Node {1}", parentNode.Text, i)
            Dim node As UltraTreeNode = nodesCollection.Add(Nothing, text)

            If (level < 3) Then
                Me.PopulateNodes(node.Nodes, level + 1)
            End If
        Next

    End Sub


    Private Sub ultraTree1_BeforeSelect(ByVal sender As System.Object, ByVal e As BeforeSelectEventArgs) Handles ultraTree1.BeforeSelect
        '  Iterate the members of the new selection and check
        '  the level of each node to determine which levels are
        '  included in the selection.
        Dim selectedNodes As SelectedNodesCollection = e.NewSelections
        Dim levels As New List(Of Integer)
        Dim i As Integer
        For i = 0 To selectedNodes.Count - 1

            Dim node As UltraTreeNode = selectedNodes(i)

            Dim level As Integer = node.Level
            If levels.Contains(level) = False Then levels.Add(level)
        Next

        '  If there are no root level nodes selected, allow descendants
        '  of collapsed nodes to be selected.
        If (levels.Contains(0) = False) Then
            e.IncludeCollapsedDescendantsOnRangeSelection = True
        End If

    End Sub
using System.Collections.Generic;
using Infragistics.Win;
using Infragistics.Win.Misc.UltraWinTree;

    private void Form1_Load(object sender, EventArgs e)
    {
        //  Set the SelectionBehavior property to 'ExtendedAcrossCollections'
        //  to allow nodes from different collections to be selected concurrently.
        this.ultraTree1.SelectionBehavior = SelectionBehavior.ExtendedAcrossCollections;

        //  Set the IncludeCollapsedDescendantsOnRangeSelection property to false
        //  so that descendants of collapsed nodes are not selected by default.
        this.ultraTree1.IncludeCollapsedDescendantsOnRangeSelection = DefaultableBoolean.False;

        //  Add nodes to the tree
        this.PopulateTree( this.ultraTree1 );
    }

    private void PopulateTree( UltraTree treeControl, bool expandAll )
    {
        try
        {
            treeControl.BeginUpdate();

            treeControl.Nodes.Clear();

            for ( int i = 0; i < 3; i ++ )
            {
                string text = string.Format( "Root {0}", i );
                UltraTreeNode rootNode = treeControl.Nodes.Add( null, text );
                this.PopulateNodes( rootNode.Nodes, 1 );
            }

            if ( expandAll )
                this.ultraTree1.ExpandAll();
        }
        finally
        {
            treeControl.EndUpdate();
        }
    }

    private void PopulateNodes( TreeNodesCollection nodesCollection, int level )
    {
        if ( level > 3 )
            return;

        UltraTreeNode parentNode = nodesCollection.ParentNode;

        for ( int i = 0; i < 3; i ++ )
        {
            string text = string.Format( @"{0}\Node {1}", parentNode.Text, i );
            UltraTreeNode node = nodesCollection.Add( null, text );
            
            if ( level < 3 )
                this.PopulateNodes( node.Nodes, level + 1 );
        }            
    }

    private void ultraTree1_BeforeSelect(object sender, BeforeSelectEventArgs e)
    {
        //  Iterate the members of the new selection and check
        //  the level of each node to determine which levels are
        //  included in the selection.
        SelectedNodesCollection selectedNodes = e.NewSelections;
        List<int> levels = new List<int>();
        for ( int i = 0; i < selectedNodes.Count; i ++ )
        {
            UltraTreeNode node = selectedNodes[i];

            int level = node.Level;
            if ( levels.Contains(level) == false )
                levels.Add(level);
        }

        //  If there are no root level nodes selected, allow descendants
        //  of collapsed nodes to be selected.
        if ( levels.Contains(0) == false )
            e.IncludeCollapsedDescendantsOnRangeSelection = true;
    }
Requirements

Target Platforms: Windows 10, Windows 8.1, Windows 8, Windows 7, Windows Server 2012, Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

See Also