Report Events
- 5 minutes to read
This document describes the events available for a report, its bands and controls. It explains the order in which main events are raised and illustrates which tasks you can solve in these event handlers.
Among the public events exposed by the XRControl class, the following four are critical to the understanding of the XtraReports page building concept (the events are listed in the same order they are raised).
Note
The general order in which the BeforePrint and 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 a report’s complexity.
Note
Runtime customization of a report provided by handling report events is not reflected in the design-time Preview. To perform required changes, you can use scripts or expression bindings.
The DataSourceDemanded Event
The XtraReportBase.DataSourceDemanded event occurs before a report demands its data source.
Use this event to set or modify the XtraReportBase.DataSource property value.
For an example of using this event, see Filter Data at the Data Source Level.
The BeforePrint Event
The XRControl.BeforePrint event occurs before an XRControl 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 DetailBand.
Most tasks that you can perform in this event (e.g. changing the XRControl.Visible, XRControl.BackColor, XRControl.BorderColor and other properties) can be easily performed without any coding using the formatting rules. And the BeforePrint event can be handled to reassign a control’s styles and adjust its XRControl.LocationF property.
In the BeforePrint event, you can obtain a data column’s current value for data-bound controls, using the XtraReportBase.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 = (XRControl)sender;
control.LocationF = new PointF(15F, 15F);
control.Styles.Style = this.StyleSheet[0];
}
}
To obtain a page number for a control being generated, we recommend you use the PrintOnPage event.
Note that in some cases (e.g., when the GroupBand.RepeatEveryPage property is enabled for the GroupHeaderBand, or GroupHeaderBand.GroupUnion is set to WithLastDetail), 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. To learn more, refer to Group and Sort a Report’s Data.
The AfterPrint Event
The XRControl.AfterPrint event occurs after an XRControl 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(((XRControl)sender).Text.ToString());
}
The PrintOnPage Event
The XRControl.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 Obtaining 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 functions‘ 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 XRControl.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. For another approach to this task, refer to Combine Reports by Alternating Pages.
In this event, you still can 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.
Other Events
After the BeforePrint and AfterPrint events have been completed, two other groups of events occur, which allow you to:
- process summaries via the special Summary* events of an XRLabel (To learn more, refer to Shaping Data (Legacy Data Bindings)).
- XRLabel.SummaryCalculated;
- XRLabel.SummaryGetResult;
- XRLabel.SummaryReset;
- XRLabel.SummaryRowChanged.
- obtain a control’s content directly in Print Preview, via the special Preview* events of an XRControl (for an example, refer to Obtain a Label’s Text in Print Preview).