GridView.CustomSummaryCalculate Event
Enables you to calculate summary values manually.
Namespace: DevExpress.XtraGrid.Views.Grid
Assembly: DevExpress.XtraGrid.v17.2.dll
Declaration
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. |
| 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
Total summaries and group summaries provide five predefined aggregate functions. These functions allow you to calculate the number of rows, the maximum and minimum values, the sum and the average value. If you need to calculate a summary value using an aggregate function not included in the predefined set, set the summary item’s GridSummaryItem.SummaryType property to SummaryItemType.Custom and handle the CustomSummaryCalculate event.
The CustomSummaryCalculate event fires for each row involved in summary calculation. When calculating a total summary value, the event is raised for each data row. When calculating a group summary value, the event fires for each data row within the currently processed group. Additionally, the event is raised before and after processing rows. This can be used to perform any needed initialization and finalization.
Generally, the process of calculating custom summary values can be described using the following sequence of steps:
- Performing calculation initialization. The CustomSummaryCalculate event is raised and its CustomSummaryEventArgs.SummaryProcess parameter returns the CustomSummaryProcess.Start value. This can be used to initialize the CustomSummaryEventArgs.TotalValue parameter that will accumulate the custom calculated value. For instance, if you need to calculate the sum of particular values, set the CustomSummaryEventArgs.TotalValue parameter to 0. If you need to perform multiplications, initialize the parameter to 1.
Performing calculations. The CustomSummaryCalculate event is raised for each row within the desired range. Its CustomSummaryEventArgs.SummaryProcess parameter returns the CustomSummaryProcess.Calculate value. Use the CustomSummaryEventArgs.RowHandle property to identify the currently processed row and obtain its values, if needed. If you only need to know the summary item’s associated field value, read the CustomSummaryEventArgs.FieldValue property.
When the CustomSummaryCalculate event is raised for a data row, you need to update the CustomSummaryEventArgs.TotalValue property value. For instance, you may need to calculate the sum of values exceeding the predefined limit. In this case, you need to check whether the current field value exceeds the limit and add the value to the CustomSummaryEventArgs.TotalValue property, if so. Thus, the property will accumulate a custom summary value.
- Performing calculation finalization. The CustomSummaryCalculate event is raised and its CustomSummaryEventArgs.SummaryProcess parameter returns the CustomSummaryProcess.Finalize value. At this time, you can update the calculated value by modifying the CustomSummaryEventArgs.TotalValue property.
Note
Custom summaries are not supported in server mode.
Refer to the Working with Summaries in Code topic for additional information.
Example
This example illustrates how to utilize values from multiple grid column summary fields to calculate a value for a custom summary item.
The sample grid control contains two numeric columns. The first column has only one summary item. To set a single summary item for a column, use the GridColumn.SummaryItem property.
colId.SummaryItem.SummaryType = DevExpress.Data.SummaryItemType.Max;
colId.SummaryItem.DisplayFormat = "Max = {0}";
The second column has more than one summary item. For such columns, use the GridColumn.Summary collection instead of the GridColumn.SummaryItem property.
this.colIdRandom.Summary.AddRange(new DevExpress.XtraGrid.GridSummaryItem[] {
new DevExpress.XtraGrid.GridColumnSummaryItem(DevExpress.Data.SummaryItemType.Min, "IdRandom", "MIN={0}", "Min"),
new DevExpress.XtraGrid.GridColumnSummaryItem(DevExpress.Data.SummaryItemType.Count, "IdRandom", "Count = {0}", "Count"),
new DevExpress.XtraGrid.GridColumnSummaryItem(DevExpress.Data.SummaryItemType.Custom, "IdRandom", "Custom Summary = {0}")});
The code above adds three summary fields. Two of them are auto-calculated and display the maximum column value and total records count. The last summary item has its SummaryItemType property set to Custom. Custom summaries receive their values on the GridView.CustomSummaryCalculate event. The code below illustrates how to handle this event to retrieve auto-calculated summary values. Based on these values, the value for the custom summary field is calculated.
private void gridView1_CustomSummaryCalculate(object sender, DevExpress.Data.CustomSummaryEventArgs e)
{
if (e.IsTotalSummary)
{
GridView view = sender as GridView;
decimal max = Convert.ToDecimal(view.Columns["Id"].SummaryItem.SummaryValue);
decimal min = Convert.ToDecimal(view.Columns["IdRandom"].Summary["Min"].SummaryValue);
decimal count = Convert.ToDecimal(view.Columns["IdRandom"].Summary["Count"].SummaryValue);
e.TotalValue = (max - min)*count;
e.TotalValueReady = true;
}
}
Complete example code is shown below.
using DevExpress.XtraGrid.Views.Grid;
using System;
namespace WindowsFormsApplication1 {
public partial class Form1 : DevExpress.XtraEditors.XtraForm {
public Form1()
{
InitializeComponent();
colId.SummaryItem.SummaryType = DevExpress.Data.SummaryItemType.Max;
colId.SummaryItem.DisplayFormat = "Max = {0}";
this.colIdRandom.Summary.AddRange(new DevExpress.XtraGrid.GridSummaryItem[] {
new DevExpress.XtraGrid.GridColumnSummaryItem(DevExpress.Data.SummaryItemType.Min, "IdRandom", "Min = {0}", "Min"),
new DevExpress.XtraGrid.GridColumnSummaryItem(DevExpress.Data.SummaryItemType.Count, "IdRandom", "Count = {0}", "Count"),
new DevExpress.XtraGrid.GridColumnSummaryItem(DevExpress.Data.SummaryItemType.Custom, "IdRandom", "Custom Summary = {0}")});
}
private void gridView1_CustomSummaryCalculate(object sender, DevExpress.Data.CustomSummaryEventArgs e)
{
if (e.IsTotalSummary)
{
GridView view = sender as GridView;
decimal max = Convert.ToDecimal(view.Columns["Id"].SummaryItem.SummaryValue);
decimal min = Convert.ToDecimal(view.Columns["IdRandom"].Summary["Min"].SummaryValue);
decimal count = Convert.ToDecimal(view.Columns["IdRandom"].Summary["Count"].SummaryValue);
e.TotalValue = (max - min)*count;
e.TotalValueReady = true;
}
}
}
}
Related GitHub Examples
The following code snippets (auto-collected from DevExpress Examples) contain references to the CustomSummaryCalculate 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.