TcxCustomGridTableItem.OnUserFilteringEx Event

Enables you to apply proper filter criteria when a custom created filter item (a fviUserEx filter value item) is selected from the View item’s filter dropdown.

Declaration

property OnUserFilteringEx: TcxGridUserFilteringExEvent read; write;

Remarks

With the View item’s OnGetFilterValues event, you can add custom items (fviUser and fviUserEx filter value items) to the View item’s filter dropdown. Since these items have no predefined filter criteria associated with them, you need to apply appropriate custom criteria by handling the following events:

• For fviUser items, handle the OnUserFiltering event;

• For fviUserEx items, handle the OnUserFilteringEx event.

The OnUserFilteringEx event is fired for each fviUserEx item selected in the filter dropdown, enabling you to apply proper filter criteria for these items.

The Sender parameter references the View item whose filter dropdown has been invoked.

The AFilterList parameter provides access to the filter criteria that is built based on all the selected filter items at the moment the event is fired. Use this parameter to add the criteria associated with the selected fviUserEx item.

The AValue and ADisplayText parameter values identify the selected fviUserEx item. These are the values you provided when adding the item in an OnGetFilterValues event handler. Refer to the OnGetFilterValues event description to learn more.

Note that unlike the fviUser items, the fviUserEx items can be combined – more than one filter criteria that corresponds to a fviUserEx item can be applied to the View at one time. That’s why a filter dropdown displays check boxes for these items in multi-selection mode. In this mode, filter criteria are combined using the OR operator, so you need to apply custom criteria that do not conflict with built-in item criteria and other custom criteria. If you want only one custom filter item to be selected in this mode, use fviUser items and handle the OnUserFiltering event instead.

The following code example demonstrates how to handle the OnGetFilterValues and OnUserFilteringEx events to add custom filter criteria to the Age column’s filter dropdown, with which end-users can filter persons in the View by age categories (predefined age ranges).

uses
   ..., cxVariants;
type
  TForm1 = class(TForm)
// ...
  private
    // Declaring age ranges
    AChildrenAgeRange: Variant;
    ATeensAgeRange: Variant;
    AAdultsAgeRange: Variant;
// ...
  end;
implementation
procedure TForm1.FormCreate(Sender: TObject);
begin
  // Initializing age range bounds
  // Children (3-12)
  AChildrenAgeRange := VarArrayCreate([0,1], varVariant);
  AChildrenAgeRange[0] := 3;
  AChildrenAgeRange[1] := 12;
  // Teens (13-18)
  ATeensAgeRange := VarArrayCreate([0,1], varVariant);
  ATeensAgeRange[0] := 13;
  ATeensAgeRange[1] := 18;
  // Adults (19-59)
  AAdultsAgeRange := VarArrayCreate([0,1], varVariant);
  AAdultsAgeRange[0] := 19;
  AAdultsAgeRange[1] := 59;
end;
procedure TForm1.<View>ColumnAgeGetFilterValues(Sender: TcxCustomGridTableItem; AValueList: TcxDataFilterValueList);
begin
  // Adding three age ranges as fviUserEx filter items
  AValueList.Add(fviUserEx, AChildrenAgeRange, 'Children (Ages 3-12)', True);
  AValueList.Add(fviUserEx, ATeensAgeRange, 'Teens (Ages 13-18)', True);
  AValueList.Add(fviUserEx, AAdultsAgeRange, 'Adults (Ages 19-59)', True);
end;
procedure TForm1.<View>ColumnAgeUserFilteringEx(Sender: TcxCustomGridTableItem; AFilterList: TcxFilterCriteriaItemList; const AValue: Variant; const ADisplayText: string);
begin
  // Applying filter criteria based on the selected age ranges
  if VarEquals(AValue, AChildrenAgeRange) then
    Sender.DataBinding.AddToFilter(AFilterList, foBetween, AChildrenAgeRange, '3;12', False)
  else
    if VarEquals(AValue, ATeensAgeRange) then
      Sender.DataBinding.AddToFilter(AFilterList, foBetween, ATeensAgeRange, '13;18', False)
    else
      if VarEquals(AValue, AAdultsAgeRange) then
        Sender.DataBinding.AddToFilter(AFilterList, foBetween, AAdultsAgeRange, '19;59', False);
end;

The screenshot below shows the resulting filter dropdown invoked for the Age column.