FastReport 2.2 for Delphi 2/3/4
Programmer's reference
========================
----------------------------------------------------------------------------
CONTENTS
Introduction.
1. Before creating report.
1.1. Report objects.
1.2. Data showing.
1.3. Variables list.
1.4. DB tables.
2. Report creating.
2.1. Simple report.
2.2. Master-detail report.
2.3. Master-detail-subdetail report.
2.4. Cross-tab report.
2.5. Reports with variable rows height.
2.6. Reports with multiple data strings.
2.7. Multicolumn reports.
2.8. Multipage reports.
2.9. Nested reports.
2.10. Master-Detail-Detail reports.
2.11. Composite reports.
2.12. Reports with breaked bands.
2.13. Reports with memo fields and pictures.
2.14. Reports without bands.
2.15. Reports with groups.
3. Data formatting.
4. Programming.
4.1. Non-DB data sets. Events.
4.2. Properties and methods.
----------------------------------------------------------------------------
INTRODUCTION.
FastReport is reporting tool. It consists of report engine, designer and preview in one. Its capabilities are comparable with QuickReport 2,3 and ReportBuilder 3.52.
In QuickReport you create report by Delphi designer. Report form is stored in resulting .exe file. This component uses another principle - report form is stored in external file, which may be modified without project recompiling.
Most significant differences from similar reporting tools are:
- cross-tab reports;
- powerful preview a-la MS Word with text search in created report;
- variables support.
1. BEFORE CREATING REPORT.
Place on the form TfrReport component. Take a look at the context menu of this component - there are report creating, editing, preview commands. All listed actions are available in designer.
In the component palette you also can see TfrDBDataset, TfrUserDataset components, which are datasets for data-bands (master data, detail data, subdetail data, varcolumn data).
TfrDBDataset component is data source linked to DB table (TDataset component), intended for dataset navigation. TfrUserDataset component is datasource linked to another (non-DB) dataset (e.g. array, file, etc). For navigating on this dataset, you must create event handlers for OnFirst, OnNext, OnCheckEOF events of component.
You must place TfrxxxDataset components on the form so many times, as much data bands in your report, and link it to TDataSource->TDataset components.
1.1.REPORT OBJECTS.
In FR you can use the following visual objects:
"Rectangle" - free-framed rectangle with multiline text inside it. You can set font and fill color, frame type, width and color, all the font attributes, text alignment and orientation (usual / 90 degrees).
"Picture" - free-framed rectangle with picture inside it. Picture can be BMP/ICO/WMF/EMF.
"Band" - one of 19 kinds. Not showed on report.
"Subreport" - as in ReportBuilder, allows using the nested reports.
It was standart objects. In package you can find three add-in objects - "RichView", "OLEView" and "FramedMemoView". In the last object, in comparison with "Rectangle", you can tune width and kind of each frame line.
All the objects can use data from DB fields.
So, "Rectangle" object corresponds to QRLabel, QRMemo, QRDBText, QRDBMemo, QRExpr, QRSysData;
"Picture" object corresponds to QRImage, QRDBImage.
1.2. DATA SHOWING.
In the memo of each object you can place multiline text with variables. Variables are surrounded by square brackets. If object contains a variable, event OnGetValue called. Event handler takes name of variable and must return its value. This is examples of using variables:
1.---------------------------------- 2.------------------------------------
?Length, cm: [Length] ?Length, cm: [Table1."Length_cm"]
3.---------------------------------- 4.------------------------------------
?Length, cm: [[Length, inch]*2.54] ?Length, cm:[Table1."Length_in"*2.54]
1.3. VARIABLES LIST.
Let's assume that we have DB table named "Employees" with fields named N, SName,
FName, TName (Number, Second name, First name, Third name).
That short fields names are difficult to understand. You can create full-name variable, linked to DB field, and insert it into object. Besides, you can assign math expression to the variable, e.g. sum of several DB fields, current date, time, rounded value, etc.
Example of using variables you can see in all demo reports. If variables list is too long, you can split it into several categories (as example - Detailed list, 3 levels of detail in demo). Unassigned variables must be handled in OnGetValue event handler. Example of this handler you can see in demo, report "Text file".
1.4. DB TABLES.
In many cases report data are stored in DB. FR allows using all the datasets (TDataSet descendants), which accessible in current time. E.g., in design-time you can access all the datasets, placed in opened units. In run-time you can access all the datasets, placed in created forms and datamodules.
2. CREATING REPORT.
In this part described report creating process, specific to FR.
FR, like all reporting tools, is a banded report generator. Here is listed all available bands:
Report title - prints once at the begin
of report.
Report summary - prints once at the end of report.
Page header - prints at the top of each page.
Page footer - prints at the bottom of each page.
Master header - prints at the begin
of the 1st level.
Master data - data of the 1st level.
Master footer - prints at the end of the 1st level.
Detail header - prints at the begin
of the 2nd level.
Detail data - data of the 2nd level.
Detail footer - prints at the bottom of the 2nd level.
Subdetail header - prints at the begin
of 3rd level.
Subdetail data - data of the 3rd level.
Subdetail footer - prints at the end of 3rd level.
Overlay - prints as bottom layer on page.
Column header - prints at the top of each column.
Column footer - prints at the bottom of each column.
Group header - prints at the begin
of group.
Group footer - prints at the end of group.
VarColumn header - this bands are intended for cross-tab reports creating.
VarColumn data
VarColumn footer
2.1. SIMPLE REPORT.
This is a simplest kind of report. For creating it, you should place "master data" band on the page, then
place objects with appropriate data in it.
2.2. MASTER-DETAIL REPORT.
For creating this report, place "master data" and "detail data" bands on the page, then
place objects with appropriate data in them.do
es not matter, in which order you place bands on the page - "master data" band will printed first. If appropriate detail list is empty, master string will be skipped. If youdo
n't want it, turn on the option "Print if detail empty" of "master data" band.
2.3. MASTER-DETAIL-SUBDETAIL REPORT.
For creating this report, place "master data", "detail data" and "subdetail data" bands on the page, then
place objects with appropriate data in them. All principles are like in master-detail report.
2.4. CROSS-TAB REPORT.
This report is intended for printing table with variable number of columns. During report building, all off-bounds columns will be printed on new page (like in MS Excel). For creating this report, place "master data" and "varcolumn data" bands on the page. Place object in the cross of this bands. This object will be printed as the cell of cross-table. That's all! If you want, place "varcolumn header" and "varcolumn footer" bands in your report. "Varcolumn footer" band is usable if you want to print sum of data in the string. "Varcolumn header" can print on each page, if option "Copy Varcolumn header" is set in page options.
2.5. REPORTS WITH VARIABLE ROW HEIGHT.
Data row height may be variable in many reports. Example of this - bill, with long goods names.
FR can print these reports. If band has variable height, you should turn on the "Stretched" option of band. You also should turn on this option of all stretched objects in the band. If calculated height of band smaller than its initial height, nothing happens. Otherwise, objects with turned option will be stretched - its bottoms will be stretched to band bottom.
2.6. REPORTS WITH MULTIPLE DATA STRINGS.
FRdo
n't allow you to place two identical bands on the page. Except of this - you can place many data-bands (master data, detail data, subdetail data) on the page. During report building, identical bands prints together. This allows you to create reports with data row consist of several identical data-bands.
This also allows you to create header/footer for each data-band. If data row exceeds the bottom of page, it prints at the next page.
All written is right, if top data band has data source, and otherdo
n't have. Otherwise, we get case of Master-detail-detail report.
2.7. MULTICOLUMN REPORTS.
FR can print multicolumn reports, like QRdo
es it. You can set the number of columns in page options.
2.8. MULTIPAGE REPORTS.
FR can print reports consisting of several pages, e.g. title page and others. For adding and removing page, use toolbar buttons or menu.
2.9. NESTED REPORTS.
Nested report is report with "Subreport" object placed in it. "Subreport" object is reference to the other report, placed in other page. During report building, on the place of "Subreport" object appropriate report will be printed. "Subreport" objects can be placed side-by-side in the page. In case subreports placed one under other, you must place it on different data bands.
There is restrictions of subreports using:
- cannot use columns;
- cannot use cross-tab reports;
- cannot use breaked bands (p.2.12);
- cannot use groups.
2.10. MASTER-DETAIL-DETAIL REPORTS.
For creating this report, place "master data" and two "detail data" bands on page. Link the bands to the appropriate data sources.
2.11. COMPOSITE REPORTS.
Composite report is report includes several other reports, like in QR. For creating composite report, you should use TfrCompositeReport object. Place it on the form and fill its "Reports" property in run-time by other reports references. Reports will be printed sequentially. If page of report have "Print to previous page" option, it will be printed at remained space at the last page of previous report.
2.12. REPORTS WITH BREAKED BANDS.
Let's create simple report. It will contain two fields: first, named "Program", and second, named "Description". If we take a look on the created report, we see, page surface used not fully - there is a lot of empty space. In our case we want carry long memos onto the next page. This will bedo
ne, if "Breaked" option of the band is set.
2.13. REPORTS WITH MEMO FIELDS AND PICTURES.
If you need showing blobfield data in the object, insert reference to appropriate field in object's memo.
If you need showing blob data from non-DB source, you mustdo
this in OnEnterRect event handler. Example of this may be found in demo, "Text file" report.
2.14. REPORTS WITHOUT BANDS.
If you want print a free-form report, containing data from one record, you cando
n't use bands. All the objects placed directly on page, will be printed at their places.
2.15. REPORTS WITH GROUPS.
These reports are included in version 2.2. It is similar to the QR groups.
There is restrictions of groups using:
- cannot use groups in the subreports;
- group can be top-level list only.
3. DATA FORMATTING.
After all objects are placed in page, you can choose formatting for each. "Rectangle" object and its descendants allows you to choose format of variables in dialog window. Variable can be shown as text, number, date, time, boolean value. For each of this categories you can choose format, or choose "custom" format and type own format string. For example, for number you can select the number of decimal digits after point, symbol used for point representation, and thousand-grouping. You can also choose custom format and type formatting string (for example, '#,###,##0.000'). Formatting strings for each category you can found in Delphi help system.
In the same dialog window, you can type condition of highlighting. If this condition is True, object will be shown with highlight attributes, which you can set in the designer by appropriate button on the toolbar. For example, you want to highlight amount paids, which are greater than $1000 (example in the demo, 3-level list). For it, you must type one of the following conditions: 'Value > 1000', or '[Part total] > 1000'.
This formatting options will be apply on the all variables, containing in the object. If variable cannot be formatted, it shows as text.
4. PROGRAMMING.
4.1. NON-DB DATA SETS. EVENTS.
Sometimes, you need to retrieve report data from non-DB data sources (e.g., array, file, etc). For navigating on this datasets, you should use TfrUserDataset component instead of TfrDBDataset. It generate OnFirst, OnNext, OnCheckEOF events to provide navigating. For retrieving data from non-DB dataset, you should use OnGetValue, OnEnterRect events of TfrReport component.
OnGetValue event handler called whenever a variable found in object's memo. Event handler takes name of variable and must return its value. If variable have an assigned value, it handles by internal handler. This is an example of OnGetValue event handler:
procedure TForm1.Doc1GetValue(const ParName: string;
var ParValue: Variant);
begin
if ParName = 'Var1' then
ParValue := '1'
else
if ParName = 'Var2' then
ParValue := 2
end;
OnEnterRect event handler called each time before object drawing. It most useful for filling object's memo or picture (for "Picture" object). This is an example of OnEnterRect event handler:
procedure TForm1.Doc1EnterRect(Memo: TStringList;
View: TView);
begin
if Memo.Count > 0 then
if Memo[0] = '[Memo]' then
Memo.Assign(Table1Memo)
else
if (Memo[0] = '[Picture]') and (View is TPictureView) then
(View as TPictureView).Picture.Assign(Table1Picture);
end;
OnUserFunction event handler called whenever a function found in expression. Function may takes up to three parameters, which is listed in p1..p3 elements. This is an example of OnUserFunction event handler:
procedure TForm1.Doc1UserFunction(const name: string;
p1, p2, p3: Variant;
var val: string);
var d:do
uble;
begin
if name <> 'MYCOOLFUNCTION' then
exit;
d := Parser.Calc(p1);
// for Parser using you should use FR_Pars.pas module
if d > 10000 then
val := '''' + FormatFloat('#,##0.00',d) + ' - wow!' + ''''
else
val := '''' + FormatFloat('#,##0.00',d) + '''';
// result is the _formatted_ string, so surround it by quotes
end;
Parser may be used independently of FR. For use parser, add FR_Pars to your 'uses' clause.
Parser operates with math and logical expressions, strings operations. It supports external variables and functions. It has two properties for event handlers - OnGetValue and OnGetFunction, identical to TfrReport events. Parser has the following built-in functions: INT, FRAC, ROUND, STR, MOD, COPY, IF. Functions are identical to Pascal functions. STR converts value to the string. IF (syntax is IF(condition, string1, string2)) returns string1, if condition is True;
otherwise, returns string2.
Parser uses 1 and 0 instead of True and False.
4.2. PROPERTIES AND METHODS.
All the functionality is within TfrReport component. There is most important methods and properties:
// load/save methods
procedure LoadFromStream(Stream: TStream);
procedure SaveToStream(Stream: TStream);
procedure LoadFromFile(FName: String);
procedure SaveToFile(FName: String);
procedure LoadFromDB(Table: TTable;
DocN: Integer);
procedure SaveToDB(Table: TTable;
DocN: Integer);
procedure LoadTemplate(FName: String;
comm: TStrings;
Bmp: TBitmap;
Load: Boolean);
procedure SaveTemplate(FName: String;
comm: TStrings;
Bmp: TBitmap);
procedure LoadPreparedReport(FName: String);
procedure SavePreparedReport(FName: String);
Group of the methods is intended for loading/saving of the report
(LoadFromStream, SaveToStream, LoadFromFile, SaveToFile, LoadFromDB, SaveToDB),
report template (LoadTemplate, SaveTemplate) and prepared report (LoadPreparedReport, SavePreparedReport). Methods LoadFromDB, SaveToDB loads/saves report form into the DB table.
Structure of that table is simply - the first field is integer (it stores ID of the report), and the second is BLOB (it stores report form).
// report manipulation methods
procedure DesignReport;
Starts designer.
function PrepareReport: Boolean;
Starts report building. If user terminates the process, returns False.
procedure ExportTo(Filter:TClass;
FileName:String);
Exports report to the file, using export filter. For example, ExportTo(TTextExportFilter,'1.txt');
procedure ShowReport;
Builds report and shows preview.
procedure ShowPreparedReport;
Shows preview, assuming that report was builded by PrepareReport function or loaded by LoadPreparedReport method.
procedure PrintPreparedReport(FromPage,ToPage,n:Integer;
Collate:Boolean);
Prints previously created (or loaded) report.
property Title: String;
Report title. Shown in the progress window, preview and in printer's job title.
property Onbegin
Doc;
Event called at the report starting.
property OnEndDoc;
Event called after report builded.
property Onbegin
Page: procedure(pg:Integer;
MasterMemo,DetailMemo,
SubDetailMemo:TStringList);
Event called each time new page started. 'Page' is a page in designer's mode.
property OnEndPage(pg:Integer);
Event called if page builded.
property OnGetValue: procedure(ParName:String;
var ParValue:Variant)
Event called whenever a variable found in object's memo. Event handler takes name of variable (ParName parameter) and must return its value (ParValue parameter).
property OnEnterRect: procedure(Memo: TStringList;
View:TView)
Event handler called each time before object drawing. It most useful for filling object's memo or picture (for "Picture" object). View reference allows to manipulate object properties.
property OnUserFunction: procedure(const name: string;
p1, p2, p3: Variant;
var val: string);
Event handler called whenever a function found in expression. Function may takes up to three parameters, which is listed in p1..p3 elements. Value of the function must be placed in Val parameter.
----------------------------------------------------------------------------
Author Tzyganenko Alexander
FidoNet: 2:5061/70.0
e-mail: Tzyganenko.Alexander@f70.n5061.z2.fidonet.org