In each event handler, the parameter list is specific to the type of event to which the function responds. Here is an outline of the BIRT handler part:
handler myBIRTHandler type BIRTHandler
function myEventHandler01 (parameterList)
{eventType = eventType, elementName="name01"...} end
function myEventHandler02 (parameterList)
{eventType = eventType, elementName="name02"...} end
end
As shown in that outline, the use of the eventType and elementName property (and other event-handler properties, as appropriate) indicate that the function is an event handler.
As a consequence of these steps, the BIRT report engine can invoke a set of event handlers during report creation.
package EGLDataSources;
program arrayProg type BasicProgram {}
function main()
arr customer[0];
cust customer;
cust.customerNumber = 102;
cust.firstName = "Jonathan";
cust.lastName = "Swift";
arr.appendElement(cust);
cust.customerNumber = 103;
cust.firstName = "Mark";
cust.lastName = "Twain";
arr.appendElement(cust);
designFile string = "eglDataSourcesRpt.rptdesign";
rptFile string = "eglDataSourcesArrayRpt.pdf";
myHandler arrayHandler = new arrayHandler;
rpt BIRTReport = new BIRTReport
(designFile, null, rptFile, "pdf", myHandler);
myHandler.setCustomerArray(arr);
rpt.createReportFromDesign();
end
end
record customer type basicrecord
customerNumber int;
firstName string;
lastName string;
end
The name of an event handler is not meaningful to the BIRT report engine. Instead, the way that the event handler is defined (its parameter types and properties) determines when the handler is invoked. The event type (the value of the eventType property) is the most important factor in determining the time of invocation.
beforeOpen (for a data source of any kind)
openEvent (for a scripted data source)
afterOpen (for the data source referenced in the previous
beforeOpen event)
beforeOpen (for a data set derived
from the data source just referenced)
openEvent (for a scripted data set just referenced)
afterOpen (for the data set referenced
in the previously listed beforeOpen event)
[loop until all rows are retrieved for the data set just referenced: ]
fetchEvent (fetch a row from a scripted data set)
onFetch (invoked for a data set
in response to a fetch)
[end loop]
[for each row retrieved from the data set,
loop until all report elements are created: ]
onCreate (invoked when a report element
used for layout is being created)
onPageBreak (invoked if a page break is specified)
[end loop]
beforeClose (for the data set whose data was just fetched)
closeEvent (for a scripted data set just referenced)
afterCloseDataSet (for the data set referenced
in the previously listed beforeClose event)
beforeClose (for the data source just referenced)
closeEvent (for a scripted data source just referenced)
afterCloseDataSource (for the data source referenced
in the previously listed beforeClose event)
Each event type whose name ends with the word "event" (that is, openEvent, fetchEvent, and closeEvent) operates only on a scripted data source or data set.
Let us clarify the meaning of fetchEvent and onFetch events. As mentioned before, fetchEvent is specific to a scripted data set, whereas onFetch can be used for any data set, including a scripted one. You can use the fetchEvent event to provide content for a row that your program is providing to the report engine, and you can use the onFetch event to review data from a single row that was retrieved by the report engine (or that you just provided to the report engine). Each event handler is invoked repeatedly by the report engine until all rows are retrieved.
When the event type is onFetch, the event handler can access the most recently retrieved row, but cannot update the row and does not return a Boolean value.
The parameter types required for a given event handler depend on the event type. Seen another way, the event type indicates the types of arguments that the BIRT report engine submits to the event handler at run time. The next table lists the event types in alphabetical order, along with the related parameter types in parameter order.
| Event types | Parameter types |
|---|---|
| afterCloseDataSet | DataSetInstance |
| afterCloseDataSource | DataSourceInstance |
| afterOpen (for a data set) | DataSetInstance, ReportContext |
| afterOpen (for a data source) | DataSourceInstance, ReportContext |
| beforeClose (for a data set) | DataSetInstance, ReportContext |
| beforeClose (for a data source) | DataSourceInstance, ReportContext |
| beforeOpen (for a data set) | DataSetInstance, ReportContext |
| beforeOpen (for a data source) | DataSourceInstance, ReportContext |
| closeEvent (for a data set supplied by EGL code) | DataSetInstance |
| closeEvent (for a data source supplied by EGL code) | DataSourceInstance |
| fetchEvent (for a data set supplied by EGL code) | DataSetInstance, UpdatableDataSetRow (the function returns a Boolean) |
| onCreate | The type of a report element used for layout (for example, LabelInstance); and then, ReportContext |
| onFetch (for a data set) | DataSetInstance, DataSetRow, ReportContext |
| onPageBreak | First, the type of report element (for example, LabelInstance) used for a layout that is anywhere on the page preceding the page break; and second, ReportContext |
| openEvent (for a data set supplied by EGL code) | DataSetInstance |
| openEvent (for a data source supplied by EGL code) | DataSourceInstance |
We can distinguish between event handlers that respond to the runtime creation of report-layout elements such as labels and images, and event handlers that respond to some aspect of data access. The former kind of event handler is accessed for onCreate or onPageBreak events; the latter kind is accessed for any other kind of event. For details, see "BIRT data-access event handlers" and "BIRT report-layout event handlers."