Software-Promoter User Manual - Built-in language

Using interpreter

FastReport has a built-in Pascal-like language interpreter. This interpreter is a powerful means of writing language-independent (Delphi or C++Builder) scripts which are used for building reports.

The language used in the interpreter is a Pascal dialect with the following capabilities:

operators: assignment operator; conditional statements, loop statements and unconditional jump: if...then...else, while...do, repeat...until, for..to..do, goto;
statement parentheses begin...end;
variables without type, arrays;
references to properties and methods of FastReport objects through dot notation.

Compared to Object Pascal this language is much simplified. The following simplifications are used:

all variables are of Variant type; there are no type definitions for variables;
all variables are global, there are no local variables;
there are no data types such as class, record, enumeration type etc.;
you cannot write your own procedures or functions;
there are no loop breaking operators (break, continue);
the number of arguments passed to a procedure or a function cannot exceed 3;
due to the fact that variables have no data type, data type control is unavailable; this should be taken into account when writing logical expressions;
arrays can only be one-dimensional.

Scripts and objects

Each object can have one or more code blocks. Script editing is done in the text editor window (to see the script you have to click the button at the top of the window). The script runs each time before printing an object. (The script is attached to the OnBeforePrint property of the object).

Not only objects can have scripts. Bands and report pages are scriptable too. To call the band script you must open the OnBeforePrint property editor of the band (either from the Object inspector or by selecting the band and pressing Ctrl+Enter). To call the script of the report page you must open the OnBeforePrint property editor of the page (to do that you can click on an empty place on the page and call the editor from the Object inspector). Both Dialog Forms and Report Pages have scripts attached to their OnActivate property. All other object's scripts can be accessed from their Memo property or by pressing Ctrl+Enter.

Code writing

In scripts, you can use properties and methods of the report objects, database table fields and various constants. Also you can create variables and arrays accessible throughout the whole report. You can use procedures and functions as well.

Using variables

There is no need to specify the "type" of variables, they all are variant. You can use Latin letters, digits and underline symbols in variable names. Variables from scripts can be used in objects and the variables from the list of variables can be used in scripts. Script variables are stored in TfrVariables object which can be accessed through the frVariables global variable.

This is an example of using an intermediate variable:

begin

Cust := [CustomerData.RepQuery."CustNo"];

if FinalPass then

TotalSales := Arr[Cust] else

TotalSales := 0;

end;

In this example we create a variable Cust and set it equal to the database table field value.

You can also call variables defined in the data dictionary, system variables and user variables. In this case the variables' names might contain symbols that are not normally allowed by syntax rules (take Page# system variable for example). To call such variables you must use square brackets:

begin

a := [Page#];

end

Referencing database fields

You can use references to database tables in your scripts. Here is the syntax of such a reference:

[FormName.TalbeName."FieldName"]

The full path is used when the table and the report are located on different forms (or data module). If the components are on the same form you can address them as [TableName."FieldName"].

You can just write ["FieldName"] if you address the table on which the band you are using is based. For example if you have master data band, which is connected to Customer.db table through a data source, you can refer to the fields of this table throughout the report using just the short path. Using the full path will not slow you down - FastReport stores database field names in cache.

Arrays

Apart from variables you can also create arrays in your scripts. The arrays can only be one-dimensional but you can use their elements in the way that they will be treated as two-dimensional.

Example of using an array:

begin

MyArr[0] := 'a'; MyArr[1] := 'b'; MyArr[3] := 'd';

MyArr[2] := MyArr[0] + MyArr[1] + 'c' + MyArr[3];

end;

Actually the array elements' values are stored in the frVariables list in Arr_array_name_index format. I.e. in the above example the contents of frVariables will be:

Arr_MyArr_0 := 'a'

Arr_MyArr_1 := 'b'

Arr_MyArr_2 := 'abcd'

Arr_MyArr_3 := 'd'

Constants

You can use constants in your scripts. A simple example is using numeric, string and logical constants:

begin

a := 0;

b := 'abcd';

c := True;

d := 'That''s all!';

end;

Pay attention to using single quotes inside string constants – like in Pascal, they have to be duplicated: d := 'That''s all!'.

Apart from simple constants you can use such constants as color names, font type names etc. Below is the list of available constants:

colors: clWhite, clBlack etc. – all standard colors + system colors;

dialog box response constants: mrNone, mrOk, mrCancel;

system: CRLF, Null;

font style types: fsBold, fsItalic, fsUnderline;

object frames: frftNone, frftRight, frftBottom, frftLeft, frftTop;

text alignment in a"Text" object: frtaLeft, frtaRight, frtaCenter, frtaVertical, frtaMiddle, frtaDown;

band aligning: baNone, baLeft, baRight, baCenter, baWidth, baBottom.

Besides these there are constants for add-in objects, for example, csCheck for "CheckBoxObject" objects. Anything you can see in a drop-down property list box in the Object inspector can be used as a constant in scripts.

Referencing objects

You can reference a report's object's properties and methods in your scripts. Report objects are visual objects, control objects, bands, report pages and reports themselves. To reference an object dot notation is used, for example: Memo1.Text. To reference intrinsic properties and methods dot notation is not necessary.

Properties that can be referenced are shown in the Object inspector. Some combined properties like those of Font can be referenced by using Font.Name, Font.Size etc.:

begin

Memo1.Font.Name := 'Courier New';

Memo1.Font.Size := 10;

Memo1.Font.Color := clRed;

Memo1.Font.Style := fsBold + fsItalic

end;

Properties such as TStrings (Memo, SQL, Items etc.) can be referenced by their index:

if Memo1.Lines[1] = 'a' then

Memo1.Lines[1] := 'b'

Such properties can also be referenced using Add, Delete, Clear and Count:

if Memo1.Lines.Count > 10 then

Memo1.Lines.Delete(10)

else

begin

Memo1.Lines.Clear;

Memo1.Lines.Add('a');

end;

A full list of object properties and methods can be found in the "Object properties and methods" paragraph. Make a note that referencing a non-existent method or property will not cause an error message, so be careful when writing code.

Using procedures and functions

Scripts can contain procedures and functions calls. A peculiar property of the interpreter, or to be more precise the parser responsible for procedure/function processing, is that procedures and functions can not have more that 3 arguments. Scripts can use both built-in procedures and external procedures, defined in the project. The list of built-in procedures and functions is in the "Built-in procedures and functions" paragraph.

Note. When referencing a procedure or function there must not be a space between the procedure name and the opening bracket.

Objects modification

In your scripts you can make any modifications to objects, like changing size, color, contents, etc. You must remember that in a single pass report you cannot modify objects which have already been processed. That is if you try to change the contents of an object in the report title from an object lying on a report summary band there will be no changes. However, you will be able to make such a modification if you make a two-pass report.

It works the same way in multi-page reports. You can reference any object by its name (names within a report are unique). But only non-processed objects can be modified. If you still need to modify a project which has already been processed you will have to make a two-pass report.

List of functions

Aggregate functions

Aggregate functions can be used in ReportSummary, PageFooter, MasterFooter, DetailFooter, SubdetailFooter, GroupFooter and CrossFooter bands.

Sum(<expression> [, band] [,1]). Calculates the sum of the values passed in <expression> for the band row given. If the band parameter is not set, sum defaults to all of the data values (on the bands MasterData, DetailData and SubdetailData); otherwise a sum refers only to data on the named band. If the "1" parameter is used, the sum includes non-visible objects too. Example:

Sum([Part total], Band1);

Sum([[Part total] + [Part price]]);

Sum([Part total], Band1, 1).

Avg, Min, Max. Syntax is analogous to the Sum function. Function Avg calculates an arithmetic average, function Min returns minimum and function Max returns maximum value from a row.
Count(<band>). Returns a count of data-rows. Example: Count(Band1).

String functions

Str(<value>). Converts number given in value to a string.
Copy(<string>, <from>, <count>). Returns a substring of <string> with length <count> characters , starting at <from>, (same as Delphi function).
If(<expression>, <string1>, <string2>). Returns string <string1>, if expression expression is true; otherwise returns <string2>.
FormatFloat(<formatstr>, <value>). Converts a numericaly significant value in string, making use of the mask in formatstr. The possible values of <formatstr> are described in the Delphi documentation's, "Formatting strings" topic.
FormatDateTime(<formatstr>, <value>). Converts a date/time value to a string, making use of the mask in <formatstr>. The possible values of <formatstr> are as described in the Delphi documentation's, "Formatting strings" topic.
StrToDate(<value>). Converts the string <value> to a date.
StrToTime(<value>). Converts the string <value> to a time.
UpperCase(<value>). Converts the string <value> to all upper case.
LowerCase(<value>). Converts the string <value> to all lower case.
NameCase(<value>). Converts the first character of string <value> to upper case and the remaining characters to lower case.
Length(<string>). Returns the length of <string>.
Trim(<string>). Trims (removes) all spaces at the beginning and end of <string> and returns the result.
Pos(<substring>, <string>). Returns the position of <substring> in the given <string>.

Arithmetic functions

Int(<value>). Returns the whole part of the number <value>.
Frac(<value>). Returns the fractional part of the number <value>.
Round(<value>). Returns rounded number.
value1 Mod value2. Returns the remainder resulting from dividing <value1> by <value2>.
MinNum(<value1>, <value2>). Returns the smaller of the two values.
MaxNum(<value1>, <value2>). Return the greater of the two values.

Other functions

Input(<caption> [,<default>]). Shows a dialog window with the heading <caption> and an edit box. If "default" parameter is set, puts this string into the edit box. After user clicks OK, returns the input string.
Date. Returns current system date.
Time. Returns current system time.
Line#. Returns the current Line number; counting begins at the start of each new group. For example:

Master data

1. Detail data

2. Detail data

3. Detail data

Master data

1. Detail data

2. Detail data

LineThrough#. Returns the current Line number; counting begins at the start of the report. For example:

Master data

1. Detail data

2. Detail data

3. Detail data

Master data

4. Detail data

5. Detail data

Column#. Returns the current column number in a cross-tab report.
Page#. Returns the current page number.
TotalPages. Returns the total number of pages in a completed report. To use of this function a report must be a two pass report.
DayOf(<date>). Returns day (1..31) of given date.
MonthOf(<date>). Returns month of given date.
YearOf(<date>). Returns year of given date.
MessageBox(<text>, <caption>, <buttons_and_icons>). Shows a message dialog window with text, caption and buttons. Returns a value that corresponds to the user's selection (mrOk, mrCancel, mrYes, mrNo). Use the following values for the <buttons_and_icons> parameter:

Buttons Icon

mb_Ok mb_IconError

mb_OkCancel mb_IconQuestion

mb_YesNo mb_IconInformation

mb_YesNoCancel mb_IconWarning

Procedures and functions that can be used during building a report

CurY. Returns the current Y position where the next band will be printed. You also can assign a value to CurY – it moves the current position accordingly. To convert pixels to millimeters and back, use the following ratio: 18 pixels = 5mm.
FreeSpace.Return space remaining in the page in pixels.
FinalPass. Returns true, if a report is two-pass and is now running the final pass.
PageHeight. Returns page height in pixels minus the height of the page footer band.
PageWidth. Return page width in pixels.
StopReport. Terminates report building.
NewPage. Starts a new page.
NewColumn. Starts a new column in a multi-column report.
ShowBand(<band>). Shows band named <band>.

Prev Next

=== Documentation is provided by Word2Help ===