Prefilter
- 3 minutes to read
The Prefilter feature serves two purposes. First, it enables PivotGridControl to display a Filter Editor allowing an end-user to apply filtering to the pivot grid’s underlying data source at runtime. Second, you can filter the underlying data source in code, without displaying a Filter Editor to end-users.
You can see the caption Filter instead of Prefilter. This is the case if Excel-style dropdown filters are enabled. To enable them, set the application-wide static setting WindowsFormsSettings.ColumnFilterPopupMode to ColumnFilterPopupMode.Excel, or set the option PivotGridOptionsFilterPopup.FieldFilterPopupMode to the FieldFilterPopupMode.Excel value.
Note
The Prefilter is not supported in an OLAP mode.
Filter Editor
By default, end-users can invoke a Filter Editor at runtime via the context menu. The Filter Editor provides an advanced UI that allows end-users to build complex filter criteria with an unlimited number of filter conditions combined by logical operators. The resulting filter condition is combined with filter conditions defined by individual fields.
The Filter Editor may contain a text panel, a visual panel, or both. This characteristic is determined by the PivotGridControl.DefaultFilterEditorView property.
To learn how to interact with a Filter Editor at runtime, see the Filter Editor topic from End-User Documentation.
You can prevent end-users from invoking a Filter Editor by disabling the PivotGridOptionsCustomization.AllowPrefilter option. In this instance, the Show Prefilter context menu item will be hidden, and the Filter Editor will be able to be invoked only in code.
To prevent a particular field from being displayed in a Filter Editor, and used in filter criteria built by end-users, use the PivotGridFieldOptions.ShowInPrefilter property.
Prefilter Panel
When the PivotGridOptionsCustomization.AllowPrefilter option is enabled, and a filter condition is specified, Pivot Grid Control displays a Filter Panel.
A Prefilter Panel displays a filter expression, an edit button used to invoke a Filter Editor, a check box used to temporarily enable/disable the filtering, and a clear button used to reset the current filter condition.
Use the PivotGridAppearances.PrefilterPanel property to customize the Prefilter Panel appearance.
Using Prefilter in Code
The Prefilter allows you to access its settings and specify filter criteria in code. To do this, use the PivotGridControl.Prefilter property. The returned object exposes the following properties and methods.
Get or set a filter expression. | |
Toggles the Filter Editor visibility state. | |
Gets or sets whether filtering is enabled or not. |
When you create a filter expression in code, use the PivotGridFieldBase.PrefilterColumnName property to refer to a field. The sample below shows how to do this.
pivotgridControl1.Prefilter.CriteriaString = "[" + fieldCategory.PrefilterColumnName + "] Like 'B%'";
Note
Prefilter cannot filter data against data fields. If a data field is used in a filter criteria that has been specified in code, an error message will be displayed within the Prefilter Panel. This message also appears if a filter criteria contains a field name that does not exist. Use the PrefilterBase.State property to determine whether the filter criteria is valid or not.
To learn more about filter criteria syntax, see the Pivot Grid Expression Syntax document.
After a filter condition has been changed via a Filter Editor or in code, the PivotGridControl.PrefilterCriteriaChanged event is raised.