Log In
[Expand]General Information
[Collapse]WinForms Controls
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Collapse]Data Grid
   [Expand]Getting Started
   [Expand]Binding to Data
   [Expand]Grid View
   [Expand]View Technology
     Summaries Overview
     Tutorial: Custom Summary Functions
     Tutorial: Format Summary Text
     Tutorial: Group Summaries
     Tutorial: Obtain Summary Values
     Tutorial: Sort Group Rows by Summary Values
     Tutorial: Total Summaries
     Total Summary
     Group Summary
     Custom Aggregate Functions
     Format Summary Values
     Obtain Summary Values
     Sorting Group Rows by Summary Values
     Controlling Visibility of Group Summaries for Individual Group Rows
   [Expand]Data Editing
   [Expand]Filtering and Locating Rows
   [Expand]Focus and Selection Handling
   [Expand]Processing Rows
   [Expand]Formatting Cell Values
   [Expand]Master-Detail Relationships
   [Expand]Asynchronous Image Load
   [Expand]Export and Printing
   [Expand]Appearance and Conditional Formatting
   [Expand]Batch Modifications
   [Expand]Hit Information
   [Expand]Popup Menus
   [Expand]Saving and Restoring Layouts
   [Expand]Visual Elements
   [Expand]Design-Time Features
   [Expand]End-User Capabilities
    Included Components
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Map Control
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]PDF Viewer
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Report Server
[Expand]eXpressApp Framework
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Custom Aggregate Functions

This topic describes a way of implementing custom aggregate functions to calculate summaries. Basic information about summaries is provided in the Summaries Overview topic.

Expanded Online Video

Learn how to implement custom aggregate functions to calculate total and group summaries.

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 a custom algorithm or any aggregate function, you need to handle a Grid View's event and implement a custom summary calculation algorithm.

Custom summaries give you the ability to:

  • calculate summaries against records that meet specific criteria;
  • involve multiple fields in calculations;
  • implement complex summary functions (for instance, the standard deviation of a population), etc.

Note that in specific cases you may wish to modify the calculation algorithm a little for one of the standard summaries. For instance, when calculating the Average function, Grid Control interprets null values as zeros. You may want to change this calculation algorithm so as to ignore the records that contain null values. The Grid Control, however, doesn't allow you to interfere in the standard summary calculation. Instead, you will need to create a custom summary (replicate the standard algorithm with required modifications).

Expanded General information

To calculate a summary manually:

The GridView.CustomSummaryCalculate event fires for each row involved in a 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 a group. Additionally, the event is raised before and after processing rows, and this can be used to perform any initialization and finalization needed.

The summary calculation consists of three stages: Initialization, Calculation and Finalization. When handling the GridView.CustomSummaryCalculate you can determine the current stage by reading an event's CustomSummaryEventArgs.SummaryProcess parameter.

  • Initialization

    The CustomSummaryCalculate event fires once and the SummaryProcess parameter is set to CustomSummaryProcess.Start. At this stage you can initialize summary start values (for instance, reset counters or variables that will cumulate running totals).

  • Calculation

    The CustomSummaryCalculate event fires multiple times (once for each row in a View or group). The SummaryProcess parameter is set to CustomSummaryProcess.Calculate during each event call. At this stage, you should cumulate summaries according to your logic.

    The currently processed row is identified by the CustomSummaryEventArgs.RowHandle property. To get row values you can use the GridView.GetRowCellValue method, which takes a row handle as a parameter.

  • Finalization

    The CustomSummaryCalculate event fires once and the SummaryProcess parameter is set to CustomSummaryProcess.Finalize. At this point, calculate a final summary value and assign it to the CustomSummaryEventArgs.TotalValue parameter.

In specific instances, you may want to calculate a custom summary at the Initialization or Finalization stage while skipping the time-consuming Calculation stage. To do this, set the CustomSummaryEventArgs.TotalValueReady parameter to true at the Initialization step. If the TotalValueReady property is set to true, the Calculation stage is skipped and the Finalization stage starts immediately.

Expanded Example

The following example shows how to create two custom summaries, which will be calculated in the GridView.CustomSummaryCalculate event. It is assumed that the grid control is bound to a data source that contains the 'UnitPrice' and 'Discontinued' fields against which the summaries will be calculated. The grid's records are grouped by a 'UnitsInStock' field in this example.

The first summary will calculate the number of records that have a 'Discontinued' field set to true. This is a group summary. The second summary will calculate the sum of values in a 'UnitPrice' field against the records that have the 'Discontinued' field set to false. This is a total summary.

The final result of this example is shown below.

  1. Customizing the total summary

    To initialize the total summary for the 'UnitPrice' column at design time, click its header in the grid, and switch it to the Properties window that now lists column settings. Use the column's GridColumn.SummaryItem property to customize the summary item. Set its properties as follows:

    - GridSummaryItem.SummaryType to Custom;

    - GridSummaryItem.DisplayFormat to "Custom Sum = {0:C2}"

    - GridSummaryItem.Tag to 1.

    The GridSummaryItem.Tag property is used to identify this summary item while calculating summaries via the GridView.CustomSummaryCalculate event. Any value can be assigned to this property. In this example. an integer value (1) is assigned to it.

    Total summaries are displayed within the view footer, which is hidden by default. To make it visible, use the GridOptionsView.ShowFooter property.

    To initialize a total summary at runtime, use the following code.

  2. Creating the group summary

    To create a group summary, open the grid's Designer and then switch to the Group Summary Items Page. Click the Add button to create a group summary item and customize it as follows:

    - GridSummaryItem.SummaryType to Custom;

    - GridSummaryItem.FieldName to 'Discontinued';

    - GridSummaryItem.DisplayFormat to "(Discontinued products = {0})"

    - GridSummaryItem.Tag to 2.

    Group summary items created at runtime must be added to the GridView.GroupSummary collection manually. The following code shows how to create a group summary item via code.

  3. Custom summary calculation

    The final step is to implement the custom summary calculation via the GridView.CustomSummaryCalculate event. This event is called for each summary item whose GridSummaryItem.SummaryType property is set to Custom. To recognize specific summary items in this example their GridSummaryItem.Tag properties are used.

Now if you run the project the result will be like the image below.

The complete code of the example is shown below.

Expanded See Also

How would you rate this topic?​​​​​​​