Events

So far we have examined scripts with only one main procedure, which is performed when a report starts running. In the main procedure, one can perform any initial settings, as well as to initialize variables. However, this is not enough for total control over the process of report's forming. To control a report as much as possible, every report's object has several events, to which a handler (i.e. a procedure from the script) may be assigned. For example, in the handler, connected to the data-band, one can perform records' filtering, which means that the band will be hidden or displayed according to any specified conditions.

Let us demonstrate the process of creation of a report and of events, which are generated during it, with the example of a simple report, which contains one page, one "Master data" band, and two "Text" objects on the band:

As it was said, the main script's procedure is called in the very beginning of a report. After that, the essential process of report construction starts. In the beginning of the report, the "OnStartReport" event of the "Report" object is called. Before the page is being formed, the "OnBeforePrint" page event is called. This event is called once for each page of the report's template (it should not be confused with the pages of a finished report!). In our case, the event is called once, as the report's pattern consists of one page, notwithstanding the number of pages in the finished report.

Then typing of data-bands begins. It is performed in the following way:
1. the "OnBeforePrint" band's event is called;
2. the "OnBeforePrint" events of all the objects, belonging to the band, are called;
3. all the objects are filled with data (in our case with values of the "Company" and "Addr1" DB fields); after that, the "OnAfterData" events of all the objects are called;
4. such actions as positioning of objects on the band (if there are stretchable objects among them), calculating of the band's height, and stretching (if it is stretchable) are performed;
5. the "OnAfterCalcHeight" band's event is called;
6. a new page is formed, if the band does not find room in white space of the page;
7. the band and all of its objects are displayed on the finished report's page;
8. the "OnAfterPrint" event of all the band's objects is called;
9. the "OnAfterPrint" event of the band itself is called.

Bands are printed as long as there are data in the source connected to the band. After that, in our case, forming of a report stops; the "OnAfterPrint" report's page events and, finally, the "OnStopReport" event of the "Report" object are called.

Thus, via using events of different objects, one can manage practically each moment of report's forming process. A key to correct use of events is complete understanding of the bands' typing process, stated in nine latter sections. Thus, most of the actions can be performed via using the "OnBeforePrint" band's event only; any modifications made to an object are displayed simultaneously. However, in this event it is impossible to analyze, in which page the band will be printed, if it is stretchable, since calculation of band's height will be performed in the step 4. This can be performed either via the "OnAfterCalcHeight" event in the step 5, or the "OnAfterPrint" event in the step 8, but in the latter case a band will be already printed and that is why any operations with objects will change nothing. In a word, you should clearly see, in what period of time each of the events should be called and use those events, which correspond to the set task.