PivotGridControl.CustomSummary Event

Enables summary values to be calculated manually.

Namespace: DevExpress.XtraPivotGrid

Assembly: DevExpress.XtraPivotGrid.v18.1.dll

Declaration

C#

public event PivotGridCustomSummaryEventHandler CustomSummary

VB.NET

Public Event CustomSummary As PivotGridCustomSummaryEventHandler

Event Data

The CustomSummary event's data class is PivotGridCustomSummaryEventArgs. The following properties provide information specific to this event:

Property	Description
ColumnField	Gets the column field that corresponds to the current cell. Inherited from PivotGridCustomSummaryEventArgsBase<T>.
ColumnFieldValue	Gets the value of the column field that corresponds to the current cell. Inherited from PivotGridCustomSummaryEventArgsBase<T>.
CustomValue	Gets or sets a custom summary value. Inherited from PivotGridCustomSummaryEventArgsBase<T>.
DataField	Gets the data field against which the summary is calculated. Inherited from PivotGridCustomSummaryEventArgsBase<T>.
FieldName	Gets the name of the data field against which the summary is calculated. Inherited from PivotGridCustomSummaryEventArgsBase<T>.
RowField	Gets the row field that corresponds to the current cell. Inherited from PivotGridCustomSummaryEventArgsBase<T>.
RowFieldValue	Gets the value of the row field that corresponds to the current cell. Inherited from PivotGridCustomSummaryEventArgsBase<T>.
SummaryValue	Gets an object that contains the values of the predefined summaries which are calculated for the current cell. Inherited from PivotGridCustomSummaryEventArgsBase<T>.

The event data class exposes the following methods:

Method	Description
CreateDrillDownDataSource()	Returns a list of the records that are associated with the cell currently being processed. Inherited from PivotGridCustomSummaryEventArgsBase<T>.

Remarks

The Pivot Grid Control calculates summaries against data fields. A field’s PivotGridFieldBase.SummaryType property specifies the type of summary function. The control automatically calculates all the predefined summary functions (see the PivotSummaryType topic for a list of the available functions) and it allows custom summaries to be calculated manually via the CustomSummary event.

To calculate a custom summary for a specific data field, set its PivotGridFieldBase.SummaryType property to PivotSummaryType.Custom. In this case, the CustomSummary event will fire for each cell that corresponds to this data field.

For instance, this event enables a custom summary to be calculated against multiple fields, particular records, etc. Use the PivotGridCustomSummaryEventArgsBase<T>.CreateDrillDownDataSource method to get a list of the records that correspond to the current cell. This list can then be traversed to calculate a summary in a custom manner. The custom summary value should be assigned to the PivotGridCustomSummaryEventArgsBase<T>.CustomValue parameter.

For each cell, the Pivot Grid Control calculates all the predefined summaries (AVERAGE, MIN, MAX, SUM, etc). The calculated values can be accessed using the PivotGridCustomSummaryEventArgsBase<T>.SummaryValue property. You can use them in custom summary calculations.

Note

The CustomSummary is not supported in server and OLAP modes.

Example

The following example shows how to calculate a custom summary.

Assume that the Pivot Grid Control is bound to a “SalesPerson” view. A field which displays the ratio of orders over $500 is to be added.

In this example, the custom summary is calculated against the “Extended Price” field. It’s PivotGridCustomTotalBase.SummaryType property is set to PivotSummaryType.Custom and the caption to “Percentage of Orders over $500”. The PivotGridControl.CustomSummary event is only handled to count those records whose total sum exceeds minSum. The ratio of these records to all the records is a custom summary value and therefore is assigned to the PivotGridCustomSummaryEventArgsBase<T>.CustomValue parameter.

The following image shows the result of the custom summary calculation:

C#

using DevExpress.XtraPivotGrid;

fieldExtendedPrice.Caption = "Percentage of Orders over $500";
// Enable a custom summary calculation for the Extended Price field.
fieldExtendedPrice.SummaryType = DevExpress.Data.PivotGrid.PivotSummaryType.Custom;
// Specify the settings used to format values.
fieldExtendedPrice.CellFormat.FormatType = DevExpress.Utils.FormatType.Numeric;
fieldExtendedPrice.CellFormat.FormatString = "p";

int minSum = 500;

private void pivotGridControl1_CustomSummary(object sender, 
  PivotGridCustomSummaryEventArgs e) {
   if(e.DataField != fieldExtendedPrice) return;
   // A variable which counts the number of orders whose sum exceeds $500.
   int order500Count = 0;
   // Get the record set corresponding to the current cell.
   PivotDrillDownDataSource ds = e.CreateDrillDownDataSource();
   // Iterate through the records and count the orders.
   for(int i = 0; i < ds.RowCount; i++) {
      PivotDrillDownDataRow row = ds[i];
      // Get the order's total sum.
      decimal orderSum = (decimal)row[fieldExtendedPrice];
      if(orderSum >= minSum) order500Count ++;
   }
   // Calculate the percentage.
   if(ds.RowCount > 0) {
      e.CustomValue = (decimal)order500Count/ds.RowCount;
   }
}

VB.NET

Imports DevExpress.XtraPivotGrid

fieldExtendedPrice.Caption = "Percentage of Orders over $500"
' Enable a custom summary calculation for the Extended Price field.
fieldExtendedPrice.SummaryType = DevExpress.Data.PivotGrid.PivotSummaryType.Custom
' Specify the settings used to format values.
fieldExtendedPrice.CellFormat.FormatType = DevExpress.Utils.FormatType.Numeric
fieldExtendedPrice.CellFormat.FormatString = "p"

Dim minSum As Integer = 500

Private Sub PivotGridControl1_CustomSummary(ByVal sender As Object, _
  ByVal e As PivotGridCustomSummaryEventArgs) Handles PivotGridControl1.CustomSummary
   If Not e.DataField Is fieldExtendedPrice Then Return
   ' A variable which counts the number of orders whose sum exceeds $500.
   Dim order500Count As Integer = 0
   ' Get the record set corresponding to the current cell.
   Dim ds As PivotDrillDownDataSource = e.CreateDrillDownDataSource()
   ' Iterate through the records and count the orders.
   Dim i As Integer
   For i = 0 To ds.RowCount - 1
      Dim row As PivotDrillDownDataRow = ds(i)
      ' Get the order's total sum.
      Dim orderSum As Decimal = row(fieldExtendedPrice)
      If orderSum >= minSum Then order500Count = order500Count + 1
   Next
   ' Calculate the percentage.
   If ds.RowCount > 0 Then
      e.CustomValue = order500Count / ds.RowCount
   End If
End Sub

Related GitHub Examples

The following code snippets (auto-collected from DevExpress Examples) contain references to the CustomSummary event.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

VB.NET

how-to-calculate-a-cell-summary-value-based-upon-another-field-value-e2392/VB/WindowsApplication53/Form1.vb#L39

Private Sub pivotGridControl1_CustomSummary(ByVal sender As Object, ByVal e As DevExpress.XtraPivotGrid.PivotGridCustomSummaryEventArgs) Handles pivotGridControl1.CustomSummary
    If e.DataField.Name = "fieldValue" Then

how-to-implement-a-custom-sort-by-summary-feature-e2917/VB/WindowsApplication53/Form1.vb#L53

Private Sub pivotGridControl1_CustomSummary(ByVal sender As Object, ByVal e As DevExpress.XtraPivotGrid.PivotGridCustomSummaryEventArgs) Handles pivotGridControl1.CustomSummary
    e.CustomValue = e.CreateDrillDownDataSource().RowCount

how-to-implement-the-distinct-count-summary-type-within-the-pivotgrid-e637/VB/CustomSummaryDistinctCountExample/Form1.vb#L20

InitializeComponent()
AddHandler pivotGridControl1.CustomSummary, AddressOf PivotGridControl1_CustomSummary
pivotGridControl1.BestFit()

how-to-display-the-difference-of-income-and-outlay-in-totals-t413352/VB/WindowsApplication53/Form1.vb#L38

Private Sub pivotGridControl1_CustomSummary(ByVal sender As Object,
                            ByVal e As PivotGridCustomSummaryEventArgs) Handles pivotGridControl1.CustomSummary
    If e.DataField.Name = "fieldValue" Then

how-to-provide-custom-summary-values-for-total-grand-total-and-ordinary-cells-t555679/VB/VBWinPivotCustomSummaryCellType/Form1.vb#L15

Private Sub pivotGridControl1_CustomSummary(ByVal sender As Object,
            ByVal e As PivotGridCustomSummaryEventArgs) Handles PivotGridControl1.CustomSummary
    If ReferenceEquals(e.DataField, fieldProductAmount1) Then

C#

how-to-implement-the-distinct-count-summary-type-within-the-pivotgrid-e637/CS/CustomSummaryDistinctCountExample/Form1.cs#L21

InitializeComponent();
pivotGridControl1.CustomSummary += PivotGridControl1_CustomSummary;
pivotGridControl1.BestFit();

how-to-provide-custom-summary-values-for-total-grand-total-and-ordinary-cells-t555679/CS/WinPivotCustomSummaryCellType/Form1.cs#L10

pivotGridControl1.CustomSummary += new PivotGridCustomSummaryEventHandler(pivotGridControl1_CustomSummary);
customerReportsTableAdapter1.Fill(nwindDataSet1.CustomerReports);