Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[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
  [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]Document Server
[Expand]Reporting
[Expand]Report 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 filtering editors' 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 unless you remove all the previously generated editors and re-create the filtering UI.

Tip

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

Expanded FilterBooleanChoice

This attribute is used to mark boolean properties and provides the following members:

  • EditorType - allows you to choose which editor is generated for this 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 the specific Boolean value. For instance, filtering by the ”InStock = false” expression makes no sense since it is not needed to see only unavailable goods. 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 - like 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 frontier 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 frontier 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 managing editors that are 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 like 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. Adding the FilterEnumChoice attribute allows you 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 Metadata Attributes

The example attached to the Data Annotation Attributes topic illustrates how to use the 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 that 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.

Like the information in the Data Bindings and Notifications topic's Meta-POCO Bindings section, you can use the MetadataBuilder to build all the required metadata using the Fluent API. See the code below for an example.

After your 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 reference 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 a generated filtering editor's caption (if it has any) and arrange this editor to a specific group. To do so, use Display attribute's Name and GroupName parameters.
  • 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 such 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 format data within the 'Price' property' editors as currency.
Refer to the Using Data Annotations to Customize Data Classes MSDN topic to learn more about data annotation attributes.

Expanded See Also

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