Home > Report Designer > Getting Started > Report Events - Custom Scripting

Report Events - Custom Scripting

This document provides an overview of a report's events. It describes the order in which main events are raised and explains the tasks that can be performed in these events.

Among the public events exposed by the Control class, the following three are critical to the understanding of the XtraReports page building concept (the events are listed in the same order they are raised).

The DataSourceDemanded event occurs before a report's data source is demanded. Use this event to set or modify the DataSource property value.

The BeforePrint event occurs before an control object creates its image in a report being previewed/printed/exported, and is primarily used to programmatically change the properties of a report, its bands and controls that are situated in the Details Band.

Most tasks that you can perform in this event can be easily performed without any coding using the formatting rules. And the BeforePrint event can be handled to re-assign a control's styles and adjust its location property.

In the BeforePrint event, you can obtain a data column's current value for data-bound controls, using the GetCurrentColumnValue method. Note that in this event, it is too late to change control binding information. So, for a data-bound control, you can only adjust its static text (which forms a part of its mail-merge).

The following code demonstrates how the BeforePrint event works.

using System.Drawing.Printing;
using DevExpress.XtraReports.UI;
// ... 

private void xrLabel1_BeforePrint(object sender, PrintEventArgs e) {
    if (Convert.ToDouble(this.GetCurrentColumnValue("UnitPrice")) > 30) {
        XRControl control = this.FindControl("xrLabel1", true);
        control.LocationF = new PointF(15F, 15F);
        control.Styles.Style = this.StyleSheet[0];
    }
}

Imports System.Drawing.Printing
Imports DevExpress.XtraReports.UI
' ... 

Private Sub xrLabel1_BeforePrint(ByVal sender As Object, _ 
ByVal e As PrintEventArgs) Handles xrLabel1.BeforePrint
    If Convert.ToDouble(Me.GetCurrentColumnValue("UnitPrice")) > 30 Then 
        Dim control As XRControl = Me.FindControl("xrLabel1", True)
        control.LocationF = New PointF(15F, 15F)
        control.Styles.Style = Me.StyleSheet(0)
    End If 
End Sub 

using System.Drawing.Printing;
using DevExpress.XtraReports.UI;
// ... 

private void xrLabel1_BeforePrint(object sender, PrintEventArgs e) {
    if (Convert.ToDouble(this.GetCurrentColumnValue("UnitPrice")) > 30) {
        XRControl control = this.FindControl("xrLabel1", true);
        control.LocationF = new PointF(15F, 15F);
        control.Styles.Style = this.StyleSheet[0];
    }
}

Imports System.Drawing.Printing
Imports DevExpress.XtraReports.UI
' ... 

Private Sub xrLabel1_BeforePrint(ByVal sender As Object, _ 
ByVal e As PrintEventArgs) Handles xrLabel1.BeforePrint
    If Convert.ToDouble(Me.GetCurrentColumnValue("UnitPrice")) > 30 Then 
        Dim control As XRControl = Me.FindControl("xrLabel1", True)
        control.LocationF = New PointF(15F, 15F)
        control.Styles.Style = Me.StyleSheet(0)
    End If 
End Sub 

Note that although the BeforePrint event is not designed to obtain a page number for a control being generated, in some scenarios this can be done (via the Document.PageCount property). An example of how this is done can be found online in our Code Central data base at How to detect that the new page is being created and obtain the current page number within the BeforePrint event handler. Note that this works properly only when the Detail band's Band.KeepTogether property is set to true, and may not work for complicated reports (such as master-detail). So, to obtain a control's page number precisely, we recommend using the PrintOnPage event.


Note that if the GroupBand.RepeatEveryPage property is enabled for the GroupHeaderBand, the number of times the BeforePrint event is raised for this band is uncertain, and is not equal to the actual number of groups in the report. For more information, refer to Grouping Data.

The AfterPrint event occurs after an Control object is displayed in the report, and is primarily used to obtain a control's actual content (the XRControl.Text property value as it will appear in the final document). In this event, you can obtain both the current value of the data field to which the control is bound and its static text. Then for example, you can pass the obtained value to another window.

The following code demonstrates how this can be performed.

using System.Windows.Forms;
using DevExpress.XtraReports.UI;
// ... 

private void xrLabel1_AfterPrint(object sender, EventArgs e) {
    MessageBox.Show(this.FindControl("xrLabel1", true).Text.ToString());
}

Imports System.Windows.Forms
Imports DevExpress.XtraReports.UI
' ... 

Private Sub xrLabel3_AfterPrint(ByVal sender As Object, _ 
ByVal e As EventArgs) Handles xrLabel3.AfterPrint
    MessageBox.Show(Me.FindControl("xrLabel3", True).Text.ToString())
End Sub 

using System.Windows.Forms;
using DevExpress.XtraReports.UI;
// ... 

private void xrLabel1_AfterPrint(object sender, EventArgs e) {
    MessageBox.Show(this.FindControl("xrLabel1", true).Text.ToString());
}

Imports System.Windows.Forms
Imports DevExpress.XtraReports.UI
' ... 

Private Sub xrLabel3_AfterPrint(ByVal sender As Object, _ 
ByVal e As EventArgs) Handles xrLabel3.AfterPrint
    MessageBox.Show(Me.FindControl("xrLabel3", True).Text.ToString())
End Sub 

The PrintOnPage event occurs after a document's page is built, when a control's representation is printed on it, and after both the BeforePrint and AfterPrint events.

For multiple controls, this event is raised in the same sequence, in which they are added to a band's collection.

Use this event to perform actions when a control is already printed on a particular page in a report. An example of such a task is obtaining the current page number for a control (for a tutorial on this, refer to How to: Obtain the Current Page Number when Printing a Control). Both the current page index and the total number of pages can be accessed via the PrintOnPageEventArgs.PageIndex and PrintOnPageEventArgs.PageCount properties respectively.

Another example of a task that uses the PrintOnPage event, is one where it is required to calculate complex functions based on summary funtions' results. In such tasks, the summary functions' results are obtained in the XRLabel.SummaryCalculated event handlers of the corresponding XRLabel,  and the resulting aggregate is assigned to another label's Text property in its PrintOnPage event handler.

Note
Note that since a report document is already created at the time the PrintOnPage event is raised, changing a control's contents in this event will not change a report's layout (locations and sizes in a final document).

Because PrintOnPage allows disabling a control's visibility (note that only setting the Visible property to false is legitimate in this event, and not vice-versa), this event can also be used to insert a blank page into a document.

In this event, you still can change a control's Text property value. However, it is too late to change a control's location, size, or obtain its current data column value.

using System.Data;
using System.Drawing.Printing;
// ...

private void Detail_BeforePrint(object sender, PrintEventArgs e) {
   // Get the value of the current row in the master report.
   xrLabel1.Text = ((DataRowView)GetCurrentRow()).Row["CategoryName"].ToString();

   // Get the value of the current cell in the CategoryName column in the master report.
   xrLabel2.Text = GetCurrentColumnValue("CategoryName").ToString();
}

private void Detail1_BeforePrint(object sender, PrintEventArgs e) {
   // You shouldn't use the GetCurrentRow method in this way in a detail report.
   // ((DataRowView)GetCurrentRow()).Row["Categories.CategoriesProducts.ProductName"].ToString();

   // Get the value of the current row in the detail report.
   xrLabel3.Text = ((DataRowView)DetailReport.GetCurrentRow()).Row["ProductName"].ToString();
         
   // You shouldn't use the GetCurrentColumnValue method in this way in a detail report.
   // GetCurrentColumnValue("Categories.CategoriesProducts.ProductName").ToString();
         
   // Get the current value of the CategoryName data column in a detail report.
   xrLabel4.Text = DetailReport.GetCurrentColumnValue("ProductName").ToString();
}

Imports System.Data
Imports System.Drawing.Printing
' ...

Private Sub Detail_BeforePrint(ByVal sender As Object, _ 
ByVal e As PrintEventArgs) Handles Detail.BeforePrint
   ' Get the value of the current row in the master report.
   XrTableCell1.Text = GetCurrentRow().Row("CategoryName").ToString()
 
  ' Get the value of the current cell in the CategoryName column in the master report.
   XrTableCell2.Text = GetCurrentColumnValue("CategoryName").ToString()
End Sub

Private Sub Detail1_BeforePrint(ByVal sender As Object, _ 
ByVal e As PrintEventArgs) Handles Detail1.BeforePrint
   ' You shouldn't use the GetCurrentRow method in this way in a detail report.
   ' GetCurrentRow().Row("Categories.CategoriesProducts.ProductName").ToString()

   ' Get the value of the current row in the detail report.
   XrTableCell3.Text = DetailReport.GetCurrentRow().Row("ProductName").ToString()

   ' You shouldn't use the GetCurrentColumnValue method in this way in a detail report.
   ' GetCurrentColumnValue("Categories.CategoriesProducts.ProductName").ToString()

   ' Get the value of the current cell in the CategoryName column in the detail report.
   XrTableCell4.Text = DetailReport.GetCurrentColumnValue("ProductName").ToString()
End Sub

using System.Data;
using System.Drawing.Printing;
// ...

private void Detail_BeforePrint(object sender, PrintEventArgs e) {
   // Get the value of the current row in the master report.
   xrLabel1.Text = ((DataRowView)GetCurrentRow()).Row["CategoryName"].ToString();

   // Get the value of the current cell in the CategoryName column in the master report.
   xrLabel2.Text = GetCurrentColumnValue("CategoryName").ToString();
}

private void Detail1_BeforePrint(object sender, PrintEventArgs e) {
   // You shouldn't use the GetCurrentRow method in this way in a detail report.
   // ((DataRowView)GetCurrentRow()).Row["Categories.CategoriesProducts.ProductName"].ToString();

   // Get the value of the current row in the detail report.
   xrLabel3.Text = ((DataRowView)DetailReport.GetCurrentRow()).Row["ProductName"].ToString();
         
   // You shouldn't use the GetCurrentColumnValue method in this way in a detail report.
   // GetCurrentColumnValue("Categories.CategoriesProducts.ProductName").ToString();
         
   // Get the current value of the CategoryName data column in a detail report.
   xrLabel4.Text = DetailReport.GetCurrentColumnValue("ProductName").ToString();
}

Imports System.Data
Imports System.Drawing.Printing
' ...

Private Sub Detail_BeforePrint(ByVal sender As Object, _ 
ByVal e As PrintEventArgs) Handles Detail.BeforePrint
   ' Get the value of the current row in the master report.
   XrTableCell1.Text = GetCurrentRow().Row("CategoryName").ToString()
 
  ' Get the value of the current cell in the CategoryName column in the master report.
   XrTableCell2.Text = GetCurrentColumnValue("CategoryName").ToString()
End Sub

Private Sub Detail1_BeforePrint(ByVal sender As Object, _ 
ByVal e As PrintEventArgs) Handles Detail1.BeforePrint
   ' You shouldn't use the GetCurrentRow method in this way in a detail report.
   ' GetCurrentRow().Row("Categories.CategoriesProducts.ProductName").ToString()

   ' Get the value of the current row in the detail report.
   XrTableCell3.Text = DetailReport.GetCurrentRow().Row("ProductName").ToString()

   ' You shouldn't use the GetCurrentColumnValue method in this way in a detail report.
   ' GetCurrentColumnValue("Categories.CategoriesProducts.ProductName").ToString()

   ' Get the value of the current cell in the CategoryName column in the detail report.
   XrTableCell4.Text = DetailReport.GetCurrentColumnValue("ProductName").ToString()
End Sub

See also