Runtime Filtering

• Aug 02, 2022
• 7 minutes to read

This topic describes how to filter data at runtime. See the Filtering Data section for writing code to implement filtering.

1. Filter Dropdown List

2. Custom Filter Dialog

3. Filter Builder Dialog

4. Filter Row

1. Filter Dropdown List

With filter dropdowns, you can filter records in tabular and Card Views by the values of grid items (column or card rows). To invoke a filter dropdown for a grid item, click its filter dropdown button.

To provide visual feedback on columns which have a filter applied, switch the display mode for the View’s columns via the OptionsView.HeaderFilterButtonShowMode option.

A filter dropdown is populated with filter conditions determined by the grid item’s unique values. In large datasets, the dropdown population may take a while, since all records are accessed. In this case, we recommend that you limit the list’s capacity via the MaxValueListCount property.

The (All) and (Custom…) items are always added to the list. Selecting the (All) item removes all the filter conditions set for the current column. The (Custom…) item invokes the Custom Filter or Filter Builder dialog which allow you to visually construct the filter criteria for the given column or current View, respectively.

The (Blanks) and (NonBlanks) elements are added automatically if your column contains NULL and non-NULL values, respectively. You can customize this list before displaying it by using the column’s OnGetFilterValues event. You can remove elements from the list, add your own elements (enabling custom actions when they are selected) and customize the displayed list of values. For more information, refer to the TcxFilterValueList class topic.

Note

For grid items that display date/time values, filter dropdowns are populated with the predefined filter items according to the filter options accessible via a View’s DateTimeHandling.Filters property.

When a user selects a value from the list (any item other than (All), (Custom…), (Blanks) or (NonBlanks)), a new filter condition is created and applied to the data in the current View. This new condition is of the type:

<Column> = <Value>,

where <Column> stands for the current column for which the filter list was activated and <Value> defines the selected value. For instance, when selecting the ‘Mercedes-Benz’ item, the “Trademark = Mercedes-Benz” filter condition is created and applied:

When filtering is applied, the filter panel appears with a description of the filter criteria. The View’s FilterBox.Visible property affects the manner in which this panel is displayed within it. You can temporarily deactivate and then activate filtering by clicking the checkbox on this panel. The ‘x’ button clears all the filter criteria applied.

2. Custom Filter Dialog

Selecting the (Custom) item from the filter dropdown list activates the Custom Filter dialog.

This dialog allows you to specify the filter criteria for a single column consisting of one or two filter conditions. You can also specify the operator for these conditions.

The following image shows all the possible operators:

Operator	Text representation
=	equals
<>	does not equal
<	is less than
<=	is less than or equal to
>	is greater than
>=	is greater than or equal to
LIKE	like
NOT LIKE	not like
= NULL	is blank
<> NULL	is not blank

In addition to the operator, values must be specified via the value box. This uses the same editor type as the column (stand-alone and in-place use the same editor classes).

When using the LIKE or NOT LIKE operator, you can substitute one or more symbols in a string value with specific characters (by default, the ‘underscore’ (_) and ‘percent’ (%)). To provide your custom characters, use the View’s DataController.Filter.UnderscoreWildcard and PercentWildCard properties.

The second filter condition is specified in the same manner. To combine two conditions, use the AND/OR check box.

3. Filter Builder Dialog

In some cases, however, filter conditions cannot be displayed with the help of the Custom Filter dialog. For instance, the Custom Filter dialog supports only one or two filter conditions for a single column. The dialog also does not support some filter operators (BETWEEN, membership test operator and date/time related operators). So if the filter criteria contains more than two conditions bound to a single column or if non-supportable operators are used, the Filter Builder dialog is activated instead when selecting the (Custom…) option from the filter dropdown list.

The filter criteria specified by this dialog is interpreted as:

(ID=1 OR ID=4 OR ID=7) AND (CustomerID>=1 AND CustomerID<=100)

The Filter Builder dialog extends the functionality of the Custom Filter dialog. Unlike the Custom Filter, the Filter Builder dialog allows you to specify the filter criteria for any column in the View. An end-user can also invoke the dialog by clicking either the Customize button in the filter panel or the corresponding View Navigator button. Set the View’s FilterBox.CustomizeDialog property to True to make the button visible.

The Filter Builder dialog supports all possible operators. In addition to those described in the above table, you can create filter conditions using the BETWEEN, membership test operators and date/time related operators:

Operator	Description
BETWEEN	The operator allows you to select records whose column values are included between two operands. To specify the range, use the editors which appear when clicking the operand boxes. The operator displayed in the picture above is equivalent to the following statement: ID>=1 AND ID<=100
NOT BETWEEN	The NOT BETWEEN operator selects records whose column values are not included in the required range. Operands are specified in the same manner as for the BETWEEN operator. The equivalent of the operator displayed in the image is: ID<1 AND ID>100
IN	Implements a membership test operator. The IN operator selects records with column values equal to operands from the specified set. To add an operand to the set, click the ‘+’ button. The equivalent to the IN operator shown in the image above is: ID=1 OR ID=4 OR ID=7
NOT IN	The negation of the IN operator. It selects a record if its column value is not a member of a specified set. The equivalent to the IN operator shown in the image above is: ID<>1 AND ID<>4 AND ID<>7
Date/time operators: is yesterday is today is tomorrow is last 7 days is last week is last 14 days is last two weeks is last 30 days is last month is last year is past is this week is this month is this year is next 7 days is next week is next 14 days is next two weeks is next 30 days is next month is next year is future	This group of operators is available only for date/time fields. They do not require any operands. For instance, the is today operator selects records with column values equal to the current day. The is this year operator selects records equal to the current year, etc. String representations of these operators are determined by the filter options accessible via a View’s DateTimeHandling.Filters property.

The Filter Builder dialog also supports two more Boolean operators to combine conditions in the list: NOT AND and NOT OR.

NOT AND combines conditions by the AND operator and then negates the result:

These criteria select all records except those with the Car column value set to ‘BMW 530i’ and PaymentType set to Cash. The equivalent text representation is:

NOT (Car=’BMW 530i’ AND PaymentType=Cash)

NOT OR combines conditions by the OR operator and then negates the result:

With these criteria, the grid selects records, which don’t have their PaymentType set to Master or Visa. The text representation is:

NOT (PaymentType=Master OR PaymentType=Visa)

To invoke the Custom Filter or Filter Builder dialog programmatically, call the View’s Filtering.RunCustomizeDialog method. You can invoke your own Filter Builder dialog by handling the OnFilterDialogShow or OnFilterCustomization events.

Set the item’s Options.Filtering property or the View’s OptionsCustomize.ColumnFiltering property to False to deactivate runtime filtering.