Table of Contents

Search and Filtering

TreeList and TreeView controls support features that allow you and a user to filter and search for data.

Search Panel (TreeList and TreeView)

The Search Panel helps a user quickly locate nodes by the data they contain. Set the control's SearchPanelDisplayMode property (inherited from the DataControlBase class) to one of the following values to enable the Search Panel:

  • SearchPanelDisplayMode.Always — The control permanently displays the Search Panel.
  • SearchPanelDisplayMode.HotKey — The control displays the Search Panel when a user presses the CTRL+F hotkey. The ESC shortcut clears the Search Panel. A subsequent ESC key press closes the panel. A user can also activate the Search Panel from a column header's context menu.

The control filters data (using the Contains comparison operator) when a user types text in the Search Panel. The TreeListControlBase.FilterMode property specifies which nodes are displayed when matches found. Two filter modes are supported:

  • FilterMode.ShowMatches — Displays nodes that match the search text.
  • FilterMode.ShowMatchesWithAncestors — Displays nodes that match the search text, and their parent nodes.

The search functionality is case-insensitive.

  • DataControlBase.IsSearchPanelVisible — Gets whether the Search Panel is currently visible.
  • DataControlBase.SearchPanelHighlightResults — Specifies whether to highlight the search text in the found nodes. The property's default value is true.
  • DataControlBase.SearchText — Gets or sets the search text. You can assign a value to this property to filter the control in code. This filtering functionality is supported even if the Search Panel is hidden or disabled (the SearchPanelDisplayMode property is set to SearchPanelDisplayMode.Never).
  • DataControlBase.ShowSearchPanelCloseButton — Allows you to hide the Search Panel's built-in Close button.

Example

The following code makes the Search Panel always visible, and enables the display of filtered nodes along with their parents. The SearchText property is used to set the search text.

treeList.SearchPanelDisplayMode = SearchPanelDisplayMode.Always;
treeList.FilterMode = FilterMode.ShowMatchesWithAncestors;
treeList.SearchText = "department";

Auto Filter Row (TreeList)

The Auto Filter Row is a special row displayed above all TreeList nodes. It allows a user to type text in its cells to filter data against corresponding columns.

Set the TreeList.ShowAutoFilterRow property to true to enable the Auto Filter Row.

You can use the ColumnBase.AutoFilterCondition property to specify the data comparison operation for specific cells (columns) of the Auto Filter Row. When a user types text the TreeList uses the specified comparison operation to compare column values while locating target nodes. The following data comparison operations are supported:

  • Equals — Node values in the target column should match the entered value.
  • Contains — Node values in the target column should contain the entered value. This mode is appropriate for String values.
  • StartsWith — Node values in the target column should start with the entered value. This mode is appropriate for String values.
  • Default — The Default option is equivalent to the Contains option for the String and Object data types. This option is equivalent to the Equals option for other data types.

The ColumnBase.AutoFilterValue property allows you to set a value for a specific Auto Filter Row cell in code. You can use the ColumnBase.AutoFilterValue to filter the TreeList even if the Auto Filter Row is hidden.

The control's default filter mode is to only display nodes that match the specified criteria. Set the TreeListControlBase.FilterMode property to FilterMode.ShowMatchesWithAncestors to display target nodes along with their parents.

The filter functionality is case-insensitive.

Example

The following code activates the Auto Filter Row, and displays nodes whose values in the 'Name' column start with "M".

treeList1.ShowAutoFilterRow = true;
TreeListColumn colName = treeList1.Columns["Name"];
colName.AutoFilterCondition = AutoFilterCondition.StartsWith;
colName.AutoFilterValue = "M";

Filter in Code

The DataControlBase.SearchText and ColumnBase.AutoFilterValue properties can be used to filter the TreeList and TreeView controls in code, even if the Search Panel and Auto Filter Row are hidden.

If you use the DataControlBase.SearchText property, the TreeList filters nodes by searching for the entered text in all columns. The Contains comparison operation is used.

If you use the ColumnBase.AutoFilterValue property, the TreeList searches for the entered text in the specified column. The ColumnBase.AutoFilterCondition property defines the comparison operation.