Add(String,SummaryType,ICustomSummaryCalculator,UltraGridColumn,SummaryPosition,UltraGridColumn) Method

Adds a new SummarySettings object created using the supplied arguments and returns that new summary settings object.

Syntax

Visual Basic
C#

'Declaration
 
Public Overloads Function Add( _
   ByVal key As String, _
   ByVal summaryType As SummaryType, _
   ByVal customSummaryCalculator As ICustomSummaryCalculator, _
   ByVal sourceColumn As UltraGridColumn, _
   ByVal summaryPosition As SummaryPosition, _
   ByVal summaryPositionColumn As UltraGridColumn _
) As SummarySettings

public SummarySettings Add( 
   string key,
   SummaryType summaryType,
   ICustomSummaryCalculator customSummaryCalculator,
   UltraGridColumn sourceColumn,
   SummaryPosition summaryPosition,
   UltraGridColumn summaryPositionColumn
)

Parameters

key: A value that uniquely identifies an object in a collection.
summaryType: SummaryType. If you specify Custom, then a valid instance ICustomSummaryCalculator must be passed in as customSummaryCalculator.
customSummaryCalculator: Only required if SummaryType is Custom.
sourceColumn: Field that will be summarized.
summaryPosition: Specifies the place where the summary will be displayed in the grid.
summaryPositionColumn: Only required if summaryPosition is UseSummaryPositionColumn

Return Value

The new SummarySettings object that was created and added to the collection with supplied arguments.

Remarks

Creates a new SummarySettings object based on the passed in arguments and adds it to the collection.

If summaryType is SummaryType.Custom, then you must also pass in a valid instance of ICustomSummaryCalculator for customSummaryCalculator argument. If SummaryType is something other than Custom, then this parameter is not required and can be null.

If summaryPosition is SummaryPosition.UseSummaryPositionColumn, then it will be displayed under summaryPositionColumn column. If summaryPositionColumn is not specified, then it will be displayed under the source column. This column must be from the same band this SummaryCollection is asscocited with. If summaryPosition is something other than UseSummaryPositionColumn, then summaryPositionColumn parameter is not required and can be null.

SourceColumn is the column whose data is being summarized. The sourceColumn must be the band associated with this SummarySettingsCollection or from one of the descendant bands.

Example

Following code adds a custom summary for calculating totals for customer orders. OrderTotalsSummary class defined above implements ICustomSummaryCalculator interface necessary to calculate custom summaries in UltraGrid.

Visual Basic

Imports Infragistics.Shared
Imports Infragistics.Win
Imports Infragistics.Win.UltraWinGrid

  ' A class that calculates the totals for orders.
  Private Class OrderTotalsSummary
      Implements ICustomSummaryCalculator

      Private totals As Decimal = 0

      Public Sub New()
      End Sub

      Private Sub BeginCustomSummary(ByVal summarySettings As SummarySettings, ByVal rows As RowsCollection) Implements ICustomSummaryCalculator.BeginCustomSummary

          ' Begins the summary for the SummarySettings object passed in. Implementation of 
          ' this method should reset any state variables used for calculating the summary.
          Me.totals = 0

      End Sub

      Private Sub AggregateCustomSummary(ByVal summarySettings As SummarySettings, ByVal row As UltraGridRow) Implements ICustomSummaryCalculator.AggregateCustomSummary

          ' Here is where we process each row that gets passed in.

          Dim unitPrice As Object = row.GetCellValue(summarySettings.SourceColumn.Band.Columns("Unit Price"))
          Dim quantity As Object = row.GetCellValue(summarySettings.SourceColumn.Band.Columns("Quantity"))

          ' Handle null values
          If unitPrice Is DBNull.Value Or quantity Is DBNull.Value Then
              Return
          End If

          ' Convert to decimal.
          Try
              Dim nUnitPrice As Decimal = Convert.ToDecimal(unitPrice)
              Dim nQuantity As Decimal = Convert.ToDecimal(quantity)

              Me.totals += nQuantity * nUnitPrice
          Catch e As Exception
              ' This should not happen if the columns are numeric.
              Debug.Assert(False, "Exception thrown while trying to convert cell's value to decimal !")
          End Try

      End Sub

      Private Function EndCustomSummary(ByVal summarySettings As SummarySettings, ByVal rows As RowsCollection) Implements ICustomSummaryCalculator.EndCustomSummary

          ' This gets called when the every row has been processed so here is where we
          ' would return the calculated summary value.
          Return Me.totals

      End Function
  End Class

  Private Sub Button12_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles button12.Click

      Dim band As UltraGridBand = Me.ultraGrid1.DisplayLayout.Bands(2)

      ' Add the OrderTotals custom summary.
      Dim summary As SummarySettings = band.Summaries.Add("OrderTotals", SummaryType.Custom, _
          New OrderTotalsSummary(), band.Columns("Unit Price"), SummaryPosition.Left, Nothing)

      ' Set the format with which to format the calculated summary when displaying
      ' in the summary footer.
      summary.DisplayFormat = "Sales Total = {0:######.00}"

      ' Set the horizontal text align to right so that the text summary text is aligned
      ' right in the summary element.
      summary.Appearance.TextHAlign = HAlign.Right

      ' Set the summary position to Left so that it shows up on the left of the
      ' summary footer area.
      summary.SummaryPosition = SummaryPosition.Right

      ' Set the appearance of the summary.
      summary.Appearance.FontData.Bold = DefaultableBoolean.True
      summary.Appearance.ForeColor = Color.Maroon
      summary.Appearance.BackColor = Color.LightGray

      ' Set the text that shows up in the caption of the summary footer.
      band.SummaryFooterCaption = "Total Sales for Order (OrderID)"

      ' Set the appearance of the summary footer area.
      Me.ultraGrid1.DisplayLayout.Override.SummaryFooterAppearance.FontData.Bold = DefaultableBoolean.True
      Me.ultraGrid1.DisplayLayout.Override.SummaryFooterAppearance.BackColor = Color.White
      Me.ultraGrid1.DisplayLayout.Override.SummaryFooterAppearance.ForeColor = Color.Black

      ' Set the appearance for the caption on top of the summary area.
      Me.ultraGrid1.DisplayLayout.Override.SummaryFooterCaptionVisible = DefaultableBoolean.True
      Me.ultraGrid1.DisplayLayout.Override.SummaryFooterCaptionAppearance.BackColor = Color.DarkBlue
      Me.ultraGrid1.DisplayLayout.Override.SummaryFooterCaptionAppearance.ForeColor = Color.LightYellow

  End Sub

using Infragistics.Shared;
using Infragistics.Win;
using Infragistics.Win.UltraWinGrid;
using System.Diagnostics;

// A class that calculates the totals for orders.
private class OrderTotalsSummary : ICustomSummaryCalculator 
{
	private decimal totals = 0;

	internal OrderTotalsSummary( )
	{
	}

	public void BeginCustomSummary( SummarySettings summarySettings, RowsCollection rows )
	{

		// Begins the summary for the SummarySettings object passed in. Implementation of 
		// this method should reset any state variables used for calculating the summary.
		this.totals = 0;

	}

	public void AggregateCustomSummary( SummarySettings summarySettings, UltraGridRow row )
	{

		// Here is where we process each row that gets passed in.

		object unitPrice = row.GetCellValue( summarySettings.SourceColumn.Band.Columns["Unit Price"] );
		object quantity = row.GetCellValue( summarySettings.SourceColumn.Band.Columns["Quantity"] );

		// Handle null values
		if ( unitPrice is DBNull || quantity is DBNull )
		{
			return;
		}

		// Convert to decimal.
		try
		{
			decimal nUnitPrice = Convert.ToDecimal( unitPrice );
			decimal nQuantity = Convert.ToDecimal( quantity );

			this.totals += nQuantity * nUnitPrice;
		}
		catch ( Exception )
		{
			// This should not happen if the columns are numeric.
			Debug.Assert( false, "Exception thrown while trying to convert cell's value to decimal !" );
		}

	}

	
	public object EndCustomSummary( SummarySettings summarySettings, RowsCollection rows )		
	{

		// This gets called when the every row has been processed so here is where we
		// would return the calculated summary value.
		return this.totals;

	}
}

private void button12_Click(object sender, System.EventArgs e)
{

	UltraGridBand band = this.ultraGrid1.DisplayLayout.Bands[2];

	// Add the OrderTotals custom summary.
	SummarySettings summary = band.Summaries.Add( 
		"OrderTotals",					// Give an identifier (key) for this summary
		SummaryType.Custom,				// Summary type is custom
		new OrderTotalsSummary( ),		// Our custom summary calculator
		band.Columns["Unit Price"],		// Column being summarized. Just use Unit Price column.
		SummaryPosition.Left,			// Position the summary on the left of summary footer
		null							// Since SummaryPosition is Left, pass in null
		);
	
	// Set the format with which to format the calculated summary when displaying
	// in the summary footer.
	summary.DisplayFormat = "Sales Total = {0:######.00}";

	// Set the horizontal text align to right so that the text summary text is aligned
	// right in the summary element.
	summary.Appearance.TextHAlign = HAlign.Right;

	// Set the summary position to Left so that it shows up on the left of the
	// summary footer area.
	summary.SummaryPosition = SummaryPosition.Right;

	// Set the appearance of the summary.
	summary.Appearance.FontData.Bold = DefaultableBoolean.True;
	summary.Appearance.ForeColor = Color.Maroon;
	summary.Appearance.BackColor = Color.LightGray;

	// Set the text that shows up in the caption of the summary footer.
	band.SummaryFooterCaption = "Total Sales for Order [OrderID]";

	// Set the appearance of the summary footer area.
	this.ultraGrid1.DisplayLayout.Override.SummaryFooterAppearance.FontData.Bold = DefaultableBoolean.True;
	this.ultraGrid1.DisplayLayout.Override.SummaryFooterAppearance.BackColor = Color.White;
	this.ultraGrid1.DisplayLayout.Override.SummaryFooterAppearance.ForeColor = Color.Black;
	
	// Set the appearance for the caption on top of the summary area.
	this.ultraGrid1.DisplayLayout.Override.SummaryFooterCaptionVisible = DefaultableBoolean.True;
	this.ultraGrid1.DisplayLayout.Override.SummaryFooterCaptionAppearance.BackColor = Color.DarkBlue;
	this.ultraGrid1.DisplayLayout.Override.SummaryFooterCaptionAppearance.ForeColor = Color.LightYellow;

}

Requirements

Target Platforms: Windows 10, Windows 8.1, Windows 8, Windows 7, Windows Server 2012, Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

Reference

SummarySettingsCollection Class
SummarySettingsCollection Members
Overload List

Windows Forms | Help Topics

Add(String,SummaryType,ICustomSummaryCalculator,UltraGridColumn,SummaryPosition,UltraGridColumn) Method

Parameters

Return Value

Reference