ActiveReports 13
Section Report Events
ActiveReports 13 > ActiveReports User Guide > Concepts > Section Report Concepts > Section Report Events

Section reports use events to allow you to control report behavior.

Single-Occurrence Events

The following events are all of the events that are raised only once during a Section report's processing. These events are raised at the beginning or at the end of the report processing cycle.

Events raised once

ReportStart

Use this event to initialize any objects or variables needed while running a report. This event is also used to set any Subreport control objects to a new instance of the report assigned to the Subreport control.

Caution: Be sure to add dynamic items to the report before this event finishes.

DataInitialize

This event is raised after ReportStart. Use it to add custom fields to the report's Fields collection. Custom fields can be added to a bound report (one that uses a Data Control to connect and retrieve records) or an unbound report (one that does not depend on a data control to get its records). In a bound report the dataset is opened and the dataset fields are added to the custom fields collection, then the DataInitialize event is raised so new custom fields can be added. The DataInitialize event can also be used to make adjustments to the DataSource or to set up database connectivity.

ReportEnd

This event is raised after the report finishes processing. Use this event to close or free any objects that you were using while running a report in unbound mode, or to display information or messages to the end user. This event can also be used to export reports.

Multiple-Occurrence Events

The following events are raised multiple times during a Section report's processing.

Events raised more than once

FetchData

This event is raised every time a new record is processed. The FetchData has an EOF parameter indicating whether the FetchData event should be raised. This parameter is not the same as the Recordset's EOF property and is defaulted to True. When working with bound reports (reports using a DataControl), the EOF parameter is automatically set by the report; however, when working with unbound reports this parameter needs to be controlled manually.

Use the FetchData event with unbound reports to set the values of custom fields that were added in the DataInitialize event or with bound reports to perform special functions, such as combining fields together or performing calculations. The FetchData event should not have any references to controls on the report.

If you need to use a value from a Dataset with a control in the Detail section, set a variable in the FetchData event and use the variable in the section's Format event to set the value for the control. Please note that this method of setting a variable in the FetchData event and using it to set a control's value is only supported in the Detail_Format event.

Also use the FetchData event to increment counters when working with arrays or collections.

PageStart

This event fires before a page is rendered. Use this event to initialize any variables needed for each page when running an unbound report.

PageEnd

This event is raised after each page in the report is rendered. Use this event to update any variables needed for each page when running an unbound report.

When Bound and Unbound Data Values Are Set

  1. The Fields collection is populated from the dataset that is bound to the report after the DataInitialize event is raised. (In an unbound report, the Fields collection values are not set to anything at this point.)
  2. The FetchData event is raised, giving the user a chance to modify the Fields collection.
  3. Any fields that are bound have the values transferred over.
  4. The Format event is raised.

Events that Occur for Each Instance of Each Section

In a Section report, regardless of the type or content of the various sections, there are three events for each section: FormatBeforePrint and  AfterPrint.

Section Events

Because there are many possible report designs, the event-raising sequence is dynamic in order to accommodate individual report demands. The only guaranteed sequence is that a section's Format event is raised before the BeforePrint event, which in turn occurs before the AfterPrint event but not necessarily all together. Reports should not be designed to rely on these events being raised in immediate succession.

Important: Never reference the report's Fields collection in these section events. Only reference the Fields collection in theDataInitialize and FetchData events.

Format

ActiveReports raises this event after the data is loaded and bound to the controls contained in a section, but before the section is rendered to a page.

The Format event is the only event in which you can change the section's height. Use this section to set or change the properties of any controls or the section itself.

Also use the Format event to pass information, such as an SQL String, to a Subreport.

If the CanGrow or CanShrink property is True for the section or any control within the section, all of the growing and shrinking takes place in the Format event. Because of this, you cannot obtain information about a control or section's height in this event.

Because a section's height is unknown until the Format event finishes, it is possible for a section's Format event to be raised while the report is on a page to which the section is not rendered. For example, the Detail Format event is raised but the section is too large to fit on the page. This causes the PageFooter events and the PageEnd event to be raised on the current page, and the PageStart, any other Header events, and possibly the FetchData event to be raised before the section is rendered to the canvas on the next page.

BeforePrint

ActiveReports raises this event before the section is rendered to the page.

The growing and shrinking of the section and its controls have already taken place. Therefore, you can use this event to get an accurate height of the section and its controls. You can modify values and resize controls in the BeforePrint event, but you cannot modify the height of the section itself.

Also use this event to do page-specific formatting since the report knows which page the section will be rendered to when this event is raised. Once this event has finished, the section cannot be changed in any way because the section is rendered to the canvas immediately after this event.

Note: If a section contains the SubReport control that occupies more than one page, the SubReport gets split into smaller parts at rendering. In this case, you can use the BeforePrint event - it will fire multiple times to get the height of each part of the rendered SubReport.

AfterPrint

ActiveReports raises this event after the section is rendered to the page.

Although AfterPrint was an important event prior to ActiveReports Version 1 Service Pack 3, it is rarely used in any of the newer builds of ActiveReports. This event is still useful, however, if you want to draw on the page after text has already been rendered to it.

Event Sequence

Multi-threaded, single-pass processing enables Section reports to surpass other reports in processing and output generation speed. ActiveReports processes and renders each page as soon as the page is ready. If a page has unknown data elements or its layout is not final, it places the page in cache until the data is available.

Sequence of Events

Summary fields and KeepTogether constraints are two reasons why a page might not render immediately. The summary field is not complete until all the data needed for calculation is read from the data source. When a summary field such as a grand total is placed ahead of its completion level, such as in the report header, the report header and all following sections are delayed until all of the data is read.

There are ten report events in the code behind a Section report, or seven in a ActiveReport script.

 

Because there are so many ways in which you can customize your reports, not all reports execute in the same way. However, when you run a report, this is generally what happens:

  1. ActiveReports raises the ReportStart event. The report validates any changes made to the report structure in ReportStart. In some cases, data source properties raise the DataInitialize event.
  2. Printer settings are applied. If none are specified, the local machine's default printer settings are used.
  3. If the DataInitialize event was not already raised, ActiveReports raises it and opens the data source.
  4. If the data source contains Parameters with unset values and the ShowParameterUI property is set to True, ActiveReports displays a parameters dialog to request values from the user.
  5. Closing the dialog raises the ParameterUIClosed event. If the report is a subreport that requires parameters, ActiveReports binds the subreport parameters to any fields in the parent report.
  6. ActiveReports raises the FetchData event.
  7. If there is no data, the NoData event is raised.
  8. The PageStart event raises, and then raises again after each PageEnd event until the final page.
  9. Group sections are bound and sections begin rendering on pages.
  10. ActiveReports raises Section Events to process sections in (roughly) the following order:
    • Report header
    • Page header
    • Group header
    • Detail
    • Group footer
    • Page footer
    • Report footer
  11. After each event, ActiveReports checks the Cancel flag to ensure that it should continue.
  12. Other events may raise, depending on the report logic.
  13. The PageEnd event raises after each page becomes full, and the PageStart raises if the report has not finished.
  14. Finally, ActiveReports raises the ReportEnd event.

Events that May Occur

These events occur in response to user actions, or when there is no data for a report.

Other Events

DataSourceChanged

This event occurs if the report's data source is changed. This is mainly useful with the end-user designer control.

NoData

This event occurs if the report's data source returns no records.

ParameterUIClosed

This event occurs when the user closes the parameter dialog.

PrintAborted

This event occurs when the user cancels a print job.

PrintProgress

This event occurs once for each page while the report document is printing.