[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
  [Expand]High DPI Support
  [Expand]Scaffolding Wizard
  [Expand]Formatting Values
   HTML Text Formatting
  [Expand]Menus
  [Expand]Tooltip Management
  [Expand]Saving and Restoring 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]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Filtering Attributes

The Filtering UI Context component can recognize attributes declared before filtering Model properties. These attributes affect the filter editor's appearance and behavior. There are two types of supported attributes:

Note

Filtering attributes have no effect if you declare them after clicking the 'Retrieve Fields' link in the component's smart tag menu unless you remove all previously generated editors and re-create the filter UI.

Tip

You can use filter attributes outside the scope of the Filtering UI Context component. For instance, you can select which editors appear inside an Excel-style filter using these attributes.

Expanded FilterBooleanChoice

This attribute marks Boolean properties and provides the following members:

  • EditorType - allows you to choose which editor is generated for the Boolean property:
    • Check Edit (default)
    • ComboBox Edit
    • Radio Group
    • Toggle Switch Edit
  • DefaultName, TrueName, FalseName - replaces the default 'True', 'False' and 'Default' option names for ComboBox Edit and Radio Group editors.
  • DefaultValue - allows you to prohibit filtering data by a specific Boolean value. For example, filtering by the ”InStock = false” expression makes no sense since browsing only unavailable goods makes no sense. In this scenario, the ”false” value is irrelevant and can be ignored. Note that you can do the same by handling the QueryBooleanChoiceData event.
  • DefaultValueMember - similar to the DefaultValue property, but instead of specifying the irrelevant Boolean value explicitly, you refer to a property or a method that returns this value. This member must be declared in either a base or parent ViewModel.
The code sample below illustrates how to use this attribute.

The figure below illustrates the result.

Expanded FilterRange

Declare this attribute before a numeric property to change the editor type and provide borderline editor values.

  • EditorType - for filtering numeric properties you can use:
    • two Text Edits (default)
    • two Spin Edits
    • Range Trackbar
  • FromName, ToName - replaces the default 'From' and 'To' captions next to Text or Spin Edit editors.
  • Minimum, Maximum, Average - sets the numeric property's borderline values. Identical to the QueryRangeData event.
  • MinimumMember, MaximumMember, AverageMember - allows you to implement a more flexible behavior, where minimum, maximum and average values are not explicitly set, but returned by specific members declared in either a base or parent ViewModel.

Expanded FilterDateTimeRange

An attribute that manages editors used for filtering DateTime properties.

  • EditorType - allows you to choose from multiple editor variations. Currently, only the Default/Range value is operational. This value allows you to display two DateEdit editors.
  • Since this attribute derives from the same base class as the FilterRange attribute, it exposes the same properties: FromName, Minimum, AverageMember, etc.

Expanded FilterEnumChoice

This attribute allows you to customize editors for properties that store enumeration values. Alternatively, it makes it possible to treat non-enumeration properties as an Enum type.

For example, in the code below, a sample filtering ViewModel contains car records with the "Doors" property as one of the data fields. This is an integer property, and the Filtering UI Context generates "From" and "To" text boxes for this field by default. Create a custom "DoorsEnum" enumeration and map the "Doors" property to this enumeration by declaring the EnumDataType attribute. The Filtering UI Context now treats this property an Enum type, which allows end-users to select the required values instead of setting value ranges. Add the FilterEnumChoice attribute to customize the editor generated for this field.

The result is shown below.

The FilterEnumChoice attribute provides the following properties.

  • EditorType - allows you to choose which editor should be generated for the current filtering Model property.
  • UseSelectAll - gets or sets whether the editor should display the item that selects all the available options. The SelectAllName property allows you to replace this item's caption.

Expanded FilterLookup

An attribute that marks properties of the String, Object and other complex types. Provides the capability to load and/or initially display a specific item number.

  • EditorType supports the following editors:
  • DataSourceMember - refers to a member that returns a collection of lookup items for this editor. This member must be declared in either the base or parent ViewModel.
  • Top, MaxCount - allows you to limit the number of initially visible items and their overall amount. See the QueryLookupData event to learn more.
  • TopMember, MaxCountMember - the same as Top and MaxCount properties, but accepts the names of either base or parent ViewModel members that return the required numbers.
  • UseSelectAll, SelectAllName - specifies an item's availability and caption which allows end-users to select all lookup items.

Expanded FilterGroup

This attribute allows an Excel-style filter dropdown to group filter items from two or more properties (columns), and present the result as a hierarchical checked list.

Assume that a grid control contains the CategoryID and ProductName columns. Each column's filter dropdown displays filter items as regular lists.

You can group products by categories in the ProductName column's filter dropdown by applying the following FilterGroup attribute:

The result is shown below:

To apply the same grouping to the CategoryID column, set the FilterGroup attribute to FilterGroup("ProductName") or FilterGroup("CategoryID;ProductName"):

For the TreeList control, instead of using the FilterGroup attribute, you can utilize the TreeListOptionsColumnFilter.PopupExcelFilterGrouping property.

Expanded Metadata Attributes

The example attached to the Data Annotation Attributes topic illustrates how to use Microsoft's MetadataType attribute to inherit attributes declared within a separate class. The Filtering UI Context supports the same attribute. Additionally, DevExpress provides the FilterMetadataType attribute, which has priority over the MetadataType attribute and is designed to inherit filtering attributes. Both attributes must be declared before the filtering Model's class declaration.

The following code displays a filtering Model that uses only standard attributes to customize the editor's appearance. All filtering attributes are declared in a separate class and inherited by the filtering Model marked with the FilterMetadataType attribute. Note that you do not need to duplicate filtering Model properties within your metadata class - declaring object-typed public fields is sufficient.

You can use the MetadataBuilder to build all required metadata using the Fluent API. See the code below (and the Data Bindings and Notifications article's Meta-POCO Bindings section) for an example.

After the metadata class is ready, you need to register it. The code below demonstrates how to register the sample metadata class and set up a relationship between it and the filtering Model .

Important

Using the metadata builder requires that your application references the DevExpress.MVVM library.

Expanded Data Annotation Attributes

These are standard Microsoft attributes, declared in the System.ComponentModel.DataAnnotations namespace. You can use these attributes to do the following:

  • Change the generated filter editor's caption (if it has any) and place this editor to a specific group. Use the Display attribute's Name and GroupName parameters to do this.
  • Prohibit generating editors for specific filtering Model properties. This feature is helpful when using code-first data sources, where your data class can be used as a filtering Model directly. Such classes often contain data field properties that should not be available for filtering (for example, product IDs). To disable filtering by these properties, set the Display attribute 's AutoGenerateFilter parameter to false.
  • Format editors' data using the DataType and DisplayFormat attributes. The code sample below illustrates how to apply the currency format to the 'Price' editor.
Refer to the Using Data Annotations to Customize Data Classes MSDN topic to learn more about data annotation attributes.

Expanded See Also

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