wpf-7788-controls-and-libraries-data-grid-filtering-and-searching-filter-editor.md
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.
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:
<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>
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.
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.
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:
Run Demo: Conditional Formatting
You can use the Filter Editor to filter data by items in bound collection properties. Specify the DataViewBase.AllowFilterEditorAggregateOperands property to display aggregate operands:
The Filter Editor displays all aggregate operators when you set the AllowFilterEditorAggregateOperands property to Aggregate or AggregateWithCondition. Use the ColumnBase.AllowedAggregateFilters property to customize the operator list for the column:
<dxg:GridColumn FieldName="Genres" AllowedAggregateFilters="Exists, Count"/>
Within the Filter Editor, TimeOnly values are rounded to minutes, ignoring seconds and milliseconds. For instance, a condition like [Time] >= 7:44 and [Time] < 7:45 is shown as [Time] = 7:44. User data is not affected.
Use the DataViewBase.FilterEditorTemplate property to specify a custom template. In the template, define the FilterEditorControl and handle its events.
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:
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:
<dxg:TableView x:Name="view">
<dxg:TableView.FilterEditorTemplate>
<DataTemplate>
<dxfui:FilterEditorControl QueryFields="OnQueryFields" />
</DataTemplate>
</dxg:TableView.FilterEditorTemplate>
</dxg:TableView>
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
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 :
<dxg:TableView x:Name="view">
<dxg:TableView.FilterEditorTemplate>
<DataTemplate>
<dxfui:FilterEditorControl QueryOperators="OnQueryOperators" />
</DataTemplate>
</dxg:TableView.FilterEditorTemplate>
</dxg:TableView>
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
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:
Create a custom function. Do one of the following:
Call the CriteriaOperator.RegisterCustomFunction method to register the custom function.
Create the FilterEditorOperatorItem and add it to the FilterEditorQueryOperatorsEventArgs.Operators collection. Specify the operator item’s edit settings to define its operands:
You can specify Predefined Filters with the ColumnBase.PredefinedFilters property. The Filter Editor displays these filters in the Predefined filters submenu:
<dxg:GridColumn FieldName="UnitPrice">
<dxg:GridColumn.PredefinedFilters>
<dxfui:PredefinedFilterCollection>
<dxfui:PredefinedFilter Name="Less than 10" Filter="?p < 10" />
<dxfui:PredefinedFilter Name="Between 10 and 50" Filter="?p > 10 and ?p < 50" />
<dxfui:PredefinedFilter Name="Between 50 and 100" Filter="?p > 50 and ?p < 100" />
<dxfui:PredefinedFilter Name="Greater than 100" Filter="?p > 100" />
</dxfui:PredefinedFilterCollection>
</dxg:GridColumn.PredefinedFilters>
</dxg:GridColumn>
Tip
Topic : Predefined Filters
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:
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:
Handle the FilterEditorControl.QueryOperators event, get the operator, and assign the created template to the OperatorItemBase.OperandTemplate property.
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:
<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>
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.
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:
<dxg:TableView x:Name="view">
<dxg:TableView.FilterEditorTemplate>
<DataTemplate>
<dxfui:FilterEditorControl QueryGroupTypes="OnQueryGroupTypes" />
</DataTemplate>
</dxg:TableView.FilterEditorTemplate>
</dxg:TableView>
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
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:
<dxg:TableView x:Name="view">
<dxg:TableView.FilterEditorTemplate>
<DataTemplate>
<dxfui:FilterEditorControl QueryGroupOperations="OnQueryGroupOperations" />
</DataTemplate>
</dxg:TableView.FilterEditorTemplate>
</dxg:TableView>
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
Run Demo: Filter Editor - Prohibit Condition Operations
Use the FilterEditorControl.QueryConditionOperations event to prohibit users from removing conditions:
<dxg:TableView x:Name="view">
<dxg:TableView.FilterEditorTemplate>
<DataTemplate>
<dxfui:FilterEditorControl QueryConditionOperations="OnQueryConditionOperations" />
</DataTemplate>
</dxg:TableView.FilterEditorTemplate>
</dxg:TableView>
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
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 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.
<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}" />
Tip
To use the legacy Filter Editor:
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.