Back to Devexpress

BandCollection.Add(Band) Method

xtrareports-devexpress-dot-xtrareports-dot-ui-dot-bandcollection-dot-add-x28-devexpress-dot-xtrareports-dot-ui-dot-band-x29.md

latest12.5 KB
Original Source

BandCollection.Add(Band) Method

Overrides the XRControlCollection.Add method.

Namespace : DevExpress.XtraReports.UI

Assembly : DevExpress.XtraReports.v25.2.dll

NuGet Package : DevExpress.Reporting.Core

Declaration

csharp
public int Add(
    Band band
)
vb
Public Function Add(
    band As Band
) As Integer

Parameters

NameTypeDescription
bandBand

A Band object to add to the collection of bands.

|

Returns

TypeDescription
Int32

An integer value indicating the position into which the new band was inserted.

|

Remarks

When you create or edit a report, use the Add method to add a new band. Note that some band types should appear only once in the report, while other band types can be added multiple times. When you attempt to add a band of a type that cannot be duplicated in the report, an exception occurs with the message Msg_IncorrectBandType.

Note that the Add method is not intended to copy bands from one report to another. You must create a new Band instance, and then add it to the BandCollection.

If you want to copy a band from an existing report, you should serialize and deserialize the band to create a new instance and then add it to the collection, as the following code snippet shows:

csharp
using DevExpress.XtraReports.Serialization;
// ...
static Band CopyBand(Band band) {
    using (var stream = new System.IO.MemoryStream()) {
        RootXmlObject rootObject = new RootXmlObject(new System.ComponentModel.IComponent[] { band });
        XRControlXmlSerializer serializer = new XRControlXmlSerializer(new XtraReportsSerializationContext() { RootObject = rootObject });
        serializer.SerializeRootObject(rootObject, stream);
        stream.Position = 0;
        rootObject = new RootXmlObject();
        serializer.DeserializeObject(rootObject, stream, string.Empty);
        return rootObject.Controls.First() as Band;
    }
}
vb
Imports DevExpress.XtraReports.Serialization
' ...
Shared Function CopyBand(ByVal band As Band) As Band
    Using stream = New System.IO.MemoryStream()
        Dim rootObject As New RootXmlObject(New System.ComponentModel.IComponent() { band })
        Dim serializer As New XRControlXmlSerializer(New XtraReportsSerializationContext() With {.RootObject = rootObject})
        serializer.SerializeRootObject(rootObject, stream)
        stream.Position = 0
        rootObject = New RootXmlObject()
        serializer.DeserializeObject(rootObject, stream, String.Empty)
        Return TryCast(rootObject.Controls.First(), Band)
    End Using
End Function

Example

The following example demonstrates how to use the BandCollection class methods to construct a simple report. The AddMarginBands method creates two margin bands and adds them to the collection.

csharp
using DevExpress.XtraPrinting;
using DevExpress.XtraReports.UI;
// ...

public class XtraReport1 : DevExpress.XtraReports.UI.XtraReport {
// ...

    // ...
    // Generated code for the XtraReport1 class.
    // ...

    public void AddMarginBands() {

        // Check if the TopMargin band is already present in the report.
        if(Bands[BandKind.TopMargin] == null) {
            // Create a new TopMargin band and add it to the report.
            TopMarginBand tmBand = new TopMarginBand();
            Bands.Add(tmBand);

            // Create a label and set its text and width.
            XRLabel label = new XRLabel();
            label.Text = "TopMargin Band";
            label.Width = 200;

            // Add the label to the TopMargin band.
            tmBand.Controls.Add(label);
        }

        // Check if the BottomMargin band is already present in the report.
        if(Bands[BandKind.BottomMargin] == null) {
            // Create a new BottomMargin band and add it to the report.
            BottomMarginBand bmBand = new BottomMarginBand();
            Bands.Add(bmBand);

            // Create an XRPageInfo object and set its width and PageInfo option.
            XRPageInfo datePageInfo = new XRPageInfo();
            datePageInfo.Width = 200;
            datePageInfo.PageInfo = PageInfo.DateTime;

            // Add the page information control to the BottomMargin band.
            bmBand.Controls.Add(datePageInfo);
        }
    }

}
vb
Imports DevExpress.XtraPrinting
Imports DevExpress.XtraReports.UI
' ...

Public Class XtraReport1
    Inherits DevExpress.XtraReports.UI.XtraReport
    ' ...

    ' ...
    ' Generated code for the XtraReport1 class.
    ' ...

    Public Sub AddMarginBands()

        ' Check if the TopMargin band is already present in the report.
        If Bands.GetBandByType(GetType(TopMarginBand)) Is Nothing Then
            ' Create a new TopMargin band and add it to the report.
            Dim tmBand As New TopMarginBand()
            Bands.Add(tmBand)

            ' Create a label and set its text and width.
            Dim label As New XRLabel()
            label.Text = "TopMargin Band"
            label.Width = 200

            ' Add the label to the TopMargin band.
            tmBand.Controls.Add(label)
        End If

        ' Check if the BottomMargin band is already present in the report.
        If Bands.GetBandByType(GetType(BottomMarginBand)) Is Nothing Then
            ' Create a new BottomMargin band and add it to the report.
            Dim bmBand As New BottomMarginBand()
            Bands.Add(bmBand)

            ' Create an XRPageInfo object and set its width and PageInfo option.
            Dim datePageInfo As New XRPageInfo()
            datePageInfo.Width = 200
            datePageInfo.PageInfo = PageInfo.DateTime

            ' Add the page information control to the BottomMargin band.
            bmBand.Controls.Add(datePageInfo)
        End If
    End Sub

End Class

The following code handles button clicks to call the AddMarginBands method and show the preview:

csharp
XtraReport1 report = new XtraReport1();

private void btnPreview_Click(object sender, System.EventArgs e) {
    ReportPrintTool preview = new ReportPrintTool(report);
    preview.ShowPreview();
}

private void btnAddBands_Click(object sender, System.EventArgs e) {
    report.AddMarginBands();
}
vb
Dim Report As New XtraReport1()

Private Sub BtnPreview_Click(sender As Object, e As System.EventArgs) _
Handles BtnPreview.Click
    Dim preview As New ReportPrintTool(report)
    preview.ShowPreview()
End Sub

Private Sub BtnAddBands_Click(sender As Object, e As System.EventArgs) _
Handles BtnAddBands.Click
    Report.AddMarginBands()
End Sub

The following code snippets (auto-collected from DevExpress Examples) contain references to the Add(Band) method.

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.

asp-net-web-forms-grid-create-report-based-on-grid-layout/CS/WebApplication1/ReportHelper.cs#L61

csharp
footerBand.Height = bandHeight;
report.Bands.Add(footerBand);
footerBand.BackColor = Color.LightGray;

reporting-wpf-create-report-in-code/CS/RuntimeReportsApplication/MainWindow.xaml.cs#L81

csharp
ReportHeaderBand reportHeader = new ReportHeaderBand();
report.Bands.Add(reportHeader);
reportHeader.Controls.Add(label);

asp-net-mvc-grid-create-report-based-on-grid-layout/CS/E4755/Models/ReportHelperMVC.cs#L44

csharp
if (gridViewState.TotalSummary.Count > 0) {
    report.Bands.Add(new ReportFooterBand() {
        HeightF = bandHeight

reporting-winforms-sql-data-source-runtime/CS/RuntimeSqlDataSourceReportSample/ReportCreator.cs#L47

csharp
ReportHeaderBand reportHeader = new ReportHeaderBand();
report.Bands.Add(reportHeader);
reportHeader.Controls.Add(label);

reporting-web-forms-object-data-source-constructor-parameters/CS/DXWebApplication1/Default.aspx.cs#L82

csharp
pageHeader.Controls.Add(paramValueLbl);
report.Bands.Add(pageHeader);

asp-net-mvc-grid-create-report-based-on-grid-layout/VB/E4755/Models/ReportHelperMVC.vb#L45

vb
If gridViewState.TotalSummary.Count > 0 Then
    report.Bands.Add(New ReportFooterBand() With {.HeightF = bandHeight})
    For Each item As MVCxSummaryItemState In gridViewState.TotalSummary

asp-net-web-forms-grid-create-report-based-on-grid-layout/VB/WebApplication1/ReportHelper.vb#L63

vb
footerBand.Height = bandHeight
report.Bands.Add(footerBand)
footerBand.BackColor = Color.LightGray

reporting-wpf-create-report-in-code/VB/RuntimeReportsApplication/MainWindow.xaml.vb#L90

vb
Dim reportHeader As New ReportHeaderBand()
report.Bands.Add(reportHeader)
reportHeader.Controls.Add(label)

reporting-winforms-sql-data-source-runtime/VB/RuntimeSqlDataSourceReportSample/ReportCreator.vb#L44

vb
Dim reportHeader As New ReportHeaderBand()
report.Bands.Add(reportHeader)
reportHeader.Controls.Add(label)

reporting-mvc-create-report-at-runtime/VB/ReportAtRuntimeMvcApp/ReportAtRuntimeMvcApp/Services/CustomReportProvider.vb#L23

vb
Dim headerBand As New ReportHeaderBand() With {.HeightF = 80}
report.Bands.Add(headerBand)
headerBand.Controls.Add(New XRLabel() With {.Text = "Categories Report", .SizeF = New SizeF(650, 80), .TextAlignment = TextAlignment.BottomCenter, .Font = New Font("Arial", 36)})

See Also

Add(XRControl)

BandCollection Class

BandCollection Members

DevExpress.XtraReports.UI Namespace