TcxDataSummaryItems.OnSummary Event

Allows you to customize summary calculation.

Declaration

delphi

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:

SenderProvides access to the summary item collection that raised the summary calculation event.Arguments``Arguments.SummaryItem and Arguments.RecordIndex fields allow you to identify the calculated summary item and the currently processed record in the source data item.OutArgumentsAllows you to customize summary calculation for the currently processed record. For example, you can assign True to the OutArguments.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:

Delphi
C++

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;

cpp

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
C++

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;

cpp

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)
}

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.

How to Test this Code Example

Follow the steps below to test this code example in your RAD Studio IDE:

Copy the DFM code snippet demonstrated within the current section.
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.

delphi

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

Delphi
C++

delphi

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;

cpp

void __fastcall TForm1::cxGrid1DBTableView1DataControllerSummaryFooterSummaryItemsSummary(
  TcxDataSummaryItems *ASender, TcxSummaryEventArguments &Arguments,
  TcxSummaryEventOutArguments &OutArguments) {
    TcxGridDBTableSummaryItem *ASummaryItem;

    ASummaryItem = dynamic_cast<TcxGridDBTableSummaryItem*>(Arguments.SummaryItem);
    if(ASummaryItem == cxGrid1DBTableViewVal) // Identifies the target column
    {
      switch(ASummaryItem->Tag) // Uses tag values to identify summary items
      {
        // Calculates the sum of only negative values (the condition excludes zero and positive values)
        case 1: OutArguments.Done = VarIsNull(OutArguments.Value) || (OutArguments.Value > 0); break;
        // Calculates the sum of only positive values (the condition excludes zero and negative values)
        case 2: OutArguments.Done = VarIsNull(OutArguments.Value) || (OutArguments.Value < 0); break;
        default: OutArguments.Done = false; break; // The first (0) item sums all values
      }
    }
}