windowsforms-206-controls-and-libraries-tree-list-feature-center-focus-selection-and-navigation-node-selection.md
You can enable node selection to allow multiple nodes to be selected. Selected nodes are highlighted in a specific manner, indicating their states. You can access these nodes in code and process them, if required.
Note that selected nodes are different from focused nodes. The focused node specifies the node containing focus. (There is only one focused node.) In node selection mode, when a node is focused by an end user, it is automatically selected - but a user can click the focused node with the CTRL key pressed to deselect it. See the following help topic to learn more: Focus and Navigation.
To enable node selection, set the TreeListOptionsSelection.MultiSelect property to true. In node selection mode, you or an end user can select contiguous and non-contiguous node ranges.
Selected nodes are highlighted in a specific manner. You can use the TreeListAppearanceCollection.SelectedRow property to customize the appearance of selected nodes. The TreeListAppearanceCollection.HideSelectionRow property specifies the appearance of selected nodes, when the Tree List control is not focused.
If the TreeListOptionsSelection.KeepSelectedOnClick option is active, selection is preserved while editing cells within the selected nodes.
To use the mouse pointer to select multiple nodes, an end user must press the SHIFT or CTRL key, and click the desired nodes. To select a continuous range of nodes, click the first node of the range. Then, hold the SHIFT key down and click the last node of the range. To select a specific node (and add it to the existing selection), click it with the CTRL key pressed.
When you click a node while pressing the CTRL key, the node’s selected state is toggled (i.e., the state changes from selected to deselected, and vice-versa).
If the UseIndicatorForSelection option is enabled, a user can utilize the node indicator panel to select nodes as follows:
For other approaches to selecting nodes, see the following help topic: Selecting Nodes.
Handle the TreeList.SelectionChanging event to control whether users can select and unselect nodes.
The following code sample does not allow users to select root nodes:
treeList.SelectionChanging += (s, e) => {
e.Cancel = e.Action == CollectionChangeAction.Add && e.Node.Level == 0;
};
treeList.SelectionChanging += Function(s, e)
e.Cancel = e.Action = CollectionChangeAction.Add AndAlso e.Node.Level = 0
End Function
The TreeList control highlights selected nodes with specific background and foreground colors. The actual colors depend on the currently applied skin. You can use the SelectedRow appearance settings to override default background and foreground colors for selected rows.
Note that appearance settings are applied to various visual elements: rows, focused row, focused cell, etc. Appearance settings are prioritized from more common visual elements and states (for example, non-focused rows) to more specific elements and states (for example, focused cells). You can use the HighPriority property to prioritize appearance settings for a specific visual element or state. For example, you can prioritize a specific column’s cell appearance settings. See the following help topic for more information about skins and appearance settings: Application Appearance and Skin Colors.
To specify appearance settings for a particular cell, handle the NodeCellStyle event. You can also specify appearance settings in the CustomDrawRow and CustomDrawNodeCell events that fire before a row or cell is painted on-screen. Appearance settings in these events have the highest priority.
Tip
DevExpress controls support consistent UIs and APIs within similar features. You can use the same approach to customize appearances in the Gantt Control, Data Grid, and Vertical Grid.
Example 1 - Prioritize cell selection appearances
treeList.NodeCellStyle += (s, e) => {
TreeList tl = s as TreeList;
if(tl.IsCellSelected(e.Node, e.Column))
e.Appearance.BackColor = tl.ViewInfo.PaintAppearance.SelectedRow.BackColor;
};
AddHandler treeList.NodeCellStyle, Sub(s, e)
Dim tl As TreeList = TryCast(s, TreeList)
If tl.IsCellSelected(e.Node, e.Column) Then
e.Appearance.BackColor = tl.ViewInfo.PaintAppearance.SelectedRow.BackColor
End If
End Sub
Tip
Run the following demo to see the result: Prioritize cell selection appearances.
Example 2 - Disable focused cell highlight
treeList.OptionsBehavior.Editable = false;
// Prevent the focused cell from being highlighted.
treeList.OptionsSelection.EnableAppearanceFocusedCell = false;
treeList.OptionsBehavior.Editable = False
' Prevent the focused cell from being highlighted.
treeList.OptionsSelection.EnableAppearanceFocusedCell = False
Tip
Run the following demo to see the result: Disable focused cell highlight.
Example 3 - Appearance of nodes (dynamically)
treeList.NodeCellStyle += (s, e) => {
TreeList tl = s as TreeList;
//Change selected rows' fore and back colors
bool mark = (bool)e.Node.GetValue(tl.Columns["Mark"]);
if(mark) {
if(tl.FocusedNode == e.Node)
e.Appearance.BackColor = tl.ViewInfo.PaintAppearance.SelectedRow.BackColor;
else {
e.Appearance.ForeColor = foreColor;
e.Appearance.BackColor = backColor;
}
}
};
AddHandler treeList.NodeCellStyle, Sub(s, e)
Dim tl As TreeList = TryCast(s, TreeList)
'Change selected rows' fore and back colors
Dim mark As Boolean = CBool(e.Node.GetValue(tl.Columns("Mark")))
If mark Then
If tl.FocusedNode = e.Node Then
e.Appearance.BackColor = tl.ViewInfo.PaintAppearance.SelectedRow.BackColor
Else
e.Appearance.ForeColor = foreColor
e.Appearance.BackColor = backColor
End If
End If
End Sub
Tip
Run the following demo to see the result: Appearances of nodes (dynamically)
Use the TreeList.Selection property to access the collection of currently selected nodes. You can add nodes to the collection to select them. To deselect the nodes, remove them from the collection.
You can also call the SelectNode, SelectNodes, UnselectNode and UnselectNodes methods to toggle node selection.
To respond to a change in node selection, you can handle the TreeList.SelectionChanged event.
The following code demonstrates how to traverse through selected nodes, in order to expand them. The selected nodes are accessed via the TreeList.Selection property.
for(int i = 0; i < treeList1.Selection.Count; i++) {
treeList1.Selection[i].Expanded = true;
}
Dim i As Integer
For i = 0 To TreeList1.Selection.Count - 1
TreeList1.Selection(i).Expanded = True
Next i
The following code shows how to select children of a specific node. In the example, nodes are selected via the TreeListMultiSelection.Set method of the TreeList.Selection object.
The image below shows the result of selecting a Sales and Marketing node’s children.
using DevExpress.XtraTreeList.Nodes;
TreeListNode node = treeList1.FindNodeByFieldValue("Department", "Sales and Marketing");
if (node != null) {
ArrayList selectedNodes = new ArrayList();
selectChildren(node, selectedNodes);
treeList1.Selection.Set(selectedNodes);
}
void selectChildren(TreeListNode parent, ArrayList selectedNodes) {
IEnumerator en = parent.Nodes.GetEnumerator();
TreeListNode child;
while(en.MoveNext()) {
child = (TreeListNode)en.Current;
selectedNodes.Add(child);
if(child.HasChildren) selectChildren(child, selectedNodes);
}
}
Imports DevExpress.XtraTreeList.Nodes
Dim node As TreeListNode = treeList1.FindNodeByFieldValue("Department", "Sales and Marketing")
If node IsNot Nothing Then
Dim selectedNodes As New ArrayList()
selectChildren(node, selectedNodes)
treeList1.Selection.[Set](selectedNodes)
End If
Sub SelectChildren(ByVal parent As TreeListNode, ByVal selectedNodes As ArrayList)
Dim en As IEnumerator = parent.Nodes.GetEnumerator()
Dim child As TreeListNode
While en.MoveNext() = True
child = CType(en.Current, TreeListNode)
selectedNodes.Add(child)
If child.HasChildren = True Then
selectChildren(child, selectedNodes)
End If
End While
End Sub
See Also