Filter and Search

TreeList and TreeView controls support the data filtering and searching features, which allow you to locate nodes based on their values.

Column Filters (TreeList)

Starting with version 1.2, users can filter TreeList columns using filter menus. When a user hovers a column header with the mouse, a filter button appears. This button activates the filter menu containing all unique column values. A user can select any value in the filter menu to filter the column.

• Users can filter the TreeList against multiple columns. In this case, filters applied to individual columns are combined by the AND operator.
• Currently, filter menus do not support multiple value selection, but this feature is under development.

Once a filter is applied, the filter panel appears at the bottom. It displays the currently applied filter criteria, and allows you to temporarily disable and clear the filter.

To learn how to filter programmatically, see the following section:

• Filter in Code

Related API

TreeList Control Members

• FilterString — Gets or sets the filter criteria applied to the control. You can use this property to construct a filter in code. The FilterString property is supported by the TreeList and TreeView controls.

• IsFilterEnabled — Gets or sets whether the filter is active. The IsFilterEnabled property is supported by the TreeList and TreeView controls.

• AllowColumnFiltering — Gets or sets whether filter buttons are allowed for all columns. You can use a column's ColumnBase.AllowColumnFiltering property to override the global setting for individual columns.

  For instance, to disable filter buttons for all columns except one, set the TreeListControl.AllowColumnFiltering property to false, and the target column's ColumnBase.AllowColumnFiltering property to true.

• ColumnFilterButtonDisplayMode — Gets or sets whether filter buttons are always visible, or only appear when a user hovers a column header with the mouse (default).

• FilterPanelText — Gets the text representation of the filter displayed in the filter panel.
• IsFilterPanelVisible — Gets whether the filter panel is currently visible.

• FilterPanelDisplayMode — Gets or sets the filter panel's visibility mode. Available options include:

  • Auto (default) — The filter panel appears when a filter is applied to any column.
  • Never — The filter panel is always hidden.

• CustomColumnDisplayText event — Allows you to provide custom display text for column values, including those displayed in the filter panel. When the CustomColumnDisplayText event is raised for column values in the filter panel, the event's SourceItemIndex parameter returns -1.

Column Members

• ColumnBase.AllowColumnFiltering — Gets or sets whether a filter button is allowed for the current column. To enable or disable filter buttons for all columns, see the TreeListControl.AllowColumnFiltering setting. The ColumnBase.AllowColumnFiltering option allows you to override the TreeListControl.AllowColumnFiltering setting for individual columns.

• ColumnBase.ColumnFilterMode — Gets or sets how a column’s data is filtered. Available options include:

  • Value — A column's data is filtered by underlying values.
  • DisplayText — A column's data is filtered by cell display text.

• ColumnBase.IsFiltered — Gets whether a filter is applied to the current column.
• ColumnBase.RoundDateTimeForColumnFilter — Gets or sets whether to ignore the time portion of DateTime values when constructing filters for columns that display DateTime values. This property is in effect for filters created using column filter menus and the auto filter row.

Search Panel (TreeList and TreeView)

The Search Panel is displayed at the top of the TreeList/TreeView control. It provides a text box in which a user can enter search text. The controls automatically filter nodes, displaying those that contain the specified text.

• A data search is case-insensitive
• The Contains comparison operator is used to locate the specified text in nodes
• The TreeList control searches all of its columns for the specified text

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 TreeListControlBase.FilterMode property specifies which nodes are displayed when matches found. Three 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.
• FilterMode.ShowBranchesWithMatches — Displays entire branches if they contain nodes that match filter criteria.

Search in Collapsed Nodes

During data search/filtering, the TreeList/TreeView controls can search within collapsed nodes. Set the TreeListControlBase.ExpandNodesOnFiltering option to true to search in collapsed nodes and automatically expand them when a match is found.

The controls only search through currently loaded nodes. For hierarchical data sources, you can set the AllowDynamicDataLoading property to false to disable dynamic node loading and load all nodes at once.

Related API

• 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.
• TreeListControlBase.ExpandNodesOnFiltering — Specifies whether to expand collapsed nodes during data searching/filtering when their child nodes match the current filter/search criteria.

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.

• The filter functionality is case-insensitive.
• To search in collapsed nodes and expand them when a match is found, set the TreeListControlBase.ExpandNodesOnFiltering option to true. See also: Search in Collapsed Nodes

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:

• Contains — Node values in the target column should contain 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.
• Equals — Node values in the target column should match the entered value.
• StartsWith — Node values in the target column should start with the entered value. This mode is appropriate for String values.

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.

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 Nodes Dynamically Using an Event

The CustomNodeFilter event allows you to hide specific nodes based on a custom condition. This event fires for each node in the following cases:

• The control's item source changes.
• The control's nodes are filtered (for instance, using the Search Panel and/or Auto Filter Row).
• The control's RefreshData method is called.

Use the Node event parameter to identify the currently processed node. To hide the node, set the Visible event parameter to false.

Example - Filter Rows with an Event

In the following example, a Tree List control displays a list of ProjectTask objects. The CustomNodeFilter event is handled to implement custom node filtration. Nodes are hidden according to a value of the ProjectTask.Status property.

It is assumed that the example contains the "Enable Filter" toggle button that activates and deactivates the custom filtration. When the button is clicked, the ToggleButton.IsCheckedChanged event handler calls the RefreshData method to refresh treelist nodes and re-raise the CustomNodeFilter event.

<ToggleButton Name="btnEnableFilter" Content="Enable Filter" IsCheckedChanged="BtnEnableFilter_IsCheckedChanged"/>

<mxtl:TreeListControl x:Name="treeList" CustomNodeFilter="TreeList_CustomNodeFilter">
<!-- ... -->

using Eremex.AvaloniaUI.Controls.TreeList;

private void BtnEnableFilter_IsCheckedChanged(object sender, RoutedEventArgs e)
{
    treeList.RefreshData();
}

private void TreeList_CustomNodeFilter(object sender, TreeListCustomNodeFilterEventArgs e)
{
    bool filterEnabled = btnEnableFilter.IsChecked == true;
    if (!filterEnabled)
        return;
    ProjectTask task = e.Node.Content as ProjectTask;
    e.Visible = task.Status!= DemoData.TaskStatus.Completed;
}

Filter in Code (TreeList and TreeView)

Starting with version 1.2, you can use the DataControlBase.FilterString property to programmatically filter data in the TreeList and TreeView controls.

treeList.FilterString = "[Description] == 'Front-end development' && [Assignee] == 'Tim Robinson'";

A filter string consists of individual filter expressions combined by logical operators (AND or OR).

Clear and Disable the Filter

• To clear the filter, set the FilterString property to null or an empty string.
• To temporarily disable the filter, use the DataControlBase.IsFilterEnabled property.

Specify Columns

In the filter string, columns should be referenced by their field names enclosed in square brackets. Examples:

• [FirstName]
• [Position]

Specify Constants

• Numeric constants must specified using standard numeric formats. Examples:

  • 500, 0
  • 10.314, .5
  • 12.0m/12.0M, 12d/12D, 12f/12F
  • -32.5

  • String constants must be wrapped in single quote characters ('). To insert ' as a literal, use the '' notation. Examples:

  • 'Research and Development'

  • 'Clair de lune'
  • 'O''Neil'

• DateTime and DateTimeOffset constants must be wrapped with the # characters and specified using an invariant culture. Examples:

  • #2018-03-22#
  • #2018-03-22 13:18:51#
  • #2018-03-22 13:18:51.94944#

• DateOnly and TimeOnly constants must be enclosed between #! and !# strings. Examples:

  • #!2026-01-01!#
  • #!12:23:45!#

• Boolean constants:

  • true, True, or TRUE
  • false, False, or FALSE

Logical Operators

You can use the following logical operators to combine individual expressions in a filter string:

• &&, and, And or AND
• ||, or, Or or OR

treeList.FilterString = "[Price] < 5 OR [Price] > 15";

Operators and Functions

The following table lists available operators and functions to construct filter expressions:

Operators and Functions	Description	Example
= or ==	Equal to	[Price] = 500
!= or <>	Not equal to	[Price] != 500
<	Less than	[Price] < 700
>	Greater than	[Price] > 600
<=	Less than or equal to	[Price] <= 600
>=	Greater than or equal to	[Price] >= 800
is null	Selects null values	[Region] is null
is not null	Selects non-null values	[Region] is not null
IsNull	Selects null values	IsNull([Region])
IsNullOrEmpty	Selects null values and empty strings	IsNullOrEmpty([Region])
In	Selects items that have any of the specified values.	[City] In ('Beijing', 'Shenzhen', 'Chengdu')
Contains	Selects items that contain the specified string. The Contains operator is case-insensitive.	Contains([Name], 'lan')
StartsWith	Selects items that start with the specified string. The StartsWith operator is case-insensitive.	StartsWith([Product], 'CPU')
EndsWith	Selects items that end with the specified string. The EndsWith operator is case-insensitive.	EndsWith([Product], '9950X')
!, not, Not or NOT	Negation operator	!Contains([Maker], 'amd')