Xtreme Report Designer

CV Pro

This guide is only applicable to enterprise clients using CV Pro or CV9.

Introduction

The ClearVantage (CV) Xtreme Report Writer (xR) includes an embedded designer. The designer provides you with all the tools for designing a report’s appearance, along with the ability of simultaneous previewing reports. It contains several toolbars, which can be docked wherever you want.

To give a user the ability to design or edit reports, you need to add the ClearVantage User as an Administrator. They will then be allowed to use the Designer to set the report’s appearance, as well as the ability to edit a finished report.

In the picture, denoted with numbers:

1. Report Design Workspace.

2. Menu Bar.

3. ClearVantage Toolbar.

4. Object Toolbar.

5. Report pages tabs.

6. Report Tree Window.

7. Object Inspector Window.

8. Data Tree Window. You can drag elements onto a report page from this window.

9. Rulers. When dragging a ruler to a report page, the guideline (which objects can be adhered to) appears.

10. Status Line.

Control Keys

Keys	Description
Ctrl + O	“Open…” menu command
Ctrl + S	“Save” menu command
Ctrl + P	“Preview” menu command
Ctrl + Z	“Edit|Undo” menu command
Ctrl + C	“Copy” menu command
Ctrl + V	“Paste” menu command
Ctrl + X	“Cut” menu command
Ctrl + A	“Select all” menu command
Arrow, Tab	Move between objects
Del	Delete of the selected objects
Enter	Call the editor of the selected object
Shift + arrows	Modify sizes of the selected objects
Ctrl + arrows	Move the selected objects

Mouse Control

Operation	Description
Left button	Selecting an object; pasting a new object; moving and resizing objects. For the selected objects, you can perform zooming in and out by dragging the red square in the left bottom corner of the selected objects’ group.
Right button	Selected object's contextual menu.
Double-click	Object editor call. Double-click on the white space of a page to open the “Page Settings” dialog box.
Mouse wheel	Scrolling a report page.
Ctrl + Mouse wheel	Zoom.
Shift + left button	Toggle object's selection.
Ctrl + left button	If you hold the left mouse button during moving a mouse, a frame appears. As soon as you release the mouse button, all the objects captured in the frame would be selected. This operation can also be performed by clicking on the blank space on the page and moving the mouse cursor to the required position.
Alt + left button	If the Text Object is selected, it edits its contents in place.

CV Xtreme Report Writer Administration

To grant user permissions for Xtreme Report Writer Administration, click on the “Administration” drop-down menu on the toolbar of ClearVantage’s home screen and select “Users”. Click on the user’s User ID to open their record and put a checkmark in the box for “Xtreme Report Writer Admin”. If this flag is checked, then the user can create and edit CV Xtreme Reports.

Toolbars

The following Toolbars are used in CV Xtreme Report Writer:

1. Designer Mode Bar

2. Standard Toolbar

3. Text Toolbar

4. CV toolbar

Designer Mode Bar

The bar is integrated on the left-hand side of the page has the following buttons:

Icon	Name	Description
Select Tool	A standard mode of operation, in which a cursor allows to select objects, modify their sizes, etc.
Hand Tool	Clicking on this icon allows dragging a report page.
Zoom	Clicking the left mouse button doubles the zoom (adds 100%), while clicking the right mouse button zooms out by 100%. When holding the left mouse button while dragging, the selected area is zoomed.
Text Editor	Clicking on the Text Object allows editing on the report page. If you hold the left mouse button when moving the cursor, the Text Object appears in the selected place, and then its editor launches.
Format Copying	The button becomes enabled when the Text Object is selected. When clicking on the Text Object with the left button, it copies formatting, from the previously selected Text Object, into the object.

"Standard" Toolbar

The following toolbar will provide options basic report functions such as saving, opening, zooming, etc.:

Icon	Name	Description
New Report	Creates a new blank report.
Open Report	Opens an existing report from the file. Hotkeys combination – “Ctrl + O”.
Save Report	Saves a report into the file. Hotkeys combination – “Ctrl + S”.
Preview	Performs report constructing and its previewing. Hotkeys combination – “Ctrl + P”.
New page	Adds a new page into the report.
New Dialogue Page	Adds a new dialog form into the report.
Delete Page	Deletes the current page.
Page Settings	Calls a dialog with page settings.
Cut	Cuts the selected objects into the clipboard. Hotkeys combination – “Ctrl + X”.
Copy	Copies the selected objects into the clipboard. Hotkeys combination – “Ctrl + C”.
Paste	Pastes objects from the clipboard. Hotkeys combination – “Ctrl + V”.
Cancel	Undo the last operation. Hotkeys combination – “Ctrl + Z”.
Repeat	Redo the last cancelled operation. Hotkeys combination – “Ctrl + Y”.
Group	Group objects together.
Ungroup	Ungroup objects from each other.
Show Grid	Shows the grid on the page. Grid pitch can be set in designer options.
Zoom	Sets the zoom amount for the Report Design Workspace.
Align to Grid	Aligns the selected object(s) to the nearest guidelines.
Fit to Grid	Modifies sizes/location of the selected object(s) so that they fit within the nearest guidelines.
Align Left	Aligns the selected object(s) to the left.
Align Middle	Aligns the selected object(s) to the middle.
Align Right	Aligns the selected object(s) to the right.
Align Top	Aligns the selected object(s) to the top.
Align Center	Aligns the selected object(s) to the center.
Align Bottom	Aligns the selected object(s) to the bottom.
Space Horizontally	Spaces selected object(s) out to fill the space horizontally.
Space Vertically	Spaces selected object(s) out to fill the space vertically.
Center Horizontally in Band	Centers the selected object(s) horizontally within the band.
Center Vertically in Band	Centers the selected object(s) vertically within the band.
Same Width	Sets selected object(s) to be the same width.
Same Height	Sets selected object(s) to be the same height.

"Text" Toolbar

The following toolbar will provide options or working with text:

Icon	Name	Description
Style	Allows you to select a style.
Font	Allows you to select a font name from the drop-down list.
Font size	Allows to select font size from the drop-down list. Size can also be entered manually.
Bold	Enables/disables font bolding.
Italic	Enables/disables italics.
Underline	Enables/disables font underlining.
Font	Displays Font Settings dialog box.
Font color	Selects font color from the drop-down list.
Highlighting	Shows the dialog box with highlighting attributes for the selected text object.
Text rotation	Allows you rotate the selected text.
Left alignment	Enables left alignment of text.
Center alignment	Enables center alignment of text.
Right alignment	Enables right alignment of text.
Justify by width	Enables text justifying by width.
Top alignment	Enables top alignment of text.
Height alignment	Enables height alignment of text.
Bottom alignment	Enables bottom alignment of text.

“Frame” Toolbar

The following toolbar will provide tools for styling the frame around an object such as a text box:

Icon	Description	Description
Top line	Enables/disables top frame line.
Bottom line	Enables/disables bottom frame line.
Left line	Enables/disables left frame line.
Right line	Enables/disables right frame line.
All lines	Enables all frame lines.
No lines	Disables all frame lines.
Edit Frame	Displays Frame Editor dialog box.
Background color	Selects background color from the drop-down list.
Shadow	Enables/disables shadow.
Frame color	Selects line color from the drop-down list.
Frame style	Selects line style from the drop-down list.
Frame width	Selects line width from the drop-down list.

"CV" Toolbar

The following options are available through the CV Toolbar:

1. Variables – Control the variables that are defined

   

2. Save As – Save current report as

3. Import – Import a saved report

4. Export – Export the current report

5. Restore Layout – Restore menus to original settings

NOTE: “Restore Layout” works incrementally so you may need to click it multiple times to fully restore the layout.

Creating Your First Report

The following tutorial will walk you through setting up your first report. You will learn how to create a basic report, add images, and use columns and headers to group and organize your report. Additional advanced CV Xtreme Report Writer techniques and tools are discussed later in the documentation.

New reports can be created within CV Pro by selecting the “Pro Tools” button on the home screen and then clicking on “Information Central”. From information central, you can select “Add Report” to add a new report, or select an existing report and click “Report Properties” or “Design Report” to edit the report.

NOTE: Information Central is not available in CV Online.

My First Report

Clicking “Add Report” will launch the Report Settings Dialogue box.

Field	Required?	Description
Report Type	Required	Must select “xTreme” for all xTreme reports.
Report Title	Required	Enter a brief, but descriptive, title for the report.
Description	Optional	Enter a description of what the report does.
Display option	Required	Formatted – Report will display with any formatting that has been configured during the report design. Data Only – Automatically exports the report data to an Excel spreadsheet with no formatting. Formatted and Data – Will prompt the user when running the report whether they want the Formatted or Data Only version.
Access Location	Required	Determines where the report will be visible within CV. Reports Menu – Makes the report visible in the “Report” drop-down on CV’s home screen. Selecting this will display a drop-down menu where you must select which sub-section the report will be displayed under. List/Notebook Report – Makes the report visible in a list or notebook. Selecting this will display a drop-down menu where you must select which list or notebook should contain the report.
Company CD	Required	If this option is available, it is required. Determines what company is able to view the report. If multiple companies need access to the report, separate instances of the report will need to be created for each company (can be done using the export/import tool).
View as Native Report	Optional	Usually not necessary. Only required if the report has extremely complicated functionality. If the report displays an error message when run, try adding this setting to see if it resolves it.
Available in Browser	Optional	Determines whether the report is visible in CV Online. Without this checked, the report will only be visible in CV Pro.
Add for ALL Users	Optional	Makes the report visible to all users.
Add User	Required	Makes the report visible to a specific user. To view the report, your user must be added to this section.
Remove User		Removes selected user so the user is no longer to view the report.

NOTE: You may have to click “Save” before you are able to select “Add for ALL Users” or “Add User”.

Once all report settings have been selected, click “Design” to open the Report Design Workspace. For now, this report will only contain one text inscription, “My First Report”. To do this, click on the “Text” button in the Objects Toolbar. Move the mouse cursor to the desired place on the page and draw a box the size and shape of the desired text box to insert the object.

Generally, the Memo (aka text editor) window will be displayed immediately, but if it does not appear then double-click the object, or right-click and select “Edit”. This is based on an option in Designer Settings (under the View drop-down menu). Enter the text “My First Report” and then click the “OK” button.

The report is now created. To preview it, click the Preview button

the Standard Toolbar or press Ctrl + P. The preview window containing a report page with the “My First Report” text will appear. From the preview window, this report can be printed out, saved to a file (*.fp3), or exported to one of the supported export formats. See section on Report Exports for more information.

Bands in ClearVantage Xtreme Report Writer

Bands are used for logically placing the objects it contains at a location on the output page.  When placing an object in a band, such as “Page Header,” we tell the report engine that the given object must be displayed at the top of each page of a finished report. Similarly, the “Page Footer” band is displayed at the bottom of each page together with all the objects it contains.

Thus, bands are responsible for object positioning in required places. Depending on band type, we can add objects either at the top or at the bottom of the page, on the first page, or on the last one. The basic bands, which we would need in most reports, work in the following way:

• “Page header” band is displayed at the very top of each page.

• “Page footer” band is displayed at the very bottom of each page.

• “Report title” band is displayed at the top of the first page, but below the Page Header band (depending upon the TitleBeforeHeader page property assigned in the Object Inspector Window).

• “Report summary” band is displayed at the very end of a report.

To demonstrate this with an example, we will create a report which contains the “My First Report” text at the top of the page, a current date to the right of it, and a page number at the foot of the page (to the right).

To add these sections, click on the “Insert Band”

and select “Report Title’, “Page Header”, and “Page Footer” from the drop-down menu. If you had any existing bands on the page, they would be moved to make room for these new ones. ClearVantage Xtreme Report Writer designer automatically positions bands on the page, and, as a result, header-bands are positioned at the top, data-bands are in the middle, and footer-bands are at the bottom.

Now let us add some objects. Click on the “Variables” tab in the Data Tree window on the right side of the screen and then click-and-drag the “Date” system variable into the Page Header data band. You could also manually enter the “Date” system variable by add a text box and typing “[Date]”. Then, click-and-drag the “Page” system variable to the Page Footer data band.

When running the report, you will see that the objects in the finished report are allocated on the page in the appropriate position.

Adding Tables, Preset Queries, and Data to a Report

The “ADO Query”

the Object Toolbar on the Data tab of the Report Tree window will allow you to create a query by either using SQL, adding a Preset Query, or through joining tables in the Dast Query Builder which is similar to the CV Report Writer. Add the ADO Query Object by clicking on the “Data” tab, then clicking on the “ADO Query” button, and then clicking on the Report Design Workspace. After adding the ADO Query to the workspace, double-click on the newly added Data Object to access the “Fast Query Builder”. If you know what SQL Query you want to use, you can type directly into the SQL Window and click

Otherwise, click on the ”Query Builder” icon

proceed to the Fast Query Builder.

Within the “Fast Query Builder Designer”, you can join tables and set conditions as needed to create the data in your report. For the purposes of creating a Membership Directory, double-click on the CUSTOMER table from the list on the right. Select the following fields from the Customer table by checking the box next to the field name:

• CustomerCD

• Firstname

• Lastname

• OrgName

• Email

• IsMemberFlg

NOTE: To search for the fields without having to scroll through the list, you can click into the CUSTOMER table and then begin typing the field name of the field for which you are searching.

Now, set Lastname to sort by “Ascending” by selecting “Ascending” from the “Sort” drop-down menu in the Lastname column. Then, set the IsMemberFlg to filter for only values where the flag is set to “Y” by entering “= ‘Y’” in the “Where” column in the “IsMemberFlg” row.

Upon completing your query, click on the  button.

When you return to the Report Design Workspace, you should see the list of fields you selected available to you in the Data Tree window on the Data tab. If your query is correctly written, you will see the list of fields available to you as shown below (note, you might have to click the small arrow to the left of the query’s name to expand the field). If no fields are available through this data tab, please check your query syntax.

Optionally, if you would like to rename your query to make it something more distinctive, click on the query and then change the values in both the “Name” and “UserName” fields in the Object Inspector Window.

Note

Names cannot contain spaces or special characters other than an underscore.

Laying Out Your Report

Return to your Report Design Workspace on the “Page1” tab of the Report Design Tabs and add a “Master Data” band. Then double-click on your “Master Data” band. Attach it to the query you previously created.

Drag the data fields from the Data Tree window, in the Data tab, and place them within the “Master Data” band.

Now that the fields are on the “Master Data” band, you align the fields as needed and add additional properties to your text. Click on

(or press Ctrl + P) to preview your report. This will give you a basic membership report showing all Members in alphabetical order by “Lastname”.

Exploring Xtreme Report Writer Tools, Features, and Objects

The following section will further elaborate on some other tools, techniques, and objects that you will find useful within CV Xtreme Report Writer.

Report Objects

A blank report in ClearVantage Xtreme Report Writer is presented as a blank piece of paper. At any place on the page, a user is able to add objects, which can display different information (such as text and/or graphics), as well as to define the report’s appearance. Let us briefly describe the ClearVantage Xtreme Report Writer objects, which are included in the standard package:

Icon	Name	Description
Select Tool	Normal cursor. Allows user to click on object, toolbars, etc.
Hand Tool	Allows user to click-and-drag anywhere in the Report Design Workspace to scroll the page.
Zoom Tool	Allows user to right-click anywhere in the Report Design Workspace to zoom in and left-click to zoom out.
Edit Text Tool	Allows to click-and-drag to create a new text box.
Copy Format Tool	Allows user to copy formatting from one object to another. Click on the object whose formatting you want to copy, then click the Copy Format Tool, then click on the open that you want to have this formatting.
Insert Band	Allows creation of a band on a design page. A band is an area which has definite behavior according to its type.
Rich Text Object	Displays a formatted text in Rich Text Format (RTF).
Text Object	Displays one or several text lines within the predefined rectangular area.
Picture Object	Displays a graphic file in “BMP,” “JPEG,” “ICO,” “WMF,” or “EMF format.
Subreport Object	Allows inserting an additional report design page inside the basic one.
System Text	Displays service information (date, time, page number, etc), as well as aggregate values.
Cross-tab Object	Used to create tables that consist of rows and columns but where it is now known beforehand how many lines or column the table will possess.
DB Cross-tab Object	Used to create tables that consist of rows and columns but where it is now known beforehand how many lines or column the table will possess and that needs to be connected to the data source.
OLE Object	Used to link or embed objects into the report.
Checkbox Object	Displays a checkbox with either a check or a cross.
Gradient Object	Displays a box with a color gradient.
Chart Object	Displays data in the form of charts of different kinds (circle chart, histogram, and so on).
Table Object	Displays data in the form of a table.
CellularText Object	Displays text so that every character is in its own box in a table.
Object “Map”	Displays a map.
Draw	Objects of “Draw” category represent different geometrical figures (diagonal line, rectangle, rounded rectangle, ellipse, triangle, and diamond).
obCatBarcode	Displays data in the form of barcode (many different types of barcodes are available).

The basic objects that are generally used the most are the “Band” and Text Objects.

The "Text" Toolbar

The Text Toolbar has many features including allowing you to display text, a frame, and fill color. The text can be displayed using any font of any size and style. All the parameters can be set visually, with the help of the toolbars:

Here are some examples of text design:

Now let us look at other features of this basic object. As an example, let us create a new text object and put two lines into it:

This is a very, very, very long text line.

And this is another line, the shorter one.

Let us enable the Select Tool, and then resize the object by selecting the black box in the corner of the text box and dragging it. We see that the object can display not only a single line of text, but several lines as well. Now let us reduce the object width to 5cm. It is obvious that long lines did not find room in the object and therefore were wrapped. This happens due to the Word Wrap object property which is enabled or disabled by left-clicking on the text box and then selecting “Word Wrap”. If it is disabled (either in inspector or in the object context menu), the long lines will be simply cut off.

Now let’s check how the text alignment inside the object works. The alignment buttons are located in the Text Toolbar. They allow the user to set horizontal or vertical text alignment. The “Block Align” button allows the user to align the paragraph on both object edges. To do this, the “Word Wrap” property option must be enabled.

Text can be rotated at any angle within the limit of 360 degrees.

in the Text Toolbar allows you to quickly rotate the text at 0, 45, 90, 180 and 270 degrees. If you wish to rotate the text at any other value, use the “Rotation” field in the Object Inspector Window. When rotating a text, setting values other than 90, 180, 270 the text can exceed bounds of the object, as in our case (see the picture below). Let us increase object height a little, so that the text would fit the object.

The text object properties that are available in the Object Inspector Window are:

Property	Description
AllowExpressions	This property allows to turn on or off the expression handling. It is on by default.
Angle	This property indicates the text rotation, in degrees.
AutoShrink	This property allows to shrink the font size or font width automatically to fit the text.
AutoShrinkMinSize	This property determines the minimum size of a font, or the minimum font width ratio, if the AutoShrink property is used.
AutoWidth	This property allows to calculate the width of object automatically.
Brackets	This property contains a pair of symbols that designate an expression.
BreakTo	With this property you can organize the text flow from one text object to another. For example, we have "A" and "B" text objects. The "A" object contains the long text that does not fit in the object's bounds. You can set the A.BreakTo to B, so the "B" object will display the part of text that does not fit in "A".
Clip	This property determines whether it is necessary to clip a text outside of object's bounds. It is on by default.
Duplicates	This property determines how the repeated values will be printed. Read more about this property in the "Formatting" chapter.
FirstTabOffset	This property determines the offset of the first TAB symbol, in pixels.
FontWidthRatio	Use this property to make the font wider or narrower. By default the property is set to 1. To make the font wider, set the property to value > 1. To make the font narrower, set the property to value between 0 and 1.
HideValue	This property is of string type. It allows to hide values that are equal to the value of this property. Read more about this property in the "Formatting" chapter.
HideZeros	This property allows to hide zero values. Read more about this property in the "Formatting" chapter.
Highlight	This property allows to setup the conditional highlight. Read more about this in the "Formatting" chapter.
HorzAlign, VertAlign	These properties determine the text alignment.
HtmlTags	Allows simple HTML tags in the object's text. Read more about this property in the "HTML tags" chapter.
LineHeight	This property allows to explicitly set the height of a text line. By default it is set to 0, so the default line spacing is used.
NullValue	The text that will be printed instead of a null value. You also need to uncheck the "Convert null values" option in the "Report/Options..." menu.
Padding	This property allows to setup the padding, in pixels.
RightToLeft	This property indicates whether the text should be displayed in right-to-left order.
TabWidth	This property determines the width of the TAB symbol, in pixels.
Text	This property contains the text of the object.
TextFill	This property determines the text fill. Use this property editor to choose between different fill types.
Trimming	This property determines how to trim the text that does not fit inside the object's bounds. It is used only if the "WordWrap" property is set to false.
Underlines	This property allows to display a graphical line after each text line. This property can be used only if the text is top-aligned.
WordWrap	This property determines whether it is necessary to wrap a text by words.
Wysiwyg	This property changes the display mode of the "Text" object to match the screen and the final printout. This mode is also used if you use the justify-align or non-standard line height.

HTML Tags in the Text Object

Text objects do understand some simple HTML tags. Tags can be located inside the text of an object. Tags are disabled by default; to enable them, select the “AllowHTMLTags” checkbox in the Properties tab of the Object Inspector Window. This is the list of supported tags:

Tag	Description
<b>...</b>	Bold text.
<i>...</i>	Text in italic.
<u>...</u>	Underlined text.
<strike>...</strike>	Strikeout text.
<sub>...</sub>	Subscript.
<sup>...</sup>	Superscript.
<font color=...>...</font>	Font color. The color may be either the named color (i.e., DarkGray), or a hexadecimal code in the #RGB format (i.e., #FF8030).

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<sup>2</sup>

A<sub>1</sub> = B<sup>2</sup>

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>

Displaying Expressions with the Help of the Text Object

One of the most important features of this universal object is its ability to display not only a static text, but expressions as well. Expressions are located in the object together with text. Let us examine a simple example of how it can be performed. Put the following line into the object:

Hello, World! Today is [DATE].

Thus, when running the report, we can get something like follows:

Hello, World! Today is 5/25/2022.

If an expression enclosed in square brackets is encountered, ClearVantage Xtreme Report Writer calculates its value and inserts the value into the text (in place of the expression). The Text Object can contain any number of expressions, together with a usual text. Both single variables and expressions can be enclosed in brackets (for example, [1+2*(3+4)]). Any constants, variables, functions, and database fields can be used in expressions.

But what should be done if our object contains square brackets, and we do not want them to be considered as expressions? For example, if we need to display such text as following:

a[1] := 10

ClearVantage Xtreme Report Writer considers [1] as an expression, and displays the following:

a1 := 10

That is not what we want, of course. One of the ways to avoid such a situation is to disable the expression. Just disable the “AllowExpressions” property in the Object Inspector Window, therefore all the expressions in the text will be ignored. In our example, ClearVantage Xtreme Report Writer would then display exactly what we need:

a[1] := 10

Sometimes text is required to contain both an expression and text in square brackets, for example:

a[1] := [myVar]

Disabling of an expression allows us to display square brackets in the required place, but it also disables handling of expression. In this case, ClearVantage Xtreme Report Writer allows you to use another set of symbols to designate the expression. The “ExpressionDelimiters” property in the Object Inspector Window, which is equal to “[,]” by default, is responsible for it. In this case, the user can use angular brackets for the expressions, instead of square ones:

a[1] := <myVar>

The “<,>” value must be set in the “ExpressionDelimiters” property. As you can see, the comma divides opening and closing symbols. There is one limitation however: the opening and closing symbols cannot be similar, so “%,%” will not work. One can set several symbols, for example “<%,%>”, and so our example will look as follows:

a[1] := <%myVar%>

Displaying Database Fields with the Help of the Text Object

The Text Object is able to display data from database, in addition to displaying static text and expressions. We can do this in two ways: by placing a link to the database (DB) field into the object text, or by connecting an object to the required field with the help of the “DataSet” and “DataField” properties. The first way is used when we want to display both field contents and any explanatory statement in the same object. For example:

Contact person: [frxDBDataSet1.“Contact_Person”]

As you can see, special syntax is used for links to the database field: datasetname.“fieldname”. The field name (as well as the set name) can contain spaces. However, spaces between the “point” and “quote” symbols are not permitted.

Not only can a link to a field can be placed in the text of the object, but we can also apply different computing operations to a field as well:

Length (cm): [<frxDBDataSet1.“Length_in”> * 2.54]

Note how square and angle brackets have been used. Remember that square brackets are used by default for delimiting expressions, which are included in the object’s text. In case of need, square brackets can be replaced by a pair of any other opening/closing sequences (see the “Displaying Expressions with the Help of the Text Object” section above). Angular brackets are used inside expressions for marking out the ClearVantage Xtreme Report Writer variables or database fields. To be logical, we should write:

Contact person: [<frxDBDataSet1.“Contact_Person”>]

Instead of:

Contact person: [frxDBDataSet1.“Contact_Person”]

Nevertheless, both these notations are correct, since ClearVantage Xtreme Report Writer allows for the absence of angular brackets, in case an expression contains only one variable or only one database field. However, if an expression contains several variable fields, the brackets are necessary:

Length (cm): [<frxDBDataSet1.“Length_in”> * 2.54]

Data Bands

Now, we are about to learn how to print the data from database (DB) tables or queries. In this case, a table or query is a set of lines (records/rows), each of which has a certain number of columns (fields). To print information of this kind, ClearVantage Xtreme Report Writer uses a special type of band (Data Bands). These are bands with names of “[data level type] Band” (i.e., “Master Data”, “Detail Data”, etc.). To print a whole table or some of its fields, you must add these band(s) to the report, connect it to the table, and add to it the objects with the fields you want to be printed out. When ClearVantage Xtreme Report Writer builds these bands, they will be printed on the output page as many times as there are records in the table.  If there is no free space left on the output page, new output pages will be formed as needed by the report engine.

Picture Object

The next object to examine is the Picture Object. It is also frequently used in reports. With the aid of this object, you can insert a logo, a photo of an employee, or any other graphical information. The object is able to display graphics in “BMP”, “JPEG”, “PNG”, “ICO”, “WMF”, and “EMF” formats.

Let’s examine the capabilities of the object. Create a blank report and place a Picture Object on the report page. In the object editor (if it does not open automatically, then double-click on the object). Load any desired picture and click “OK.” You can load a picture from a file or clear an existing picture by clicking on the eraser button.

The text object properties that are available in the Object Inspector Window are:

Property	Description
AutoSize	The object gets the size of the picture. Disabled by default.
Center	The picture is centered inside the object.
KeepAspectRatio	Stops the picture from distorting when the object’s sizes are modified. Enabled by default.
Stretched	The picture is stretched to the size of the object. Enabled by default.
Hyperlink	You can put a filename (c:\picture.bmp) or variable containing a filename ([picture_file]) to this property. The picture will be loaded from given filename when you run a report.

The “KeepAspectRatio” option works only together with the “Stretch” option. Therefore, when applying any object dimensions, a drawn circle will remain a circle, without turning into an oval. The stretched picture then occupies only the part of the internal space of the object needed to display it using correct ratios. If the option is disabled, a picture will be stretched to fill the object size, and if object’s size does not correspond to the initial dimensions of the picture, it will be distorted.

Linking to an Image in ClearVantage

When linking to the CV Image table, you need to first construct a query object that will link the picture to the customer that it is displaying for:

Next, link the image being used in the Master Data band properly to the query:

On the Report Tree Window, open the query being used to on the CUSTIMAGE table and add CUSTOMERCD as a parameter after clicking on the button.

If an image exists within the CV Image table for the Customer, an image will appear.

Linking to a Notebook in CV

A PrimaryKey value can be used to pull a “Notebook” on a report and can be made to look like a hyperlink setting its Font-color(blue) and Font-style(underline) property.

To do this, click on the Primary Key Value (Customer CD, Org CD, Invoice Num, etc.) on the Page Layout, click on “Events” tab at the top of the Object Inspector Window, then double-click “OnPreviewClick” drop-down option to see the code.

The cursor will be placed between a 'begin' and 'end' statement, enter the following statements to call the Notebook function. Functions with ParamType of “String” can be called as: OpenEventNB(Trim(TfrxMemoView(Sender).Text)); Functions with ParamType of “Integer” can be called as: OpenOrgNB(StrToInt(Trim(TfrxMemoView(Sender).Text)));

Additional function syntax can be found on the “Functions” tab of the right-hand Data Tree Window:

Multi-Lined Text Displaying

The Text Object can automatically set its height and width to find room for its contents. One can use the “AutoWidth” and “StretchMode” properties for this. The “AutoWidth” property allows the Text Object width to vary so that all the lines find room without division of words. This mode is useful when an object has a single text line and growing to the right will not affect other objects.

The “Stretch” property lets the object’s height grow to accommodate the text, without changing the objects width. This property has several modes which you can choose from in the Object Inspector Window:

• smDontStretch – Do not stretch an object, by default.

• smActualHeight – Stretch an object to find room for the whole text.

• smMaxHeight – Stretch an object so that its bottom would coincide with the bottom of the band in which the object is placed. We will examine this mode in the section on displaying data in a table.

The report shown below demonstrates the “Stretch” property of the Text Object. Enable it in the object context menu or set the “StretchMode” value to “smActualHeight”. Also, enable the “Stretch” band property by clicking on the data band and updating the property. Preview the report and make sure that everything works as expected.

As you can see, when constructing a report, ClearVantage Xtreme Report Writer fills objects with data, stretches them with the “Stretch” option enabled, and then computes the band’s height to find room for all the objects. If the band “Stretch” option is disabled, the height setting is not performed, and the band is displayed according to height specified in the designer. If we disable this option, objects with longer texts are still stretched, although the band is not. This leads to text overlaying, since each next band is displayed right after the previous one.

Data Splitting

Let us pay attention to a peculiarity of this report: There is a lot of blank space at bottom of the pages. Why does it happen? When a report is constructed, the ClearVantage Xtreme Report Writer core fills whitespace of the page with bands. After displaying each band, the current position shifts down. When the report writer finds out that there is not enough space to display the next band (its height is larger than white space left on the page), then a new page is formed and band displaying continues there. This operation continues being performed as many times as there are records in the dataset.

Our report contains an object with large text, and that is why the band height is rather large. Furthermore, if a large band does not find room on a page, it is transferred to the next one, and much unused space remains at the bottom of the page. This is shown at the following illustration:

To limit paper wastage, let us use a ClearVantage Xtreme Report Writer feature which splits the band’s contents in a way similar to splitting paragraphs. Enable the “AllowSplit” option of the “First level data” band and you will see that there is less white space at the bottom of report pages:

Only some objects in ClearVantage Xtreme Report Writer (i.e., Text, Line, and RichEdit) support this feature. When the report writer comes across the need to split a band, it performs it in the following way:

• Displays the non-splitable objects, which find room on white space.

• Partially displays splitable objects (text objects are displayed in a way that all lines find room in the object).

• Forms a new page and continues object displaying.

• If a non-splitable object does not find room on whitespace, it is transferred to the next page; at the same time, all the objects located underneath, are shifted according to need.

• The process continues until all the band objects are fully displayed.

The splitting algorithm will become clearer if to look at the illustration:

It should be noted that the splitting algorithm is not perfect, and quality of the output report may not be as expected. You should use this option very carefully in cases when objects on the split band are grouped in a complicated way, and/or their font sizes differ. Here is the example of what could be received:

Text Wrap of Objects

For report designing, in some cases it becomes necessary to wrap text around other objects (often, when using pictures). Let us demonstrate this ClearVantage Xtreme Report Writer feature with our current example.

Add one more Text Object to databand below the “Bio.Notes” object, as shown in the following illustration:

We will disable stretching for the “Bio.Notes” object. We will enable this property for the bottom object. To make the text “flow” from the “Bio.Notes” object to the bottom one, set the “FlowTo” property of the “Bio.Notes” object. This property is set in the Object Inspector Window and is of the “drop list” type. The bottom object’s name must be selected from this list. The result will look like the following illustration:

When constructing a report, if the text does not find room in the top object, the part which does not fit the object will be transferred to the bottom object. Since the objects are located around the picture, the effect of text wrapping is performed.

NOTE: The main object should be inserted in the report before inserting the linked one, otherwise the text wrapping may function incorrectly. If your report operates incorrectly, select the linked object, and then transfer it to the forefront by right-clicking on it and selecting the “Bring to Front” menu command.

Displaying Data in the Form of a Table

Sometimes it is necessary to display a report in the form of a table with a frame. One example of such a report is a price list. To build such report in ClearVantage Xtreme Report Writer, a user just needs to enable framing function for the objects located in the “Data” band. Let us demonstrate several types of frames with a test report example.

Let us create a report of the following kind:

Place the Text Objects on the band side-by-side, and minimize band’s height.

The first and the simplest type of the table is a table with a full frame. To do this, one needs to enable all frame lines in every object:

The next type of framing would display only horizontal or only vertical lines. Such framing is performed in the same way. Horizontal or vertical frames can be enabled in objects.

Finally, to show only the external framing, the report needs to be slightly modified:

As you can see, we have added two Text Objects: one in “PageHeader” and one in “ReportSummary” bands and enabled frame lines for the objects along the edges of the data-band. As a result, the report will look as follows:

All examples we have covered contained bands with fixed sizes. But how is it possible to display a table where the band is stretched? Let us explain using the example below. Add a new field (a multi-lined text from “Bio.Notes”) to our report. As you already learned, the “Stretch” property must be enabled both for this object and for the band in which the object is located. In this case, the band height is sized depending on size of the text in the Text Object. Thus, we would output a report which appears like this:

This is a little bit different from what we need; one would prefer the frames of the neighboring objects to be able to stretch as well. ClearVantage Xtreme Report Writer allows one to solve this problem easily. For constructing such reports, it is enough to enable the “Stretch downwards” property (or “StretchMode” of “smMaxHeight” in the Object Inspector Window) for all objects which are to be stretched. Thus, the ClearVantage Xtreme Report Writer core first calculates the maximum band height, then it stretches objects with the enabled option to the bottom band edge. Since object frames stretch together with the object, the report’s appearance changes:

Using Group Headers and Columns in Your Report

Additional formatting can be used to create an entirely different look and feel for the report. For the purposes of this next report, add an additional filter on any STATECD, and add a sort by CITY.

Returning to the layout page of your report, set “Columns” to “3” under the “Properties” tab of the Object Inspector Window. This will create three columns in your report.

Add a “GroupHeader” band and place it above your Master Data band. Link this to your query used to generate your report and select a value to filter on. Additional options are also provided as shown below.

The report is now set to group based on the “GroupHeader” set above. Information will now appear across three columns.

Previewing this report will display the data across 3 columns.

Child Bands

To add additional spacing considerations to a report, you may want to use a “Child” band to further organize your data. “Child” bands should always be places after the “MasterData” band.

It is important to link the “MasterData” band to the “Child’ band by setting its “Child” property in the Object Inspector Window. Now, each time the “MasterData” band prints, the “Child” band will be printed immediately afterward:

As you can see, now the title is typed exactly where it is supposed to be. To avoid ‘Child” bands transferring to the next page (which basically means, it will be widowed from the parent band), enable the “KeepChild” property for the parent band in the Object Inspector Window.

Shifting Objects

You have already seen how the “Shift” property works. Let us look at the next mode of shifting: “Shift When Overlapped”. In the Object Inspector Window, the “ShiftMode” of “smWhenOverlapped” property value corresponds to this mode. Object shifting will be performed in cases when the object from above overlaps the given object during stretching. Three cases are shown in the illustration below. As you see, the bottom object with the enabled “Shift When Overlapped” option shifts only in the latter case (i.e., when there is too much text in the top object and it overlaps the bottom one).

If the “Shift” option is enabled, the bottom object will be shifted anyway:

This allows one to create rather complicated report outputs, by using the logic of the object’s design properties, especially if an object overlaps several other objects at the same time. Thus, in the following example both upper objects contain stretchable texts, and the bottom one has the enabled “Shift When Overlapped” option. The bottom object will always be displayed closely to the object, which contains more text, irrespective of text size in the upper objects:

In this example, if the “Shift” option is enabled for this object, the bottom object will shift twice, since it is located underneath two objects and thus an unnecessary gap is formed.

Report With Two Data Levels (Master-Detail)

So far our example reports have used only one data-band, (“First level data” or “MasterData”), to control report output. This enabled output of data from one DB table. ClearVantage Xtreme Report Writer allows one to design report layouts having up to six data levels, on one design page.  (It is possible to have more data levels by using the Subreport Object. This feature will be covered later). Generally, most reports are limited to 1-3 data levels with large numbers of data levels being rare.

Let us examine the two data level report design process. It will output data from the demo tables: “Customer” and “Invoice.” The first table is the list of clients; the second one is the list of outstanding Invoices that members have. The tables contain data in the following fields:

In the report designer, we’ll connect our data sources to the Customers table and to an Invoice Query. Now add a “Master data” and “Detail data” bands on the page:

Note that the “Master Data” band must be placed above the “Detail Data” band! If placed under it, ClearVantage Xtreme Report Writer will generate an error message when you preview the report.

If you previewed the report now, you would see that the list of invoices remains the same for each customer and contains all records from the “Invoice” table. This happens because we did not set the mastersource property of the “Invoice” table. Set the “MasterSource = Customers” property in the “Table2” component on the Page Designer. Now, we have set a “master-detail” connection.

We need to link together two “CUSTOMERCD” fields in both sources. To perform this, select the desired fields, and then click on “Add” button. Fields linkage will appear in the bottom pane. After that, close the editor.

When previewing a report, ClearVantage Xtreme Report Writer does the following. After outputting a record from the master table (Customer), it will set the filter on the detail table (Orders). Only those records, which match the “INVOICE.SHIPTOCD = CUSTOMER.CUSTOMERCD” condition will remain in the table. That means that for each customer only those orders which belong to the current customer will be displayed in the detail band. Note this is an important concept to grasp. Even though databands may be of master or detail type, they only control where the data appears on the output page (order and no of times of appearance). What data their objects display is dependant upon which fields the objects contain and the external tables relationship linkage.

The illustration below shows the new output appearance.

Reports, containing up to 6 data levels can be constructed in the similar way.

Headers and Footers of a Data Band

Each data band may have header and footer. Headers are output before a data band; footers are output after all data records are output. Here is an example of how the headers/footers working in case of simple report:

Let's look at more complex example using two data levels - master-detail:

As we can see the header is output before all data-band records. Thus, master data header is printed once at the beginning of a report, detail data header is output before each group of detail bands belonging to the current master record band. The detail footer is output after the group of detail bands belonging to the master record band, the Master footer is not output until after all the master databand records.

Using the FooterAfterEach property of the data band, we may override this behavior. Setting this property to True (you may also use context menu of the data band, “Footer after each row” item) will cause the footer to output after each data row. It may be useful in some cases when designing master-detail reports. The previous example with FooterAfterEach property of the master data set to True will appear this way:

Multipage Reports

ClearVantage Xtreme Report Writer reports can consist of several design pages. You can adjust such parameters as size and orientation for each page, as well as to place different objects and bands on it. When outputting this type of report, all bands from the first design page will be displayed, then the bands from the second one, etc.

When you create a new report in the designer, it already contains one page by default. You can add a new page by clicking on

in the toolbar. Then you would see that a new page tab appears in the designer:

One can easily switch between pages by clicking on the required page tab. Page tabs can be dragged (“drag&drop”), to easily modify their order. An unnecessary page can be deleted using

in the toolbar or by selecting the “Edit|Delete page” menu command. One can also call the context menu by right-clicking on the page tab:

The number of design pages in a report is unlimited. As a rule, additional pages are used either for previewing title pages, or in more complicated reports, those which contain data from many sources.

A simple example of title page creation. Let us use our previous report with one data level. Add a new page to it, this will be the second page. To move it to the front of the report, grab the page tab using the mouse, and then drag it to the place near the first page. At that, the pages order will be changed. Switch to the new page and place a Text Object (with the “Our report” text inside) in the middle of the page. That is all we need to do. The report with a title page is finished:

It is necessary to pay attention to one feature of multipage reports. If the “Print to previous page” option is enabled in the second page (use the “PrintToPreviousPage” property in the Object Inspector Window), then the second page objects will start printing not on a new output page, but on the white space of the previous one. This allows to print the pages’ contents “line-to-line.”

RowCount and PageCount Properties

Sometimes you need to show static data several times. As an example, we can look at printing “Clean” business cards or post cards. For this, data bands have the property “RowCount”, and Report page has the property got “PageCount”.

These properties set the needed quantity of bands/pages repeating without being attached to the data.

The figure below shows an example of this. Bands’ RowCount property is equal to 14, which makes the bands repeatedly show 14 times.

Groups and Aggregates

The following section will further elaborate on creating groups and aggregates within CV Xtreme Report Writer.

Report with Groups

In another example we constructed a two-leveled report based on the data from two tables. ClearVantage Xtreme Report Writer also allows designing of reports which appear the same, based on one set of data, the result of a joined query.

To perform this, one needs to create a query using SQL, which would return data arranged according to a certain condition from both tables. In our case, a condition will be the value of the “CUSTOMERCD” fields in both tables. A SQL query may look as follows:

select * from dbo.INVOICE d

where d.balancedue > '0'

order by INVOICE.PAYEENAME, INVOICE.INVOICEDATE asc

The “order by” line is needed to sort the records on the “PAYEENAME and INVOICEDATE” fields.

How can a multi-leveled report be constructed based on this data? In ClearVantage Xtreme Report Writer there is a special band – “Group Header”. A special condition is established for the band (DB field value or an expression); the band is output every time the field's value is changed. The following example illustrates this.

Let us open the designer and connect our data source to the report. After that, add the “Group header” and “Master data” bands to the report. Set a condition (in this case, it is “Group.PAYEENAME” data field) in the “Group header” band editor:

Let us link the data-band to the “Group” data source and place the objects in the following way (note, that the group header must be placed above the data-band):

On previewing, we would see a report similar to the one shown below:

As you can see, the “Group header” band is output only when the field, to which it is associated, changes its value. Otherwise, the data-band connected to the group is displayed. If compare this report to the master-detail report, which we constructed earlier, it should be obvious that the report is sorted by Payee Name/Invoice Date. This is easily corrected by changing the SQL query’s order by clause text to include the desired field.

Similarly, reports with nested groups can be constructed. The number of nested groups is unlimited in such reports. Reports using groups, have some advantages over reports of the master-detail type:

• the whole report needs only one dataset (query).

• the number of the data grouping levels is unlimited.

• the additional data sorting feature.

• more optimal usage of the DB resources (the query returns only one dataset, which can be output, without having to filter the data).

Other Group Features

When looking at the printout of the report, it is unclear which client the list of orders on the very top of the second page refers to. ClearVantage Xtreme Report Writer allows repeating the group header output (which in our case contains information about the client) on the next page. To perform this, the “Reprint on new page” menu item (or the “ReprintOnNewPage” property in the Object Inspector Window) should be enabled in the “Group header” band.

There is another way, which allows one to avoid breaking of groups. This is the “Keep together” group header property (or “KeepTogether” context menu). When this is enabled, if the whole group does not find room on the output page, it is transferred to a new page.

Thus, much blank space may appear on several pages, but the group will be displayed as a whole on the page if possible.

In conclusion, the “StartNewPage” group header property allows output of each group on a separate page. This probably will lead to a waste of paper; however it might be useful in some cases.

Reset Page Numbers

Group has a “ResetPageNumbers” property which allows us to reset page numbers when printing a group. This is used when the report is actually distributed as separate documents.

For example, you have created the report with groups. In the group header, you have the customer name inside the group - customer's orders. Now you need to print a report and send it to customers (each customer should get only its own pages of report). Unfortunately, the page numbering in such report is continuous. Some customers may get the pages with numbers 50, 51, 52 (which might lead them to ask where is the first 49 pages). To avoid that situation, you have to give a number to each customer's document separately. Inside one report you will have pages with their own numbering for each group.

Pay attention to the following: if you set ResetPageNumbers property to True, you also should set the StartNewPage property to “True”. Thus, each group will start a new page. To print a page number or total pages, you may use [Page], [TotalPages] system variables.

Drill-Down Groups

The group header has a property called DrillDown. If you set it to “True”, the group becomes interactive. This means you can click on the group header in the preview window. The group will expand (display all group records) or collapse (display only header and footer, if ShowFooterIfDrillDown is “True”).

Here is an example of such group with one expanded header:

You can control whether to display all groups collapsed or expanded when you run a report first time. By default, all groups are collapsed. You can set ExpandDrillDown property to “True“ if you want it expanded. You can also use the preview window's context menu to expand or collapse all groups.

Lines Numbering

Let us use our example in order to show how to number lines in the group. To do this, add a Text Object with a system variable [Line] to both of our bands (it is easier to perform this using the drag&drop method from the “Variables” page tab of the “Data Tree” tool window).

When previewing the report, we can see that both the data levels now have their line numbers:

For continuous numbering of the second level data, we use the “Line#” variable instead of “Line” in the text object on the data-band. The result will then appear as below:

Aggregate Functions

In most cases, group reports need to display some summary result information (such as: “total of a group,” “number of group elements,” etc). ClearVantage Xtreme Report Writer provides these aggregate functions this purpose. With their use, one can retrieve the defined aggregate value over a data span. The list of aggregate functions:

• SUM – Returns the total of the expression

• MIN – Returns the minimal value of the expression

• MAX – Returns the maximal value of the expression

• AVG – Returns the average value of the expression

• COUNT – Returns the number of lines (rows) in the data span

The syntax of all aggregate functions (except COUNT) is as shown below, using an example of the “SUM” function:

• SUM(expression, band, flags)

• SUM(expression, band)

• SUM(expression)

The parameters assignment is as follows:

• Expression – the expression, the value of which will be handled

• Band – the name of data band, on which the value(s) to be handled originally reside

• Flags – a bit field, which can be the following values or their sum

• Include invisible bands in calculation

• Accumulate the value or running total (do not reset the result value when the current data span resets)

An expression is the only mandatory parameter; all the rest are optional. Nevertheless, it is recommended to always use band parameters, to avoid mistakes.

The “COUNT” function has the following syntax:

• COUNT(band, flags)

• COUNT(band)

The parameters assignment is similar to the one described above.

There is a general rule for all aggregate functions: a function can be counted only for the data-band and used only in that band’s footer (the following bands refer to the latter: footer, page footer, group footer, column footer, and report footer( summary band) ).

How do aggregate functions work? We will examine it using our group report example. Let us add some new elements to the report:

The Group “ItemsTotal” field on the data-band will display the current order total. Place a Text Object in the group footer containing the aggregate SUM call, as shown above. It will display the total of all orders placed by the given client when previewed.  Using a calculator, we can check to make sure that everything works as expected:

So, how do the aggregate functions work? Before outputting a report, ClearVantage Xtreme Report Writer scans the Text Objects’ contents in order to find the aggregate functions. The functions found will be associated to the corresponding data-bands (in our example, the “SUM” function is associated with the “MasterData1” band). During outputting of a report (when the data-band is displayed) the value of the aggregate functions linked to it is counted. In our case, the “Group.”ItemsTotal”“ field’s values are accumulated. After outputting a group footer (the one where the accumulated value of the aggregate function is displayed) the function value is reset, and the cycle is repeated for the next groups.

The purpose of the optional “Flags” parameter in the aggregate functions. In some reports, some of data-bands (or all of them) may be hidden, however, we may need to result value which considers all data-bands, visible or not. In our example, set the “Visible” property of the data-band to false; after that it will stop displaying. To count a total on the hidden data-band, we add the optional parameter to the function call:

[SUM(<Group.”ItemsTotal”>,MasterData1,1)]

It will give us a report, which would look as follows:

When the “Flag parameter” value = 2,  the accumulated value will not be reset  right after it is displayed. The result will become a “running total” on each successive output. Let’s modify the call of the function as shown below:

[SUM(<Group.”ItemsTotal”>,MasterData1,3)]

The “3” value is a bit combination of “1” and “2,” which means that we need to take into consideration the invisible bands without resetting the total. As a result, we have:

Page and Report Totals

Quite often, one needs to display summary total values of a page or a whole report. We can use the aggregate functions in this situation as well. We will show this by making some changes to our example.

As you can see, we added the “Report Summary” band and a Text Object with the aggregate sum to the “Report Summary” and the “Page Footer” bands.

Inserting Aggregate Function

So far, we have inserted the aggregate functions into the Text Object manually. Now we will look at other ways to insert aggregate functions.

First, we can use the System Text Object for output of the aggregate function value. As a matter of fact, it is the same Text Object, but one that has a special editor for easier insertion of system variables or aggregate functions.

You should step by step select a function type, a data-band (according to which it will be counted), and a database field or an expression, the value of which will be computed. You can also set the “Count invisible bands” and “Running totals” flags.

The second way is to use the Text Object and

in its editor, to invoke the additional window, similar to the System Text Object Editor. When clicking the “OK” button, the call of the aggregate function is inserted into the object's text.

Formatting and Highlighting

The following section will explain how to best format and highlight data displayed within CV Xtreme Report Writer.

Formatting of Values

A peculiarity of the numerical values aggregate functions is that they are not formatted. It should be evident, when referring to the first example with the “SUM” function:

This happens because, as a rule, the data fields return a formatted value, which is simply displayed by the Text Object, with no changes applied. To apply formatting to the “SUM” function result, let us use the value formatting tools of ClearVantage Xtreme Report Writer.

Select the object with the sum and call its context menu. The format editor is called either by using the “Formatting...” menu command, or with the “DisplayFormat” property editor in the Object Inspector Window.

Here you can see, the list of formatting categories on the right and the list of the available category formats on the left. We will select the “Number” category, and the “$1,234.50” format. The format string corresponding to the selected format and the decimal separator character will be displayed based on your Windows regional settings

After clicking

and previewing the report, you will see that the sum total in the report is now formatted correctly:

Inline Formatting

In the example, formatting was applied to the object and any expression located in the object. Everything worked correctly because there was only one expression in each object. However, if we have multiple expressions that require different formatting, we can use inline formatting.

Using the example, resize the footer, its object and the objects text as shown below.

*Total: [SUM(<Group.”ItemsTotal”>,MasterData1)] *

Number: [COUNT(MasterData1)]

The total and number of orders will display in the object.

When previewing, both values are presented in monetary format (which we had previously set), which is incorrect:

To display each value correctly, they should be formatted individually. To accomplish this, we use format tags. They are added before the closing square bracket of the expression. For our example, disable the object formatting (select the “Text (without formatting)” category in the format editor). Now we need to modify the format of the first variable, since the second will be displayed correctly (without formatting, i.e., as an integer). Modify the object text in the following way:

*Sum: [SUM(<Group.”ItemsTotal”>,MasterData1) #n%2,2m] *

Number: [COUNT(MasterData1)]

Preview, to make sure that the object displays correctly:

When using format tags, the general syntax is as follows:

[expression #tag]

Note that space between the expression and the “#” sign is mandatory! The tag itself might look as follows:

• #nFormattingLine – the numerical format

• #dFormattingLine – date/time format

• #bFalse,True – boolean format

“FormattingLine” in every case is the argument to the function, by which formatting is accomplished. Below are several values used in ClearVantage Xtreme Report Writer:

For the numerical formatting:

• %g – a number with the minimal signs number after decimal point

• %2.2f – a number with the fixed number of signs after decimal point

• %2.2n – a number with bits delimiter

• %2.2m – a monetary format, accepted in the Windows OS, depending on the regional settings in the control panel

For the date/time format:

• dd.mm.yyyy – date of the 23.12.2003 type

• dd mmm yyyy – date of the 23 Nov. 2003 type

• dd mmmm yyyy – date of the 23 November 2003 type

• hh:mm – time of the 23:12 type

• hh:mm:ss – time of the 23:12:00 type

• dd mmmm yyyy, hh:mm – time and date of the 23 November 2003, 23:12 type

It is acceptable to use a comma or dash instead of period in the line for the numerical format. This symbol will be used as a separator between the integer and the fractional parts of the value. Usage of other separators is not acceptable.

Formatting of the “#b” type (Boolean), the formatting line is presented as two values separated by comma. The first value corresponds to “False,” the second one corresponds to “True.”

To avoid the necessity to memorize all these tags and their meanings, there is a convenient resource for formatting insertion in the Text Object editor. When clicking the button, the format editor is called. After selecting a format, it is inserted to the text. Thus, if the cursor is placed before or after the closing square bracket, the format will be inserted correctly.

Conditional Highlighting

This feature of the Text Object allows one to color an object according to a specified condition. Any expression can be a condition. We will use the example with groups to demonstrate. Let the order totals, which are larger than 5000, be green-colored.  Select the object with the ""Group."ItemsTotal"" field and click on the "Conditional highlighting" button in the designer toolbar. In the conditional highlight editor, enter a condition, which after the value is exceeded, the object will be highlighted, and specify the color attributes to change (font parameters and background color).

The preview result will appear as follows:

Note the conditional expression we specified (Value > 5000). Value is the database field value, to which the object is linked. In a similar way, the “<Group.”ItemsTotal”> > 5000” condition may be set. In general, any expression, which is correct in terms of ClearVantage Xtreme Report Writer, may be specified here.

Coloring Alternate Data Rows

Using conditional highlighting, it is easy to create a report having this appearance, by “coloring” every second data line. Using the “Customer List” report example which we constructed previously, to save effort.

Remove all the Text Objects from the “Master data” band. Put a Text Object on the data-band and stretch it, so that it would occupy practically all the band space:

This object will modify its color depending on the data line number. Select the object and set the following conditional expression in the highlight editor:

<Line> mod 2 = 1

Note

If you have selected C++ Script as a script language (see more details in the “Script” chapter), you should write the condition using C++ Script:

<Line> % 2 == 1

Select gray color for highlighting, but not too saturated (closer to white). Now other objects can be added to the data-band on top of the empty Text Object:

When previewing the report, we see the following output:

Nested Reports (Subreports)

The need to combine multiple reports in one is available through CV Xtreme Report Writer when using Nested or subreports.

Basic Nest Reports or Subreports

Sometimes it is required to display in a particular place, on a design page additional data, which may represent a separate report with a complicated structure. One may construct such report by using a set of ClearVantage Xtreme Report Writer bands, but it is not always possible. In such cases, the Subreport Object is used.

After inserting such an object to a report, we can see that ClearVantage Xtreme Report Writer automatically adds a new page, connected to this object. A nested report resembles a multipage one in terms of structure. The only difference is that the nested report is displayed in a specified location on the basic design page and not after it. When outputting a report, as soon as the Subreport Object is encountered, the report engine outputs the associated design page until it is complete. After the subreport basic design page output will continue.

It should be noted that ClearVantage Xtreme Report Writer’s ability to construct subreports enables it to increase nesting levels of data. Remember that number of data levels in ClearVantage Xtreme Report Writer is limited to six when you do not use the Subreport Object.

Side-by-Side Reports

You can have two or more Subreport Objects side by side on the same band:

This allows one to design reports, where the data output by each has different lengths (rows/records), or stretching or heights:

As you can see, ClearVantage Xtreme Report Writer continues to output the basic design page after the longest Subreport is finished. One can also use the Vertical alignment property to adjust text object alignment within each subreport.

Limitations on Using Subreports

Since subreports are substituted on the basic design page, it cannot contain the following bands: “ReportTitle/ReportFooter,” “PageTitle/PageFooter/PageBackground,” and “ColumnTitle/ColumnFooter.” It is possible to put these bands on the nested report page, but they however will not be handled properly. For the same reason, there is no sense in modifying nested report pages options, inasmuch as the options of basic report’s page are used during outputting of a report.

Do not put objects below the Subreport Object:

When displaying a nested report, the nested report objects will overlay everything placed below, and the user will see something like this:

To display the objects below/after the nested report, use a child-band:

This method is also used when it is necessary to display several Subreports one under another, use a child band for each Subreport and chain them together. Child1’s child property is set to child2 and so on.

PrintOnParent Option

The Subreport Object has the “PrintOnParent” property which can be useful in some cases. This property is “False” by default.

Usually a subreport is output as a set of bands on the basic report page. In this case the parent band (which contains a Subreport Object) do not depend on the subreport bands, i.e., can't stretch. If the “PrintOnParent” property is True (you can set it from the Object Inspector Window or in the context menu), subreport's objects are printed physically on the band which contains the Subreport Object. You can make this band stretched and put on it stretched objects:

Script

A script is a program written in a higher-level language which is a part of a report. As a report runs, the script runs as well. A script is able to perform data handling, which cannot be performed via regular means of the ClearVantage Xtreme Report Writer core, for example, to hide useless data according to any predefined condition. The script is also used for controlling properties of dialog forms which are the components of the report.

The script should be written using one of the languages, which are the components of the script engine. Currently, the following languages are supported:

• Pascal Script

• C++ Script

• BasicScript

• JScript

The following features are available in the script engine:

• Standard language set: variables, constants, procedures, functions (with nesting capability) with variables, constants, default parameters, all standard operators (including case, try, finally, except, with), types (integral, fractional, logical, character, line, multidimensional arrays, set, variant), classes (with methods, events, properties, indexes, and default properties).

• Declarations of the following types absent: records, classes in the script; no records, no pointers, no sets (however, the 'IN' - “a in ['a'..'c','d']” operator usage is possible), no shortstring type, no unconditional jump (GOTO).

• Types’ compatibility checking.

• Ability to access any report’s object.

You can create scripts in the ClearVantage Xtreme Report Writer designer, which contains the scripts’ editor with syntax’s highlighting. Additionally, there is an embedded debugger, which possesses the following functions: “Step,” “Breakpoint,” “Run to cursor,” and “Evaluate.”

A Taste of Script

Tools for working with the script are located in the “Code” tab of the ClearVantage Xtreme Report Writer editor. When switching to this tab, the designer appears as follows:

In the illustration above, the figures denote:

1 – “Code” tab

2 – script’s editor window

3 – a drop-down for selecting a language, in which the script is to be written

4 – debugger’s toolbar:

Description	Toolbar
run report in debugging mode
run to cursor
perform the regular code line
interrupt script’s work
preview expressions’ evaluation
toggle breakpoint

5 – “Watches” window

6 – bookmarks and breakpoints are displayed in this field; in addition, the lines, possessing the executable code are highlighted there.

Below there is the list of the keys, which can be used in the script editor.

Key	Meaning
Cursor arrows	Move the cursor
PageUp, PageDown	Go to the previous/next page
Ctrl+PageUp	Go to the beginning of the text
Ctrl+PageDown	Go to the end of the text
Home	Go to the beginning of the line
End	Go to the end of the line
Enter	Go to the next line
Delete	Delete the symbol at cursor’s position; delete the selected text
Backspace	Delete the symbol to the left from the cursor
Ctrl+Y	Delete the current line
Ctrl+Z	Undo last action (up to 32 events)
Shift+Cursor arrows	Select a text block
Ctrl+A	Select the whole text
Ctrl+U	Shift the selected block by 2 symbols to the left
Ctrl+I	Shift the selected block by 2 symbols to the right
Ctrl+C, Ctrl+Insert	Copy the selected block to the clipboard
Ctrl+V, Shift+Insert	Paste the text from the clipboard
Ctrl+X, Shift+Delete	Cut the selected block to the clipboard
Ctrl+Shift+<number>	Set a bookmark with the 0-9 number on the current line
Ctrl+<number>	Jump to the set bookmark
Ctrl+F	Search a line
Ctrl+R	Replace a line
F3	Repeated search/replacement from the cursor’s position
F4	Set the breakpoint and script’s running (Run to cursor)
Ctrl+F2	Reset the program
Ctrl+F7	Preview variables’ values (Evaluate)
F9	Run the script (Run)
F7 or F8	Execute code line (Step into)
Ctrl + Space	Shows list with methods and properties of object
Ctrl+Shift+Delete	Delete word above cursor
Ctrl+Shift+Backspace	Delete word below cursor

Structure of a Script

A script’s structure depends on the language you use; however, there are some common elements. They are the script’s title, body, and the main procedure, which will be executed when the report runs. Below are examples of the scripts for all four supported languages:

Pascal Script Structure:

C++ Script Structure:

Javascript Script Structure:

Basic Script structure:

Later, we will examine examples of scripts written in “Pascal Script” language. When a new report is created, this language is selected by default.

"Hello, World!" Script

We have already examined an example of the “Hello, World!” report. Now let us review how to create a simple script, which would display a window with a greeting.

Create a blank report for ClearVantage Xtreme Report Writer. Switch to the “Code” page tab and write the following script:

Pascal Script:

C++ Script:

After that, run the report. As we expected, ClearVantage Xtreme Report Writer displays a little window with a greeting:

We created a script consisting of a single “begin..end” block. Thus, our script has a very simple structure; it consists of a main procedure only (see the “Structure of a script” in this chapter). The main procedure is executed as soon as the report runs. In this case, it displayed a greeting window; the procedure ends right after the window is closed. After the main procedure is finished, report building starts.

Using Objects in the Script

One can address any report’s object from the script. So, if there are, for example, the “Page1” page and the Memo1 Object, one can use them in the script, calling them by names, for example:

Pascal Script:

Memo1.Color := clRed

C++ Script:

Memo1.Color = clRed

The list of the report’s objects available from the script is displayed in the “Report tree” service window. What objects’ properties are available in the script? The answer is simple: those ones, which are visible in the object’ inspector. At the same time, at the bottom of the inspector, there is a hint concerning the selected property. Both windows (report’s tree and inspector) are available during working with the script.

A simple example. Put a Text Object with the “MyTextObject” name and the “Test” text on the report’s design page. Then write in the script:

Pascal Script:

begin

MyTextObject.Color := clRed

end.

C++ Script:

{

MyTextObject.Color = clRed

}

Run the report and see that our object’s color became red.

Calling the Variables from the Report’s Variables List

One can call any variable, which is specified in the list of the report’s variables from the script. Variable’s name should be enclosed in angle brackets:

Pascal Script:

if <my variable> = 10 then ...

C++ Script:

if (<my variable> == 10) { ... }

An alternative way is to use the “Get” function:

Pascal Script:

if Get('my variable') = 10 then ...

C++ Script:

if (Get(“my variable”) == 10) { ... }

Modification of such variable’s value is available only via the “Set” procedure:

Pascal Script:

Set('my variable', 10);

C++ Script:

Set(“my variable”, 10);

Worth noting that for conferring string value, you need to use additional brackets.

Pascal Script:

Set('my variable', '''' + 'String' + '''');

C++ Script:

Set(“my variable”, “\”String\”“);

One should address the system variables, such as “Page#,” in exactly the same way:

Pascal Script:

if <Page#> = 1 then ...

C++ Script:

if (<Page#> == 1) { ... }

Referencing the Database Fields

Just as with variables, one should use angle brackets for calling the Database fields:

Pascal Script:

if <Table1.”Field1”> = Null then...

C++ Script:

if (<Table1.”Field1”> == Null) { ... }

And just as well, one can use the “Get” function (as a matter of fact, this function is always used in implicit way for calculating expressions, enclosed in angle brackets).

Using Aggregate Function in the Script Report

An idiosyncrasy of an aggregate function is that it should be used inside the Text Object; one can call it in the script after it is used. If an aggregate function is used in the script only, (without using it in the Text Object), an error message will appear. That happens due to the fact that an aggregate function must be connected with a definite band, and only then will it work correctly.

Displaying the Variable’s Value in a Report

To display the contents of any script variable in a report, one should describe this variable and bind a value to it. Here is a simple example of a script variable:

Pascal Script:

var

MyVariable: String;

begin

MyVariable := 'Hello!';

end.

C++ Script:

string MyVariable;

{

MyVariable = ”Hello!”;

}

The variable’s value can be displayed in the Text Object, for example, by placing the [MyVariable] text into it.

A variable’s name should be unique, which means that it should not coincide with the names of the report’s objects, standard functions, and constants. If there is an error in the script, a message will be displayed, and report construction process will be stopped.

Events

So far, we have examined scripts with only one main procedure, which is performed when a report starts running. In the main procedure, one can perform any initial settings, initialize variables. However, this is not enough for total control over the process of report's forming. To control a report as much as possible, every report object has several events, to which a handler (i.e., a procedure from the script) may be assigned. For example, in the handler, connected to the data-band, one can perform records' filtering, which means that the band will be hidden or displayed according to any specified conditions.

Let us demonstrate the process of creation of a report and of events, which are generated during it, with the example of a simple report, which contains one page, one “Master data” band, and two Text Objects on the band:

As stated previously, the main script's procedure is called in the very beginning of a report. After that, the essential process of report construction starts. In the beginning of the report, the “OnStartReport” event of the Report Object is called. Before the page is being formed, the “OnBeforePrint” page event is called. This event is called once for each design page of the report's template (it should not be confused with the output pages of a report!). In our case, the event is called once, as the report's design consists of one design page.

Then output of data-bands begins, in the following order:

1. The band's “OnBeforePrint” event is called.

2. The “OnBeforePrint” events of all the objects, belonging to the band, are called.

3. All the objects are filled with data (in our case with values of the “Company” and “Addr1” DB fields); after that, the “OnAfterData” events of all the objects are called.

4. Such actions as positioning of objects on the band (if there are stretchable objects among them), calculating of the band's height, and stretching (if it is stretchable) are performed.

5. The band's “OnAfterCalcHeight” event is called.

6. A new output page is formed, if the band does not find room in white space of the page.

7. The band and all of its objects are displayed on the report’s output page.

8. The “OnAfterPrint” event of all the band's objects is called.

9. The “OnAfterPrint” event of the band itself is called.

Bands are printed as long as data exists in the source connected to the band. After that, forming of a report stops; the “OnAfterPrint” report's page events and, finally, the “OnStopReport” event of the Report Object are called.

Thus, by using events of different objects, one can manage practically every moment of report's formation process. A key to using events is a thorough understanding of the bands' output process, discussed in the next nine sections. Most of the actions can be performed using the band's “OnBeforePrint” event only; any modifications made to an object are displayed immediately. However, in this event it is impossible to analyze, in which page the band will be printed, if it is stretchable, since calculation of band's height will be performed in the step 4. This can be performed either by the “OnAfterCalcHeight” event in the step 5, or the “OnAfterPrint” event in step 8, but in the latter event a band will already have been output so any modification of objects will not have any effect.

One should clearly understand “where and when” bands are output and the timing (firing order) of each of their events, as well as those of objects contained in the band.

Example of Using the “OnBeforePrint” Event

To demonstrate, create a report, which represents the list of clients. This report will include only those companies, whose names begin with the letter “A.”

Let us create a new Xtreme Report on the CV Xtreme Report Writer canvas:

Table1:

DatabaseName = YourDatabase_CV

TableName = CUSTOMER

frxDBDataSet1:

DataSet = Table1

UserName = 'Customers'

Enter the report’s editor and create a report of the following type:

Select the data-band and switch to the “Events” page tab in the objects’ inspector:

To create the “OnBeforePrint” event’s handler (this is exactly what would be most appropriate to us), double-click on the blank field to the right of the event’s name:

At the same time, a blank handler is added to the script’s text, and the designer switches to the “Code” page.

The only thing we should do after that is to write the following code in the handler’s body:

Pascal Script:

if Copy(<Customers.”Company”>, 1, 1) = 'A' then

MasterData1.Visible := True else

MasterData1.Visible := False;

C++ Script:

if (Copy(<Customers.”Company”>, 1, 1) == ”A”)

MasterData1.Visible = true;

else

MasterData1.Visible = false;

Run the report and make sure, that the script works correctly:

You can assign one handler to several events of different objects at once; in this case the “Sender” parameter defines the object, which has initiated the event. To assign a name of the already existing handler to the event, one can either enter it manually in the objects’ inspector, or select it in the drop:

The link to the handler can be easily deleted. To do that, select a required property and click the “Delete” key.

Printing a Group Sum in the Group Header

This quite often-used method requires use of scripts because total value in an ordinary report becomes available only after all group's records are handled. To display a sum in the group's header (before the group is handled), the following algorithm is used:

• The two-pass option of the report is turned on (“Report|Options...” menu item).

• In the first pass, the sum of each group is calculated and saved in an array.

• In the second pass, the values are extracted from the array and typed in the group's header.

Let us show, two ways of how this task may be accomplished. First, let us create a new project in Delphi, put the “TQuery,” “TfrxReport,” and “TfrxDBDataSet” components to the form. Set them in the following way:

Query1:

DatabaseName = 'YourDatabase_CV'

SQL =

select * from customer, orders

where orders.CustNo = customer.CustNo

order by customer.CustNo, orders.OrderNo

frxDBDataSet1:

DataSet = Query1

UserName = 'Group'

Enter the designer and connect our data source to the report. Enable the double pass in report's settings (the “Report|Options...” menu item). Add two bands to the report: “Group header” and “Master data.” In the “Group header” band's editor, specify the condition (“Group.CustNo” data field). Connect the data-band to the “Group” data source, and then arrange objects in the following way:

For entering sum value, we use the selected object in the picture (in our example its name is “Memo8”).

The first way:

We use the “TStringList” class as an array for sums' storage. We will store numeric values as strings. At the same time, the first line in the list corresponds to the value of the first group, etc. The integer-valued variable (which we will augment after printing the next group) is used for calculating the group's number.

Thus, our script will look as follows:

Pascal Script:

var

List: TStringList;

i: Integer;

procedure frReport1OnStartReport(Sender: TfrxComponent);

begin

List := TStringList.Create;

end;

procedure frReport1OnStopReport(Sender: TfrxComponent);

begin

List.Free;

end;

procedure Page1OnBeforePrint(Sender: TfrxComponent);

begin

i := 0;

end;

procedure GroupHeader1OnBeforePrint(Sender: TfrxComponent);

begin

if Engine.FinalPass then

Memo8.Text := 'Sum: ' + List[i];

end;

procedure GroupFooter1OnBeforePrint(Sender: TfrxComponent);

begin

if not Engine.FinalPass then

List.Add(FloatToStr(SUM(<Group.”ItemsTotal”>,MasterData1)));

Inc(i);

end;

begin

end.

C++ Script:

TStringList List;

int i;

void frReport1OnStartReport(TfrxComponent Sender)

{

List = TStringList.Create();

}

void frReport1OnStopReport(TfrxComponent Sender)

{

List.Free();

}

void Page1OnBeforePrint(TfrxComponent Sender)

{

i = 0;

}

void GroupHeader1OnBeforePrint(TfrxComponent Sender)

{

if (Engine.FinalPass)

Memo8.Text = ”Sum: “ + List[i];

}

void GroupFooter1OnBeforePrint(TfrxComponent Sender)

{

List.Add(FloatToStr(SUM(<Group.”ItemsTotal”>,MasterData1)));

i++;

}

{

}

Looking at the names of the procedures, you can easily find out the events we have used. They are: “Report.OnStartReport,” “Report.OnStopReport,” “Page1.OnBeforePrint,” “GroupHeader1.OnBeforePrint,” and “GroupFooter1.OnBeforePrint.” As for the first two events, they are called, as it was said, in the beginning and in the end of the report respectively. To create handlers for these events, one should select the Report Object in the Report Tree Window; its properties will appear in the objects' inspector. After that, we would switch to the inspector's “Events” page tab and create the handlers.

Why didn't we use the main procedure for creation of the “List” list in the “OnStartReport” event? That is because the created object should be cleared after a report is finished. This is logical to create objects in the “OnStartReport” event and clear them via the “OnStopReport.” In other cases (when memory does not need to be emptied) one can use the main procedure for initialization of variables.

Now let us examine the work of the script. In the beginning of the page, the counter of the current group (the “i” variable) is reset to “0” and increments after printing each group (in the “GroupFooter1.OnBeforePrint” event). The calculated sum's value is added to the list in this event. The “GroupHeader1.OnBeforePrint” event does not trigger during the first pass (the “Engine.FinalPass” verification). During the second pass (when the “List” list is filled with values), the value, which corresponds to the current group is retrieved in this event, and it is output to the “Memo8” object's text, which displays the sum total in the group title. In a finished report, it appears as follows:

As we can see, the algorithm is rather simple. Nevertheless, it can be simplified.

The second way:

We use the list of report's variables as an array for sums' storage. As we remember, reference to such objects is performed via the “Get” and “Set” functions. This saves us from having to create extra objects and to free them. Our script will look as follows:

Pascal Script:

procedure GroupHeader1OnBeforePrint(Sender: TfrxComponent);

begin

if Engine.FinalPass then

Memo8.Text := 'Sum: ' + Get(<Group.”CustNo”>);

end;

procedure GroupFooter1OnBeforePrint(Sender: TfrxComponent);

begin

Set(<Group.”CustNo”>,

FloatToStr(SUM(<Group.”ItemsTotal”>,MasterData1)));

end;

begin

end.

C++ Script:

void GroupHeader1OnBeforePrint(TfrxComponent Sender)

{

if (Engine.FinalPass)

Memo8.Text = ”Sum:” + Get(<Group.”CustNo”>);

}

void GroupFooter1OnBeforePrint(TfrxComponent Sender)

{

Set(<Group.”CustNo”>,

FloatToStr(SUM(<Group.”ItemsTotal”>,MasterData1)));

}

{

}

A code in the “GroupFooter1.OnBeforePrint” handler sets a variable's value with a name similar to the client's number (one can use any identifier, which unambiguously identifies the client, for example, his name <Group.”Company”>). If there is no such variable, it would be created; if there is, its value would be changed. In the “GroupHeader1.OnBeforePrint” handler, a variable's value with the number of the current group is computed.

“OnAfterData” Event

This event is generated after the report's object is filled with the data, to which it is connected. Use this event for analyzing either a Database field value, or an expression contained in the object. The fact is that this value is placed to the “Value” service variable, the value of which is available in this event only. So, having two Text Objects with the [Table1.”Field1”] and [<Table2.”Field1”> + 10] contents, one could analyze the value of these expressions referring to the “Value” variable:

Pascal Script:

if Value > 3000 then

Memo1.Color := clRed

C++ Script:

if (Value > 3000)

Memo1.Color = clRed;

Instead of writing something like this:

Pascal Script:

if <Table1.”Field1”> > 3000 then

Memo1.Color := clRed

C++ Script:

if (<Table1.”Field1”> > 3000)

Memo1.Color = clRed;

The use of “Value” instead of an expression provides you with a possibility to write one multipurpose handler of the “OnAfterData” event, and to connect it to several objects.

One more thing is to be noted. If there are several expressions in an object (for example, [expr1] [expr2]) a value of the last expression is transferred to the “Value” variable.

Event ”OnAfterData” excellently fits for calculating the height and width  of  such objects like  “Text”, if in the  report’s  script you need to  get  exact  value of  the height (stretched object). If in the Text Object you use an expression, you can use this script in the event OnAfterData:

Pascal Script:

var

MemoWidth: Extended;                                                        

begin

MemoWidth := TfrxMemoView(Sender).CalcWidth;                                     

end;

C++ Script:

float MemoWidth;

MemoWidth = TfrxMemoView(Sender).CalcWidth;

If the given code is put in the event OnBeforePrint, the result will be the height of the object in which the expression is written and not its value.

Cross-tab Reports

This kind of report has a table structure, which means that it consists of rows and columns. At the same time, it is not known beforehand, how many lines and columns a table would possess. That is why a report grows not only downwards (as the report types examined above) but sideways as well. A typical example of a report of such type is shown below.

Let us examine the elements of the table:

In the illustration, we see a table with two lines (rows) and four columns, where “a” and “b” are line titles, “1,” “2,” “3,” and “4” are column titles, and “a1”..”a4,” “b1”..”b4” are cells. To construct a report like this, we need just one set of data (a query or a table), which has three fields and contains the following data:

a        1        a1

a        2        a2

a        3        a3

a        4        a4

b        1        b1

b        2        b2

b        3        b3

b        4        b4

As you can see, the first field contains a line number, the second one has a column number, and the third one contains the cell contents at intersection of the table with the selected number. When outputting a report, ClearVantage Xtreme Report Writer creates a table in memory and fills it with data. Thus, the table expands dynamically, if a line or a column with a specified number does not exist.

Titles can consist of more than one level. See the following illustration:

In this illustration, the number, or index of the column is composite, i.e., it consists of two values. This report requires the following data:

a        10        1        a10.1

a        10        2        a10.2

a        20        1        a20.1

a        20        2        a20.2

b        10        1        b10.1

b        10        2        b10.2

b        20        1        b20.1

b        20        2        b20.2

In this example, the first field contains the line index, as it was before; the second and the third fields contain column indexes. The last field contains the cell value. Examine the following picture in order to make it clear, how ClearVantage Xtreme Report Writer constructs a table with complex titles:

Before handling is accomplished, our table would look like the table shown in the picture. During handling, ClearVantage Xtreme Report Writer unites the title cells with equal values, which are allocated on one level.

The next table element, which is shown in the following picture, displays intermediate totals and totals:

This report is constructed using the same data, as we used in the previous one. The columns, highlighted with gray in the picture, are calculated automatically and are not included in the initial data set.

Constructing a Cross-tab Report

Now let us turn from theory to practice. We will construct a simple cross-report, which will display employees’ salary over four years. To do this, we need the “crosstest” table. This table contains data of the following kind:

Name        Year        Salary

Ann        1999        3300

Ben        2002        2000

….

For cross-reports designing, one should use the “TfrxCrossObject”

the ClearVantage Xtreme Report Writer component palette. Just put it on the design canvas; it is not required to set anything. At the same time, the “frxCross” unit, which contains all necessary functionality, will be added to the “uses” list.

Enter the report design mode. First, connect our data source using the “Data” tab. Select the DB Cross-tab

the list. Click on the design page to place the object:

All settings are specified using the object’s editor. Call it by double-clicking on the object:

The Numerical list of the Editor’s items from the illustration above:

1 – A drop-down list with available data sources.

2 – The list of fields in the selected data source. The fields from this list can be dragged to the “3,” “4,” and “5” lists.

3 – The list of fields, which generate a line (row), header.

4 – The list of fields, which generate a column header.

5 – The list of fields, which generate a table cell.

6 – Table structure preview.

7 – Structure options here one can specify whether it is necessary to display titles and totals.

You can only use the mouse in this editor to make modifications. For our demo, it is enough to drag fields from the “2” list to the “3”, “4”, and “5” lists, as shown in the illustration above. After that, close the editor by clicking the “OK” button. We can see that the object displays its structure now:

When previewing the report now, you will see a table resembling the one shown below:

Changing the Appearance

Let us modify the object’s appearance. The first thing we want to do is to modify the titles’ colors and to display “Total” instead of “Grand total.” To change the title color into gray, click on the “Year,” “Name,” and “Grand Total” elements one after another, and then select the desired color using

in the toolbar.

You also can use a set of predefined styles. It is available in the cross-tab editor: click the “Select style” and choose one you like.

To change the “Grand Total” text, double-click on the cell, and then you will see the familiar text editor, where you can type “Total”:

To set the format of the currency values, select the first cell (on cross of [Name] and [Year] in our case), right-click to display a context menu and select the “Display Format...”:

Then select the required format and close format editor. You will get the following result:

Using Functions

In our previous example, we see the sum total of each employee’s salary during four years in the “Total” line. One can use the following functions:

• SUM – sum of values

• MIN – minimal value

• MAX – maximal value

• AVG – average value

• COUNT – number of values

Let us use the “MIN” function in our example. Open the cross-object editor in area (6) the “Salary” field item, click the down arrow.

Select the “MIN” function in the menu. Now one can modify a text in the cell of totals from “Total” to “Minimum.” A finished report will look as follows:

Sorting Values

Lines and columns values are arranged in ascending order, if values have numerical type, they are sorted by value, and if they have line type, they are sorted alphabetically. We can separately set our own sorting mode for each line and/or column value. The following modes are available: “arrange in ascending order,” “arrange in descending order” and “perform no sorting.” In the latter case, values in lines/columns will be displayed depending on their entries.

Let us modify column sorting in our example. We will arrange years in decreasing order. To perform this, let us enter the cross-object editor and select the “Year” column element. To modify sorting, click on the item’s down arrow select descending:

Close the editor and preview the report. It will look as follows:

Tables with Composite Headers

Our previous example contained one value per line, and column headers. Let us examine cross table design using a complex header, which means that it will contain two or more values. The table contains data of the following kind:

Name        Year        Month                Days        Salary

Ann        1999        2                3        1000

Ben        2002        1                5        2000

….

We have added the “Month” and “Days” fields, which contain month number and the number of working days, respectively. One can construct several reports based on this data; for example, salary of all the employees during all years, broken down by months.

What kind of a report we are going to get? It must resemble the report from the previous example, but at the same time it must be broken down by months as well. The cross-object must be set in the same manner. We’ll add the “Month” field into the column header by dragging it to the column header list. See the illustration below.

As a result, when previewing, we would see the following report:

Note, that ClearVantage Xtreme Report Writer automatically added a column of the intermediate totals, which are displayed after each year. This option can be set in the cross-object editor, by selecting the “Year” column element and disable the “Subtotal” flag:

In addition, one can note that there is no intermediate total in the bottommost column element (the same is true in cases, when this element is the only one). In our example, we do not need intermediate totals for each month.

Another feature of intermediate totals: In our example, it is desirable to display “Year + year total” instead of the “Total” text. In the cross-object editor, select the required object in the bottom part of the editor, and then enter the following text to it:

Total for [Value]

During construction, the “Value” expression will be replaced by the actual value of the column header value, located above:

Adjusting Cell Width

As you can see in the previous illustration, ClearVantage Xtreme Report Writer automatically adjusts cells width to allow the longer lines to fit the cells. However, in some cases (i.e., values with very long text lines) it might not be desirable. In cases such as that, there are 3 ways of changing the width.

The simplest way is to break lines in the text of object with intermediate totals, i.e., to insert a line into it:

Total

for[Value]

You see that the table appears more compact now:

However, this method cannot be used if the lines’/columns’ values are rather long, they cannot be corrected by breaking the line manually. This is why the cross-object has the “MinWidth” and “MaxWidth” properties (minimal and maximal cell width respectively). Both these properties are accessible only via the Object Inspector Window.

The “MinWidth” value is “0,” and the “MaxWidth” value is “200” by default. This is usually enough, but if you need more you can set your values according to any special requirement you desire.

Thus, in our example, we can set the following: MinWidth = MaxWidth = 50. This would signify that table cell width must be 50 pixels at any rate. If a cell is smaller, it is “adjusted” to the “MinWidth” value, if it is bigger, its width is fixed according to the “MaxWidth” value, and the text in the cell is divided. In our example, it would appear as follows:

The third way is to change table width manually. To do this, set AutoSize property to “False”. Now you are able to resize the cross-tab using the mouse. When moving the mouse cursor over cross elements, you will see that cursor shape changes. Here is an example of what we can do:

Remember that if you turn off the auto size, the cross-tab will not adjust the widths/heights of the table elements. You may get something like this when previewing our table:

In this case, just increase a cell width a little.

Font Colors and Highlighting

Sometimes it is necessary to highlight values and/or change font color. We have examined such a task in the group report example. Where we used conditional highlighting for the Text Object, this can be useful for us now as well.

To add highlighting: using our example, assume that we need to change font color for the values, which are more than 3000. Click on the object, representing the table cell. To set highlighting parameters, click on in the toolbar. The already familiar highlighting editor window will open, where one can set the following condition:

Value > 3000

And the font color to red:

This is all we need. Close the editor by clicking on the “OK” button and preview our report:

In the same way, a user is able to highlight total values, columns and lines, if necessary.

Managing a Cross-tab in Script

If setting table visual resources is not enough, one can use the report’s script to adjust settings for the appearance of the table. The Cross-table Object has the following events:

Event	Description
OnAfterPrint	Event is called after printing a table.
OnBeforePrint	Event is called before printing a table
OnCalcHeight	Event is called before calculating length of a row in the table. The event handler can return either the required value of height, or “0” when the row needs to be hidden.
OnCalcWidth	Event is called before calculating column’s width in a table. The event handler can return either the required value of width, or “0” when the column needs to be hidden.
OnPrintCell	Event is called before displaying a table’s cell. The event handler can modify the cell’s design or its contents.
OnPrintColumnHeader	Event is called before displaying a title of the table’s columns. The event handler can modify design or contents of the title’s cell.
OnPrintRowHeader	Event is called before displaying a title of the table’s rows. The event handler can modify design or contents of the title’s cell.

We can use the following methods of the Cross-table Object in events:

Method	Description
function ColCount: Integer	Returns the number of columns in a table.
function RowCount: Integer	Returns the number of rows in a table.
function IsGrandTotalColumn (Index: Integer): Boolean	Returns “True,” if the column with specified number is the total one.
function IsGrandTotalRow (Index: Integer): Boolean	Returns “True,” if the row with specified number is a total one.
function IsTotalColumn (Index: Integer): Boolean	Returns “True,” if the column with specified number is a column with intermediate totals.
function IsTotalRow (Index: Integer): Boolean	Returns “True,” if the line with specified number is a line with intermediate totals.
procedure AddValue(const Rows, Columns, Cells: array of Variant)	Adds a value to the table.

Let us show, how one can highlight the third column (in our example it is the “November 1999” date). To do this, select the cross-table object from the report design page, in the Object Inspector Window click on the events page tab, locate the OnPrintCell event and create the handler’s on the script page by double-clicking in the empty list to the right of the event name, the script editor will appear with the basic declaration created for you then add the code required in the empty begin end block of the declaration:

Pascal script:

procedure Cross1OnPrintCell(Memo: TfrxMemoView;

RowIndex, ColumnIndex, CellIndex: Integer;

RowValues, ColumnValues, Value: Variant);

begin

if ColumnIndex = 2 then

Memo.Color := clRed;

end;

C++ Script:

void Cross1OnPrintCell(

TfrxMemoView Memo,

int RowIndex,

int ColumnIndex,

int CellIndex,

Variant RowValues,

Variant ColumnValues,

Variant Value)

{

if (ColumnIndex == 2) { Memo.Color = clRed; }

}

We will see the following result when the report is previewed:

To highlight a column title, create an “OnPrintColumnHeader” event handler, as described above:

Pascal script:

procedure Cross1OnPrintColumnHeader(Memo: TfrxMemoView;

HeaderIndexes, HeaderValues, Value: Variant);

begin

if (VarToStr(HeaderValues[0]) = '1999') and

(VarToStr(HeaderValues[1]) = '11') then

Memo.Color := clRed;

end;

C++ Script:

void Cross1OnPrintColumnHeader(

TfrxMemoView Memo,

Variant HeaderIndexes,

Variant HeaderValues,

Variant Value)

{

if ((VarToStr(HeaderValues[0]) == ”1999”) &&

(VarToStr(HeaderValues[1]) == ”11”))

{

Memo.Color = clRed;

}

}

Result would appear as follows:

How the scripts work. The “OnPrintCell” event handler is called before printing a cell included in the table’s body (when printing cells from the table title, either the “OnPrintColumnHeader,” or the “OnPrintRowHeader” handler is called). At the same time, a link to the Text Object, which represents a table’s cell (“Memo” parameter), and the cell’s “address” in two variants: the number of row, column and cell (the last is relevant, if your cross-table contains multi-leveled cells) in the “RowIndex,” “ColumnIndex,” and “CellIndex” parameters respectively, are transmitted into the “OnPrintCell” handler. The “RowValues” and the “ColumnValues” parameters are the second variant of the “address.” The “Value” parameter is the cell’s contents.

To specify an “address,” you can use the second variant (RowValues, ColumnValues), since it is easier in the given case (as well as the first one (RowIndex, ColumnIndex)). In our case, it was necessary to highlight the third column; therefore, it would be more convenient to analyze the first variant. Since numbering of columns and rows begins with “0,” the “ColumnIndex = 2” checking allows us to define the third column. One could do it in a different way, i.e. by analyzing the required column by its data (we need the 11th month of 1999):

Pascal script:

procedure Cross1OnPrintCell(Memo: TfrxMemoView;

RowIndex, ColumnIndex, CellIndex: Integer;

RowValues, ColumnValues, Value: Variant);

begin

if (VarToStr(ColumnValues[0]) = '1999') and

(VarToStr(ColumnValues[1]) = '11') then

Memo.Color := clRed;

end;

C++ Script:

void Cross1OnPrintCell(

TfrxMemoView Memo,

int RowIndex,

int ColumnIndex,

int CellIndex,

Variant RowValues,

Variant ColumnValues,

Variant Value)

{

if ((VarToStr(ColumnValues[0]) == ”1999”) &&

(VarToStr(ColumnValues[1]) == ”11”))

{

Memo.Color = clRed;

}

}

Values, which are transferred in the “RowValues” and the “ColumnValues” parameters, are arrays of the “Variant” type with a zero base. The zero element is a value of the highest level of the table’s title; the first one is a value of the next level, etc. In our case, the “ColumnValues[0]” contains years, and the “ColumnValues[1]” contains months.

Why is “VarToStr” function necessary? This guarantees absence of errors during type conversion. When operating with the “Variant” type, ClearVantage Xtreme Report Writer attempts to automatically cast the strings to number format, which, in its turn, can lead to an error when attempting to cast the “Total” and “Grand Total'“ columns’ values.

The “OnPrintColumnHeader” event handler is called during output of column title cells. The set of parameters is similar to the parameters of the “OnPrintCell” handler, although in this case the cell’s “address” (the “HeaderIndexes” and “HeaderValues” parameters) is transferred in a different way. The “HeaderValues” parameter returns the same values, as the “ColumnValues” and “RowValues” parameters in the “OnPrintCell” handler. The “HeaderIndexes” parameter is also an array of values of the “Variant” type, which contains an address of the title’s cell in a different form: the zero element is the serial number of the highest level of the table’s title, the first one is the number of the next level, etc. To make the principle of cells numbering clear, refer to the picture below:

In our case, it is easier to analyze the “HeaderValues” value, but one can write the following handler as well:

Pascal script:

procedure Cross1OnPrintColumnHeader(Memo: TfrxMemoView;

HeaderIndexes, HeaderValues, Value: Variant);

begin

if (HeaderIndexes[0] = 0) and (HeaderIndexes[1] = 2) then

Memo.Color := clRed;

end;   C++ Script:

void Cross1OnPrintColumnHeader(

TfrxMemoView Memo,

Variant HeaderIndexes,

Variant HeaderValues,

Variant  Value)

{

if ((HeaderIndexes[0] == 0) && (HeaderIndexes[1] == 2)) { Memo.Color = clRed; }

}

Adjusting Row/Column Size

The user can adjust width and height of the table’s rows and columns using the “OnCalcWidth” and “OnCalcHeight:” events’ handlers. Let us show how to increase width of the column, which corresponds to the 11th month of 1999 by the following example. To do this, create the “OnCalcWidth” event’s handler:

Pascal script:

procedure Cross1OnCalcWidth(ColumnIndex: Integer;

ColumnValues: Variant; var Width: Extended);

begin

if (VarToStr(ColumnValues[0]) = '1999') and

(VarToStr(ColumnValues[1]) = '11') then

Width := 100;

end;

C++ Script:

void Cross1OnCalcWidth(

int ColumnIndex,

variant ColumnValues,

Extended &Width)

{

if ((VarToStr(ColumnValues[0]) == ”1999”) &&

(VarToStr(ColumnValues[1]) = ”11”))

{

Width = 100;

} 

}

And the result would appear as follows:

In our example, to hide a column, you can return the Width := 0. Note, that the sums are not recalculated at the same time, since the matrix is already full of values at this time.

Filling a Table Manually

There are two versions of the cross-table: the “DB cross-table” and the “Cross-table”. Until now, we’ve been working with the first object attached to the data from the DB table and fills itself automatically, as soon as the report runs. Let us examine the second object, “Cross-table”.

This object is not attached to the data from a DB. Therefore, you have to fill the cross-table with data manually. This object possesses a similar editor, but you will have to select the number of dimensions in the table’s titles and in its cells instead of DB fields:

Let us demonstrate using the Cross-table Object with an example. Put an object on the report design page and set it as shown in the illustration above: the number of levels in the strings’ title is “1,” in the columns’ title – “2,” in the cell – “1.” To fill the table with data, let us use the “OnBeforePrint” object’s event handler:

Pascal Script:

procedure Cross1OnBeforePrint(Sender: TfrxComponent);

begin

with Cross1 do

begin

AddValue(['Ann'], [2001, 2], [1500]);

AddValue(['Ann'], [2001, 3], [1600]);

AddValue(['Ann'], [2002, 1], [1700]);

AddValue(['Ben'], [2002, 1], [2000]);

AddValue(['Den'], [2001, 1], [4000]);

AddValue(['Den'], [2001, 2], [4100]);

end;

end;

C++ Script:

void Cross1OnBeforePrint(TfrxComponent Sender)

{

Cross1.AddValue([“Ann”], [2001, 2], [1500]);

Cross1.AddValue([“Ann”], [2001, 3], [1600]);

Cross1.AddValue([“Ann”], [2002, 1], [1700]);

Cross1.AddValue([“Ben”], [2002, 1], [2000]);

Cross1.AddValue([“Den”], [2001, 1], [4000]);

Cross1.AddValue([“Den”], [2001, 2], [4100]);

}

In the handler, it is necessary to add the required data into the table via the “TfrxCrossView.AddValue” method. This method has three parameters; each of them is an array of values of the “Variant” type. The first parameter is the row's value, the second one is the column’s value, and the third one contains the cells’ values. Note that the number of values in each array should correspond to the object’s setting! In our case, the object has one level in the rows' title, two levels in the columns’ title, and one level of cells. Therefore, we transfer one value for rows, two values for columns, and one value for cells into the AddValue.

When running the report, we would see the following:

One can use the “AddValue” method for the “DB cross-table” object as well. This allows adding the data (which are not in the data source attached to the object) into the cross-table. Otherwise, if there are such data, they are summarized with the data in the table.

Adding External Objects to the Table

You can put external objects (such as lines, shapes, pictures) into the cross-table. What for? For example, you may need to show some values in a graphic form. Let's look at an example that uses shapes to display a little progress bar:

Red bar is displayed if cell value is less than 100, yellow - less than 3000, green - more that 3000.

Let's start with our report. Put the DB Cross-tab Object on a report page and setup it’s properties.:

Turn off the “Auto Size” property and setup the column widths as shown below:

Now we add the shape object into our table. To do this, select the “Rectangle” object and put it inside the cell:

In the same way put another 2 rectangles.

Now create a script that will display the needed number of colored shapes (depending on cell value). To do this, select the cell and create OnBeforePrint event handler:

Write the following code in the event handler (pay attention to the shape names: our inserted shapes have exactly these names):

procedure DBCross1Cell0OnBeforePrint(Sender: TfrxComponent);

begin

// Value it's a current cell's value

if Value < 100 then

begin

   // first shape object

   DBCross1Object1.Color := clMaroon; // red

   // second shape object

   DBCross1Object2.Color := clWhite;

   // third shape object

   DBCross1Object3.Color := clWhite;

end

else if Value < 3000 then

begin

   DBCross1Object1.Color := $00CCFF;  *// yellow*

   DBCross1Object2.Color := $00CCFF;

   DBCross1Object3.Color := clWhite;

end

else

begin

   DBCross1Object1.Color := $00CC98;  *// green*

   DBCross1Object2.Color := $00CC98;

   DBCross1Object3.Color := $00CC98;

end;

end;

That's all - run our report and will see the same picture as at the beginning of this chapter.

Same Useful Settings

Let's look at some settings available in the cross-table editor.

First six options allow you to show or hide some table elements.

The “Auto size” option is already familiar. It allows us to set table width and height manually.

The “Border around cells” option allows drawing a frame around cell elements. Here is example of such table (note that cells itself don't have a frame):

The “Print down then across” option determines how to print a table across several pages. Here are two examples of using this option, with and without (pay attention to page numbers):

1) “Print down then across” is on:

2) “Print down then across” is off:

The “Reprint headers on new page” option determines if it is necessary to print table headers on each new preview page.

The “Side-by-side cells” option is used if you have two or more cell values in a table. It determines if it is necessary to print cells side-by-side or stacked (default).

The “Join equal cells” option allows printing side-by-side cells with equal values as one big cell:

Using the Object Inspector Window you can also setup the following properties:

- AddWidth, AddHeight - adds specified amount of space to the cell width or height. It will be used when calculating cell size (the AutoSize options must be on);

- NextCross - pointer to the next crosstab that will be displayed side-by-side to this one;

- NextCrossGap - gap between side-by-side crosstabs.

Charts

ClearVantage Xtreme Report Writer allows us to insert charts into the report.

Add the Chart

the report design page. Set the object size (18x8 cm). To customize the object, call its editor by double-clicking on it.

The areas of the chart editor in the illustration:

1 – chart structure. A chart can contain either one or several series.

2 – object inspector, which displays the properties of the element selected in the window.  Teak the chart’s properties here.

3 – toolbar for connection the series to data; it is activated once the series in the window 1 is selected.

On the first activation, the editor window will appear as in the image shown above. The first thing to be done is to add one or several series (one series in our example). To perform this, click

and select the pie chart:

Buttons with arrows pointing up and down helps to move diagram series and give them an ordered drawing. When needed you can also give the series a name simply by clicking on it with a mouse.

There are many different types of series available. After adding the series, the bar 3 becomes active. Here you specify, which data should be used for plotting. First of all, let us select the data set in the “DataSet” pulldown. Fill the “Label” and “Pie” fields using their respective pulldowns:

Click “OK” to close the editor and then preview the report:

What can be improved in this report? First of all, it would be nice to sort values in descending order. Again, we enter the chart editor and select the series in the upper part of the window. Now we select the required sorting mode:

If we previewed the report now, we would see that the data in the legend table is sorted.

Limiting the Number of Chart Values

Our chart looks rather crowded, since there are too many small values in the chart, which are invisible anyway. ClearVantage Xtreme Report Writer allows limiting of the number of values displayed in a chart by a predefined value. Thus, all the values, which do not belong to the limit set, would be displayed as a single value, representing the sum of values, which did not fit the chart.

In our example, the chart has 18 values, and only 8 of them can be displayed. Let us enter the editor and set limiting:

The limiting will work if the “TopN” is not zero. The name in the “TopN title,” which will be displayed opposite to the sum value, should be specified. Sorting mode is not significant; values will be sorted by default.

As a result, the report will look as follows:

Some Useful Settings

Let us examine several settings, which can be useful for setting chart appearance. These settings can be specified in the Object Inspector Window only.

The following basic properties are available when selecting a chart in the top of the list:

- Gradient – settings for gradient background filling. Enable the “Gradient.Visible” property for gradient displaying.

- Legend – settings for explanatory table appearance. The table can be disabled with the help of the “Legend.Visible” property. The table position is set with the help of the “Legend.Alignment” property.

The following properties are available when selecting a series:

- ColorEachPoint – color each value with different colors.

- ExplodeBiggest – select the largest value (only for the series of the “circle chart” type.

- Marks – settings for the explanatory hints appearance.

- ValueFormat – the line for formatting values.

Chart with Manually Entered Values

In the previous example, we constructed a chart on the basis of the Database table data. There is another way of constructing a chart: to enter the necessary data manually. This way is convenient when constructing small charts.

Let us demonstrate how it works with a simple example. Put a chart on the report design page and enter its editor. Add the series of the “Bar chart” type and set its properties:

The result:

Chart Completion from Script

Let us examine the last chart completion from script. To perform this leave empty XValues and YValues fields in chart editor. In the report script write the following:

Pascal Script:

begin

Chart1.SeriesData[0].XSource := 'Jan;Feb;Mar;Apr';

Chart1.SeriesData[0].YSource := '31;28;31;30';

end.

C++ Script:

{

Chart1.SeriesData[0].XSource = ”Jan;Feb;Mar;Apr”;

Chart1.SeriesData[0].YSource = ”31;28;31;30”;

}

SeriesData[0] in this case allows us to set parameters for the first series in the chart. If chart has several series, you can address them via SeriesData[data_number].

Dialogue Forms

In addition to usual report design pages, you can use dialog forms in a report. For dialog form creation, the same designer as for report pages is used.

in the designer toolbar is used for creating a new dialog form; it adds a new dialog design page to a report. When switching to the page with the dialog form, the designer workspace changes, thus becoming a form where control objects can be placed:

Controls

The following controls are available for use in the reports:

Element	Name	Description
TfrxLabelControl	This control is used for displaying explicative inscription on the dialog form.
TfrxEditControl	This control is used for entering a text line with the help of the keyboard.
TfrxMemoControl	This control is used for entering several text lines with the help of the keyboard.
TfrxButtonControl	The control represents a button.
TfrxCheckBoxControl	The control represents a flag, which can perform two statuses: enabled and disabled. Near the flag, the explicative inscription is displayed.
TfrxRadioButtonControl	The control represents a switch key counterpart with radio button. This is the reason why it cannot be used alone.
TfrxListBoxControl	The control represents the list of lines with a possibility to select one of them.
TfrxComboBoxControl	The control represents the drop-down list of lines with a possibility to select one of them.
TfrxDateEditControl	The control represents a field with a drop-down calendar for date entering.
TfrxGroupBoxControl	The control represents a bar with explicative inscription which is used for uniting several controls.
TfrxPanelControl	The control represents a bar, which is designed for uniting several controls.
TfrxBitBtnControl	The control represents a button with picture.
TfrxSpeedButtonControl	The control represents a button with picture.
TfrxMaskEditControl	The control represents a text box for entering information set in a template.
TfrxCheckListBoxControl	The control represents a list of lines with flags.
TfrxBevelControl	The control is used for the dialog form design.
TfrxImageControl	The control represents a picture in “BMP,” “ICO,” “WMF,” or “EMF” format.

"Hello, World!" Report

In this example, we will create a report displaying a greeting window before outputting the report by using a dialog form. Call ClearVantage Xtreme Report Writer designer by double-clicking on the “TfrxReport” component and add a dialog form into the report. Put the “TfrxLabelControl” and “TfrxButtonControl” objects on the form:

Set objects’ properties:

TfrxLabelControl:

Caption = 'Hello, World!'

TfrxButtonControl:

Caption = 'OK'

Default = True

ModalResult = mrOk

Set the “BorderStyle = bsDialog” property in the form.

As soon as design of the dialogue form is finished, return to the report design page and place a Text Object with some text in it there. Preview the report and you will see the dialog form:

When clicking on the “OK” button, a report will be constructed and displayed. If closing a form via the “OK” button, the report will not be constructed. This is the mechanism of ClearVantage Xtreme Report Writer working: if there are dialogue forms in a report, it is constructed only when each form is closed with the “OK” button, i.e. it returns ModalResult = mrOk. That is why the “ModalResult” property of the button is set equal to “mrOk.”

Entering Parameters and Transferring Them into a Report

Let us make this example more complicated in order to show how to transfer the values entered in the dialog form into a report. To perform this, modify the dialog form in the following way:

Place a Text Object containing the following text on a page:

You entered:

[Edit1.Text]

Preview the report and make sure that the parameter you entered is successfully displayed in the report. You can address other objects of the dialog form In the same way. Since each object has a name, which is unique within the whole report, it can be used anywhere within the report.

Interaction with Controls

By using script, you can easily create logic for the dialog form’s work, for example, its controls’ interaction. Let us illustrate this by a simple example. Modify the form in the following way:

Double-click on the Checkbox Object, so that the “OnClick” event handle would be created, and then write the following script:

Pascal Script:

procedure CheckBox1OnClick(Sender: TfrxComponent);

begin

Button1.Enabled := not CheckBox1.Checked;

end;

C++ Script:

void CheckBox1OnClick(TfrxComponent Sender)

{

Button1.Enabled = !CheckBox1.Checked;

}

When running the report, you would see that the button responds to the flag condition’s modification.

Several Dialogue Forms

Let us examine how report with two dialogs forms works. Create a report with two dialog and one design page:

Set ModalResult properties of OK and Cancel buttons (mrOk and mrCancel accordingly). Now run the report. First of all we will be offered to answer questions from the first dialog (name, are there any children), then, on clicking 'OK' – from the second one (children’s names). After clicking 'OK' in the second dialogue the report will be built. In such a way works ClearVantage Xtreme Report Writer kernel – involving several dialog boxes they appear in the order of their creation, moreover, every further dialogue will be displayed after clicking OK in the previous one (with ModalResult property = mrOk). If any dialog were denied (via Cancel or cross on window heading), report building would stop.

Managing Dialogue Forms

In the previous example both dialog forms are displayed irrespective of the fact whether we ticked “Have children” or not. Let us show how to hide the second dialog in case when this flag is disabled. To perform this create OnClick handler of 'OK' button on the first dialogue form (double-click on the button to create handler):

Pascal Script:

procedure Button1OnClick(Sender: TfrxComponent);

begin

DialogPage2.Visible := CheckBox1.Checked;

end;

C++ Script:

void Button1OnClick(TfrxComponent Sender)

{

DialogPage2.Visible = CheckBox1.Checked;

}

This code hides the second dialog form (DialogPage2) if the flag is not marked. Preview the report, to see that everything works correctly.

Another way of form managing is to use the OnRunDialogs report event. In order to create this event handler select Report object in report tree or Object Inspector Window and switch to “Events” tab in the inspector. Double-click on OnRunDialogs event to create necessary handler:

Write the following code in handler:

Pascal Script:

procedure frxReport1OnRunDialogs(var Result: Boolean);

begin

Result := DialogPage1.ShowModal = mrOk;

if Result then

begin

if CheckBox1.Checked then

Result := DialogPage2.ShowModal = mrOk;

end;

end;

C++ Script:

void frxReport1OnRunDialogs(bool &Result);

{

Result = DialogPage1.ShowModal == mrOk;

if (Result)

{

if (CheckBox1.Checked)

Result = DialogPage2.ShowModal == mrOk;

}

}

How the handler works we show the first dialog. If it was closed via 'OK', look at CheckBox1 flag status and show the second dialog, if it is necessary. If handler returns Result = True, report is building; if Result = False, report stops.

Data Access Components

Most reports, as a rule, are based on data from a Database.

In addition to accessing data defined in the reportas we have done in our examples using the TfrxDBDataset, ClearVantage Xtreme Report Writer has available, several DB engine specific components for use within reports, which ones are dependant upon choices made during installation. In ClearVantage Xtreme Report Writer the principles for data access are much the same as those used in the Delphi environment. The same as in Delphi, a component is put on a dialogue form and its properties are set in the Object Inspector Window. Component ideology is very flexible: you can also create new components to support different data access engines easily (see the developers manual). They also, with the additional use of the TfrxDesigner, give the end user of the application the ability to design reports in runtime.

Component Descriptions

Let us examine usage of components for data access via ADO. They are available by adding the“TfrxADOComponents” component from the ClearVantage Xtreme Report Writer palette to the project.

The following objects appear in the Object Toolbar when you switch to the “Data” page in the designer: “TfrxADOTable,” “TfrxADOQuery,” and “TfrxADODataBase.” These components are similar to the corresponding Delphi components (“TADOTable,” “TADOQuery,” and “TADOConnection”) in terms of their functioning. Also you will able to use the “TfrxDBLookupComboBox” control on a dialogue form.

Icon	Name	Description
TfrxDBLookupComboBox	The control is used for selecting a value from a directory.
TfrxBDETable	The control is used for access to DB table.
TfrxBDEQuery	The control is used for performing SQL-query.
TfrxBDEDataBase	The control is used for connecting to DB.

Let us examine each component.

TfrxDBLookupComboBox

This element is used for selecting a value in the directory table. It substitutes the directory identifier of the selected value.

The element has the following properties:

Property	Description
DataSet	Data source, which a control is connected to.
ListField	Name of the DB field, which will be displayed in a control.
KeyField	Name of the DB key field, which will identify the selected record.
KeyValue	Value of the DB key field, which was selected in the list.
Text	Value of the DB field displayed in the list.
AutoOpenDataSet	If the property is set to true, the connected data source will be opened automatically after the event  OnActivate dialogue.

For connecting of a control to the directory, you should fill values of the three properties: “DataSet,” “ListField,” and “KeyField.” The selected value is available via either the “Text” or “KeyValue” properties. You can set the initial position of a cursor in the list with the help of the “KeyValue.”

TfrxADOTable

The component is used for organization of Database table access. The component has the following properties:

Property	Description
DatabaseName	Connection name (name of the TfrxADODatabase component).
FieldAliases	Enables to set fields aliases.
Filter	Expression for records’ filtering.
Filtered	Defines whether it is necessary to use filter.
IndexFieldNames	Names of index fields.
IndexName	Secondary index name.
MasterFields	Fields connected with master dataset.
Master	Master dataset.
TableName	DB table name.
UserName	Username (alias) of the dataset.

Component properties’ functions are similar to the “TADOTable” Delphi properties. To connect a component to the DB table, it is enough to fill the “DatabaseName” and “TableName” properties. Table opening is performed either via the “Active: = True” setting, or with the help of the “Open” method.

The “FieldAliases” property editor allows to select fields, which will be available upon addressing the table, and to set aliases for the whole table and for each field.

The “MasterFields” property editor is used for creation of master-detail connections between two tables. To connect two tables with the master-detail relation, a user should specify a general table in the “Master” property and call the “MasterFields” property editor for the subordinate table. If the table has secondary indexes, which are necessary to be used, set the “IndexName” property beforehand.

Here you can visually bind the “master” and the “detail” fields of data sets. When the sets’ connection is of “Master-Detail” type, then when moving within the master set, the contents of the detail set is filtered in a way that it contains only records belonging to the current record of the master set.

To connect the sets’ fields, select a field from the list on the left (detail set), then a field from the list on the right (master set), and click on the “Add” button. Thus, the fields’ bond would be transferred to the bottom list. To clear the bottom list, use the “Clear” button. The bound fields must be of an equal type and be the key ones.

TfrxADOQuery

The component is used for performing SQL-queries to DB. The component has the following properties:

Property	Description
DatabaseName	Connection name (name of the TfrxADODatabase component).
FieldAliases	Allows to set user’s field aliases.
Filter	Expression for records’ filtering.
Filtered	Defines whether it is necessary to use the filter.
Master	Master dataset.
Params	The list of query parameters.
SQL	Query text.
UserName	User name (alias) of the dataset.
IgnoreDupParams	If true, the name of the inquiry parameters will not be edited in the parameter editor

The “Active,” “DatabaseName,” “FieldAliases,” “Filter,” “Filtered,” and “Master” properties are similar to the properties of the “TfrxADOTable” component described above. The “SQL” property has its own editor for filling the SQL-query.

The “Params” property also has its editor. It becomes available as soon as a query text contains parameters.

A parameter can be of two types: either one assigned from the master-source or one having a concrete value (either an absolute symbol or a link to the variable or object’s property, as it is shown in the illustration above, can act as a value).

In case when a parameter is taken from the data master-set, it is necessary to adjust the “TfrxADOQuery.Master” property. The data set must contain a field with the name coinciding with the name of the parameter. At the same time, it is not necessary to specify either a parameter type, or its value.

TfrxADODataBase

This component is used to connect to a database. The component has the following properties:

Property	Description
Connected	If “True,” it activates the connection.
DatabaseName	The ADO connection string.
LoginPrompt	Defines whether it is necessary to request a password upon connection to DB.

The LoginPrompt property defines whether it is necessary to request a password when connecting to DB. If  “LoginPromt” = “False,” a user name and a password must be specified in connection parameters.

Query Construction

For Visual query construction CV Xtreme Report Writer's QueryBuilder is used. Constructor is shown in the illustration below:

Constructor working area and the list of available tables support allow you to drag and drop for placing a table into the working area. You can also click on the table title in the available list of tables.

To include any field from the table in the query mark it:

Marked fields appear in the fields parameter table area (4):

You can set the following properties for each field:

• Visibility: defines whether field is included in output. You can select 'Visible' or 'Not Visible'. If the property is blank the field is visible.

• Where: field selecting condition. For example, you can enter '>5'.

• Sort: defines sorting according to field. You can select 'No', 'Ascending', or 'Descending'

• Function: defines function applicable to field. You can select 'No', 'Aug', 'Count', 'Max', 'Min' or 'Sum'

• Group: grouping according to field. You can select 'No' or 'Grouping'

By “dragging” fields between tables in the work area (2), “Join lines” will appear. On joining fields the type compatibility is verified. It is impossible to create joins between incompatible fields. For link parameter settings, place the cursor on the “join line”,  right click and select Options item. The join parameters window appears, where you can set the required values: See the illustration below.

Query Construction

Build a simple report using the query constructor.

Click “New report” on designer toolbar. A report page with “Report heading”, “First level data”, “Page footer” bands is created.

Put the “ADO Query” component on the “Data” page. Double-click on the component and you will see query editor window.

Click button in the SQL editor and you will see the query constructor window. Select the Customer table in the table list (3) and drag it to the work area (or can double-click on it). Mark CUSTOMERCD, ORGNAME and Phone fields:

That is all that necessary for query building. You can see query code on SQL page tab, and on Result page tab you can see data which the query has returned.

Click to close constructor. At that we return to query editor window where the generated query code is now displayed:

NOTE: If you modify query code, you will lose your data plan (tables placed in the query constructor and their joins). Do not modify query code manually, you can always enter query constructor and correct the plan visually.

By clicking the check in editor we return to the report designer. All that is left to do is to connect “Master data” band to data source and place fields on the band.

Report Viewing, Printing, and Exporting

The report can be displayed, printed or exported into one of the supported formats. Everything can be performed in preview window.

On the picture with figures the following is displayed:

1 – ready report pages;

2 – toolbar;

3 – status line;

4 – outline area. Either the outline tree (as shown on a picture) or thumbnails can be displayed here.

The following buttons are on the toolbar:

Icon	Name	Description
Print report	Prints report. Hotkey – Ctrl+P.
Open report	Opens file with ready report (*.fp3).
Save report	Saves report to file (*.fp3).
Report export	Exports report to one of the supported formats.
Export to PDF	Exports report to Adobe Acrobat file (*.pdf). .
Send via e-mail	Exports report to one of the supported formats and sends it via e-mail as enclosure.
Text search	Text search in report. Hotkey – Ctrl+F.
Zoom in	Zooms in the preview.
Scale	Selects arbitrary scale.
Zoom out	Zooms out the preview.
Full screen	Displays report at full screen. For returning to normal conditions perform double-click on report.
Outline	Shows or hides the report outline.
Thumbnails	Shows or hides the thumbnail view.
Page properties	Calls dialogue with page properties.
Edit page	Edits current page.
To beginning	Transfer to the first report page.
Previous page	Transfer to previous report page.
Page number	Transfer to report page with pointed number. Enter number and press Enter.
Next page	Transfer to next report page.
To end	Transfer to the last report page.
Close window	Close preview window.

Control Keys

Keys	Description
Ctrl+S	Save report to *.fp3 file.
Ctrl+P	Print report.
Ctrl+F	Text search.
F3	Continue search.
Arrows	Smooth document scrolling.
PageUp, PageDown	Up/down scrolling.
Ctrl+PageUp, PageDown	Next/previous page scrolling.
Home	Document beginning.
End	Document end.

Mouse Control

Action	Description
Left button	Click on selected object (in interactive report); report scrolling in “hand” mode (move mouse with pressed button); zoom in is performed in “magnifier” mode.
Right button	Context menu; in “magnifier” mode zoom out is performed.
Double-click	It full screen mode it performs returning to normal conditions.
Mouse scroll	Report list scrolling.

Report Printing

To print a report click

on button (or Ctrl+P hotkey). The print dialog box appears.

Let's look at options available in this dialog box.

The “Printer” group: you can select a printer via which you want to print a report; set printer properties, for example, printing quality; and choose print to file.

The “Pages” group: you can select which pages to print (all, current, selected range).

The “Copies” group: you can set how many copies to print. If Collate flag is set and you choose to print several copies, at first one report copy is printed, then – the next etc. If flag is disabled, several copies of the first page are printed, then – several copies of the second one etc.

The “Other” group:

• Print - you can select which pages to print. Variants: All pages, Even pages, Odd pages.

• Order - print pages in direct or reverse order (from last to first page).

• Duplex - handle duplex by default (report settings are used) or choose one of duplex options: vertical, horizontal, simplex.

The "Print mode" group: you can select one of the printing modes.

• Default mode. The printer prints on the sheet defined in a report. One preview page is printed on one sheet.

• Split big pages. This mode is useful if you need to print an A3 size report on A4 sheet. One preview page is printed on several sheets. If you choose this mode, you have to choose the sheet size (“Print on sheet”) as well.

• Join small pages. This mode is useful if you want to print an A4 size report on A3 sheet. Two or more preview pages are printed on one sheet. If you choose this mode, you have to choose the sheet size (“Print on sheet”) as well.

• Scale mode. Report is printed on specified sheet. All report output is scaled. One preview page is printed on one sheet. If you choose this mode, you have to choose the sheet size (“Print on sheet”) as well.

After clicking 'Print' the report printing begins. If the “Print to file” flag is selected, file name is called. And report is saved to this file (file with *.prn extension. It contains a copy of information sent to printer).

Text Search in Reports

ClearVantage Xtreme Report Writer allows to search a set text line in a text in preview window. To perform that there

on toolbar (or its hotkey - Ctrl+F). After that search dialog appears:

Here you can set search line and options as well:

• Search from beginning – to search text from the beginning of document. Otherwise search will be performed from current page;

• Case sensitive – to distinguish letter cases (lower-case and capital types) on searching.

On clicking 'OK' text search is performed and the first found element is highlighted:

To continue search click F3. The following element will be highlighted.

Report Export

ClearVantage Xtreme Report Writer allows exporting a report to different formats for further editing, archiving, sending via e-mail, etc.

Export to 13 formats is supported. They are PDF, Open Document Spreadsheet, Open Document Text, Excel, XML, RTF, HTML, text, CSV, BMP, Jpeg, Tiff, and Gif. There is also the ability to send report via e-mail in any above-listed formats using ClearVantage Xtreme Report Writer.

Exports in ClearVantage Xtreme Report Writer use one of the following three export methods:

• Layer-by-layer – object transferring to resulting file is performed alternately. Expert accuracy is approximated to original;

• Table – on object transferring transitional matrix of object allocation is used. There is high accuracy to original based on the assumption that rules of creating correct report sample were followed (“Report Design References” chapter);

• Enveloping – for all report objects enveloping is performed on page image. There is full original accuracy. It is used on export to graphic formats.

Export to PDF Format

When exporting reports, PDFs use a layered export format. Also, Rich Text objects are exported as graphics. On exporting to PDF format the dialog box for output file parameter settings appears.

You can choose to enable the following export settings:

• Compressed – output file compressing. It reduces file size but increases export time;

• Embedded fonts – all fonts used in report will be contained in the PDF output file for correct file displaying on computers where these fonts may be absent. Output file size increases considerably;

• Background – export of graphic image assigned to a page into PDF file. It considerably increases output file size;

• Print optimized – output of graphic images in high resolution for further correct printing. This option enabling is necessary only when the document contains graphics and its printing is necessary. It considerably increases output file size;

• Outline – option is enabled when report outline is used. It enables export of the outline to the PDF document;

• Open after export – resulting file is opened right after export via PDF files viewing program such as Adobe Acrobat Reader which must be installed on the computer.

Export to Open Document

ClearVantage Xtreme Report Writer supports export to table (.ods file) and text (.odt file). These files can be opened in OpenOffice.

When exporting to these formats, the table export method is used. Rich Text objects are transfered as text and graphic images are exported as well.

On exporting to ODF format the dialog box for output file parameter settings appears.

You can choose to enable the following export settings:

• Continuous - generate continuous document without page breaks and page headers/footers;

• Page breaks – enables page breaks in document file;

• WYSIWYG – full compliance to report appearance. Disabling the option allows optimization, reducing the number of lines and columns in the output file;

• Background – export of graphic image assigned to a page into ODF file. It considerably increases output file size;

• Open after export – output file will be opened right after export.

Export to RTF Format

When exporting to RTF format the dialog box for output file parameter settings appears.

You can choose to enable the following export settings:

• Pictures – enables graphic images export to output file;

• Page breaks – enables page breaks in RTF file;

• WYSIWYG – full compliance to report appearance. Disabling the option allows optimization, reducing the number of lines and columns in the output file;

• Continuous - generate continuous document without page breaks and page headers/footers;

• Page header/footer - header/footer export mode. Variants are: Text (head/footer exported as usual text), Header/Footer (head/footer inserted in the document) and None (head/footer are not exported);

• Open after export – output file will be opened right after export via the RTF files such as Microsoft Word viewing program which must be installed on the computer

RichText objects are fully integrated into RTF format. The file appearance and size depend on report sample accuracy (“Report Design References” chapter);

Export to Excel

Exports to Excel use the table/diagram method. RichText objects are transferred as simple text, and graphic images transference is supported

On exporting to Excel format the dialogue box for output file parameter settings appears.

You can choose to enable the following export settings:

• Styles – transferring of text objects design styles into the table. Disabling increases exporting speed but worsens document appearance;

• Pictures – includes graphic images exported into the output table;

• As text – all objects are transferred into table/diagram as text ones. This option may be useful when transferring numeric fields with complicated formatting;

• Fast export – usage of optimized fast data transferring to Excel. This option disabling slows down data transferring but increases export compatibility on any errors during data transferring;

• Merge cells – cells integration in resulting table/diagram for achieving maximum correspondence to the original. Disabling increases exporting but reduces document appearance;

• WYSIWYG – full compliance to report appearance. On this option disabling the optimization for reducing the number of lines and columns in resulting table is performed;

• Background – export of filling color assigned to report page;

• Page breaks – includes page breaks in Excel;

• Open Excel after export – resulting file will be opened right after exporting into Excel as long as Excel is installed on your computer.

Export to XML Format

XML (Extensible Markup Language) is an expansible marking language. XML is intended for structured data storage and also for information interchange between different programs. ClearVantage Xtreme Report Writer uses XML format for data transferring into Excel 2003 and later.

The Excel export method uses the table/diagram method.

On exporting to XML format the dialog box for output file parameter settings appears.

You can choose to enable the following export settings:

• Continuous - generates continuous document without page breaks and page headers/footers;

• Page breaks – includes page breaks in resulting document;

• WYSIWYG – full compliance to report appearance. Disabling allows reducing the number of lines and columns in resulting table;

• Background – export of filling color assigned to report page;

• Open Excel after export – resulting file will be opened right after exporting into Excel as long as Excel is installed on your computer.

Export to CSV Format

CSV (Comma Seperated Value) files export using the table/diagram method. The report format design is not exported and graphic images are not supported.

On exporting to CSV format the dialog box for output file parameter settings appears.

You can choose to enable the following settings:

• OEM codepage – resulting file OEM coding selecting;

• Separator – values separator in files;

• Open after export – resulting file will be opened right after exporting via CSV files viewing program which must be installed on the computer.

Export to HTML Format

Exporting to HTML uses the table/diagram method. The export may consist of several files. Each graphic image will be a seperate file and Rich text objects export as simple text. Appearences and file volume depend greatly on report design (Report Design References Chapter).

On exporting to HTML format the dialogue box for output file parameter settings appears.

You can choose to enable the following export settings:

• Styles – transferring of text objects design styles. Disabling increases exporting but worsens document appearance;

• All in one folder – all additional files are saved in the same folder with main file;

• Page navigator – special navigator for fast shift between pages is created;

• Fixed width – blocking of automatic table/diagram width modifying on changing preview window size;

• Multipage – every page will be written to separate file;

• Background – export of graphic attributes assigned to report page;

• Pictures – includes graphic images exporting possibility;

• Open after export – resulting file will be opened right after exporting via a Web browser.

Export to Text Format

Exporting to text uses a table/diagram method. The report design is not saved in a text format and graphic images are not supported.

On exporting to text format the dialog box for output file parameter settings appears.

Export parameters:   - Page breaks – export of page breaks to resulting file;

• Empty lines – export of empty lines;

• Frames – export of text objects frames;

• OEM codepage – resulting file OEM coding selecting;

• Open after export – resulting file will be opened right after exporting via default text files viewing program which is installed on the computer.

Export to Jpeg, BMP, Gif, Tiff Graphic Formats

ClearVantage Xtreme Report Writer allows exporting information to the graphic formats of JPEG, BMP, GIF and TIFF. These formats use the export method of enveloping.

On exporting to one of above-named graphic formats the dialog box for image parameters setting appears.

You can choose to enable the following settings:

• Separate files – if option is enabled, every report page is exported to separate file. File name is given according to the selected one with addition of underlining and page number. Disabling this option requires heavy system resources.

• Monochrome – monochrome picture creation;

• Crop pages – after exporting blank area cropping will be performed along edges;

• JPEG quality – JPEG file compression ratio. Option is enabled only on exporting to JPEG format;

• Resolution – output graphic presentation resolution.

Sending a Report via E-mail

ClearVantage Xtreme Report Writer allows sending of a report by e-mail in any format you need. You do not need any additional programs to send mail.

On selecting export by e-mail the dialog box for setup of message and exporting format parameters appears. Before sending via e-mail, it is necessary to set parameters of mailbox owner. All these parameters are on the “Account” page tab:

• From Name – sender’s name;

• From Address – sender’s e-mail;

• Organization – sender’s organization;

• Signature – signature for mail. It may be automatically formed on clicking on “Build” button on condition that the earlier examined fields are filled;

• Host – SMTP server port;

• Port – SMTP server port;

• Login – access name for authorization on SMTP server, if its usage is necessary for mail sending via specified SMTP server; only plain authentication is supported;

• Password – authorization password;

• Remember properties – remember all parameters for further usage.

After filling in the necessary parameters for mail sending, you must fill in message parameters in “E-mail” page tab:

• Address – e-mail address of receiver. Earlier used addresses can be selected in drop-down menu;

• Subject – message subject. Earlier used topics can be selected in drop-down menu;

• Text – message text;

• Format – format of report attached to mail. One of the available export formats and also own format of ClearVantage Xtreme Report Writer report may be selected;

• Advanced export settings – on this option enabling after clicking on “OK” the dialogue box for selected export format setting appears. Otherwise default export parameters will be used.

Report Design References

It is significant that the quality of the export into any other format depends greatly on competent design of initial report. ClearVantage Xtreme Report Writer allows a great number of ways to manipulate objects during report output creation. This gives the advantage of fast development of any reports and their further printing. Printed document will look just as on display. And this is the primary intent of ClearVantage Xtreme Report Writer report generator usage. The downside of such development freedom is the complexity of exporting the ClearVantage Xtreme Report Writer document to different data formats, which have their own limits and requirements for information presentation, and are sometimes rather complex. In this chapter, special design requirements of reports intended for export to other data formats will be discussed.

Many formats, including HTML, XLS, XML, RTF and CSV, use table data presentation. Some of these formats do not allow cell crossing or arranging in layers when exporting. In contrast to freedom of report development in ClearVantage Xtreme Report Writer designer, export filters, as a rule, take into account these requirements when objects are transferred from ClearVantage Xtreme Report Writer report to necessary format. This is carried out by special algorithms which takes object crossings into account and their optimal placing. At object crossing points new columns and lines in the resulting output table appear. That is necessary for saving of the ClearVantage Xtreme Report Writer transferable objects exact positioning and for getting maximum resemblance between the result and original report. A large number of cross objects in report design, leads to an increased number of columns and lines in the resulting table. This leads to the need to edit the resulting file in its own editor for further use.

For example, on report design a slight crossing of two objects placed one under another on the same band. The number of records on report forming was 150. On export to RTF format 450 lines will be created (150 lines for each object and 150 ones for crossing). If we remove crossing there will be already 300 lines. In large reports and on huge number of objects the difference will be really tremendous. That, of course, will affect output file size.

           

Objects in the report Export to Excel - result

Remember this while designing, if you want to export your reports in any table format.

On creating tables in reports, keep an eye on neighboring cell’s borders to adjoin each other. It is important that cells do not cross and arrange in layers. The export filter algorithm will cut off cells but the export result may be far from desirable (you will see not exactly what you wanted to). Arrange objects in such a way that they are placed in line vertically as well as horizontally. Guidelines can help to perform this.

Using guidelines in the designer

To use guidelines in ClearVantage Xtreme Report Writer designer just click on the horizontal or vertical ruler limiting report page from the left and the top. Then, holding the mouse button down, drag the guideline to the required position on the page. You will be able to place objects immediately along guidelines horizontally and vertically.

Text objects grid alignment can also be helpful in case of cells overlapping. Keep an eye on enabling grid alignment in designer options. In order to simplify alignment you can extend the grid pitch. Setting of grid pitch and alignment can be found in designer menu “View” – ”Options” – ”Grid”.

For text framing it is better to use text object embedded properties instead of single graphic objects – lines, rectangles, etc. Try not to use background objects under transparent text objects.

Keeping these simple rules in mind will help you to create a report which will look perfect after export to any format using table (or table-based) exporting for data presentation.

Below there are some examples of correct and undesirable object arrangement on report design creation.

           

Bad                                                Good

Objects are displaced horizontally. It is necessary to use alignment according to extension lines as far as possible for objects to have the same horizontal coordinate.

Bad

Good

Objects are overlapping. In such a case on export to table/diagram format additional useless lines and columns and also 3 additional cells in crossing zone are created.

It is recommended to get acquainted with demo reports included with the ClearVantage Xtreme Report Writer installation for mastering basic methods of optimum report development.