TcxDataSummaryItems.OnSummary Event
Allows you to customize summary calculation.
Declaration
property OnSummary: TcxSummaryEvent read; write;
Remarks
A summary item in the collection can use one of the predefined summary calculation algorithms to iterate through all target record values of the associated data item. A footer summary iterates through all record values of the associated data item while a group summary iterates through the data item’s record values that belong to the corresponding group.
You can handle the OnSummary
event to override or complement the selected summary calculation algorithm. For example, you can exclude Null Variant record values from summary calculation as demonstrated in the code example below.
Event Occurrence
The OnSummary
event occurs every time a summary item processes a record in the source data item to calculate a summary. The OutArguments
.CountValue field returns the number of OnSummary
event occurrences during the current calculation process.
Event Parameters
The following parameters are accessible within an OnSummary
event handler:
Sender
- Provides access to the summary item collection that raised the summary calculation event.
Arguments
Arguments
.SummaryItem andArguments
.RecordIndex fields allow you to identify the calculated summary item and the currently processed record in the source data item.OutArguments
- Allows you to customize summary calculation for the currently processed record. For example, you can assign
True
to theOutArguments
.Done field to exclude the currently processed record’s value from the resulting summary.
Refer to the TcxSummaryEvent procedural type description for detailed information on all available options.
Code Examples
Exclude Null Values from Summary Calculation
The following code example excludes all Null Variant record values from summary calculation:
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;
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):
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;