TcxCustomGridTableItem.OnUserFiltering Event

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

Declaration

property OnUserFiltering: TcxGridUserFilteringEvent 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.

When an end-user selects the fviUser item in the filter dropdown, the OnUserFiltering event is fired, enabling you to apply filter criteria that correspond to this item.

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

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 fviUserEx items, the fviUser items cannot be combed – only one filter criteria that corresponds to a fviUser item can be applied to the View at one time. That’s why check boxes are not displayed for these items when the multi-selection mode is enabled in a filter dropdown. To allow multiple custom filter items to be selected in this mode, use fviUserEx items and handle the OnUserFilteringEx event instead.

Consider an example of using the OnGetFilterValues and OnUserFiltering events. The OnGetFilterValues event will add the ‘Filter TODAY‘ and ‘Filter YESTERDAY‘ items to the filter dropdown. The OnUserFiltering event will apply the corresponding filter criteria.

First, consider the OnGetFilterValues event handler.

Delphi

const
  filterTodayID = 0;
  filterYesterdayID = 1;
// An OnGetFilterValues event handler
// Add the 'Filter TODAY' and 'Filter YESTERDAY' elements for the tvOrdersPurchaseDate column
procedure <Form>.tvOrdersPurchaseDateGetFilterValues(Sender: TcxCustomGridTableItem; AValueList: TcxDataFilterValueList);
begin
  AValueList.Add(fviUser, filterTodayID, 'Filter TODAY', True);
  AValueList.Add(fviUser, filterYesterdayID, 'Filter YESTERDAY', True);
end;

C++

const  filterTodayID = 0;
const  filterYesterdayID = 1;
// An OnGetFilterValues event handler
// Add the "Filter TODAY" and "Filter YESTERDAY" elements for the tvOrdersPurchaseDate column
void <Form>::tvOrdersPurchaseDateGetFilterValues(TcxCustomGridTableItem *Sender; TcxDataFilterValueList *AValueList)
{
  AValueList->Add(fviUser, filterTodayID, "Filter TODAY", true);
  AValueList->Add(fviUser, filterYesterdayID, "Filter YESTERDAY", true);
}

As a result, you will see two new elements in the filter dropdown list for the tvOrdersPurchaseDate column:

The following code creates and applies appropriate filters when a user selects the ‘Filter TODAY’ or ‘Filter YESTERDAY’ entries from the list.

Delphi

// An OnUserFiltering event handler
procedure TSummaryFooterDemoMainForm.tvOrdersPurchaseDateUserFiltering(Sender: TcxCustomGridTableItem; const AValue: Variant; const ADisplayText: String);
var
  ADate: TDateTime;
  ADateStr: string;
begin
  case AValue of
    filterTodayID:
    begin
      ADate := Today;
      ADateStr := 'Today';
    end;
    filterYesterdayID:
    begin
      ADate := Yesterday;
      ADateStr := 'Yesterday'
    end;
  end;
  Sender.DataBinding.AddToFilter(nil, foEqual, ADate, ADateStr, True);
end;

C++

// An OnUserFiltering event handler
void TSummaryFooterDemoMainForm::tvOrdersPurchaseDateUserFiltering(TcxCustomGridTableItem *Sender, const Variant AValue, const String ADisplayText)
{
  TDateTime ADate;
  string ADateStr;
  switch (AValue) {
    case filterTodayID:
      ADate = Today;
      ADateStr = "Today";
      break;
    case filterYesterdayID:
      ADate = Yesterday;
      ADateStr = "Yesterday";
  }
  Sender->DataBinding->AddToFilter(NULL, foEqual, ADate, ADateStr, true);
}

The following image shows a sample grid control after selecting the ‘Filter YESTERDAY’ entry.