ActiveReports Events
Events that are Raised Only Once
The following events are all of the events that are raised only once during a report's processing. These events are raised at the beginning and at the end of the report processing cycle.
ReportStart
This event is raised before the DataInitialize event. Use this event to initialize any objects or variables needed while running a report. Also use this event to set any Subreport control objects to a new instance of the report assigned to the Subreport control. Do not add items dynamically to a report once this event has finished.
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.
Events that are Raised Multiple Times
The following ActiveReports events are raised multiple times during a report's processing.
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.
Section Events
There are three events that are raised for each section, regardless of its type or content. The sequence of these events depends on the summary objects and their section dependencies. 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. Never access a report's Fields collection in any of these section events, but rather in the DataInitialize and FetchData events.
Format
This event is raised after data is loaded and bound to the fields but before the section is laid out for printing. Use this event to modify the layout of a section or any of the controls in the section. This is the only event in which a section's height can be changed. Also use the Format event to pass information, such as an SQL String, to a Subreport. 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 event 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
This event is raised before the section is rendered to the page. You can use this event to modify the values of the controls before they are printed. Any changes made here will not affect the height of the section. We recommend that you do NOT access any fields in a DataSource's dataset in this event. 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 is raised.
AfterPrint
This event is raised after the section is rendered to the canvas object. You can use this event to draw directly to the canvas. Do not use the AfterPrint event to make any changes to the section since the section has already been rendered to the canvas at this point.
When Bound and Unbound Data Values are Set
- 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.)
- The FetchData event is raised, giving the user a chance to modify the Fields collection.
- Any fields that are bound have the values transferred over.
- The Format event is raised.