Filter Editor

May 05, 2022
10 minutes to read

The Filter Editor allows users to build complex filter criteria. A user can add any number of conditions that apply to individual fields and then use logical operators to build the composite filter expression.

Filter Editor

Invoke the Filter Editor at Runtime

Users can invoke the Filter Editor in the following ways:

Right-click a column header and select Filter Editor…:
Click the Edit Filter button ( ) in the Filter Panel:

Tip

Set the DataViewBase.AllowFilterEditor property to false to prohibit users from invoking the Filter Editor.

To invoke the Filter Editor in code, call the DataViewBase.ShowFilterEditor method or the DataViewCommandsBase.ShowFilterEditor command:

XAML

<Button Content="Show Filter Editor" Command="{Binding Path=Commands.ShowFilterEditor, ElementName=view}" />

<!-- ... -->

<dxg:GridControl>            
    <dxg:GridControl.View>
        <dxg:TableView x:Name="view" />
    </dxg:GridControl.View>
</dxg:GridControl>

Invoke the Filter Editor at Design Time

You can use the Filter Editor to configure filter criteria at design time. Locate the GridControl‘s FilterString property in the Visual Studio Properties window and click the ellipsis button to invoke the editor.

Filter Editor at Design Time

Filter Editor UI

The Filter Editor displays filter criteria as a tree structure where nodes are filter conditions. The entire expression is organized as a tree where parent nodes are logical operators that link individual filter conditions.

Filter Editor Elements

Conditional Formatting Filters

You can filter data by applying Conditional Formatting rules. The Filter Editor displays available rules and indicates the number of records that meet rule conditions:

Filter Editor - Conditional Formatting Filters

Run Demo: Conditional Formatting

Customize the Filter Editor

Use the DataViewBase.FilterEditorTemplate property to specify a custom template. In the template, define the FilterEditorControl and handle its events.

Customize the Field List

Run Demo: Filter Editor - Customize the Field List

The Filter Editor shows a list of the GridControl‘s fields. If the GridControl displays Bands, the Filter Editor shows fields in a hierarchical structure:

Filter Editor Bands

Tip

The FilterEditorControl.PropertySelectorMode property specifies whether to show fields in List or Tree mode.

Use the FilterEditorControl.QueryFields event to customize the field list. The following code sample shows how to add the ShipCountry, ShipCity, and ShipAddress fields to the Ship category:

Filter Editor Fields

Xaml

<dxg:TableView x:Name="view">
    <dxg:TableView.FilterEditorTemplate>
        <DataTemplate>
            <dxfui:FilterEditorControl QueryFields="OnQueryFields" />
        </DataTemplate>
    </dxg:TableView.FilterEditorTemplate>
</dxg:TableView>

C#
VB.NET

void OnQueryFields(object sender, QueryFieldsEventArgs e) {
    var shipCountry = e.Fields["ShipCountry"];
    var shipCity = e.Fields["ShipCity"];
    var shipAddress = e.Fields["ShipAddress"];

    shipCountry.Caption = "Country";
    shipCity.Caption = "City";
    shipAddress.Caption = "Address";

    e.Fields.Remove(shipCountry);
    e.Fields.Remove(shipCity);
    e.Fields.Remove(shipAddress);

    var shipGroup = new FieldItem { Caption = "Ship" };
    shipGroup.Children.Add(shipCountry);
    shipGroup.Children.Add(shipCity);
    shipGroup.Children.Add(shipAddress);
    e.Fields.Add(shipGroup);
}

Private Sub OnQueryFields(ByVal sender As Object, ByVal e As QueryFieldsEventArgs)
    Dim shipCountry = e.Fields("ShipCountry")
    Dim shipCity = e.Fields("ShipCity")
    Dim shipAddress = e.Fields("ShipAddress")

    shipCountry.Caption = "Country"
    shipCity.Caption = "City"
    shipAddress.Caption = "Address"

    e.Fields.Remove(shipCountry)
    e.Fields.Remove(shipCity)
    e.Fields.Remove(shipAddress)

    Dim shipGroup = New FieldItem With {
        .Caption = "Ship"
    }
    shipGroup.Children.Add(shipCountry)
    shipGroup.Children.Add(shipCity)
    shipGroup.Children.Add(shipAddress)
    e.Fields.Add(shipGroup)
End Sub

Customize the Operator List

Standard Operators

Run Demo: Filter Editor - Customize the Operator List

The Filter Editor shows a list of operators the selected field accepts. Use the FilterEditorControl.QueryOperators event to customize the operator list.

The code sample below removes all operators except Equals and Does not equal:

Filter Editors - Customize Standard Operators

Xaml

<dxg:TableView x:Name="view">
    <dxg:TableView.FilterEditorTemplate>
        <DataTemplate>
            <dxfui:FilterEditorControl QueryOperators="OnQueryOperators" />
        </DataTemplate>
    </dxg:TableView.FilterEditorTemplate>
</dxg:TableView>

C#
VB.NET

void OnQueryOperators(object sender, FilterEditorQueryOperatorsEventArgs e) {
    if(e.FieldName == "OrderDate") {
        e.Operators.Clear();
        e.Operators.Add(new FilterEditorOperatorItem(FilterEditorOperatorType.Equal));
        e.Operators.Add(new FilterEditorOperatorItem(FilterEditorOperatorType.NotEqual));
    }
}

Private Sub OnQueryOperators(ByVal sender As Object, ByVal e As FilterEditorQueryOperatorsEventArgs)
    If e.FieldName = "OrderDate" Then
        e.Operators.Clear()
        e.Operators.Add(New FilterEditorOperatorItem(FilterEditorOperatorType.Equal))
        e.Operators.Add(New FilterEditorOperatorItem(FilterEditorOperatorType.NotEqual))
    End If
End Sub

Custom Operators

Run Demo: Filter Editor - Customize the Operator List

You can use the FilterEditorControl.QueryOperators event to add custom operators. The example below adds the Last Years operator:

Filter Editor - Custom Operators

Create a custom function. Do one of the following:

Use the CustomFunctionFactory.Create method.

The CustomFunctionFactory is an extension of the DevExpress.Xpf.Grid.v23.2.Extensions.dll library. Refer to C:\Program Files\DevExpress 23.2\Components\Sources\XPF\DevExpress.Xpf.Grid\DevExpress.Xpf.Grid.Extensions\ for information on how extension methods work.

The CustomFunctionFactory.Create method allows you to create a custom function with a maximum of 4 operands.
Implement the ICustomFunctionOperator interface. Refer to the following topic for more information: Implementing Custom Functions.

C#
VB.NET

const string CustomFunctionName = "LastYears";
var currentYear = DateTime.Now.Year;

ICustomFunctionOperatorBrowsable customFunction = CustomFunctionFactory.Create(CustomFunctionName, 
    (DateTime date, int threshold) => {
        return currentYear >= date.Year && currentYear - date.Year <= threshold;
    }
);

Const CustomFunctionName As String = "LastYears"
Private currentYear = DateTime.Now.Year

Dim customFunction As ICustomFunctionOperatorBrowsable = CustomFunctionFactory.Create(CustomFunctionName, 
    Function(ByVal date As DateTime, ByVal threshold As Integer) currentYear >= date.Year AndAlso currentYear - date.Year <= threshold)

Call the CriteriaOperator.RegisterCustomFunction method to register the custom function.

C#
VB.NET

CriteriaOperator.RegisterCustomFunction(customFunction);

CriteriaOperator.RegisterCustomFunction(customFunction)

Create the FilterEditorOperatorItem and add it to the FilterEditorQueryOperatorsEventArgs.Operators collection. Specify the operator item’s edit settings to define its operands:

C#
VB.NET

void OnQueryOperators(object sender, FilterEditorQueryOperatorsEventArgs e) {
    if(e.FieldName == "OrderDate") {
        // ...

        var customFunctionEditSettings = new BaseEditSettings[] { 
            new TextEditSettings { MaskType = MaskType.Numeric, Mask = "D", MaskUseAsDisplayFormat = true } 
        };
        e.Operators.Add(new FilterEditorOperatorItem(CustomFunctionName, customFunctionEditSettings) { Caption = "Last Years" });
    }
}

Private Sub OnQueryOperators(ByVal sender As Object, ByVal e As FilterEditorQueryOperatorsEventArgs)
    If e.FieldName = "OrderDate" Then
        ' ...

        Dim customFunctionEditSettings = New BaseEditSettings() {New TextEditSettings With {
            .MaskType = MaskType.Numeric,
            .Mask = "D",
            .MaskUseAsDisplayFormat = True
        }}
        e.Operators.Add(New FilterEditorOperatorItem(CustomFunctionName, customFunctionEditSettings) With {
            .Caption = "Last Years"
        })
    End If
End Sub

Predefined Filters

You can specify Predefined Filters with the ColumnBase.PredefinedFilters property. The Filter Editor displays these filters in the Predefined filters submenu:

Filter Editor - Predefined Filters

Xaml

<dxg:GridColumn FieldName="UnitPrice">
    <dxg:GridColumn.PredefinedFilters>
        <dxfui:PredefinedFilterCollection>
            <dxfui:PredefinedFilter Name="Less than 10" Filter="?p &lt; 10" />
            <dxfui:PredefinedFilter Name="Between 10 and 50" Filter="?p &gt; 10 and ?p &lt; 50" />
            <dxfui:PredefinedFilter Name="Between 50 and 100" Filter="?p &gt; 50 and ?p &lt; 100" />
            <dxfui:PredefinedFilter Name="Greater than 100" Filter="?p &gt; 100" />
        </dxfui:PredefinedFilterCollection>
    </dxg:GridColumn.PredefinedFilters>
</dxg:GridColumn>

Tip

Topic: Predefined Filters

Customize Operand Template

Run Demo: Filter Editor - Customize Operands

The Filter Editor automatically creates operand editors based on the field and operator type. You can customize operand editors.

The following code sample specifies the TrackBarEdit as an operand for the Between and NotBetween operators:

Filter Editor - Custom Operand Template

Create a template for the operands. The following models depend on the operator type. Use their properties to bind to operand values in the template:

ConstantFilterModel (for example, Is null, Is Yesterday)
BinaryFilterModel (for example, Equals, Is greater than)
TernaryFilterModel (for example, Is between, Is between dates)
VariadicFilterModel (for example, Is any of, Is none of)

Xaml

<UserControl.Resources>
    <DataTemplate x:Key="ternaryTemplate">
        <dxe:TrackBarEdit Minimum="0" Maximum="300" MinWidth="120" 
                          TickPlacement="None" dxfui:FilterEditorNavigation.Index="0">
            <dxe:TrackBarEdit.EditValue>
                <MultiBinding Converter="{local:TrackBarEditRangeConverter}">
                    <Binding Path="LeftValueItem.Value"/>
                    <Binding Path="RightValueItem.Value"/>
                </MultiBinding>
            </dxe:TrackBarEdit.EditValue>
            <dxe:TrackBarEdit.StyleSettings>
                <dxe:TrackBarRangeStyleSettings />
            </dxe:TrackBarEdit.StyleSettings>
        </dxe:TrackBarEdit>
    </DataTemplate>
</UserControl.Resources>

TrackBarEditRangeConverter

C#
VB.NET

public class TrackBarEditRangeConverter : BaseMultiValueConverter {
    public override object Convert(object[] values, Type targetType, object parameter, CultureInfo culture) {
        if(values.Length != 2)
            return new TrackBarEditRange();
        return new TrackBarEditRange(GetApproptiateValue(values[0]), GetApproptiateValue(values[1]));
    }

    short GetApproptiateValue(object value) {
        if(value is int)
            return System.Convert.ToInt16(value);
        return value is short ? (short)value : (short)0;
    }

    public override object[] ConvertBack(object value, Type[] targetTypes, object parameter, CultureInfo culture) {
        var trackBarEditRange = value as TrackBarEditRange;
        if(trackBarEditRange == null)
            return new object[] { (short)0, (short)0 };
        return new object[] { (short)trackBarEditRange.SelectionStart, (short)trackBarEditRange.SelectionEnd };
    }
}

Public Class TrackBarEditRangeConverter
Inherits BaseMultiValueConverter

    Public Overrides Function Convert(ByVal values As Object(), ByVal targetType As Type, ByVal parameter As Object, ByVal culture As CultureInfo) As Object
        If values.Length <> 2 Then Return New TrackBarEditRange()
        Return New TrackBarEditRange(GetApproptiateValue(values(0)), GetApproptiateValue(values(1)))
    End Function

    Private Function GetApproptiateValue(ByVal value As Object) As Short
        If TypeOf value Is Integer Then Return System.Convert.ToInt16(value)
        Return If(TypeOf value Is Short, CShort(value), CShort(0))
    End Function

    Public Overrides Function ConvertBack(ByVal value As Object, ByVal targetTypes As Type(), ByVal parameter As Object, ByVal culture As CultureInfo) As Object()
      Dim trackBarEditRange = TryCast(value, TrackBarEditRange)
        If trackBarEditRange Is Nothing Then Return New Object() {CShort(0), CShort(0)}
        Return New Object() {CShort(trackBarEditRange.SelectionStart), CShort(trackBarEditRange.SelectionEnd)}
    End Function
End Class

Handle the FilterEditorControl.QueryOperators event, get the operator, and assign the created template to the OperatorItemBase.OperandTemplate property.

Xaml

<dxg:TableView x:Name="view">
    <dxg:TableView.FilterEditorTemplate>
        <DataTemplate>
            <dxfui:FilterEditorControl QueryOperators="OnQueryOperators" />
        </DataTemplate>
    </dxg:TableView.FilterEditorTemplate>
</dxg:TableView>

C#
VB.NET

void OnQueryOperators(object sender, FilterEditorQueryOperatorsEventArgs e) {
    if(e.FieldName == "Quantity") {
        var template = (DataTemplate)FindResource("ternaryTemplate");
        e.Operators[FilterEditorOperatorType.Between].OperandTemplate = template;
        e.Operators[FilterEditorOperatorType.NotBetween].OperandTemplate = template;
    }
}

Private Sub OnQueryOperators(ByVal sender As Object, ByVal e As FilterEditorQueryOperatorsEventArgs)
    If e.FieldName = "Quantity" Then
        Dim template = CType(FindResource("ternaryTemplate"), DataTemplate)
        e.Operators(FilterEditorOperatorType.Between).OperandTemplate = template
        e.Operators(FilterEditorOperatorType.NotBetween).OperandTemplate = template
    End If
End Sub

Customize Operand Values

The Filter Editor displays only those operand values that meet the current filter criteria. To show all values in the operand list, set the DataControlBase.ShowAllTableValuesInFilterPopup property to true.

Run Demo: Filter Editor - Customize Operand Values

You can allow users to select date-time functions and fields as operand values:

Date-time Functions

Fields

Use the FilterEditorControl.QueryOperands event to specify available operand types:

Filter Editor - Custom Operand Values

Xaml

<dxg:GridControl>
    <dxg:GridControl.Columns>
        <dxg:GridColumn FieldName="ProductName"/>
        <dxg:GridColumn FieldName="RequiredDate"/>
        <dxg:GridColumn FieldName="ShippedDate"/>
        <dxg:GridColumn FieldName="ShipCountry"/>
        <dxg:GridColumn FieldName="ShipCity"/>
        <dxg:GridColumn FieldName="ShipAddress"/>
    </dxg:GridControl.Columns>
    <dxg:GridControl.View>
        <dxg:TableView x:Name="view">
            <dxg:TableView.FilterEditorTemplate>
                <DataTemplate>
                    <dxfui:FilterEditorControl QueryOperands="FilterEditorControl_OnQueryOperands" />
                </DataTemplate>
            </dxg:TableView.FilterEditorTemplate>
        </dxg:TableView>
    </dxg:GridControl.View>
</dxg:GridControl>

C#
VB.NET

void FilterEditorControl_OnQueryOperands(object sender, QueryOperandsEventArgs e) {
    switch(e.FieldName) {
        case "RequiredDate":
        case "ShippedDate":
            e.AllowPropertyOperand = true;
            e.AllowDateTimeFunctionOperand = true;
            e.AllowValueOperand = true;
            break;
    }
}

Private Sub FilterEditorControl_OnQueryOperands(ByVal sender As Object, ByVal e As QueryOperandsEventArgs)
    Select Case e.FieldName
        Case "RequiredDate", "ShippedDate"
            e.AllowPropertyOperand = True
            e.AllowDateTimeFunctionOperand = True
            e.AllowValueOperand = True
    End Select
End Sub

Use the FilterEditorControl.QueryDateTimeFunctions event to customize the list of date-time functions that are displayed when the DateTime function operand is selected.

Use the FilterEditorControl.QueryOperandFields event to customize the list of fields that are displayed when the Property operand is selected.

Prohibit Operations

Prohibit Group Types

Run Demo: Filter Editor - Prohibit Group Types

Use the FilterEditorControl.QueryGroupTypes event to prohibit group types. The following code sample prohibits users from specifying the Or and NotOr logical operators:

Filter Editor - Prohibit Group Types

Xaml

<dxg:TableView x:Name="view">
    <dxg:TableView.FilterEditorTemplate>
        <DataTemplate>
            <dxfui:FilterEditorControl QueryGroupTypes="OnQueryGroupTypes" />
        </DataTemplate>
    </dxg:TableView.FilterEditorTemplate>
</dxg:TableView>

C#
VB.NET

void OnQueryGroupTypes(object sender, QueryGroupTypesEventArgs e) {
    e.AllowNotAnd = false;
    e.AllowNotOr = false;
}

Private Sub OnQueryGroupTypes(ByVal sender As Object, ByVal e As QueryGroupTypesEventArgs)
    e.AllowNotAnd = False
    e.AllowNotOr = False
End Sub

Prohibit Group Operations

Run Demo: Filter Editor - Prohibit Group Operations

Use the FilterEditorControl.QueryGroupOperations event to prohibit group operations. The following code sample prohibits users from adding custom expressions:

Filter Editor - Prohibit Group Operations

Xaml

<dxg:TableView x:Name="view">
    <dxg:TableView.FilterEditorTemplate>
        <DataTemplate>
            <dxfui:FilterEditorControl QueryGroupOperations="OnQueryGroupOperations" />
        </DataTemplate>
    </dxg:TableView.FilterEditorTemplate>
</dxg:TableView>

C#
VB.NET

void OnQueryGroupOperations(object sender, QueryGroupOperationsEventArgs e) {
    e.AllowAddCustomExpression = false;
}

Private Sub OnQueryGroupOperations(ByVal sender As Object, ByVal e As QueryGroupOperationsEventArgs)
    e.AllowAddCustomExpression = False
End Sub

Prohibit Users from Removing Conditions

Run Demo: Filter Editor - Prohibit Condition Operations

Use the FilterEditorControl.QueryConditionOperations event to prohibit users from removing conditions:

Filter Editor - Prohibit Condition Operations

Xaml

<dxg:TableView x:Name="view">
    <dxg:TableView.FilterEditorTemplate>
        <DataTemplate>
            <dxfui:FilterEditorControl QueryConditionOperations="OnQueryConditionOperations" />
        </DataTemplate>
    </dxg:TableView.FilterEditorTemplate>
</dxg:TableView>

C#
VB.NET

void OnQueryConditionOperations(object sender, QueryConditionOperationsEventArgs e) {
    e.AllowRemoveCondition = false;
}

Private Sub OnQueryConditionOperations(ByVal sender As Object, ByVal e As QueryConditionOperationsEventArgs)
    e.AllowRemoveCondition = False
End Sub

Standalone Filter Editor

Run Demo: Filter Editor - Standalone Filter Editor

A standalone FilterEditorControl is available.

Specify the FilterEditorControl.Context property to associate the FilterEditorControl with the GridControl‘s filter context:

The FilterEditorControl retrieves values, filter criteria, format settings and other details from the GridControl‘s context.
The FilterEditorControl applies filter criteria to the GridControl‘s context.

The filter criteria specified in the FilterEditorControl are not automatically applied to the GridControl. To apply the current filter criteria, call the FilterEditorControl.ApplyFilter method or the FilterEditorCommands.ApplyFilter command.

Xaml

<dxg:GridControl x:Name="filterGrid" ... />

<!-- ... -->

<dxfui:FilterEditorControl x:Name="filterEditor" 
                           Context="{Binding Path=FilteringContext, ElementName=filterGrid}"/>
<Button Content="Apply Filter" 
        Command="{Binding Commands.ApplyFilter, ElementName=filterEditor}" />

Standalone Filter Editor

Tip

When users edit filter conditions in the FilterEditorControl (for example, add/remove conditions, select a field/operator, specify a value), the FilterEditorControl.FilterChanged event occurs.
Use the FilterEditorControl.Filter property to get the current filter criteria specified in the FilterEditorControl.

Legacy Filter Editor

To use the legacy Filter Editor:

For a specific GridControl, set the DataViewBase.UseLegacyFilterEditor property to true.
For all controls (GridControl, TreeListControl, and PivotGridControl) in the project, set the CompatibilitySettings.UseLegacyFilterEditor property to true.

Limitations

In Virtual Sources and Server Mode, record counts are not displayed (the default setting). To display record counts, handle the DataControlBase.CustomUniqueValues event. For Virtual Sources, you can alternatively handle the GetUniqueValues event.

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Invoke the Filter Editor at Runtime

Invoke the Filter Editor at Design Time

Filter Editor UI

Conditional Formatting Filters

Customize the Filter Editor

Customize the Field List

Customize the Operator List

Standard Operators

Custom Operators

Predefined Filters

Customize Operand Template

Customize Operand Values

Prohibit Operations

Prohibit Group Types

Prohibit Group Operations

Prohibit Users from Removing Conditions

Standalone Filter Editor

Legacy Filter Editor

Limitations