Search and Filter Nodes
- 7 minutes to read
The TreeViewControl allows you and application users to search and filter data. This topic describes the following related aspects:
- The built-in UI that makes user search operations possible
- The settings that customize the built-in UI and search operation behavior
- Ways to search and filter nodes in code
Search Panel
The TreeViewControl can display the Search Panel that allows users to search and filter data. Set the ShowSearchPanel property to true to display the Search Panel.
Highlight and Filter Search Results
Once a user enters text in the Search Panel, the control’s default response includes two parts:
- Highlight search results. You can set SearchPanelHighlightResults to false to disable this default behavior.
- Filter out nodes that do not match the search text. Set the SearchPanelAllowFilter property to false to disable this default behavior and display all nodes.
Search Panel UI
- Search String
- A user specifies a search string in the Search Panel. Use the SearchString property to specify a search string in code.
- Null Text
The null text is displayed in the Search Panel when the search string is null. Use the SearchPanelNullText property to specify the null text.
- Result Info Panel
You can display the total search result count and the position of the focused search result among other results. To do this, set the ShowSearchPanelResultInfo to true. This property works only if you set the SearchPanelAllowFilter property to false.
Use the SearchResultNext() and SearchResultPrev() methods to move focus between nodes that contain search results. A user can press the
Enterkey to move focus to the next search result.
- MRU Search List
To display the MRU button, set the ShowSearchPanelMRUButton property to true. If a user clicks this button, the control displays a drop-down list with most recently used search strings. Set the SearchPanelImmediateMRUPopup property to true to display the drop-down list when a user types text in the Search Panel.
Keyboard Shortcuts
Ctrl+F- Focuses the Search Panel.
Esc- Clears the search string.
Enter- If SearchPanelAllowFilter is false, moves focus to the next search result.
Alt+Down Arrow- Opens the MRU search drop-down list.
Up Arrow- If the first node is focused, moves focus to the Search Panel.
Down Arrow- If the Search Panel is focused, moves focus to the first node.
Pre-Filter Data in Code
Use the FilterCriteria or FilterString property to apply a filter in code. If you use one of these properties, application users cannot modify your filter condition or access the nodes that were filtered out. If they use the Search Panel, the TreeViewControl searches only among the nodes that passed the filter condition.
If you use the FilterCriteria property, you should create a CriteriaOperator object or its descendant that defines the filter expression. For information on supported syntax, refer to the following help topic: Criteria Language Syntax.
treeview.FilterCriteria = new GroupOperator(
GroupOperatorType.And,
new FunctionOperator(FunctionOperatorType.Contains, new OperandProperty("DisplayName"), new OperandValue("activity")),
new FunctionOperator(FunctionOperatorType.Contains, new OperandProperty("DisplayName"), new OperandValue("int"))
);
You can also use the CriteriaOperator.Parse method:
treeview.FilterCriteria = CriteriaOperator.Parse("Contains([DisplayName], 'activity') AND Contains([DisplayName], 'int')");
The DataControlBase.FilterString property allows you to specify a filter string:
<dxg:TreeViewControl FilterString = "Contains([DisplayName], 'activity') AND Contains([DisplayName], 'int')"/>
treeview.FilterString = "Contains([DisplayName], 'activity') AND Contains([DisplayName], 'int')";
To clear the TreeViewControl‘s filter, set the FilterCriteria property to null or the FilterString property to an empty string.
Apply a Custom Filter
Use the CustomNodeFilter event to apply a custom filter condition. The TreeViewControl raises this event for each node. The e.Node property returns the processed node, and the e.CalcVisibility() method returns the node’s visibility state based on the currently applied filter.
To hide or show a node, specify the e.Visible property, and set the e.Handled property to true.
If the e.Handled property is set to false, the node’s visibility is determined by the filter applied to the TreeViewControl.
The following code sample adds the Hide Root Nodes checkbox that controls the visibility of root nodes:
<Grid>
<Grid.RowDefinitions>
<RowDefinition Height="36"/>
<RowDefinition Height="*"/>
</Grid.RowDefinitions>
<CheckBox Name="chkHideRoot" Grid.Row="0" Margin="7,0,0,0"
VerticalAlignment="Center"
Content="Hide Root Nodes"
Checked="chk_CheckedOrUnchecked"
Unchecked="chk_CheckedOrUnchecked"/>
<dxg:TreeViewControl x:Name="treeview"
Grid.Row="1"
ItemsSource="{Binding EmployeeDepartments}"
ChildNodesPath="Employees"
TreeViewFieldName="Name"
CustomNodeFilter="treeview_CustomNodeFilter"/>
</Grid>
void treeview_CustomNodeFilter(object sender, DevExpress.Xpf.Grid.TreeList.TreeViewNodeFilterEventArgs e) {
if (chkHideRoot.IsChecked.Value && e.Node.Level == 0) {
e.Visible = false;
e.Handled = true;
}
}
void chk_CheckedOrUnchecked(object sender, RoutedEventArgs e) {
treeview.RefreshData();
}
Search Nodes in Code
To specify a search string in code, use the SearchString property.
<dxg:TreeViewControl SearchString = "activity +int"/>
Set the SearchString property to an empty string to clear the search string.
Search Panel Parse Modes
Use the SearchPanelParseMode property to specify how the TreeViewControl parses the search string.
- Mixed / Or (Default)
The Or operator combines search words:
To use the And operator for a search word, add the
+character before this word:
- Exact
The exact match. If the search string contains space characters, the words are not treated separately:
- And
The And operator combines search words:
Additional Search Syntax
- Plus character
Precede a condition with the plus character (
+) to use the And operator for a search word.stat +int- Selects records that contain both “stat” and “int” strings.
- Minus character
Precede a condition with the minus character (
-) to exclude records that match this condition from the result set.stat -void- Selects records that contain “stat” and excludes records that contain “void”.
- Quotation marks
To search for a string that contains a space character, specify this string in quotation marks (
" ")."type : int"- Selects records that contain the “type : int” string.
Control Parent-Child Node Availability in Filtered View
Use the FilteringMode property to specify how the TreeViewControl filters its nodes.
- Nodes Mode (Default)
The TreeViewControl displays only nodes that meet the filter criteria. A node at the hierarchy’s highest level that meets the filter criteria becomes the root node. The node’s closest child that meets this criteria changes the hierarchy level to the next level down from the root.
- ParentBranch Mode
The TreeViewControl displays a node that meets the filter criteria and all its parent nodes, even if they do not meet the filter criteria.
- EntireBranch Mode
The TreeViewControl displays a node that meets the filter criteria and all its parent and child nodes, even if they do not meet the filter criteria.
- Recursive Mode
The TreeViewControl displays a node that meets the filter criteria only if its parent nodes also meet the filter criteria.
Related API
| Property | Description |
|---|---|
| ExpandNodesOnFiltering | Gets or sets whether to expand a node if its child nodes contain the search string. This is a dependency property. |
| RestoreTreeStateOnClearFilter | Gets or sets whether to restore the TreeViewControl state (expanded nodes, selected node) when a user clears the search string. This is a dependency property. |
| SearchDelay | Gets or sets the time in milliseconds before the search is initiated. This is a dependency property. |
| SearchPanelFindFilter | Gets or sets the type of the comparison operator used to create filter conditions. This is a dependency property. |