TcxSummaryEventOutArguments Record

Stores output arguments of summary calculation events.

Declaration

TcxSummaryEventOutArguments = record

Remarks

A summary item uses one of the predefined calculation algorithms to iterate through all target record values of the associated data item. Every iteration of the summary calculation process raises a summary calculation event that allows you to modify the calculation algorithm for individual target values.

TcxSummaryEventArguments and TcxSummaryEventOutArguments records are accessible within a summary calculation event handler through Arguments and OutArguments parameters. These records allow you to identify the currently processed summary item, record, and its value as well as modify the active summary calculation algorithm based on this information.

Main API Members

The list below outlines key members of the TcxSummaryEventOutArguments record. These members allow you to override or complement the selected predefined calculation algorithm for the currently processed record value.

CountValue

Returns the number of processed record values (summary calculation event occurrences before the current one).

Done

Specifies if the active predefined algorithm is applied to the currently processed record value.

Tip

Assign True to the Done field to exclude the currently processed record value from summary calculation.

SummaryValue

Returns the intermediate summary value calculated during all previous iterations (event occurrences).

You can use the CountValue field to identify the number of previous iterations.

Value

Stores the value of the currently processed record.

Code Examples

Exclude Null Values from Summary Calculation

The following code example excludes all Null Variant record values from summary calculation:

Delphi

procedure TMyForm.cxGrid1DBTableView1DataControllerSummaryDefaultGroupSummaryItemsSummary(
  ASender: TcxDataSummaryItems; Arguments: TcxSummaryEventArguments;
  var OutArguments: TcxSummaryEventOutArguments);
begin
  if (VarIsNull(OutArguments.Value)) then // If the currently processed value is Null Variant
    OutArguments.Done := True;  // Ignores the Null Variant record value
end;

C++

void __fastcall TMyForm::cxGrid1DBTableView1DataControllerSummaryDefaultGroupSummaryItemsSummary(
  TcxDataSummaryItems *ASender, TcxSummaryEventArguments &Arguments,
  TcxSummaryEventOutArguments &OutArguments) {
  if (VarIsNull(OutArguments.Value)) {  // If the currently processed value is Null Variant
    OutArguments.Done = true;  // Ignores the Null Variant record value
  }
}

Custom Summary Calculation

All predefined summary calculation algorithms use record values of only one data item. The OnSummary event allows you to modify a predefined summary calculation algorithm in any manner. For example, you can use values of multiple data items in every iteration of the summary calculation process.

The code example below demonstrates an OnSummary event handler that modifies the predefined algorithm MAX. The event handler calculates the highest population density based on data-aware grid columns that display country areas (DBTableView1Area) and corresponding population values (DBTableView1Population):

Delphi

procedure TMyForm.cxGrid1DBTableView1DataControllerSummaryDefaultGroupSummaryItemsSummary(
  ASender: TcxDataSummaryItems; Arguments: TcxSummaryEventArguments;
  var OutArguments: TcxSummaryEventOutArguments);
var
  AArea, APopulation: Variant;
begin
  // Obtain the area value for the currently processed record
  AArea := ASender.DataController.Values[Arguments.RecordIndex, DBTableView1Area.Index];
  // Obtain the population value for the currently processed record
  APopulation := ASender.DataController.Values[Arguments.RecordIndex, DBTableView1Population.Index];
  OutArguments.Value := APopulation/AArea; // Calculates the custom summary value (maximum population density)
end;

C++

void __fastcall TMyForm::cxGrid1DBTableView1DataControllerSummaryDefaultGroupSummaryItemsSummary(
  TcxDataSummaryItems *ASender, TcxSummaryEventArguments &Arguments,
  TcxSummaryEventOutArguments &OutArguments) {
  // Obtain the area value for the currently processed record
  Variant AArea = ASender->DataController->Values[Arguments.RecordIndex][DBTableView1Area->Index];
  // Obtain the population value for the currently processed record
  Variant APopulation = ASender->DataController->Values[Arguments.RecordIndex][DBTableView1Area->Index];
  OutArguments.Value = APopulation/AArea;  // Calculates the custom summary value (maximum population density)
}

Direct TcxSummaryEventOutArguments Type Reference

The OutArguments parameter of the TcxSummaryEvent procedural type references the TcxSummaryEventOutArguments record.