Report Events
- 5 minutes to read
This topic describes how to apply changes to a report while the report is rendered. To do so, handle events that occur in the report, report bands, and report controls.
The DataSourceDemanded Event
The DataSourceDemanded event occurs for the following entities:
- Report
- Bands that have data sources (DetailReportBand)
- Controls that have data sources (XRChart, XRCrossTab, XRPivotGrid)
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:
- Change a control’s visibility, BackColor, BorderColor, and other properties
- Reassign a control’s styles
- Adjust a control’s location
- Modify a control’s static text (the text can include mail-merge placeholders)
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.ComponentModel;
using DevExpress.XtraReports.UI;
// ...
private void xrLabel1_BeforePrint(object sender, CancelEventArgs 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:
Find out on which page a control is printed.
Refer to the following topic for more information: Obtain the Current Page Number when Printing a Control.
Calculate composite summaries.
Handle each summary-holding label‘s SummaryCalculated event to obtain the summary function results and assign the resulting aggregate to another label’s Text property in its PrintOnPage event handler.
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, because the hidden control is not printed on the page and the PrintOnPage event does not occur. You can also use this event to insert a blank page in a document.
Summary-Related Events
After the BeforePrint and AfterPrint events were raised, the following events occur for XRLabel controls if your report uses legacy data bindings. This allows you to process summaries. Refer to the following topic for more information: Shape Report Data:
- XRLabel.SummaryCalculated;
- XRLabel.SummaryGetResult;
- XRLabel.SummaryReset;
- XRLabel.SummaryRowChanged.
Parameter-Related Events
The following report events help you to update report parameter values:
- XtraReport.ParametersRequestBeforeShow - occurs before the Parameters panel appears in a Print Prevew.
- XtraReport.ParametersRequestSubmit - occurs when all parameter values in the Parameters UI are entered, and the Submit button is pressed.
- XtraReport.ParametersRequestValueChanged - occurs when the parameter values are changed in the Parameters UI.
Preview-Related Events
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: