Keyboard Support
RadTreeView allows you to navigate through the nodes without using the mouse. The keyboard can entirely replace the mouse by allowing you to perform navigation, editing, expanding, collapsing and selecting the nodes.
Keys List
RadTreeView provides support for the following keys:
Arrow Keys (Up, Down, Left and Right): Up and Down navigate through the items and change the selection. Left and Right, collapse and expand the selected node.
PageUp and PageDown: Scroll the visible area up or down with an offset that equals the viewport (visible area) size. This action changes the selected item.
End and Home: Go to the first or last RadTreeViewItem and selects it.
Enter: If the selected item is in edit mode - commits the changes. Otherwise, toggles collapsed/expanded state.
Esc: If the selected item is in edit mode - cancels the edit. If the drag operation is in progress it cancels it.
Multiply: Expands all child items of the selected item.
Divide - Collapses all child items of the selected item.
Add and Substract: Expand/collapses the selected item.
F2 and Space: Starts edit mode.
Ctrl and Shift: Selects multiple item selection while holding Ctrl or Shift and clicking on items with the mouse.
RadTreeView exposes several useful properties and events, which can help you control the keyboard interaction and get notified when a key is up or down.
Properties
Set the IsTabStop property to include/exclude the control in the tab navigation cycle. If this property is set to True, then the control will be included; if it is False then it will be skipped.
The TabIndex property defines the index of the control in the tab navigation cycle. The lower the number is, the earlier the control will be focused while navigating using the Tab key. If you set this property, do not forget to set IsTabStop to True. Once focused, you can navigate through the tab pages using the left and the right arrow keys.
Events
- KeyDown: Get notofied when the user has pressed a keyboard key.
- KeyUp: Get notified when the user has released a keyboard key.
To obtain the pressed key, the object that raised the event or some other information, use the instance of System.Windows.Input.KeyEventArgs passed as a parameter to the event handler method.
In the example below you can see how to attach to KeyDown and KeyUp events and how to specify a value for the TabNavigation property from your XAML.
Example 1: Subscribing to the KeyDown and KeyUp events
<telerik:RadTreeView x:Name="radTreeView" KeyDown="radTreeView_KeyDown" KeyUp="radTreeView_KeyUp"/>
The implementation of both of the event handlers radTreeView_KeyDown and radTreeView_KeyUp is located in the code-behind file (C# or VB.NET) and looks like in Example 2.
Example 2: Handling the KeyDown and KeyUp events
private void radTreeView_KeyDown( object sender, KeyEventArgs e )
{
MessageBox.Show( "The pressed key is: " + e.Key.ToString() );
}
private void radTreeView_KeyUp( object sender, KeyEventArgs e )
{
MessageBox.Show( "The released key is: " + e.Key.ToString() );
}
Private Sub radTreeView_KeyDown(ByVal sender As Object, ByVal e As KeyEventArgs)
MessageBox.Show("The pressed key is: " & e.Key.ToString())
End Sub
Private Sub radTreeView_KeyUp(ByVal sender As Object, ByVal e As KeyEventArgs)
MessageBox.Show("The released key is: " & e.Key.ToString())
End Sub
Keyboard Selection
More information on the IsSelectable property of RadTreeViewItem can be found in the Selection topic. The IsSelectable property is available since the R3 2018 version.
By default, navigating through the keyboard will select the given RadTreeViewItem. It exposes the IsSelectable property through which this default behavior can be altered. Let's have the following example. In it the first item is selected and the second one has its IsSelectable property set to False.
Figure 1: RadTreeView with its first item selected
When pressing the Down arrow key in this case the end result will be as follows.
Figure 2: RadTreeView with the IsSelectable of the second item set to False
Text Search Navigation
RadTreeView allows you to navigate through items by typing on the keyboard while the control is focused. This will search and select the corresponding item.
To enable the feature, set the IsTextSearchEnabled property to True.
To change the search mode that is used to match the results, set the TextSearchMode property. This allows you to set one of the following modes:
- StartsWith: This is the default mode.
- Contains
- StartsWithCaseSensitive
- ContainsCaseSensitive
You can also utilize the IsTextSearchCaseSensitive property of RadTreeView in order to determinne if the search is case sensitive.
Example 3: Setting up text search navigation
<telerik:RadTreeView IsTextSearchEnabled="True" TextSearchMode="Contains" />
When data binding the RadTreeView's ItemsSource property to a collection of business objects, you should set the TextSearch.TextPath attached property in order to tell what property should be used for the text search.
Example 4: Setting TextPath
<telerik:RadTreeView IsTextSearchEnabled="True" telerik:TextSearch.TextPath="MyProperty" />
In Example 4 MyProperty points to a property defined in the view model of the treeview items. If the type text matches the value of this property, the corresponding item will get selected.
To increase the time interval for typing before the text is reset, set the TextSearch.AutoCompleteTimeout static property.
Example 5: Setting search text reset timeout
public MyUserControl()
{
Telerik.Windows.Controls.TextSearch.AutoCompleteTimeout = new TimeSpan(1500);
InitializeComponent();
}
Note that this property is used in several other Telerik controls and setting it will affect them as well.