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;
#Sum Different Value Types Separately
The code example in this section demonstrates an OnSummary
event handler. This handler configures three existing summaries to display sums of positive and negative values as well as the total value.
The grid Table View’s OptionsView.FooterMultiSummaries property is set to True
to display all summary items.
Follow the steps below to test this code example in your RAD Studio IDE:
- Copy the DFM code snippet below.
- Create a new project in the IDE and focus an empty form.
- Press Ctrl+V to populate the form with preconfigured components.
- Select cxGrid1DBTableView1 in the TcxGrid on the form.
- Create an empty
OnSummary
event handler in the DataController.Summary.FooterSummaryItems node, paste the code example, and run the project.
object cxGrid1: TcxGrid
Left = 8
Top = 8
Width = 441
Height = 278
TabOrder = 0
object cxGrid1DBTableView1: TcxGridDBTableView
Navigator.Buttons.CustomButtons = <>
ScrollbarAnnotations.CustomAnnotations = <>
DataController.DataSource = DataSource1
DataController.Summary.DefaultGroupSummaryItems = <>
DataController.Summary.FooterSummaryItems = <
item
Kind = skSum
Tag = 1
Column = cxGrid1DBTableView1Val
end
item
Kind = skSum
Tag = 2
Column = cxGrid1DBTableView1Val
end
item
Kind = skSum
Column = cxGrid1DBTableView1Val
end>
DataController.Summary.SummaryGroups = <>
OptionsView.Footer = True
OptionsView.FooterMultiSummaries = True
object cxGrid1DBTableView1RecId: TcxGridDBColumn
DataBinding.FieldName = 'RecId'
Width = 84
end
object cxGrid1DBTableView1Desc: TcxGridDBColumn
DataBinding.FieldName = 'Desc'
Width = 190
end
object cxGrid1DBTableView1Val: TcxGridDBColumn
DataBinding.FieldName = 'Val'
Width = 165
end
end
object cxGrid1Level1: TcxGridLevel
GridView = cxGrid1DBTableView1
end
end
object dxMemData1: TdxMemData
Active = True
Indexes = <>
Persistent.Data = {
5665728FC2F5285C8FFE3F020000000A00000001000500446573630002000000
0200040056616C000105000000446573633101FDFF0105000000446573633201
03000105000000446573633301FEFF01050000004465736334010200}
SortOptions = []
Left = 72
Top = 224
object dxMemData1Desc: TStringField
FieldName = 'Desc'
Size = 10
end
object dxMemData1Val: TSmallintField
FieldName = 'Val'
end
end
object DataSource1: TDataSource
DataSet = dxMemData1
Left = 120
Top = 224
end
object dxSkinController1: TdxSkinController
SkinName = 'WXICompact'
SkinPaletteName = 'Clearness'
Left = 192
Top = 224
end
procedure TForm1.cxGrid1DBTableView1DataControllerSummaryFooterSummaryItemsSummary(
ASender: TcxDataSummaryItems; Arguments: TcxSummaryEventArguments;
var OutArguments: TcxSummaryEventOutArguments);
var
ASummaryItem: TcxGridDBTableSummaryItem;
begin
ASummaryItem := Arguments.SummaryItem as TcxGridDBTableSummaryItem;
if ASummaryItem.Column = cxGrid1DBTableView1Val then // Identifies the target column
begin
case ASummaryItem.Tag of // Uses tag values to identify summary items
1: // Calculates the sum of only negative values (the condition excludes zero and positive values)
OutArguments.Done := VarIsNull(OutArguments.Value) or (OutArguments.Value > 0);
2: // Calculates the sum of only positive values (the condition excludes zero and negative values)
OutArguments.Done := VarIsNull(OutArguments.Value) or (OutArguments.Value < 0);
end;
end;
end;