Skip to main content

DevExpress v24.2 Update — Your Feedback Matters

Our What's New in v24.2 webpage includes product-specific surveys. Your response to our survey questions will help us measure product satisfaction for features released in this major update and help us refine our plans for our next major release.

Take the survey Not interested

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:

Sender
Provides 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.
OutArguments
Allows 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:

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.

How to Test this Code Example

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

  1. Copy the DFM code snippet below.
  2. Create a new project in the IDE and focus an empty form.
  3. Press Ctrl+V to populate the form with preconfigured components.
  4. Select cxGrid1DBTableView1 in the TcxGrid on the form.
  5. 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;

VCL Data Grid: Three Different Summaries for the Same Column

See Also