Referencing the Database Fields

Events

So far we have looked at scripts with only a main procedure, which is executed when a report starts running. In the main procedure initial settings can be made and variables initialized. However this is not enough for total control over the process of report generation. To enable as much control as possible over report generation every object has several events to which handlers (i.e. procedures in the script) can be assigned. For example, connecting a handler to the data band enables records to be filtered, such that the band can be hidden or revealed according to specific conditions being met.

Let's demonstrate the process of report creation and the events triggered by means of a simple report containing one page and having one “MasterData” band, with two “Text” objects on the band:

As described above, the script's main procedure is called at the very start of running the report. After that the essentials of report construction begin. Firstly the “OnStartReport” event of the "Report" object is called. Then, before an output page is created, the “OnBeforePrint” page event is called. This event is called once for each design page in the report template (design pages should not be confused with the output pages of a report!). In our example the event is called once, as the report design consists of only one design page.

Then the events of the data bands are called in the following order:

1. the band's “OnBeforePrint” event is called

2. the “OnBeforePrint” event of each object contained in the band is called

3. each object is filled with data (in our example with values of the “Company” and “Addr1" DB fields)

4. the “OnAfterData” event of each object is called

5. actions such as positioning objects on the band (if there are stretchable objects among them), calculating band height and stretching it (if it is stretchable) are performed

6. the band's “OnAfterCalcHeight” event is called

7. a new output page is created if the band hasn't enough room in the page's white space

8. the band and all of its objects are displayed on the output  page

9. the “OnAfterPrint” event of each band object is called

10. the “OnAfterPrint” event of the band itself is called

Bands continue to be printed as long as the source connected to the band has data. After that report printing stops, the report page's “OnAfterPrint” event is called and finally the “Report” object's “OnStopReport” event.

So by using the events of different objects practically every step of the report creation process can be managed. The key to using events is a thorough understanding of the band output process, which is discussed in the next sections. Most of the actions can be performed using the band's “OnBeforePrint” event only; any modifications made to an object are displayed immediately. However, if the band is stretchable, it is impossible to say in this event on which page the band will be printed, since calculation of the band's height is performed in step 5. It can be done, however, either in the “OnAfterCalcHeight” event in step 6 or in the “OnAfterPrint” event in step 9. Note that in the last event the band will already have been output so modification to objects will not have any visible effect.

It is essential to clearly understand “where and when” the bands are output and to understand the timing (calling order) of each of their events. Likewise for each of the objects contained in the bands.