Using the "Engine" Object
We have already said that the “Engine” object represents the report's engine, which manages report construction. The process of arranging band(s) on a page can be managed by using the engine's properties and methods. First some theory.
The diagram below shows various dimensions of the report page.
The physical dimensions of the page are the “PaperWidth” and “PaperHeight” properties, visible in the object inspector when the page is selected. So the size of an A4 page is 210 x 297mm.
“PageWidth” and “PageHeight” are the dimensions of the printable region, which is usually less than the physical dimensions of the page. The size of the printable region is dependent on the report page properties “LeftMargin”, “TopMargin”, “RightMargin” and “BottomMargin”. The printable region’s size in pixels is returned by the “Engine.PageWidth” and “Engine.PageHeight” functions.
Finally, “FreeSpace” is the height of the free space on a page. If there is a "Page Footer" band on the page, its height is taken into account when calculating the “FreeSpace”. This height is returned in pixels by the “Engine.FreeSpace” function. Note that after displaying the next band the free space is reduced on the page, this is taken into account when calculating the “FreeSpace”.
How are report pages constructed? The FastReport core displays bands on a page as long as there is enough free space. When there is no more free space left the “Page Footer" band is printed (if required) and a new blank page is created. As already said, after displaying the next band the height of free space is reduced. Moreover, display of the next band begins from the current position, which is defined by coordinates on the X-axis and the Y-axis. The current position is returned by “Engine.CurX” and “Engine.CurY” respectively. After printing the next band, CurY automatically increases by the height of the printed band. After a new page is created “CurY” equals “0.” “CurX” is changed when printing multi-column reports.
“Engine.CurX” and “Engine.CurY” are available not only for reading but also for writing. This means that bands can be shifted by incrementing or decrementing these values. For example, in a report resembling this:
it can be printed in the following way:
This is achieved by writing a handler for the band's “OnBeforePrint” event:
procedure MasterData1OnBeforePrint(Sender: TfrxComponent);
begin
Engine.CurX := Engine.CurX + 5;
end;
Changing “CurY” can make bands overlap, for example:
Achieved by this script:
PascalScript:
procedure MasterData1OnBeforePrint(Sender: TfrxComponent);
begin
Engine.CurY := Engine.CurY - 15;
end;
C++ Script:
void MasterData1OnBeforePrint(TfrxComponent Sender)
{
Engine.CurY = Engine.CurY - 15;
}
The “Engine.NewPage” method inserts a page break at any required point in a report, following which printing continues from the top of the new output page. In our example a break can be inserted after printing the second record:
PascalScript:
procedure MasterData1OnAfterPrint(Sender: TfrxComponent);
begin
if <Line> = 2 then
Engine.NewPage;
end;
C++ Script:
void MasterData1OnAfterPrint(TfrxComponent Sender)
{
if (<Line> == 2)
Engine.NewPage();
}
Note that we used the “OnAfterPrint” event (that is to say, after the band has been printed). Also note that the “Line” system variable returns the sequential number of the record.
The “Engine.NewColumn” method inserts a column break in multi-columned reports. If there are no more free columns left on the page then a new page is created.