[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Expand]Controls and Libraries
 [Collapse]Common Features
  [Expand]Data Binding Common Concepts
  [Expand]Data Source Wizard
  [Expand]Expressions
  [Expand]Behaviors
  [Expand]Application Appearance and Skin Colors
  [Collapse]Filtering UI Context
    Filtering Events
    Filtering Attributes
    Base and Parent Filtering ViewModels
    Filtering UI Context Designer
   Find Panel Syntax
  [Expand]Graphics Performance and High DPI
  [Expand]Scaffolding Wizard
  [Expand]Formatting Values
   HTML-inspired Text Formatting
  [Expand]Menus
  [Expand]Tooltip Management
  [Expand]Save and Restore Layouts
   Clipboard - Copy and Paste Operations. Data Formatting
   Version Compatibility: Default Property Values
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Filtering Events

Handling filtering events allows you to customize editors the Filtering UI Context generates and manage UI generation for complex (Sting, Object) properties.

Expanded The PrepareTemplate and CustomizeTemplate Events

These events allow you to alter (CustomizeTemplate) or completely replace (PrepareTemplate) templates that the Filtering UI Context component employs when generating editors. In the sample below, handling the PrepareTemplate replaces the default CheckedListBoxControl with a custom "TileList" control that displays filtering options as flat buttons.

Tip

Click this link to view the complete example at GitHub.

The CustomizeTemplate allows you to customize a template without replacing it.

Expanded The QueryLookupData Event

Allows you to provide the child items list for lookup filters manually. This event handler's QueryLookupDataEventArgs argument provides the following properties:

  • PropertyPath - the name of the data field for which the current lookup editor was created;
  • Result - exposes three properties for populating your lookup editor:

    • DataSource - gets or sets the lookup item collection.
    • Top - receives an integer value that specifies how many items should be shown initially. The remaining items can be displayed by clicking the 'More' button at runtime.
    • MaxCount - the integer property that specifies the total number of lookup items.

The code sample below illustrates the "RetrieveCategoryList" method, which iterates through Data Grid records and adds unique "Category_Name" column values to a list. This list is later used as an item source for the filtering lookup editor.

QueryLookupData and other "Query..." events allow you to customize filtering items' HTML texts. For instance, the following code sample from the Data Filtering Charts demo illustrates how to provide images to items under the "Company" category.

Expanded The QueryGroupData Event

If you want to group multiple data fields in one hierarchical drop-down filter, you need to decorate the root field with the FilterGroup attribute.

In case the Filtering UI Context component is attached to a data-aware control (the Client property), all you need to do is to decorate required fields with this attribute. Otherwise, if the Filtering UI Context recieves a filtering Model (the ModelType property), you need to use this attribute and handle the QueryGroupData. This event supplies grouped drop-down filters with data, and has the following parameters:

  • PropertyPath - returns a field name decorated with the FilterGroup attribute;
  • GroupPropertyPath - returns a field name that corresponds to the current group level;
  • Result.SetGroupData - allows you to set values and captions for fitler items;
  • ParentCriteria - returns criteria that can be used to obtain values for the current group level;
  • ParentValues - returns an array with parent nodes' values.

In the sample above, the "TypeOfObject" field is decorated with the FilterGroup attribute. For this field the Filtering UI Context should display a drop-down list with the "ParentId" and "Name" field values as children. The code below illustrates how to provide these child values.

Expanded The QueryRangeData Event

Handle this event to customize filtering editors for numeric properties. The QueryRangeDataEventArgs argument provides the following properties:

  • PropertyPath - the name of the data field for which the current lookup editor was created;
  • Result - provides access to the Minimum, Maximum and Average properties that allow you to limit the available value range.

In the following example, end-users can filter records by price only in $500 ~ $2000 range:

Expanded The QueryBooleanChoiceData Event

Handle this event to ignore unwanted boolean filtering values (see the example below). The event receives an argument of the QueryBooleanChoiceDataEventArgs type, which provides access to the following properties:

  • PropertyPath - the name of the data field for which the current lookup editor was created;
  • Result.DefaultValue - assign an unwanted boolean value to this property. If a user selects this unwanted value, no filter applies (see the example below).

In the example below, Data Grid is bound to a source that provides the "In Stock" field. It is unlikely that customers would like to browse only unavailable products, so for this property the false value is irrelevant.

The animation below illustrates the result: when a user clears the "In Stock" checkbox, the Data Grid displays all records instead of showing only those whose "In Stock" values equal false.

 

Expanded See Also

Is this topic helpful?​​​​​​​