Report Events

  • 5 minutes to read

This document describes how to apply changes to a report while this report is rendered. To do so, handle events that occur in a report, report bands, and report controls.

The DataSourceDemanded Event

The DataSourceDemanded event occurs for the following entities:

This event is raised before data is requested from the report, band, or control’s data source. Use this event to set or modify the DataSource property value.

Use the DataSourceManager class to process multiple data sources contained in a report. You can retrieve data sources from a report and report controls, retrieve controls with data sources (for instance, charts or cross tabs), or add data sources to a report.

The BeforePrint Event

The XRControl.BeforePrint event occurs for a report, all bands, and all controls contained in the report. The order in which the BeforePrint events are raised for multiple controls is from left to right and from top to bottom. However, this sequence is not always strictly kept, as it depends on report complexity.

This event is raised before an XRControl creates its image in a report document when you preview, print, or export a report. Use this event to change report properties, bands, or controls that are placed in the DetailBand.

The following list shows sample tasks that you can handle in the BeforePrint event:

In this event, it is too late to bind a report or control to data. However, you can use the XtraReportBase.GetCurrentColumnValue method to obtain a data column’s current value for data-bound controls.

The following code demonstrates how to handle the BeforePrint event.

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 = (XRControl)sender;
        control.LocationF = new PointF(15F, 15F);
        control.Styles.Style = this.StyleSheet[0];
    }
}

Use the PrintOnPage event to obtain the page number where a control is located.

Note

When a GroupHeaderBand‘s RepeatEveryPage property is enabled or the GroupHeaderBand‘s GroupUnion property is set to WithLastDetail, the BeforePrint event is raised an uncertain number of times.

The AfterPrint Event

An XRControl‘s AfterPrint event occurs for a report, all bands, and all controls that the report contains. This event is raised after the entity is displayed. Use this event to obtain a control’s resulting content (the Text property value as it appears in the generated document). You can obtain the control’s static text and the current value of the data field to which the control is bound.

The order in which the AfterPrint events are raised for multiple controls is from left to right and from top to bottom. However, this sequence is not always strictly kept, as it depends on report complexity.

The following code demonstrates how to handle the AfterPrint event.

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

private void xrLabel1_AfterPrint(object sender, EventArgs e) {
    MessageBox.Show(((XRControl)sender).Text.ToString());
}

The PrintOnPage Event

The XRControl.PrintOnPage event occurs for all controls that a report contains. This event is raised after a document page is built, when a control is printed on it, and after the BeforePrint and AfterPrint events occurred. You can handle this event to accomplish the following tasks:

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

You can access the current page index and the total number of pages. Use the PrintOnPageEventArgs.PageIndex and PrintOnPageEventArgs.PageCount properties to do that.

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

The PrintOnPage event allows you to disable (but not to enable) a control’s visibility. You can also use this event to insert a blank page in a document. Refer to the following topic for an alternative approach to this task: Merge Reports: Specify Page Sequence Manually.

After the BeforePrint and AfterPrint events were raised, the following events occur for XRLabel controls, which allow you to process summaries. Refer to the following topic for more information: Shape Report Data:

The following events occur for all XRControls in a report, which allow you to obtain a control’s content in Print Preview. Refer to the following topic for more information: Obtain a Label's Text in Print Preview: