Report and Engine objects

Apart from objects, which are contained in the report, there are two variables defined in the script: Report and Engine.

The Report variable refers to the current report. In the list below, a list of the report object's methods is given:

Method	Description
object Calc( string expression)	Calculates an expression and returns the value. When calling this method the first time, an expression gets compiled, which needs some time.
object GetColumnValue( string complexName)	Returns the value of the data column. The name must be presented in the "DataSource.Column" form. If the column has got the null value, it is converted into a value by default (0, empty string, false).
object GetColumnValueNullable( string complexName)	Returns the value of the data column. Contrary to the previous method, it does not get converted into a default value and may be null.
Parameter GetParameter( string complexName)	Returns the reports parameter with the indicated name. Name can be compounded when referring to the nested parameter: "MainParam.NestedParam".
object GetParameterValue( string complexName)	Returns the value of the report parameter with the indicated name.
void SetParameterValue( string complexName, object value)	Sets the value of the report parameter with the indicated name.
object GetVariableValue( string complexName)	Returns the value of the system variable, for example, "Date".
object GetTotalValue( string name)	Returns the value of the total, defined in the "Data" window, by its name.
DataSourceBase GetDataSource( string alias)	Returns the data source, defined in the report, by its name.

The Engine object is an engine that controls the report creation. By using the methods and properties of the engine, you can manage the process of placing bands onto the page. You can use the following properties of the Engine object:

Property	Description
float CurX	Current coordinates on the X-axis. This property can be assigned a value, so as to shift the printed object.
float CurY	Current printing position on the Y-axis. To this property, a value can be assigned so as to shift the printed object.
int CurColumn	Number of the current column in a multicolumn report. The first column has the number 0.
int CurPage	Number of the page being printed. This value can be received from the "Page" system variable.
float PageWidth	Width of the page minus the size of the left and right margins.
float PageHeight	Height of the page minus the size of the top and bottom margins.
float PageFooterHeight	Height of the page footer (and all its child bands).
float ColumnFooterHeight	Height of the column footer (and all of its child bands).
float FreeSpace	Size of the free space on the page.
bool FirstPass	Returns true, if the first (or only) report pass is being executed. Number of passes can be obtained from the Report.DoublePass property.
bool FinalPass	Returns true, if the last (or only) report pass is being executed.

Engine.PageWidth and Engine.PageHeight properties determine the size of the printing area, which is almost always less than the actual size of the page. Size of the printed area is determined by the page margins, which is given by the LeftMargin, TopMargin, RightMargin and BottomMargin page properties.

Engine.FreeSpace property determines the height of the free space on the page. If there is the "Page footer" band on the page, its height is considered when calculating the FreeSpace. Note that, after printing a band, free space is reduced.

How does the formation of a prepared report page take place? FastReport engine displays bands on the page until there is enough space for band output. When there is no free space, the "Report footer" band is printed and a new empty page is formed. Displaying a band starts from the current position, which is determined by the X and Y coordinates. This position is retuned by the Engine.CurX and Engine.CurY properties. After printing a band, CurY automatically increases by the height of the printed band. After forming a new page, the position of the CurY is set to 0. The position of the CurX changes when printing a multicolumn report.

Engine.CurX and Engine.CurY properties are accessible not only for reading, but also for writing. This means that you can shift a band manually by using one of the suitable events. Examples of using these properties can be seen in the "Examples" section.

When working with properties, which return the size or position, remember that, these properties are measured in the screen pixels.

Method	Description
void AddOutline(string text)	Adds an element into the report outline (read the chapter "Interactive reports") and sets the current position to the added element.
void OutlineRoot()	Sets the current position on the root of the outline.
void OutlineUp()	Shifts the current position to a higher-level outline element.
void AddBookmark(string name)	Adds a bookmark (read the chapter "Interactive reports").
int GetBookmarkPage(string name)	Returns the page number on which the bookmark with the indicated name is placed.
void StartNewPage()	Starts a new page. If the report is multicolumn, a new column is started.

By using the AddOutline, OutlineRoot, OutlineUp methods, you can form the report outline manually. Usually, this is done automatically with the help of the OutlineExpression property, which every band and report page have got.

The AddOutline method adds a child element to the current outline element, and makes it current. The current report page and the current position on the page are associated with the new element. If you call the AddOutline method several times, then you will have the following structure:

For controlling the current element, there are OutlineUp and OutlineRoot methods. The first method moves the pointer to the element, located on a higher level. So, the script

The OutlineRoot method moves the current element to the root of the outline. For example, the following script:

For working with bookmarks, the AddBookmark and GetBookmarkPage methods of the Engine object are used. Usually bookmarks are added automatically when using the Bookmark property, which all objects of the report have got.

By using the Add Bookmark method, you can add a bookmark programmatically. This method creates a bookmark on the current page at the current printing position.

The GetBookmarkPage method returns the page number on which the bookmark is placed. This method is often used when creating the table of contents, for displaying page numbers. In this case, the report must have a double pass.