Chapter 1

Fundamentals

In this chapter we will learn the principles of working with a report in the FastReport. We will also take a close look at report elements such as report pages, bands, and report objects.

The report

The report building process can be represented as follows:

Report template (later-Report) - this is, what we see in the designer. Reports are saved in files with an extension .FRX. A Report can be created with the help of designer or programmatically.

Data can be any: this is data, defined in the program, or data from DBMS, for example, MS SQL. FastReport can also work with business-logic objects (later - business-objects).

Prepared Report - this is what we see in the preview window. Prepared report can be previewed, printed, saved in one of the supported formats (.doc, .xls, .pdf and others), or can be sent by email.

Report designer

In order to create a report template, a report designer is used. A designer gives the user comfortable facilities for designing the report and allows previewing the report at the same time.

The report designer is the compound part of FastReport and does not depend on the development environment (for example, MS Visual Studio). If you are a software developer, you may include the report designer into your application. This will give your end-users the ability to either change the existing report or create a new one.

Report options

A window with report options can be called in the "Report|Options..." menu. You will see a dialogue window with several tabs:

On the "General" tab, you can control the following report parameters:

• "Double pass" parameter allows to enable two report passes. This can be necessary when you use the "total number of pages" system variable;  

• "Compress report file" parameter allows saving a report in a compressed form. For compressing, zip algorithm is used, that is why you can easily extract original contents with the help of any archive;

• "Use file cache" parameter allows to save the memory when creating a report. Use this parameter if your report has got a lot of pages;

• "Convert null values" controls converting the null value data column into the default value (0, empty string, false - depending on the data type of a column); 
  "Text quality" parameter allows choosing the mode of text displaying in the report. This mode does not affect printing of the report;

• "Smooth graphics" parameter allows to enable the smooth mode when drawing graphical objects (line, border, picture).

On the Description" tab, you can give the description of the report. All these parameters are not obligatory, and they serve for informational purposes:

On the "Script" tab, you can choose the script language for the report. Detailed work with script can be found in the "Script" chapter.

On the "Security" tab you can give the password which will be requested when opening the report. A report which has a password, is saved in an encoded form, so do not forget your password! Restoring a report in this case will be practically impossible.

On the "Inheritance" tab, you can control report inheritance. This functionality will be looked at later.

Report pages

Template consists of one (mostly) or several report pages. Report page, in turn, contains bands. Report objects like Text, Picture and others are placed on the band:

Report template can consist of several pages. For example, you can create a template containing title-page and a page with data. When creating such a report, the first page will be printed first, then the second page and so on. Every page of template can generate one or several pages of a prepared report this depends on the data it contains:

Report pages are also used when working with subreports. Contrary to other report generators, subreports in FastReport are saved in a separate template page, and not in a separate file.

Apart from report pages, a template can contain one or more dialogue forms. Dialogue forms can be used for inquiring some parameters before creating a report. Detailed work with dialogue forms will be covered in the "Dialogue forms" chapter.

Managing pages

When you have created a new report, it already contains one page with several bands. For adding a new page, click the button. A page can also be added by clicking the and choosing "New Report Page" in the window.

In a similar way, dialogue forms can be added into the report. For this, use the

Template pages are displayed in the designer as tabs:

The first tab is the report code. It can neither be moved nor deleted.

In order to switch to the needed page, simply click on its tab. Changing order of the pages can be done with the help of the mouse. For this, left click on the tab and, without leaving the 
mouse, move the tab to the desired place.

For deleting a page, click the button. This button is not active if the report consists of only one page.

Page properties

Every report page can have its own settings, such as paper size, orientation (landscape or portrait), margins, columns, paper source and others. Report template can contain several pages with different orientations and paper sizes. The window with page setup can be called  button or by choosing the "File|Page setup..." menu item.

The "Paper" group allows to set the paper size and orientation. It is possible to choose one of the supported sizes, by using the drop-down list. It contains all paper sizes which are supported by the current printer.

Current printer can be configured by using "File|Printer Setup..." menu.

The "Margins" group allows to setup page margins. The "Mirror margins on even pages" options can be used to print booklets:

The "Source" group allows choosing the source of the paper. Note that the sources can be given separately, that of the first page of the prepared report, and that of the rest of pages:

The source can be chosen in the "Print" dialog as well.

The "Columns" group allows setup the column parameters for multi-columned report. For this, the number of columns need to be indicated and (optional) correct the width of the column and the position of every column:

The "Other" group allows giving certain helpful page properties. It is possible to indicate duplex mode for duplex printing if your printer supports this mode. Here it is also possible to set the watermark, which will be printed on prepared report pages:

The "Extra design width" checkbox allows to increase the page width in the design mode. It may be useful if you work with such objects as "Table" or "Matrix".

The duplex mode can be chosen in the "Print" dialog as well.

Bands

The band is an object which is located directly on the report page and is a container for other objects like "Text", "Picture" and others. In all, in FastReport there are 13 types of bands. Depending on its type, the band is printed in a certain place in the report.

Bands in designer

A band in the designer appears in form of a rectangular area. A band, like many other report objects, can have a border and fill (by default they are disabled). Apart from this, a band displays a grid. To set the grid mode, go the "View|Options..." menu and choose "Report page". Grid can also be enabled or disabled in the "View" menu.

You can set the band's height in three ways:

• place the mouse pointer at the bottom of the band. The cursor shape will be changed to "horizontal splitter" and you can resize a band.

• drag the band handle on the left ruler.

• use "Properties" window to set the band's Height property.

The designer has two modes of displaying bands, between which you can switch at any time. In the first mode, every band has got a header, which contains the title of the band and useful information about it (for example, the name of the data source to which it is connected).

In the second mode, the band does not have a header. Instead of that, on the left side of the window, the structure of the bands is displayed. This mode helps to easily understand the structure of the report, especially if it was not created by you.

You can switch between these modes by clicking the

Configuring bands

You can configure the bands in the "Configure Bands" window. It can be called from the "Report|Configure Bands..." menu or with the help of the "Configure bands" button, placed over the bands tree:

In this window, it is possible to add bands into the report, delete them or change their order. To add a band, click the "Add" button or right click on band tree. A context menu will come up containing a list of bands. A band which cannot be added is dimmed.

The "Add" operation depends on what band was chosen in the band tree. For example, adding "Data Header" and "Data Footer" bands is possible only if the "Data" band was selected beforehand.

There is also another way of configuring some bands. This can be done from the "Report" menu:

To delete a band, select it and press "Delete" key.

When configuring bands, FastReport does not allow to do operations which leads to the creation of a wrong report template. For example, you cannot delete the "Data" band, which is connected to the group - for this, the group needs to be deleted first. Another example, when deleting the "Data" band, its header and footer are deleted automatically. Also, it is not possible to delete a band if it is the only one on the page.

Printing Bands

So, there are several bands placed on the page. How will FastReport compose a prepared report? Let us look at the following example:

The "Report Title" band will be printed first. The "Page Header" band will be printed immediately after it. Further, the "Data" band will be printed as many times as there are rows in the data source, to which the band is connected. After all the rows of the "Data" band have been printed, the "Report Summary" band is printed and at the bottom of the page - the "Page Footer" band. Printing of the report ends with this. A prepared report will be looking something like this:

In the process of printing, FastReport checks if there is enough space on the current page of the prepared report, so that the band can be printed. If there isn't enough space, the following occurs:

• page footer is printed;

• a new page is added;

• page header is printed;

• continues to print the band which did not fit on the previous page.

Band properties

Every band has several useful properties, which affect the printing process. They can be configured by using the band's context menu.To do this, right-click on an empty space on the band, not occupied by other objects. Also, it is possible by clicking on the band header (if the classic display mode is used) or on band structure (otherwise). Another method choose a band and change the corresponding properties in the "Properties" window.

Report objects

A wide variety of objects can be used in a report.

An object can be used to display an information ("Text" object) or to improve the report appearance ("Picture", "Line", "Shape" objects). Complex objects like "Table" and "Matrix" can contain other simple objects.

Common object properties

All report objects are inherited from one basic class (ReportComponentBase) and have got certain set of common properties. Before studying each object, we will look at these properties.

You can change the value of properties with the help of the "Properties" window. Some properties can be changed using the object's context menu or toolbars (for example, border and fill).

The "Text" object

The "Text" object is the main object which you will use often. It looks like this:

The object can display any text data, specifically:

• one or several text lines;

• data columns;

• report parameters;

• total values;

• expressions;

• any combination of the above items.

Text editing

In order to edit an object's text, just double click on it. You will see a text editor:

There is a data tree on the right side of the editor, which elements can be added into the text. This can be done by dragging the element onto needed place by using the mouse. Another way to insert an element into the text - double click on the element, and it will be added onto the cursor's current position.

In order to save the changes and close the editor window, click the OK button or press the Ctrl+Enter keys.

Another method of editing a text - in-place editing. To do this, select the "Text" object and press Enter. To finish editing, click somewhere outside the objects bounds or press Ctrl+Enter. Press Esc key to cancel the changes.

When editing an object in-place, its size can be changed by using a mouse.

Displaying the expressions

The "Text" object can contain a plain text mixed with expressions. For example:

Today is [Date]

When printing such an object, all expressions contained in the text will be calculated. So the result may look like this:

Today is 12.09.2010

As seen, expressions are identified by square brackets. This is set in the "Brackets" property, which by default contains the string "[,]".When needed, you can use a different set of symbols, for example "<,>", or "<!,!>". In the last case, an expression in the text will be like this:

Today is <!Date!>

Apart from this, it is possible to disable all expressions. To do this, set the AllowExpressions property to false. In this case the text will be shown "as is".

Inside the square brackets, you can use any valid expression. Read more about expressions in the "Expressions" chapter. For example, an object with the following text:

2 * 2 = [2 * 2]

will be printed like this:

2 * 2 = 4

Frequent mistake - attempt to write an expression outside the square brackets. Reminding, that it is considered an expression and gets executed only that, which is located inside square brackets. For example:

2 * 2 = [2] * [2]

This text will be printed this way:

2 * 2 = 2 * 2

There may be elements inside an expression that needs own square brackets. For example, it may be a reference to a system variable (see the "Expressions" chapter for details). Let's look at the following example:

The next page: [[Page] + 1]

The text contains an expression [Page] + 1. Page is a system variable which returns the number of the current report page. It is included in own brackets. These brackets must be square brackets, regardless of the "Text" object settings.

Strict speaking, we were supposed to use two pairs of square brackets when using the "Date" system variable in the examples above:

Today is [[Date]]

However FastReport allows to leave out unnecessary pair of brackets if there is only one member in an expression.

Displaying the data columns

You can print the data column in the following way:

[Datasource name.Column name]

As you can see, the square brackets are used here. The data source name and data column name are separated by the period. For example:

[Employees.FirstName]

Read more about using the data columns in the "Expressions" chapter.

There are several ways to insert a data column into the "Text" object.

1. In the "Text" object's editor we write the name of the data column manually. This method is the most inconvenient as it is easy to make a mistake.

2. In the object's editor we choose the needed data column and drag&drop it into the text:

3. 

4. Click on the small button in the upper right corner of the object and choose the data column from a list:

4. Drag&drop a data column from the "Data" window into the report page. In this case the "Text" object is created which contains a link to the column.

HTML tags

You may use some simple HTML tags in the "Text" object. By default, tags are disabled; to enable it, go "Properties" window and set the "HtmlTags" property to true. Here is a list of supported tags:

The following examples demonstrate how these tags can be used.

text <b>bold text</b> <i>text in italic</i> <b><i>bold and in italic</b></i> E = mc²

A₁ = B²

this is regular text, <font color=red>and this is a red one</font> this is regular text, <font color=#FF8030>and this is an orange one</font>

This text will be displayed in the following way:

Object's properties

The "Rich Text" object

This object displays the formatted text (in the RTF format). It looks like this:

Try to use the "Text" object to display a text. When you export the report to some document formats, the "Rich Text" object will be exported as a picture.

This object supports only the solid fill type. Gradient, hatch, glass fills are not supported.

To edit the object, double click on it. You will see the editor window:

You can also use the Microsoft Word to create a text. When you have done, save the text in the .RTF format. Next, you need to open the "Rich Text" editor and load the .RTF file into it by

The "Rich Text" object does not support all of the Microsoft Word formatting features.

You can display a data in this object the following ways:

• you can insert an expression in the object's text, just as you do this in the "Text" object. Insert the necessary data column into the text;

• use the "DataColumn" property to bind the object to the column.

The object has the following properties:

The "Picture" object

An object can display graphics in the following formats: BMP, PNG, JPG, GIF, TIFF, ICO, EMF, WMF. With the help of the "Picture" object, you can print your company logo, a photo of employee or any graphical information. The object looks like this:

An object can show data from the following sources:

 In order to call a picture editor, double click on the object. In the editor, you can choose the data source for the picture:

In order to bind the object to a data column, click on the small button in the upper right corner of the object and choose the data column from a list:

You also can drag&drop a data column from the "Data" window into the report page. In this case the "Picture" object is created which contains a link to the column. The column you drag should have the "byte[]" data type.

In the context menu of the "Picture" object you can choose the size mode:

• AutoSize. The object gets the size of the picture.

• CenterImage. The picture is centered inside the object.

• Normal. The picture is displayed in the left corner of the object.

• StretchImage. The picture is stretched to the size of the object.

• Zoom. The picture is stretched to the size of the object in accordance with the aspect ratio.

The difference between modes is shown in the following picture:

The "Picture" object has the following properties:

The "Line" object

The "Line" object can display horizontal, vertical or diagonal line. The object is as follows:

If possible, use the object's border instead of "Line" object. This will simplify the report and avoid possible problems with the export to different formats.

FastReport designer has convenient tools for drawing a line. In order to insert a line into a report, click the  button on the "Objects" toolbar and in the menu choose the "Line" object or "Diagonal Line". Place the mouse cursor at the location where the line will start from. Then left click and hold the mouse, in order to draw the line. After this, you can draw the line again.

When all the lines have been drawn, click on the  button on the "Objects" toolbar.

An ordinary line differs from a diagonal line in that you can make it only vertical or horizontal.

Do not choose the "Double" line style for this object. This style applies only to the object's border.

The "Line" object has the following properties:

The "Shape" object

The "Shape" object displays one of the following shapes:

• rectangle;

• rounded rectangle;

• ellipse;

• triangle;

• diamond.

The object is as follows:

In order to insert a shape into the report, click the button on the "Objects" toolbar and choose the needed shape type.

The shape, like any other report object, has a fill and border. Contrary to the "Text" object, you cannot control each border line. Also, don't use the "Double" line style.

Instead of rectangular shape, use the object's borders if possible.

The "Shape" object has the following properties:

The "Barcode" object

The object displays barcodes in the report. It looks like this:

The object supports the following types of barcodes:

Code93 Extended                                                                                       128 ASCII chars

A detailed description of different barcode types can be found in the internet, for example, here: http://www.barcodeisland.com

Barcode data in an object is of a string type. The string can contain any symbol, allowed for the chosen type of barcode. You can choose the type of barcode in the context menu of the "Barcode" object.

You can connect an object to data by using one of the following methods:

• set the barcode data in the "Text" property;

• bind the object to a data column using the "DataColumn" property; 

• set the expression that returns the barcode data in the "Expression" property.

The "Barcode" object has the following properties:

The following properties are specific to the barcode type. To change them, select the barcode, go "Properties" window and expand the "Barcode" property.

The "CheckBox" object

The object displays the checkbox in the report. It looks as follows:

The object can display two states: "Checked" and "Unchecked". Use the following ways to handle the object's state:

set the state in the "Checked" property;

bind the object to a data column using the "DataColumn" property; set the expression that returns the true or false in the "Expression" property.

The "CheckBox" object has the following properties:

use values in the 0.2 - 2 range.

The "Table" object

The "Table" object is made up of rows, columns and cells. It is a simplified analog of Microsoft Excel table. It looks like this:

You can learn more about this object in the "Creating reports" chapter.

The "Table" object has the following properties:

The "Matrix" object

The "Matrix" object is, like the "Table" object, made up of rows, columns and cells. At the same time, it is not known beforehand how many rows and columns will be in the matrix - this depends on the data to which it is connected.

The object looks like this:

You can learn more about this object in the "Creating reports" chapter.

The "Matrix" object has the following properties:

The "Chart" object

The "MS Chart" object allows to display charts. There are more than 30 different series types available - bars, columns, areas, lines, bubbles, pie, circular, financial, pyramidal, ranges. The object looks like this:

You can learn more about this object in the "Report creation" chapter.

The "Chart" object has the following properties:

The "Zip Code" object

The "Zip Code" object allows to print a zip code on envelopes. It may display numeric characters (0-9).

The object is as follows:

You can connect an object to data by using one of the following methods:

• set the zipcode data in the "Text" property;

• bind the object to a data column using the "DataColumn" property; 

• set the expression that returns the zipcode data in the "Expression" property.

The "Zip Code" object has the following properties:

The "Cellular Text" object

This object can display each character of a text in its individual cell. It is often used to print some forms in financial applications.

The object is as follows:

In fact, this object is directly inherited from the "Text" object. You may connect it to data in the same manner. For example, you may invoke the object's editor and type the following text:

[Employees.FirstName]

The "Cellular Text" object has the following properties:

Your first report in the FastReport

Let us create a simple report, which prints a list of products. We will use the Products table, which can be found in the demo data base as our data source.

Assuming that, you will be performing the actions written below in the demonstration program, Demo.exe, from which the report designer can be called.

Example 1. Creating a report manually

In this example, we will create a report manually. For this, we will do the following:

press the button on the toolbar, and in the "Add New Item" window, choose "Blank report"; in the "Data" menu, choose the "Choose Report Data..." item and check the "Products" data source:

switch to the "Data" service window (if it is not on the screen, it can be shown by choosing the "Data|Show Data Window" menu item). Expand the "Data Sources" item, then the "Products" item:

• drag the "ProductName" data column onto the "Data" band. FastReport creates a "Text" object, which is connected to this column and a header for it; 
  

• we will create the "UnitPrice" data column by using another method. For this, press the "Text" button on the "Objects" toolbar:

• leave the mouse and drag its pointer onto the "Data" band - you will see that FastReport offers to insert an object. Choose the needed position and click the mouse to insert the object;

• place the mouse pointer on the object and click the small button in the right corner of the object. You will see a list of data columns. Choose the "UnitPrice" item from the list:

create the "Text" object - header for the "UnitPrice" column. Place in on the "Page Header" band. Double click the object and write the text "Unit Price"; 
create the "Text" object - report title. Place it on the "Report Title" band and write the text "PRODUCTS";

set "Bold" as font style for all objects that are placed on the "Page Header" and "Report Title" bands. For this, select objects by pressing Shift, and press the toolbar. After this, the report will be looking like this:

In order to run the report, click the  button on the toolbar. The report will be built and shown in the preview window:

Example 2. Creating a report with the wizard

In this example, we will create a report with the help of the "Standard Report Wizard". For this, do the following:

press the button on the toolbar and in the "Add New Item" window, choose "Standard Report Wizard":

on the first step of the wizard, choose the "Products" table and click the "Next" button:

on the second step of the wizard, choose the "ProductName" and "UnitPrice" data columns:

• the rest of the steps can be skipped, click the "Next" button; 

• on the last step of the wizard, choose "Blue" style and click the "Finish" button:

FastReport will create the following report:

To run a report, click the  button on a toolbar. The report will be built and shown in the preview window: