The text report engine recognizes a specific set of events
during report generation. Each event is represented by a variable
in the engine.
You can assign custom functions from your generic handler to any
of these variables, using the same dot syntax you use when making
an assignment to a variable in a library. For example, if you have
a function named
printPageTotals(), you can assign
it to the
onPageTrailerListener variable
so that the function runs on every page when the page trailer is to
be printed. The following sample code shows the assignment:
myReport.onPageTrailerListener = printPageTotals;
Each of these TextReportListener variables is a Delegate type.
This means that you can assign any function with a matching signature
(having the same number and type of parameters) to one of these variables.
Each variable takes a single argument that is a TextReportEvent type
(TextReportEvent is another EGL ExternalType part). In most cases,
you do not need to focus on the details of this event type; declare
the variable at the same time you declare the function, as in the
following example:
function printPageTotals(myEvent TextReportEvent in)
...
end
You do not need to reference
myEvent within the
function. Like the exception record (see
Exception handling),
the TextReportEvent parameter can provide information about the state
of the report and why the function was called. There are four fields
within the TextReportEvent variable that you can access. The first
field holds a value that indicates why the function was called, and
the other three fields contain constant values to compare against
the first value:
- state
- An integer that contains information about the event that triggered
the calling of the function. The variable is set to one of the following
fields (in most cases to STATE_UNSPECIFIED).
- STATE_UNSPECIFIED
- An integer constant equal to 1. When the state field is equal
to the STATE_UNSPECIFIED field, no information is provided as to why
the function was called.
- STATE_LASTROW
- An integer constant equal to 2. When the state field is equal
to the STATE_LASTROW field, the function is called because the last
row has been printed.
- STATE_FIRSTROW
- An integer constant equal to 3. When the state field is equal
to the STATE_FIRSTROW field, the function is called because the first
row is about to be printed.
The following code provides an example of using the
state field
to allow for the special case in which you have just begun printing
the report:
function beforeGroup (myEvent TextReportEvent in)
if ((currentReportRecord.customerName != previousReportRecord.customerName)||
(myEvent.state == myEvent.STATE_FIRSTROW))
printCustomerName(currentReportRecord);
end
end
You can assign a function to any of the following variables:
- onFirstPageHeaderListener
- Points to the function that prints the first page header. Do not
assign anything to this if the first page does not have a unique header.
- onPageHeaderListener
- Points to the function that prints the page header. If no first
page header is specified, this is printed on all pages; otherwise,
it is printed starting with the second page.
- onEveryRowListener
- Points to the function that prints the row data.
- onLastRowListener
- Points to the function that prints text after the last row. This
is the last thing that is printed on a report other than the trailer
at the bottom of the last page.
- onPageTrailerListener
- Points to the function that prints the trailer text.
- onBeforeGroupListener
- Always called immediately before the onEveryRowListener function.
It provides a mechanism to print text before printing a group of data.
- onAfterGroupListener
- Called immediately before the onBeforeGroupListener function (except
on the first row of data). It provides a mechanism to print text after
printing a group of data. It is also called immediately before the
onLastRowListener function.