Adding Custom Filter and Grouping Date Ranges

• Dec 28, 2020
• 3 minutes to read

The ExpressQuantumGrid allows you to manage filter and grouping date ranges by handling the OnInitFilteringDateRanges and OnInitGroupingDateRanges events, respectively. You should handle a View’s OnInitFilteringDateRanges event to manage filter date ranges which are common to all items in this View. To manage filter date ranges for a particular item, you should handle the item’s OnInitFilteringDateRanges event. You can manage grouping date ranges in a similar manner by handling a View’s OnInitGroupingDateRanges and/or an item’s OnInitGroupingDateRanges events.

To use the predefined date ranges when filtering and grouping data in a View by date/time values, use the View’s DateTimeHandling.Filters and DateTimeHandling.Grouping properties. Also you can specify grouping options for each individual column, which displays date/time values, via the column’s DateTimeGrouping property. Refer to the descriptions of these properties to learn about the correspondence between the predefined date ranges, and filter and grouping options.

The ExpressQuantumGrid allows you to extend a list of the predefined date ranges with custom date ranges. In order to do this, you should:

• create a TcxCustomGridDateRange descendant;

• to add the date range as a filter date range, handle the OnInitFilteringDateRanges event and add this date range to a collection of filter date ranges;

• to add the date range as a grouping date range, handle the OnInitGroupingDateRanges event and add this date range to a collection of grouping date ranges.

The following code snippet demonstrates how to create a date range which represents a one-quarter period.

type
  TcxGridQuarterRange = class(TcxCustomGridDateRange)
  public
    function Contains(const ADate: TDateTime): Boolean; override;
    function GetDisplayText(const ADate: TDateTime): string; override;
    function GetRangeValue(const ADate: TDateTime; AIgnoreTime: Boolean): Variant; override;
    function GetValue(const ADate: TDateTime): Variant; override;
  end;
implementation
uses
  ..., cxDateUtils;
// ...
// Utility functions
function GetStartMonthOfQuarter(const ADate: TDateTime): Integer;
begin
  Result := (dxGetDateElement(ADate, deMonth) - 1) div 3 * 3 + 1;
end;
function GetStartDateOfQuarter(const ADate: TDateTime): TDateTime;
begin
  Result := EncodeDate(dxGetDateElement(ADate, deYear), GetStartMonthOfQuarter(ADate), 1);
end;
function GetEndDateOfQuarter(const ADate: TDateTime; AIgnoreTime: Boolean): TDateTime;
var
  AMonth, AYear: Integer;
begin
  AYear := dxGetDateElement(ADate, deYear);
  AMonth := GetStartMonthOfQuarter(ADate) + 2;
  Result := EncodeDate(AYear, AMonth, MonthDays[IsLeapYear(AYear), AMonth]);
  if not AIgnoreTime then
    Result := Result + EncodeTime(23, 59, 59, 999);
end;
{ TcxGridQuarterRange }
function TcxGridQuarterRange.Contains(const ADate: TDateTime): Boolean;
begin
  Result := True;
end;
function TcxGridQuarterRange.GetDisplayText(const ADate: TDateTime): string;
begin
  Result := 'Qtr' + IntToStr((dxGetDateElement(ADate, deMonth) - 1) div 3 + 1) + ' ' + IntToStr(dxGetDateElement(ADate, deYear));
end;
function TcxGridQuarterRange.GetRangeValue(const ADate: TDateTime; AIgnoreTime: Boolean): Variant;
begin
  Result := VarBetweenArrayCreate(GetStartDateOfQuarter(ADate), GetEndDateOfQuarter(ADate, AIgnoreTime));
end;
function TcxGridQuarterRange.GetValue(const ADate: TDateTime): Variant;
begin
  Result := GetStartDateOfQuarter(ADate);
end;

The following code snippet demonstrates how to add the created date range to filter and grouping collections of date ranges by handling a View’s OnInitFilteringDateRanges and OnInitGroupingDateRanges events.

// A View's OnInitFilteringDateRanges event handler
procedure TForm1.tvCustomersInitFilteringDateRanges(
  Sender: TcxCustomGridTableItem; ADateRanges: TcxGridDateRanges);
begin
  ADateRanges.Add(TcxGridQuarterRange);
end;
// A View's OnInitGroupingDateRanges event handler
procedure TForm1.tvCustomersInitGroupingDateRanges(
  Sender: TcxCustomGridTableItem; ADateRanges: TcxGridDateRanges);
begin
  ADateRanges.Add(TcxGridQuarterRange);
end;

The following image shows the resulting View.

To narrow an item’s filter list to display only values that correspond to date ranges, handle the item’s OnGetFilterValues event.