GridView.CustomSummaryCalculate Event

Allows custom summary value calculation. Fires for summary items with SummaryType set to SummaryItemType.Custom.

Namespace: DevExpress.XtraGrid.Views.Grid

Assembly: DevExpress.XtraGrid.v25.1.dll

NuGet Packages: DevExpress.Win.Grid, DevExpress.Win.Navigation

Declaration

C#

[DXCategory("Data")]
public event CustomSummaryEventHandler CustomSummaryCalculate

VB.NET

<DXCategory("Data")>
Public Event CustomSummaryCalculate As CustomSummaryEventHandler

Event Data

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

Property	Description
FieldValue	Gets the processed field value.
GroupLevel	Gets the nested level of the group whose summary value is being calculated.
GroupRowHandle	Gets a value identifying the group row whose child data rows are involved in summary calculation.
IsGroupSummary	Gets whether a group summary value is being calculated.
IsTotalSummary	Gets whether a total summary value is being calculated.
Item	Gets a summary item whose value is being calculated.
Mode	Specifies how summaries are calculated - against all rows or for the selected rows.
Row	Gets the currently processed row.
RowHandle	Gets the handle of the processed row.
SummaryProcess	Gets a value indicating calculation stage.
TotalValue	Gets or sets the total summary value.
TotalValueReady	Gets or sets whether the Calculation stage of the custom summary calculation process should be skipped.

The event data class exposes the following methods:

Method	Description
GetGroupSummary(Int32, Object)	Returns the value of the specified group summary for the specified group row.
GetValue(String)	Returns the value in the specified field

Remarks

The GridControl calculates predefined summary types (for example, MAX, MIN, COUNT, AVG, etc.) automatically. To implement custom summary logic, handle the CustomSummaryCalculate event.

Note

A summary is treated as custom if its GridSummaryItem.SummaryType property equals to SummaryItemType.Custom.

The grid raises the CustomSummaryCalculate event in three stages:

1. Start

   The event fires with the e.SummaryProcess == CustomSummaryProcess.Start. Use this stage to initialize the e.TotalValue parameter.

2. Calculate

   The event fires once for each data row (in total summaries) or group row (in group summaries), with e.SummaryProcess == CustomSummaryProcess.Calculate. Use e.RowHandle and e.FieldValue to access the row and value. Update e.TotalValue accordingly.

3. Finalize

   After processing all rows, the event fires with e.SummaryProcess == CustomSummaryProcess.Finalize. Use this stage to finalize e.TotalValue.

See the following help topic for more information: Working with Summaries in Code. Custom Summaries.

Specific Notes

Server Mode

In Server Mode, the CustomSummaryCalculate event fires only once with e.CustomSummaryProcess == CustomSummaryProcess.Finalize. The event does not process individual data rows. Assign the final value to e.TotalValue directly.

C#

gridView1.CustomSummaryCalculate += (obj, e) => {
    e.TotalValueReady = true;
    e.TotalValue = 100;
};

VB.NET

gridView1.CustomSummaryCalculate += Function(obj, e)
    e.TotalValueReady = True
    e.TotalValue = 100
End Function

Summary Field Not Represented by a Grid Column

If the summary item references a data field that is not displayed in the grid (for example, no column is bound to this field), the CustomSummaryCalculate event fires only twice — once with CustomSummaryProcess.Start and once with CustomSummaryProcess.Finalize. The CustomSummaryProcess.Calculate stage is skipped, as the grid does not iterate through data rows.

Example

The example below creates a new custom summary items and populates it on the GridView.CustomSummaryCalculate event. You can test this sample in our DevExpress Demo Center (the link requires Demo Center of version 16.2 or newer to be installed).

The custom summary item is located under the “Length” column. To add it, set up the GridColumn.SummaryItem property.

C#

gridView.OptionsView.ShowFooter = true;
GridColumn column = gridView.Columns["Length"];
column.SummaryItem.SummaryType = SummaryItemType.Custom;

VB.NET

gridView.OptionsView.ShowFooter = True
Dim column As GridColumn = gridView.Columns("Length")
column.SummaryItem.SummaryType = SummaryItemType.Custom

The CustomSummaryCalculate event handler checks the current calculation state by reading the CustomSummaryEventArgs.SummaryProcess value. Cell values are added to the total sum only if the corresponding cell under the “Mark” column is checked.

C#

double sum = 0;
gridView.CustomSummaryCalculate += (sender, e) => {
    GridView view = sender as GridView;
    if (e.IsTotalSummary && (e.Item as GridSummaryItem).FieldName=="Length") {
        GridSummaryItem item = e.Item as GridSummaryItem;
        if (item.FieldName == "Length") {
            switch (e.SummaryProcess) {
                case CustomSummaryProcess.Start:
                    sum = 0;
                    break;
                case CustomSummaryProcess.Calculate:
                    bool shouldSum = (bool)view.GetRowCellValue(e.RowHandle, "Mark");
                    if (shouldSum) {
                        sum += (double)e.FieldValue;
                    }
                    break;
                case CustomSummaryProcess.Finalize:
                    e.TotalValue = sum;
                break;
            }
        }
    }
};

VB.NET

Dim sum As Double = 0
AddHandler gridView.CustomSummaryCalculate, Sub(sender, e)
    Dim view As GridView = TryCast(sender, GridView)
    If e.IsTotalSummary AndAlso (TryCast(e.Item, GridSummaryItem)).FieldName="Length" Then
        Dim item As GridSummaryItem = TryCast(e.Item, GridSummaryItem)
        If item.FieldName = "Length" Then
            Select Case e.SummaryProcess
                Case CustomSummaryProcess.Start
                    sum = 0
                Case CustomSummaryProcess.Calculate
                    Dim shouldSum As Boolean = CBool(view.GetRowCellValue(e.RowHandle, "Mark"))
                    If shouldSum Then
                        sum += CDbl(e.FieldValue)
                    End If
                Case CustomSummaryProcess.Finalize
                    e.TotalValue = sum
            End Select
        End If
    End If
End Sub

To automatically update the summary item when users check or clear the “Mark” column checkboxes, the GridView.UpdateTotalSummary method is called on the RepositoryItem.EditValueChanged event.

C#

RepositoryItemCheckEdit edit = gridView.Columns["Mark"].RealColumnEdit as RepositoryItemCheckEdit;
edit.EditValueChanged += (sender, e) => {
    //Post an editor's value to a data source
    gridView.PostEditor();
    //Force calculation of the total summary
    gridView.UpdateTotalSummary();
};

VB.NET

Dim edit As RepositoryItemCheckEdit = TryCast(gridView.Columns("Mark").RealColumnEdit, RepositoryItemCheckEdit)
AddHandler edit.EditValueChanged, Sub(sender, e)
    'Post an editor's value to a data source
    gridView.PostEditor()
    'Force calculation of the total summary
    gridView.UpdateTotalSummary()
End Sub

The code below is a complete example code.

C#

    // Handle this event to calculate summary values manually
    double sum = 0;
    gridView.CustomSummaryCalculate += (sender, e) => {
        GridView view = sender as GridView;
        if (e.IsTotalSummary && (e.Item as GridSummaryItem).FieldName=="Length") {
            GridSummaryItem item = e.Item as GridSummaryItem;
            if (item.FieldName == "Length") {
                switch (e.SummaryProcess) {
                    case CustomSummaryProcess.Start:
                        sum = 0;
                        break;
                    case CustomSummaryProcess.Calculate:
                        bool shouldSum = (bool)view.GetRowCellValue(e.RowHandle, "Mark");
                        if (shouldSum) {
                            sum += (double)e.FieldValue;
                        }
                        break;
                    case CustomSummaryProcess.Finalize:
                        e.TotalValue = sum;
                        break;
                }
            }
        }
    };

    gridView.OptionsView.ShowFooter = true;
    GridColumn column = gridView.Columns["Length"];
    column.SummaryItem.SummaryType = SummaryItemType.Custom;

    RepositoryItemCheckEdit edit = gridView.Columns["Mark"].RealColumnEdit as RepositoryItemCheckEdit;
    edit.EditValueChanged += (sender, e) => {
        //Post an editor's value to a data source
        gridView.PostEditor();
        //Force calculation of the total summary
        gridView.UpdateTotalSummary();
    };

VB.NET

    ' Handle this event to calculate summary values manually
    Dim sum As Double = 0
    AddHandler gridView.CustomSummaryCalculate, Sub(sender, e)
        Dim view As GridView = TryCast(sender, GridView)
        If e.IsTotalSummary AndAlso (TryCast(e.Item, GridSummaryItem)).FieldName="Length" Then
            Dim item As GridSummaryItem = TryCast(e.Item, GridSummaryItem)
            If item.FieldName = "Length" Then
                Select Case e.SummaryProcess
                    Case CustomSummaryProcess.Start
                        sum = 0
                    Case CustomSummaryProcess.Calculate
                        Dim shouldSum As Boolean = CBool(view.GetRowCellValue(e.RowHandle, "Mark"))
                        If shouldSum Then
                            sum += CDbl(e.FieldValue)
                        End If
                    Case CustomSummaryProcess.Finalize
                        e.TotalValue = sum
                End Select
            End If
        End If
    End Sub

    gridView.OptionsView.ShowFooter = True
    Dim column As GridColumn = gridView.Columns("Length")
    column.SummaryItem.SummaryType = SummaryItemType.Custom

    Dim edit As RepositoryItemCheckEdit = TryCast(gridView.Columns("Mark").RealColumnEdit, RepositoryItemCheckEdit)
    AddHandler edit.EditValueChanged, Sub(sender, e)
        'Post an editor's value to a data source
        gridView.PostEditor()
        'Force calculation of the total summary
        gridView.UpdateTotalSummary()
    End Sub