Log In
[Expand]General Information
[Collapse]WinForms Controls
 [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]Application Appearance
  [Collapse]Filtering UI Context
   [Collapse]Getting Started
     Lesson 1 - Initial Setup
     Lesson 2 - Generating Editors. Filtering Model
     Lesson 3 - Filtering Events
     Filtering UI Context Designer
     Lesson 4 - Filtering Attributes
   [Expand]Advanced Concepts
  [Expand]High DPI Support
  [Expand]Scaffolding Wizard
  [Expand]Formatting Values
   HTML Text Formatting
  [Expand]Tooltip Management
  [Expand]Saving and Restoring Layouts
   Clipboard - Copy Data and 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]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Report Server
[Expand]eXpressApp Framework
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Lesson 3 - Filtering Events

The Filtering UI Context generates editors depending on filtering Model property types. For instance, numeric properties will result in generating two text boxes that allow end-users to filter data by setting numeric ranges. However, the component is unable to predict what you require from more complex properties, such as of the String or Object types. To resolve such issues and/or supply editors with the additional information, the Filtering UI Context provides multiple filtering events.

  • QueryLookupData - handle this event to provide child items for any look-up editor.
  • QueryRangeData - allows you to set frontier minimum and maximum values for numeric properties.
  • QueryBooleanChoiceData - when only one boolean property value is relevant, you handle this event to ignore filtering this property by another value.

Expanded The QueryLookupData Event

After the previous lesson you have ended up with an empty editor for the 'Category_Name' property. The only child item it contains is the automatically added 'All' item. (see the figure below).

This happens because string properties have an unlimited number of possible values and the Filtering UI Context cannot generate a valid child editor item for each of them. At this point, you need to step in and provide the child item list manually. To do so, handle the QueryLookupData event. The QueryLookupDataEventArgs argument for this event handler 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 initially shown by this editor. 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.

For example, the following code iterates through every row of the DataTable to which the Data Grid control is bound. This code checks the cell values of the 'Category_Name' column for every row and writes all unique values to a List object.

You can use this list to populate the lookup editor as the following code sample illustrates.

The result is shown below.

By specifying the Result.Top property you can limit the number of initially visible lookup items.

Expanded The QueryRangeData Event

By handling this event, you can set minimum, maximum and average values for any editor that filters numeric properties.

In the following image minimum and maximum values are used to limit the RangeTrackBarControl. Refer to the Lesson 4 - Filtering Attributes article to learn how to choose the filtering editor's type.

Expanded The QueryBooleanChoice Event

In this example a filtering Model contains a boolen property, values of which indicate whether or not the product is currently in stock. By default, this results in generating a check box with three possible states: clear, checked and intermediate.

It is unlikely that a customer would like to browse only unavailable products. Thus, for this property, the false value is irrelevant. The QueryBooleanChoice event allows you to ignore such values by assigning them to the DefaultValue property.

The following animation illustrates the result: the check box now has only checked and clear states. Clear check box is now treated as 'do not apply any filtering by this property' and is the default editor state.

Vice versa, if you specify true as a default value, you will leave your end-users two options to choose from: display either all records (checked state) or only those with false values for the desired property (see the following figure).

Conversely, the clear check box now applies filtering by the false value to display up-to-date versions only, while the checked editor means 'display all existing versions'.

Expanded See Also

How would you rate this topic?​​​​​​​