TreeList.GetCustomSummaryValue Event

Enables you to perform custom summary value calculations.

Namespace: DevExpress.XtraTreeList

Assembly: DevExpress.XtraTreeList.v19.1.dll

Declaration

C#

public event GetCustomSummaryValueEventHandler GetCustomSummaryValue

VB.NET

Public Event GetCustomSummaryValue As GetCustomSummaryValueEventHandler

Event Data

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

Property	Description
Column	Obtains the Tree List column used by the summary calculations.
CustomValue	Gets or sets a value to be displayed within a summary.
IsSummaryFooter	Gets a value indicating whether the total or group summary value is to be calculated.
Nodes	Gets the nodes collection for which to calculate a custom summary.

Remarks

The summary feature calculates the result of an aggregate function applied to column values. There are two types of summaries that can be used as described below.

• Total Summary. This type of aggregate function is specified by the TreeListColumn.SummaryFooter property of a column. The function is applied to all values within the column or to values within the root nodes only. This is specified by the TreeListColumn.AllNodesSummary property of the column. The summary result is displayed within the summary footer (its visibility is controlled by the TreeListOptionsView.ShowSummaryFooter option).
• Group Summary. This type of aggregate function is specified by the TreeListColumn.RowFooterSummary property. The function is applied to each group of column values that belong to nodes which have the same parent. The result is displayed within row(group) footers.

There are 5 summary functions provided by the Tree List control. However, you can implement your own logic for summary calculations by setting the TreeListColumn.SummaryFooter or TreeListColumn.RowFooterSummary property to SummaryItemType.Custom. In this instance, the GetCustomSummaryValue event fires each time the summary value needs to be obtained.

The value to be displayed must be assigned to the GetCustomSummaryValueEventArgs.CustomValue parameter of the event. Mainly, you will have to visit each node affected by the summary in order to perform calculations. This can be done in the following ways depending on the summary type:

• If the group summary value is to be calculated, you must visit each node from the collection specified by the GetCustomSummaryValueEventArgs.Nodes parameter.
• If the total summary is calculated and the TreeListColumn.AllNodesSummary property is set to false, all the required nodes are also transmitted via the GetCustomSummaryValueEventArgs.Nodes parameter.
• If the total summary value is to be calculated and the TreeListColumn.AllNodesSummary property value is true you must visit each node within the control. This can be done be means of the nodes iterator that can be accessed via the TreeList.NodesIterator property. Please refer to this property description for details.

Example

The following sample code declares a new node operation class. This class can be used to calculate the number of nodes in which the specified field value is greater than the predefined limit. The code also handles the TreeList.GetCustomSummaryValue event. This is used to calculate the number of nodes that have a value greater than 500,000 in the Budget field.

Note: you must set a column’s TreeListColumn.SummaryFooter property to SummaryItemType.Custom to make use of the TreeList.GetCustomSummaryValue event.

C#

using DevExpress.XtraTreeList;

// declaring the custom operation class
public class TreeListExceedLimitOperation : TreeListOperation {
   private string fieldName;
   private int upperLimit;
   private int result;

   public TreeListExceedLimitOperation(string fieldName, int upperLimit) {
      this.fieldName = fieldName;
      this.upperLimit = upperLimit;
      result = 0;
   }
   // incrementing the counter if the node's value exceeds the limit
   public override void Execute(TreeListNode node) {
      int nodeValue = Convert.ToInt32(node[fieldName]);
      if (nodeValue > upperLimit)
         result++;
   }
   public int Result {
      get { return result; }
   }
}

// ...
// using the created class to calculate the number of nodes
// that have a value greater than 500000 in their Budget field
private void treeList1_GetCustomSummaryValue(object sender, GetCustomSummaryValueEventArgs e) {
   if (e.IsSummaryFooter) {
      TreeListExceedLimitOperation operation = 
        new TreeListExceedLimitOperation("Budget", 500000);
      treeList1.NodesIterator.DoOperation(operation);
      e.CustomValue = operation.Result;
   }
}

VB.NET

Imports DevExpress.XtraTreeList

' declaring the custom operation class
Public Class TreeListExceedLimitOperation
   Inherits TreeListOperation

   Private FieldName As String
   Private UpperLimit As Integer
   Private _result As Integer

   Public Sub New(ByVal FieldName As String, ByVal UpperLimit As Integer)
      Me.FieldName = FieldName
      Me.UpperLimit = UpperLimit
      _result = 0
   End Sub

   ' incrementing the counter if the node's value exceeds the limit
   Public Overrides Sub Execute(ByVal Node As TreeListNode)
      Dim NodeValue As Integer = Convert.ToInt32(Node(FieldName))
      If NodeValue > UpperLimit Then _result += 1
   End Sub

   Public ReadOnly Property Result() As Integer
      Get
         Return _result
      End Get
   End Property
End Class

' ...
' using the created class to calculate the number of nodes
' that have a value greater than 500000 in their Budget field
Private Sub TreeList1_GetCustomSummaryValue(ByVal sender As Object, _
ByVal e As GetCustomSummaryValueEventArgs) Handles TreeList1.GetCustomSummaryValue
   If (e.IsSummaryFooter) Then
      Dim Operation As New TreeListExceedLimitOperation("Budget", 500000)
      TreeList1.NodesIterator.DoOperation(Operation)
      e.CustomValue = Operation.Result
   End If
End Sub