Specification

Report XML template structure specification.

A report template is a single UTF-8 XML file. Its root element is <NCReport>, which contains the page options, data sources, parameters, variables, scripts, and the report sections. This chapter describes the structure of that file element by element, together with the attributes and values that the report engine recognizes.

The overall skeleton of a report definition file is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<NCReport version="2.0" name="myreport" type="report">
	<options>...</options>
	<datasources>...</datasources>
	<parameters>...</parameters>
	<variables>...</variables>
	<scripts>...</scripts>
	<pageheader>...</pageheader>
	<reportheader>...</reportheader>
	<details>...</details>
	<reportfooter>...</reportfooter>
	<pagefooter>...</pagefooter>
</NCReport>

Root element

The <NCReport> element is the root of every report definition. All other elements are its children.

XML syntax

<NCReport version="2.0" name="..." type="report">...</NCReport>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`version`	number		The template format version. The report engine requires version 2.0 or higher; older files are rejected as incompatible.
`name`	text		The report name.
`type`	`report`, `textdoc`, `label`	`report`	The report type: report (the default paged report), textdoc (text document print mode), label (label sheet report; see Label and Multi-Column Reports).

version

number

The template format version. The report engine requires version 2.0 or higher; older files are rejected as incompatible.

name

text

The report name.

type

report, textdoc, label

report

The report type: report (the default paged report), textdoc (text document print mode), label (label sheet report; see Label and Multi-Column Reports).

Page options

The <options> element holds the global page and report settings. Unlike most other elements, each option is stored as its own child element whose text content carries the value. All options are optional; when omitted, the engine uses its built-in default.

XML syntax

<options>
	<encoding>UTF-8</encoding>
	<orientation>portrait</orientation>
	<pagesize width="210" height="297">A4</pagesize>
	<topmargin>15</topmargin>
	<bottommargin>15</bottommargin>
	<leftmargin>20</leftmargin>
	<rightmargin>20</rightmargin>
	<fontname>Helvetica</fontname>
	<fontsize>10</fontsize>
	...
</options>

Elements

Element Values Default Description

Element	Values	Default	Description
`encoding`	encoding name	`UTF-8`	Character encoding of the report.
`language`	language codes	`00`	The list of language codes used by the report for multi-language templates.
`langrole`	`0`, `1`	`0`	Behavior when a translation is missing. 0 uses the default language, otherwise the value is left empty.
`orientation`	`portrait`, `landscape`	`portrait`	Page orientation.
`pagesize`	paper size name; `width`, `height` attributes in mm	`A4 (210 × 297)`	Paper size. The element text is the paper size name (for example A4), and the `width` and `height` attributes hold the custom size in millimeters (used when the name denotes a custom size).
`topmargin`	number (mm)	`15`	Top page margin in millimeters.
`bottommargin`	number (mm)	`15`	Bottom page margin in millimeters.
`leftmargin`	number (mm)	`20`	Left page margin in millimeters.
`rightmargin`	number (mm)	`20`	Right page margin in millimeters.
`backcolor`	#RRGGBB color	`#ffffff`	Page background color in #RRGGBB format.
`columns`	integer	`0`	Number of page columns. The value is stored in the report definition but is currently not used by the report engine.
`columnspace`	number (mm)	`0`	Space between page columns in millimeters. Stored but currently not used by the report engine.
`fontname`	font family	`Helvetica`	Name of the default report font.
`fontsize`	integer (pt)	`10`	Size of the default report font in points.
`fontstyle`	text		Style of the default report font.
`zoneSpacing`	number (mm)	`0`	Vertical spacing between zones in millimeters. See the Zones feature.
`zoneBreak`	`true`, `false`	`false`	If true, zones are allowed to break across pages.
`doublePass`	`true`, `false`	`false`	If true, the report is rendered in two passes (double-pass mode), for example when the total page count is required.
`subReportOnNewPage`	`true`, `false`	`false`	If true, each sub-report starts on a new page.
`subReportResetPageNo`	`true`, `false`	`false`	If true, the page number is reset for each sub-report.
`htmlBodyStyle`	CSS text	`{DEFAULT}`	CSS style applied to the HTML body when producing HTML output. (`htmlOpt` is also accepted for backward compatibility.)
`htmlHead`	HTML text		Content inserted into the HTML `<head>` element of HTML output.
`customdata`	text		Arbitrary custom data stored with the report definition.
`dataTrimming`	`true`, `false`	`true`	Record trimming for correct totals. When enabled (the default), the engine steps back one record at page breaks and group footers, so that the variable values shown in page footers, page headers, and group footers are correct. Set this to false to disable it. See Variables and Totals.
`updateOnlyCurrentDataSourceVariables`	`true`, `false`	`false`	If true, only the variables that belong to the current data source are updated.
`varErrorAlert`	`true`, `false`	`false`	If true, the engine alerts on variable evaluation errors.
`tocGen`	`true`, `false`	`false`	If true, a table of contents is generated.
`tocReset`	`true`, `false`	`false`	If true, the table of contents is reset.
`tocFile`	file name		File name for the generated table of contents.
`tocSectionTypes`	comma-separated integers		Comma-separated list of section type codes included in the table of contents.
`labelDirection`	`horizontal`, `vertical`	`horizontal`	Fill direction for label reports.
`labelColumnCount`	integer	`0`	Number of label columns.
`labelRowCount`	integer	`0`	Number of label rows.
`labelHGap`	number (mm)	`0`	Horizontal gap between labels in millimeters.
`labelVGap`	number (mm)	`0`	Vertical gap between labels in millimeters.
`labelWidth`	number (mm)		Label width in millimeters.
`labelHeight`	number (mm)		Label height in millimeters.
`endless`	`true`, `false`	`false`	If true, the report uses an endless (continuous, non-paginated) page.
`dpi`	integer (dpi)		Print resolution in dots per inch.
`emptyValue`	text		The value displayed for empty (null) data.
`fullPage`	`true`, `false`	`true`	Full-page mode. On by default; set to false to respect the printer’s non-printable margins.
`outputBaseName`	file name		Base file name used for the generated output file.

encoding

encoding name

UTF-8

Character encoding of the report.

language

language codes

00

The list of language codes used by the report for multi-language templates.

langrole

0, 1

0

Behavior when a translation is missing. 0 uses the default language, otherwise the value is left empty.

orientation

portrait, landscape

portrait

Page orientation.

pagesize

paper size name; width, height attributes in mm

A4 (210 × 297)

Paper size. The element text is the paper size name (for example A4), and the width and height attributes hold the custom size in millimeters (used when the name denotes a custom size).

topmargin

number (mm)

15

Top page margin in millimeters.

bottommargin

number (mm)

15

Bottom page margin in millimeters.

leftmargin

number (mm)

20

Left page margin in millimeters.

rightmargin

number (mm)

20

Right page margin in millimeters.

backcolor

#RRGGBB color

#ffffff

Page background color in #RRGGBB format.

columns

integer

0

Number of page columns. The value is stored in the report definition but is currently not used by the report engine.

columnspace

number (mm)

0

Space between page columns in millimeters. Stored but currently not used by the report engine.

fontname

font family

Helvetica

Name of the default report font.

fontsize

integer (pt)

10

Size of the default report font in points.

fontstyle

text

Style of the default report font.

zoneSpacing

number (mm)

0

Vertical spacing between zones in millimeters. See the Zones feature.

zoneBreak

true, false

false

If true, zones are allowed to break across pages.

doublePass

true, false

false

If true, the report is rendered in two passes (double-pass mode), for example when the total page count is required.

subReportOnNewPage

true, false

false

If true, each sub-report starts on a new page.

subReportResetPageNo

true, false

false

If true, the page number is reset for each sub-report.

htmlBodyStyle

CSS text

{DEFAULT}

CSS style applied to the HTML body when producing HTML output. (htmlOpt is also accepted for backward compatibility.)

htmlHead

HTML text

Content inserted into the HTML <head> element of HTML output.

customdata

text

Arbitrary custom data stored with the report definition.

dataTrimming

true, false

true

Record trimming for correct totals. When enabled (the default), the engine steps back one record at page breaks and group footers, so that the variable values shown in page footers, page headers, and group footers are correct. Set this to false to disable it. See Variables and Totals.

updateOnlyCurrentDataSourceVariables

true, false

false

If true, only the variables that belong to the current data source are updated.

varErrorAlert

true, false

false

If true, the engine alerts on variable evaluation errors.

tocGen

true, false

false

If true, a table of contents is generated.

tocReset

true, false

false

If true, the table of contents is reset.

tocFile

file name

File name for the generated table of contents.

tocSectionTypes

comma-separated integers

Comma-separated list of section type codes included in the table of contents.

labelDirection

horizontal, vertical

horizontal

Fill direction for label reports.

labelColumnCount

integer

0

Number of label columns.

labelRowCount

integer

0

Number of label rows.

labelHGap

number (mm)

0

Horizontal gap between labels in millimeters.

labelVGap

number (mm)

0

Vertical gap between labels in millimeters.

labelWidth

number (mm)

Label width in millimeters.

labelHeight

number (mm)

Label height in millimeters.

endless

true, false

false

If true, the report uses an endless (continuous, non-paginated) page.

dpi

integer (dpi)

Print resolution in dots per inch.

emptyValue

text

The value displayed for empty (null) data.

fullPage

true, false

true

Full-page mode. On by default; set to false to respect the printer’s non-printable margins.

outputBaseName

file name

Base file name used for the generated output file.

Data sources

Since the report generator builds a printable representation from data, the data source is one of the most important parts of the system. Data may come from an SQL query using Qt’s SQL database connection drivers, or from other sources: Text, XML, String list, Item model, or a custom data source written in Qt/C++. One report can contain multiple data sources, and each detail can be connected to its own data source. Whenever a data source is not assigned to any detail, the initial (first) row of data in the data source is used.

All data source definitions are wrapped in a single <datasources> element, and each individual source is a <datasource> child element. The attributes listed below are common to every data source type; type-specific attributes follow in each subsection.

Common tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`id`	text		Data source ID. Identification name of the data source. Details are assigned to the data source by this ID.
`type`	`sql`, `txt`, `xml`, `list`, `model`, `custom`		The data source type. Any other value is rejected as an invalid data source type.
`source`	`static`, `file`, `http`, `ftp`, `parameter`	`static`	The location of the data source definition. Depending on this value, the definition is read from the report file, an external file, a URL, or a parameter.
`openRole`	`begin`, `child`, `group`, `sub`	`begin`	When the data source is opened/updated: begin (opened once at the beginning of the report), child (a child data source updated by its parent through a data relation), group (updated on a group change), sub (a sub-report data source).
`parentID`	data source ID		If the data source is a child in a data relation (sub-query system), this is the ID of the parent data source.
`enabled`	`true`, `false`	`true`	Whether the data source is enabled.
`allowEmpty`	`true`, `false`	`true`	Whether the data source is allowed to return no rows. (The legacy `emptyIsForbidden` attribute is the inverse of this value.)
`primaryKeyColumn`	integer	`0`	The zero-based index of the primary-key column, used by the data relation system.
`headers`	comma-separated names		A comma-separated list of predefined column header names.
`briefDesc`	text		A short, human-readable description of the data source.

id

text

Data source ID. Identification name of the data source. Details are assigned to the data source by this ID.

type

sql, txt, xml, list, model, custom

The data source type. Any other value is rejected as an invalid data source type.

source

static, file, http, ftp, parameter

static

The location of the data source definition. Depending on this value, the definition is read from the report file, an external file, a URL, or a parameter.

openRole

begin, child, group, sub

begin

When the data source is opened/updated: begin (opened once at the beginning of the report), child (a child data source updated by its parent through a data relation), group (updated on a group change), sub (a sub-report data source).

parentID

data source ID

If the data source is a child in a data relation (sub-query system), this is the ID of the parent data source.

enabled

true, false

true

Whether the data source is enabled.

allowEmpty

true, false

true

Whether the data source is allowed to return no rows. (The legacy emptyIsForbidden attribute is the inverse of this value.)

primaryKeyColumn

integer

0

The zero-based index of the primary-key column, used by the data relation system.

headers

comma-separated names

A comma-separated list of predefined column header names.

briefDesc

text

A short, human-readable description of the data source.

SQL data source

SQL queries (the SQL data source) are the most common and widely used data sources for NCReport. They require an SQL database connection using Qt’s database driver plugins. The database connection can be either internal or external.

For an internal connection (the default), a valid database connection must be established by the application using NCReport before running the report. If an external connection is used, the connection parameters must be specified accordingly.

XML syntax

<datasource type="sql">[SQL query]</datasource>
<datasource type="sql" source="file">[query filename]</datasource>

Additional tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`connection`	`internal`, `external`	`internal`	Specifies the SQL database connection handling method. With an internal connection (the default), a valid database connection must be established by the application using NCReport before running the report. If an external connection is specified, the report generator connects to the database when opening the data source. In this case, the host, database, user, password, port connection parameters are used. (The values `global` and `private` are also accepted as synonyms of `internal` and `external`.)
`connID`	connection name		The name of the database connection that is used when the QSqlDatabase::addDatabase(…) method is called in the report engine. This ID is required for running the SQL query assigned to the data source.
`connOpt`	text		Extra connection options passed to the database driver (equivalent to QSqlDatabase::setConnectOptions()).
`driver`	`QDB2`, `QIBASE`, `QMYSQL`, `QOCI`, `QODBC`, `QPSQL`, `QSQLITE2`, `QSQLITE`, `QTDS`		The name of the Qt SQL database driver.
`host`	host name		Host name for the SQL database connection. Used only when an external connection is defined.
`database`	text		Database name for the SQL database connection. Used only when an external connection is defined.
`user`	text		User name for the SQL database connection. Used only when an external connection is defined.
`password`	text		Password for the SQL database connection. Used only when an external connection is defined.
`port`	integer		Port number for the SQL database connection. Used only when an external connection is defined.
`recordFilter`	text		An optional filter applied to the fetched records.
`forceUpdateOnStepBackRel`	`true`, `false`	`false`	If true, the data source is re-queried when a data relation steps back to a previous parent row.
`fwOnly`	`true`, `false`	`false`	If true, the query is treated as forward-only, which can improve performance and reduce memory use for large result sets.

connection

internal, external

internal

Specifies the SQL database connection handling method. With an internal connection (the default), a valid database connection must be established by the application using NCReport before running the report. If an external connection is specified, the report generator connects to the database when opening the data source. In this case, the host, database, user, password, port connection parameters are used. (The values global and private are also accepted as synonyms of internal and external.)

connID

connection name

The name of the database connection that is used when the QSqlDatabase::addDatabase(…) method is called in the report engine. This ID is required for running the SQL query assigned to the data source.

connOpt

text

Extra connection options passed to the database driver (equivalent to QSqlDatabase::setConnectOptions()).

driver

QDB2, QIBASE, QMYSQL, QOCI, QODBC, QPSQL, QSQLITE2, QSQLITE, QTDS

The name of the Qt SQL database driver.

host

host name

Host name for the SQL database connection. Used only when an external connection is defined.

database

text

Database name for the SQL database connection. Used only when an external connection is defined.

user

text

User name for the SQL database connection. Used only when an external connection is defined.

password

text

Password for the SQL database connection. Used only when an external connection is defined.

port

integer

Port number for the SQL database connection. Used only when an external connection is defined.

recordFilter

text

An optional filter applied to the fetched records.

forceUpdateOnStepBackRel

true, false

false

If true, the data source is re-queried when a data relation steps back to a previous parent row.

fwOnly

true, false

false

If true, the query is treated as forward-only, which can improve performance and reduce memory use for large result sets.

Text data source

Text and text files can be used as a data source for NCReport. The data columns of a text are usually delimited by a tab or another delimiter character. This kind of data source even makes it possible to avoid an SQL database connection. You must set the delimiter type; this delimiter separates the columns, and each row represents a data record. Text data sources can be static, stored in the XML definition, or a file.

XML syntax

<datasource type="txt">[static text]</datasource>
<datasource type="txt" source="file">[filename]</datasource>

XML data source

The Extensible Markup Language (XML) format can also be used as a data source for NCReport.

The following example shows what the data structure should look like:

Example

<textobject><textdata fileref="codes/xmltestdata.xml" /></textobject>

XML syntax

<datasource type="xml">...</datasource>

String list data source

It is also possible to use a QStringList as a data source for NCReport. Before running the report, a QStringList must be assigned to the specified data source, and it is also necessary to set a delimiter character to separate the columns in each list item, which represents a data record.

XML syntax

<datasource type="list"></datasource>

Additional tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`listID`	text		ID of the list. This identification name specifies the ID of the `QStringList` added to NCReport.

listID

text

ID of the list. This identification name specifies the ID of the QStringList added to NCReport.

Item model data source

Qt’s item model classes provide a generic model for storing custom data. For example, QStandardItemModel can be used as a repository for standard Qt data types. It is one of the Model/View classes and is part of Qt’s model/view framework. It is possible to use item models as a data source for NCReport. Before running the report, a QAbstractItemModel-based class must be created and assigned to the specified data source.

XML syntax

<datasource type="model"></datasource>

Additional tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`modelID`	text		ID of the model. This identification name specifies the ID of the model added to NCReport.

modelID

text

ID of the model. This identification name specifies the ID of the model added to NCReport.

Custom data source

Data is often stored in a special repository such as a list, array, etc. You can build your own data source class derived from the NCReportDataSource base class. It is an abstract class; you just have to implement the required methods.

XML syntax

<datasource type="custom"></datasource>

Data source relations

A child data source can be driven by a parent (master) data source, which is the basis of the master/detail (sub-query) system. The relation is established with two attributes: the child data source sets openRole="child" and points to its parent with parentID. The parent’s primary-key column and the child’s foreign-key column are matched so that, as the parent steps from row to row, the child data source is re-queried for the matching records. This relation is supported for SQL and Item Model data sources. See the Data Relation system chapter for a full description.

Report Parameters

Parameters are data pulled from outside the report generator. The application that calls the NCReport object passes information as parameters to the NCReport class via the addParameter(…) method. Parameters are evaluated within SQL queries, fields, and script expressions. Field objects may have a parameter data source type, so they can be presented as data in the report. Parameters are mostly used in queries. If you want to embed a parameter into a query or an expression, use this syntax:

$P{parametername}

Example of using a parameter in an SQL query:

SELECT productId, productName FROM db.products WHERE primaryKey=$P{parametername}

Parameters may also be stored statically in the report definition inside the <parameters> element. Each parameter is a <par> element (the long form <parameter> is also accepted), whose text content is the value and whose type attribute declares the data type.

XML syntax

<parameters>
	<par id="date_from" type="date">2026-01-01</par>
	<par id="limit" type="int">100</par>
	<par id="title" type="string">Sales report</par>
</parameters>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`id`	text		The name/ID of the parameter.
`type`	`string` (or `QString`), `int`, `bool`, `float`, `double` (or `numeric`), `long`, `longlong`, `date` (or `QDate`), `datetime` (or `QDateTime`)	`string`	The data type of the parameter value. If the type is unknown, the value is treated as a string.

id

text

The name/ID of the parameter.

type

string (or QString), int, bool, float, double (or numeric), long, longlong, date (or QDate), datetime (or QDateTime)

string

The data type of the parameter value. If the type is unknown, the value is treated as a string.

Variables

Variables are specific items of the report. They are special fields used for providing counts and totals. Each variable has a name, a function type, a data type, and an assigned data source column that the variable is based on.

Variables are defined inside the <variables> element, one <variable> element each. The text content of the element is the expression: either a plain data source column name (price or ds.price) or a script expression enclosed in <% %>. Do not use the $D{} syntax here.

XML syntax

<variables>
	<variable id="sumPrice" type="num" funcType="sum" scope="group" initValue="0">price</variable>
</variables>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`id`	text		The name/ID of the variable.
`type`	`num`	`num`	The data type of the variable. The writer stores num; the attribute is ignored when reading, since variables are always numeric.
`funcType`	`count`, `sum`, `average`, `std`, `min`, `max`	`count`	The aggregation function (see the function types below). Unknown values fall back to count.
`scope`	`report`, `page`, `group`	`report`	The scope at which the variable is reset. Unknown values fall back to report.
`initValue`	number	`0`	The initial (reset) value of the variable.

id

text

The name/ID of the variable.

type

num

The data type of the variable. The writer stores num; the attribute is ignored when reading, since variables are always numeric.

funcType

count, sum, average, std, min, max

count

The aggregation function (see the function types below). Unknown values fall back to count.

scope

report, page, group

report

The scope at which the variable is reset. Unknown values fall back to report.

initValue

number

0

The initial (reset) value of the variable.

The function types have the following meaning:

count: Increments by 1 for every row returned by the data source.
sum: Sums the values of the specified data source column. The values are converted to numbers.
average: Computes the average (mean) of the specified column’s values.
std: Computes the standard deviation of the specified column’s values.
min: Returns the smallest value of the specified column.
max: Returns the largest value of the specified column.

To embed a variable into an expression, use this syntax:

$V{variablename}

System Variables

System variables are special variables that provide report system information such as the page number, the current date/time, etc. for fields. The most frequently used system variables are listed below. For the complete list, see System variables.

Variable Description

Variable	Description
`pageno`	Returns the current page number
`pagecount`	Returns the total number of pages in the report. Available in double pass mode and in Text document printout mode.
`forcecopies`	Returns the total number of forced copies
`currentcopy`	Returns the current forced copy number (zero-based)
`currentrow`	Returns the current detail row number
`date`	Returns the current date
`time`	Returns the current time
`datetime`	Returns the timestamp
`appname`	Returns the name of this application
`applongname`	Returns the long name of this application
`appinfo`	Returns the full info string of this application
`appversion`	Returns the version of this application
`appcopyright`	Returns the copyright info of this application
`qtversion`	Returns the Qt version
`os`	Returns the operating system

pageno

Returns the current page number

pagecount

Returns the total number of pages in the report. Available in double pass mode and in Text document printout mode.

forcecopies

Returns the total number of forced copies

currentcopy

Returns the current forced copy number (zero-based)

currentrow

Returns the current detail row number

date

Returns the current date

time

Returns the current time

datetime

Returns the timestamp

appname

Returns the name of this application

applongname

Returns the long name of this application

appinfo

Returns the full info string of this application

appversion

Returns the version of this application

appcopyright

Returns the copyright info of this application

qtversion

Returns the Qt version

os

Returns the operating system

For variable fields, or to embed a system variable into an expression, use this syntax:

$V{systemvariablename}

Scripts

Named scripts are reusable script functions stored in the report definition. A script can be referenced from expressions (see Data/Script Expressions) by its ID using the $S{scriptID} syntax, which keeps complex or repeated logic in one place. Scripts are held in the <scripts> element, one <script> element each; the element text is the script code.

XML syntax

<scripts>
	<script id="ageGroup"><![CDATA[ if ($D{age}<18) "MINOR"; else "ADULT"; ]]></script>
</scripts>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`id`	text		The name/ID of the script, used to reference it as `$S{id}`.

id

text

The name/ID of the script, used to reference it as $S{id}.

Expressions

Since version 2.0, NCReport handles script expressions using Qt Script, the powerful feature introduced in Qt 4.3. Qt Script is based on the ECMAScript scripting language, as defined in the ECMA-262 standard. Fields and group expressions may be script code instead of a data source column. The report engine evaluates the specified script code each time the fields are refreshed. Report items can have a printWhen property. These are also script expressions that return a boolean result. To use a script expression in a field, the ftype="exp" field property must be specified.

References in expressions

Expressions can contain and evaluate references such as:

data source data
parameter
variable

References are always replaced with their current value before the expression is evaluated. The syntax of the references is as follows: $D{[data source.]column[,n]} data source column reference. Returns the current value of the data source column from the current row/record. If data source. is not specified, the current data source (assigned to the current detail) is used.

If n is specified, the data source is first positioned to the nth record. Works only if the ::seek( int ) method is defined in the appropriate data source class.

$P{parametername}: Parameter reference. Returns the value of the parameter by name/ID.
$V{variablename}: Variable reference. Returns the current value of the variable by name/ID.
$S{scriptID}: Script reference. Evaluates the named script and returns its result.

Using a script expression in a field:

"$D{db.productName}"+" "+"some string"+"$P{parametername}"

Using a script expression in the printWhen property:

$D{price}<1500

Quotation marks in expressions are required only when string data is used. Otherwise (i.e., for numbers) quotation marks are not necessary.

Report sections

Report sections are the representations of the function-specific areas inside the report. The whole report is built from sections. They are often recurring areas such as the detail, headers, and footers. The most important section is called Detail, since details can contain the fields that change row by row. Each section can contain all kinds of report items. An item’s coordinates are always relative to its parent section.

One report can contain the following sections: report header, report footer, page headers, page footers, group headers and footers, and details.

Common section properties

The following properties may appear on any section element. Section-specific properties are listed with each section below.

Attribute Values Default Description

Attribute	Values	Default	Description
`id`	text		Name/ID of the section, for identification purposes.
`height`	number (mm)		The height of the section in millimeters.
`autoHeight`	`true`, `false`	`false`	If true, the section height is calculated automatically from its content instead of using the fixed `height`.
`printWhen`	script expression		A logical script expression that controls whether the section is printed. If it is not empty, the engine evaluates it before rendering; the section is printed only when the expression returns true.
`startsOnNewPage`	`true`, `false`	`false`	If true, the section starts on a new page.
`pageBreakExp`	script expression		A script expression that, when it returns true, forces a page break at the section.
`repeatExp`	expression		A repeat expression; while it holds, the section is repeated (see repeated detail sections).
`notAlone`	`true`, `false`	`false`	If true, the section is not printed alone at the bottom of a page (keeps it together with related content).
`orphanedTolerance`	number (mm)	`0`	The tolerance, in millimeters, used to avoid orphaned sections near a page break.
`hideIfBlank`	`true`, `false`	`false`	If true, the section is hidden when it has no content.
`anchorToPageFooter`	`true`, `false`	`false`	If true, the section is anchored to the page footer.
`altBackRowColor`	#RRGGBB color	`#dcdcdc`	The alternating row background color in #RRGGBB format.
`altBackRowMode`	`disabled`, `odd`, `even`	`disabled`	The alternating background mode.
`useDefaultAltBackRowColor`	`true`, `false`	`true`	If true, the default alternating row color is used.
`parentId`	section ID		The ID of the parent section, used to build nested (child) detail sections.

id

text

Name/ID of the section, for identification purposes.

height

number (mm)

The height of the section in millimeters.

autoHeight

true, false

false

If true, the section height is calculated automatically from its content instead of using the fixed height.

printWhen

script expression

A logical script expression that controls whether the section is printed. If it is not empty, the engine evaluates it before rendering; the section is printed only when the expression returns true.

startsOnNewPage

true, false

false

If true, the section starts on a new page.

pageBreakExp

script expression

A script expression that, when it returns true, forces a page break at the section.

repeatExp

expression

A repeat expression; while it holds, the section is repeated (see repeated detail sections).

notAlone

true, false

false

If true, the section is not printed alone at the bottom of a page (keeps it together with related content).

orphanedTolerance

number (mm)

0

The tolerance, in millimeters, used to avoid orphaned sections near a page break.

hideIfBlank

true, false

false

If true, the section is hidden when it has no content.

anchorToPageFooter

true, false

false

If true, the section is anchored to the page footer.

altBackRowColor

#RRGGBB color

#dcdcdc

The alternating row background color in #RRGGBB format.

altBackRowMode

disabled, odd, even

disabled

The alternating background mode.

useDefaultAltBackRowColor

true, false

true

If true, the default alternating row color is used.

parentId

section ID

The ID of the parent section, used to build nested (child) detail sections.

Page headers are used to contain page headings. Page headers have the following characteristics:

Always printed at the top of a page
Always contain the first information printed on a page
Display only one (current) row of data returned by a data source
Only one allowed per page

XML syntax

<pageheader>...</pageheader>

Page footers are commonly used to close the pages. Page footers have the following characteristics:

Always printed at the bottom of a page
Display only one (current) row of data returned by a data source
Only one allowed per page
Usually used to display information such as the page number, report titles, and so on.

XML syntax

<pagefooter>...</pagefooter>

Report header

The report header is used to contain report headings. The report header has the following characteristics:

Always printed after the page header
Printed only once, at the beginning of the report
Displays only one (current) row of data returned by a data source

XML syntax

<reportheader>...</reportheader>

The report footer is commonly used to close the report. The report footer has the following characteristics:

Always printed before the page footer, at the end of the report
Displays only one (current) row of data returned by a data source
Only one allowed per report

XML syntax

<reportfooter>...</reportfooter>

Details

The core information in a report is displayed in its Detail section. This section is the most important part of the report, since it contains the row-by-row data from the data source. Detail sections have the following characteristics:

Generally printed in the middle of a page
Always contain the core information for a report
Display multiple rows of data returned by a data source
Generally contain fields or dynamic objects
Multiple independent details are allowed in one report, each detail after the other
Each detail is assigned to one specified data source

XML syntax

<detail>...</detail>

Structure:

<details>
	<detail datasource="ds1">
		<items>...</items>
		<groups>...</groups>
	</detail>
	<detail datasource="ds2">
		<items>...</items>
		<groups>...</groups>
	</detail>
	...
</details>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`datasource`	data source ID		The name/ID of the data source the detail section is assigned to.
`datasource2`	data source ID		The name/ID of an optional secondary data source for the detail section.

datasource

data source ID

The name/ID of the data source the detail section is assigned to.

datasource2

data source ID

The name/ID of an optional secondary data source for the detail section.

(The common section properties above, such as id and height, also apply.)

Group sections

While most reports can be defined using a single Detail section with multiple columns and rows of data, others require summary data, such as subtotals. For reports requiring summary data, the report writer supports Group sections. Group sections have the following characteristics:

Always associated with a Detail section
Defined by Group Headers and Group Footers
Group Headers always print above their Detail section
Group Footers always print below their Detail section
Reference the database column on which Group Headers and Group Footers will break
Force a new Group Header each time the value of the referenced column changes
Force a new Group Footer each time the value of the referenced column changes
Unlimited number of group levels allowed

The groups added to the XML definition are shown in the order in which you added them. They are structured hierarchically. The first group is the primary group level, the second one is the second level, and so on. The added group sections appear in the designer after you apply the group settings.

XML syntax

<groups>
	<group id="g1" groupExp="$D{category}">
		<groupheader>...</groupheader>
		<groupfooter>...</groupfooter>
	</group>
</groups>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`id`	text		Identification label for naming the group.
`groupExp`	expression, column name, or `%CONST`		Group expression or data source column. Specifies the name of the data source column on which Group Headers and Group Footers will break. The expression can also be a constant value; in this case the detail rows do not break. The constant group expression is `%CONST`.
`resetVariables`	comma-separated variable IDs		A comma-separated list of variable IDs to reset when the current group ends. This is very useful when, for example, you want to reset a total or a count variable at each group change.
`reprintHeader`	`true`, `false`	`false`	If true, the group header is reprinted at the top of the next page when the group spans a page break.
`startsOnNewPage`	`true`, `false`	`false`	If true, each new group starts on a new page.
`pageBreakExp`	script expression		A script expression that forces a page break within the group when it returns true.
`resetPageNo`	`true`, `false`	`false`	If true, the page number is reset at each group change.
`printLock`	`true`, `false`	`true`	Controls whether print locking is allowed for the group. Set to false to disallow it.

id

text

Identification label for naming the group.

groupExp

expression, column name, or %CONST

Group expression or data source column. Specifies the name of the data source column on which Group Headers and Group Footers will break. The expression can also be a constant value; in this case the detail rows do not break. The constant group expression is %CONST.

resetVariables

comma-separated variable IDs

A comma-separated list of variable IDs to reset when the current group ends. This is very useful when, for example, you want to reset a total or a count variable at each group change.

reprintHeader

true, false

false

If true, the group header is reprinted at the top of the next page when the group spans a page break.

startsOnNewPage

true, false

false

If true, each new group starts on a new page.

pageBreakExp

script expression

A script expression that forces a page break within the group when it returns true.

resetPageNo

true, false

false

If true, the page number is reset at each group change.

printLock

true, false

true

Controls whether print locking is allowed for the group. Set to false to disallow it.

Group header

Group headers are used to contain group heading items such as column head titles. They are always printed above their Detail section. A new Group Header is forced each time the value of the referenced column changes.

XML syntax

<groupheader>...items...</groupheader>

Group footer

Group footers are used to contain group footing items such as totals and subtotals. They are always printed below their Detail section. A new Group Footer is forced each time the value of the referenced column changes.

XML syntax

<groupfooter>...items...</groupfooter>

Report items

Report items are the visual building blocks placed inside sections. The following item types are available: label, field, text (HTML text), line, rectangle, ellipse, image, barcode, graph (custom item), crosstab, table (item-view table), graphicsview, and chart.

Common item properties

Most item types share a set of common properties. They are listed here once; the sections that follow describe only the properties that are specific to each item.

Attribute Values Default Description

Attribute	Values	Default	Description
`id`	text		Item ID for internal identification.
`posX`	number (mm)		The item’s X coordinate in millimeters, relative to the current section.
`posY`	number (mm)		The item’s Y coordinate in millimeters, relative to the current section.
`width`	number (mm)		The item’s width in millimeters.
`height`	number (mm)		The item’s height in millimeters.
`zValue`	integer	`0`	An integer Z-order value that determines the stacking order of sibling (neighboring) items.
`resource`	item-specific		The source of the item’s content. The accepted values depend on the item type (see each item below).
`printWhen`	script expression		A logical script expression that controls the item’s visibility. If it is not empty, the engine evaluates it before each rendering; the item is shown when the expression returns true (or 1) and hidden otherwise.
`template`	`true`, `false`	`false`	If true, the item’s content is treated as a template, so data references are embedded directly in the text without a script.
`canBreak`	`true`, `false`	`false`	If true, the item is allowed to break across a page boundary.
`autoHeight`	`true`, `false`	`false`	If true, the item’s height is calculated automatically from its content.
`pageBreakAfter`	`true`, `false`	`false`	If true, a page break is forced after the item.
`clickable`	`true`, `false`	`false`	If true, the item is clickable in interactive output.
`description`	text		A free-text description of the item.
`zoneID`	integer	`0`	The zone the item belongs to. Items that share a zone ID form a virtual band inside the section (see the Zones feature).
`pinToLeft`	`true`, `false`	`false`	If true, the item is pinned to the left edge.
`pinToRight`	`true`, `false`	`false`	If true, the item is pinned to the right edge.

id

text

Item ID for internal identification.

posX

number (mm)

The item’s X coordinate in millimeters, relative to the current section.

posY

number (mm)

The item’s Y coordinate in millimeters, relative to the current section.

width

number (mm)

The item’s width in millimeters.

height

number (mm)

The item’s height in millimeters.

zValue

integer

0

An integer Z-order value that determines the stacking order of sibling (neighboring) items.

resource

item-specific

The source of the item’s content. The accepted values depend on the item type (see each item below).

printWhen

script expression

A logical script expression that controls the item’s visibility. If it is not empty, the engine evaluates it before each rendering; the item is shown when the expression returns true (or 1) and hidden otherwise.

template

true, false

false

If true, the item’s content is treated as a template, so data references are embedded directly in the text without a script.

canBreak

true, false

false

If true, the item is allowed to break across a page boundary.

autoHeight

true, false

false

If true, the item’s height is calculated automatically from its content.

pageBreakAfter

true, false

false

If true, a page break is forced after the item.

clickable

true, false

false

If true, the item is clickable in interactive output.

description

text

A free-text description of the item.

zoneID

integer

0

The zone the item belongs to. Items that share a zone ID form a virtual band inside the section (see the Zones feature).

pinToLeft

true, false

false

If true, the item is pinned to the left edge.

pinToRight

true, false

false

If true, the item is pinned to the right edge.

Dynamic position and size. Items support data-driven position and size. When one of these properties is set, its value is an expression (a data source column, parameter, variable, or script) that supplies the measurement in millimeters. When left empty, the corresponding static value is used.

Attribute Values Default Description

Attribute	Values	Default	Description
`dynPosX`	expression		The source of the item’s X position.
`dynPosY`	expression		The source of the item’s Y position.
`dynWidth`	expression		The source of the item’s width.
`dynHeight`	expression		The source of the item’s height.
`dynOffset`	`true`, `false`	`false`	If true, the dynamic values are relative to the item’s original static position (offset mode); otherwise they are explicit coordinates.

dynPosX

expression

The source of the item’s X position.

dynPosY

expression

The source of the item’s Y position.

dynWidth

expression

The source of the item’s width.

dynHeight

expression

The source of the item’s height.

dynOffset

true, false

false

If true, the dynamic values are relative to the item’s original static position (offset mode); otherwise they are explicit coordinates.

Font properties. Text-bearing items (label, field, HTML text) support the following font properties.

Attribute Values Default Description

Attribute	Values	Default	Description
`fontName`	font family		Font family / face name. When omitted, the report’s default font (`fontname` page option) is used.
`fontSize`	number (pt)		Font size in points.
`fontWeight`	`light`, `normal`, `demibold`, `bold`, `black`	`normal`	Font weight.
`fontItalic`	`true`, `false`	`false`	If true, the font is italic.
`fontUnderline`	`true`, `false`	`false`	If true, the text is underlined.
`fontStrikeOut`	`true`, `false`	`false`	If true, the text is struck out.
`letterSpacing`	number		Absolute letter spacing.
`capital`	integer		Capitalization mode (numeric code, following Qt’s `QFont::Capitalization`).

fontName

font family

Font family / face name. When omitted, the report’s default font (fontname page option) is used.

fontSize

number (pt)

Font size in points.

fontWeight

light, normal, demibold, bold, black

normal

Font weight.

fontItalic

true, false

false

If true, the font is italic.

fontUnderline

true, false

false

If true, the text is underlined.

fontStrikeOut

true, false

false

If true, the text is struck out.

letterSpacing

number

Absolute letter spacing.

capital

integer

Capitalization mode (numeric code, following Qt’s QFont::Capitalization).

Alignment. Alignment can be given either as a single numeric alignment value (a combination of Qt alignment flags) or with the separate horizontal and vertical attributes below (kept for backward compatibility).

Attribute Values Default Description

Attribute	Values	Description
`alignment`	integer (Qt flags)	Numeric combination of Qt alignment flags.
`alignmentH`	`left`, `right`, `center`	Horizontal alignment.
`alignmentV`	`top`, `center`, `bottom`	Vertical alignment.

alignment

integer (Qt flags)

Numeric combination of Qt alignment flags.

alignmentH

left, right, center

Horizontal alignment.

alignmentV

top, center, bottom

Vertical alignment.

Line (pen) and fill (brush) properties. Shape items (line, rectangle, ellipse) and bordered items use these.

Attribute Values Default Description

Attribute	Values	Default	Description
`lineColor`	#RRGGBB color		Line/outline color in #RRGGBB format.
`lineWidth`	number (mm)		Line/outline width in millimeters.
`lineStyle`	`solid`, `dash`, `dot`, `dashdot`, `dashdotdot`, `nopen`	`solid`	Line drawing style. (no and none are also accepted for no line.)
`fillColor`	#RRGGBB color		Fill color in #RRGGBB format.
`fillStyle`	`no`, `solid`, `dense1` … `dense7`, `hor`, `ver`, `cross`, `bdiag`, `fdiag`, `diagcross`	`no`	Fill (brush) pattern. The dense patterns are `dense1`, `dense2`, `dense3`, `dense4`, `dense5`, `dense6`, and `dense7`.

lineColor

#RRGGBB color

Line/outline color in #RRGGBB format.

lineWidth

number (mm)

Line/outline width in millimeters.

lineStyle

solid, dash, dot, dashdot, dashdotdot, nopen

solid

Line drawing style. (no and none are also accepted for no line.)

fillColor

#RRGGBB color

Fill color in #RRGGBB format.

fillStyle

no, solid, dense1 … dense7, hor, ver, cross, bdiag, fdiag, diagcross

no

Fill (brush) pattern. The dense patterns are dense1, dense2, dense3, dense4, dense5, dense6, and dense7.

Text label

The Label represents simple text or label items. Label items are used to display descriptive information in a report definition, such as titles, headings, etc. Labels are static items; their values do not change when rendering the report.

XML syntax

<label>Text label...</label>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`forecolor`	#RRGGBB color		The foreground (text) color in #RRGGBB format.
`backcolor`	#RRGGBB color		The background color in #RRGGBB format.
`bgMode`			The background drawing mode.
`wordbreak`	`true`, `false`	`false`	If true, long text wraps at word boundaries.
`wrapanywhere`	`true`, `false`	`false`	If true, text may wrap anywhere, not only at word boundaries.
`elide`	`none`, `left`, `mid`, `right`	`none`	How text is elided (shortened with an ellipsis) when it does not fit.
`rotation`	integer (degrees)	`0`	Text rotation in degrees.
`hideRepeated`	`true`, `false`	`false`	If true, the value is hidden when it repeats the previous displayed value. This option takes effect for fields only; see Hiding Repeated Values.
`fillchar`	character	`(space)`	The fill character used for padding.
`lang`	language code		The language code of the label text (for multi-language reports).
`tr`	`true`, `false`		If true, the label text is marked for translation.

forecolor

#RRGGBB color

The foreground (text) color in #RRGGBB format.

backcolor

#RRGGBB color

The background color in #RRGGBB format.

bgMode

The background drawing mode.

wordbreak

true, false

false

If true, long text wraps at word boundaries.

wrapanywhere

true, false

false

If true, text may wrap anywhere, not only at word boundaries.

elide

none, left, mid, right

none

How text is elided (shortened with an ellipsis) when it does not fit.

rotation

integer (degrees)

0

Text rotation in degrees.

hideRepeated

true, false

false

If true, the value is hidden when it repeats the previous displayed value. This option takes effect for fields only; see Hiding Repeated Values.

fillchar

character

(space)

The fill character used for padding.

lang

language code

The language code of the label text (for multi-language reports).

tr

true, false

If true, the label text is marked for translation.

(The common item properties, including the font and alignment properties, also apply.)

Field

The field is the core report item. It represents data field objects. By data type, fields may be text, numeric, or date. Field items are used to pull dynamically generated data into a report from the specified data source, such as the database the report generator uses. For example, a field item may be used to present SQL data, variables, and parameters. NCReport handles data formatting for the different types of fields, such as numbers and text.

XML syntax

<field>[data sourcename.]column</field>
<field>[expression]</field>
<field>[parametername]</field>
<field>[variablename]</field>
<field>[system variablename]</field>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`type`	`txt`, `num`, `date`, `bool`		The field’s base data type: txt (text data), num (numeric data — the numeric formatting options apply only to this type), date (date data — the date formatting options apply only to this type), bool (boolean data, rendered as Yes/True or No/False).
`ftype`	`ds` (or `sql`), `par`, `var`, `sys`, `exp`, `tpl`		The field’s source type; it determines where the field’s value comes from: ds (or sql — from the default or specified data source), par (from a parameter), var (from a variable), sys (from a system variable), exp (evaluates a script expression), tpl (a template that embeds data references in text). Unknown values are treated as ds.
`formatting`	`true`, `false`	`false`	If the field’s data type is numeric, this option controls whether number formatting is applied.
`numwidth`	integer	`0`	The minimum field width, in digits, that the value is padded to using `fillchar`. A positive value produces right-aligned text; a negative value produces left-aligned text. Works only when number formatting is on.
`format`	`e`, `E`, `f`, `g`, `G`	`f`	A one-character numeric format code. With e, E, and f, `precision` is the number of digits after the decimal point; with g and G, `precision` is the maximum number of significant digits. Used by the `QString::arg(double a, int fieldWidth, char format, int precision, const QChar &fillChar)` function.
`precision`	integer	`-1`	The number of digits after the decimal point for numeric data.
`fillchar`	character	`(space)`	The padding character used together with `numwidth`.
`numChars`	integer	`0`	If greater than zero, limits the number of characters taken from the value.
`dateFormat`	date format string		Date formatting expression, using the same format as QDate::toString(). Works only when the field type is date.
`localized`	`true`, `false`	`false`	Whether localization is applied. Works for numeric data only.
`blankifzero`	`true`, `false`	`false`	If true, the field is left blank when its value is zero.
`ssifzero`	`true`, `false`	`false`	If true, a substitution string is displayed instead of the value when the value is zero.
`ssifzero_str`	text		The substitution string displayed when `ssifzero` is on and the value is zero.
`usedsapproles`	`true`, `false`	`false`	If true, the field takes its appearance (colors, font) from the data source’s appearance roles (for example, Qt item-model roles).
`arg`	template string		A QString::arg(…) template string. The field’s value replaces the first `%1` occurrence in this string. A `%` may be followed by an `L` to produce a localized representation, using the default locale set by QLocale::setDefault() (or the "C" locale if none was set).

type

txt, num, date, bool

The field’s base data type: txt (text data), num (numeric data — the numeric formatting options apply only to this type), date (date data — the date formatting options apply only to this type), bool (boolean data, rendered as Yes/True or No/False).

ftype

ds (or sql), par, var, sys, exp, tpl

The field’s source type; it determines where the field’s value comes from: ds (or sql — from the default or specified data source), par (from a parameter), var (from a variable), sys (from a system variable), exp (evaluates a script expression), tpl (a template that embeds data references in text). Unknown values are treated as ds.

formatting

true, false

false

If the field’s data type is numeric, this option controls whether number formatting is applied.

numwidth

integer

0

The minimum field width, in digits, that the value is padded to using fillchar. A positive value produces right-aligned text; a negative value produces left-aligned text. Works only when number formatting is on.

format

e, E, f, g, G

f

A one-character numeric format code. With e, E, and f, precision is the number of digits after the decimal point; with g and G, precision is the maximum number of significant digits. Used by the QString::arg(double a, int fieldWidth, char format, int precision, const QChar &fillChar) function.

precision

integer

-1

The number of digits after the decimal point for numeric data.

fillchar

character

(space)

The padding character used together with numwidth.

numChars

integer

0

If greater than zero, limits the number of characters taken from the value.

dateFormat

date format string

Date formatting expression, using the same format as QDate::toString(). Works only when the field type is date.

localized

true, false

false

Whether localization is applied. Works for numeric data only.

blankifzero

true, false

false

If true, the field is left blank when its value is zero.

ssifzero

true, false

false

If true, a substitution string is displayed instead of the value when the value is zero.

ssifzero_str

text

The substitution string displayed when ssifzero is on and the value is zero.

usedsapproles

true, false

false

If true, the field takes its appearance (colors, font) from the data source’s appearance roles (for example, Qt item-model roles).

arg

template string

A QString::arg(…) template string. The field’s value replaces the first %1 occurrence in this string. A % may be followed by an L to produce a localized representation, using the default locale set by QLocale::setDefault() (or the "C" locale if none was set).

(The common item properties, including the font and alignment properties, also apply.)

HTML Text

HTML Text represents rich text in HTML format.

XML syntax

<text>Static (encoded) HTML text</text>
<text>[data source].column</text>
<text>[filename]</text>

Tag properties

Attribute Values Default Description

Attribute	Values	Description
`forecolor`	#RRGGBB color	The foreground color in #RRGGBB format. Takes effect only if the font settings are enabled for the item.
`useFont`	`true`, `false`	If true, the item’s own font settings are applied to the text.
`markdown`	`true`, `false`	If true, the content is interpreted as Markdown rather than HTML.
`plain`	`true`, `false`	If true, the content is treated as plain text.
`editorMode`	`0`, `1`	The editor mode used for the text content: 0 selects the rich-text editor, any other value the source-code editor.

forecolor

#RRGGBB color

The foreground color in #RRGGBB format. Takes effect only if the font settings are enabled for the item.

useFont

true, false

If true, the item’s own font settings are applied to the text.

markdown

true, false

If true, the content is interpreted as Markdown rather than HTML.

plain

true, false

If true, the content is treated as plain text.

editorMode

0, 1

The editor mode used for the text content: 0 selects the rich-text editor, any other value the source-code editor.

(The common item properties, including the font properties, also apply.)

Line

The Line option enables you to create Line items. In general, Line items are used to draw vertical and horizontal lines for headings, to underline titles, and so on. Lines are defined by their start and end point coordinates.

XML syntax

<line></line>

Tag properties

Attribute Values Default Description

Attribute	Values	Description
`fromX`	number (mm)	X coordinate of the start point of the line in millimeters, relative to the current section.
`fromY`	number (mm)	Y coordinate of the start point of the line in millimeters, relative to the current section.
`toX`	number (mm)	X coordinate of the end point of the line in millimeters, relative to the current section.
`toY`	number (mm)	Y coordinate of the end point of the line in millimeters, relative to the current section.

fromX

number (mm)

X coordinate of the start point of the line in millimeters, relative to the current section.

fromY

number (mm)

Y coordinate of the start point of the line in millimeters, relative to the current section.

toX

number (mm)

X coordinate of the end point of the line in millimeters, relative to the current section.

toY

number (mm)

Y coordinate of the end point of the line in millimeters, relative to the current section.

(The common line/pen properties — lineColor, lineWidth, lineStyle — and the common item properties also apply.)

Rectangle

The Rectangle option enables you to create Rectangle items. Rectangles are usually used to draw boxes or borders around a specified area. A rectangle makes box drawing easier than drawing four separate lines.

XML syntax

<rectangle></rectangle>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`roundX`	integer	`0`	Horizontal corner rounding radius.
`roundY`	integer	`0`	Vertical corner rounding radius.

roundX

integer

0

Horizontal corner rounding radius.

roundY

integer

0

Vertical corner rounding radius.

(The common line/pen and fill/brush properties, together with the common item properties, also apply.)

Ellipse

The Ellipse item draws an ellipse or a circle. Like the rectangle, it uses the common line (pen) and fill (brush) properties.

XML syntax

<ellipse></ellipse>

Tag properties

(The common line/pen and fill/brush properties, together with the common item properties, apply.)

Image

The Image option enables you to create Image items. Image items are used to insert either static or dynamic images into a report definition. Static images, such as a company logo often displayed in the Report Header, can be loaded from a static file or from the report definition. Dynamic images can be loaded from the specified SQL data source.

XML syntax

<image>[image in Base64-encoded format]</image>
<image>[image file name]</image>
<image>[data source.]column</image>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`resource`	`static`, `datasource`, `file`		The source of the image: static (loaded from the report definition; the image is stored Base64-encoded in the XML), datasource (loaded from the data source, e.g. an SQL database), file (loaded from the specified file, given with a full path or relative to the program’s directory).
`format`	`b64`, `bin`, `svg`		The encoding of a static image: b64 (Base64-encoded raster image), bin (binary), svg (SVG vector image). (The numeric codes `1`, `0`, and `2` are also accepted.)
`scaling`	`true`, `false`	`true`	Whether the image is scaled. (The current report engine ignores this attribute when reading and always scales the image.)
`aspectRatio`	`ignore`, `keep`, `expand`	`keep`	When scaling is on, this controls how the aspect ratio is handled: ignore (scaled freely, aspect ratio not preserved), keep (scaled as large as possible inside the rectangle while preserving the aspect ratio), expand (scaled as small as possible while covering the rectangle and preserving the aspect ratio).
`transformMode`	`fast`, `smooth`	`fast`	The scaling quality: fast (fast transformation) and smooth (smooth transformation).

resource

static, datasource, file

The source of the image: static (loaded from the report definition; the image is stored Base64-encoded in the XML), datasource (loaded from the data source, e.g. an SQL database), file (loaded from the specified file, given with a full path or relative to the program’s directory).

format

b64, bin, svg

The encoding of a static image: b64 (Base64-encoded raster image), bin (binary), svg (SVG vector image). (The numeric codes 1, 0, and 2 are also accepted.)

scaling

true, false

true

Whether the image is scaled. (The current report engine ignores this attribute when reading and always scales the image.)

aspectRatio

ignore, keep, expand

keep

When scaling is on, this controls how the aspect ratio is handled: ignore (scaled freely, aspect ratio not preserved), keep (scaled as large as possible inside the rectangle while preserving the aspect ratio), expand (scaled as small as possible while covering the rectangle and preserving the aspect ratio).

transformMode

fast, smooth

fast

The scaling quality: fast (fast transformation) and smooth (smooth transformation).

(The common item properties also apply.)

Barcode

The Barcode option enables you to create barcodes. Barcodes are rendered through the Zint barcode library, so a wide range of symbologies is supported. Barcodes may be either static or dynamic items, similar to images: static barcodes read their value from the report definition, while dynamic barcodes are loaded from the specified data source.

XML syntax

<barcode>[code]</barcode>
<barcode>[data source.]column</barcode>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`resource`	`static`, `datasource`		The source of the barcode: static (the code is stored in the report definition) and datasource (the code is loaded from the data source).
`barcodeType`	integer (Zint symbol ID)	`13`	The barcode symbology, given as the numeric Zint symbol ID. (The legacy values EAN13, EAN, and EANX are accepted for backward compatibility and map to the default symbology.)
`code`	text		The static barcode value.
`showText`	`true`, `false`	`true`	Whether the human-readable text is shown beneath the barcode.
`foreColor`	#RRGGBB color		The barcode foreground color in #RRGGBB format.
`backColor`	#RRGGBB color		The barcode background color in #RRGGBB format.
`rotation`	integer (degrees)		The barcode rotation in degrees.
`scale`	number		The rendering scale factor. This is useful when printing barcodes to a high-resolution device such as a printer.
`whiteSpace`	integer		The quiet-zone (white space) width around the barcode.
`borderType`	integer		The border type of the barcode.
`borderWidth`	integer		The border width of the barcode.
`fontSize`	number (pt)		The font size, in points, of the barcode’s human-readable text.

resource

static, datasource

The source of the barcode: static (the code is stored in the report definition) and datasource (the code is loaded from the data source).

barcodeType

integer (Zint symbol ID)

13

The barcode symbology, given as the numeric Zint symbol ID. (The legacy values EAN13, EAN, and EANX are accepted for backward compatibility and map to the default symbology.)

code

text

The static barcode value.

showText

true, false

true

Whether the human-readable text is shown beneath the barcode.

foreColor

#RRGGBB color

The barcode foreground color in #RRGGBB format.

backColor

#RRGGBB color

The barcode background color in #RRGGBB format.

rotation

integer (degrees)

The barcode rotation in degrees.

scale

number

The rendering scale factor. This is useful when printing barcodes to a high-resolution device such as a printer.

whiteSpace

integer

The quiet-zone (white space) width around the barcode.

borderType

integer

The border type of the barcode.

borderWidth

integer

The border width of the barcode.

fontSize

number (pt)

The font size, in points, of the barcode’s human-readable text.

(The common item properties also apply. Additional advanced Zint options — such as mode, secure, cols, vers, primary, opt1, opt2, and opt3 — are also stored when set, for symbologies that need them.)

Cross tab

The Cross tab item renders a cross-tabulation (pivot) table from a data source: it summarizes data across row and column dimensions with aggregated values in the cells.

XML syntax

<crosstab></crosstab>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`datasource`	data source ID		The name/ID of the data source the cross tab is built from.
`isPivot`	`true`, `false`	`false`	If true, the item works in pivot-table mode.
`ptRow`	column name		The data column used as the pivot row dimension.
`ptColumn`	column name		The data column used as the pivot column dimension.
`ptValue`	column name		The data column used as the pivot value.
`ptAgg`	integer	`1`	The aggregation function applied to the pivot value, given as a numeric code.
`ptSort`	`true`, `false`	`false`	The sort order applied to the pivot: if true, the pivot is sorted automatically.
`showColHeader`	`true`, `false`	`true`	Whether the column header is shown.
`showRowHeader`	`true`, `false`	`true`	Whether the row header is shown.
`showBottomSummary`	`true`, `false`	`true`	Whether the bottom summary row is shown.
`showSideSummary`	`true`, `false`	`true`	Whether the side summary column is shown.
`cellPadding`	number (mm)	`0`	The cell padding.
`cellSpacing`	number (mm)	`0`	The spacing between cells.
`leftMargin`	number (mm)	`0`	The left margin of the table.
`rightMargin`	number (mm)	`0`	The right margin of the table.
`topMargin`	number (mm)	`0`	The top margin of the table.
`bottomMargin`	number (mm)	`0`	The bottom margin of the table.
`autoWidth`	`true`, `false`		If true, the column widths are calculated automatically. (Currently not read by the report engine.)
`autoHeight`	`true`, `false`		If true, the row heights are calculated automatically. (Currently not read by the report engine.)
`breakTable`	`true`, `false`	`true`	If true, the table may break across pages.

datasource

data source ID

The name/ID of the data source the cross tab is built from.

isPivot

true, false

false

If true, the item works in pivot-table mode.

ptRow

column name

The data column used as the pivot row dimension.

ptColumn

column name

The data column used as the pivot column dimension.

ptValue

column name

The data column used as the pivot value.

ptAgg

integer

1

The aggregation function applied to the pivot value, given as a numeric code.

ptSort

true, false

false

The sort order applied to the pivot: if true, the pivot is sorted automatically.

showColHeader

true, false

true

Whether the column header is shown.

showRowHeader

true, false

true

Whether the row header is shown.

showBottomSummary

true, false

true

Whether the bottom summary row is shown.

showSideSummary

true, false

true

Whether the side summary column is shown.

cellPadding

number (mm)

0

The cell padding.

cellSpacing

number (mm)

0

The spacing between cells.

leftMargin

number (mm)

0

The left margin of the table.

rightMargin

number (mm)

0

The right margin of the table.

topMargin

number (mm)

0

The top margin of the table.

bottomMargin

number (mm)

0

The bottom margin of the table.

autoWidth

true, false

If true, the column widths are calculated automatically. (Currently not read by the report engine.)

autoHeight

true, false

If true, the row heights are calculated automatically. (Currently not read by the report engine.)

breakTable

true, false

true

If true, the table may break across pages.

(The common item properties also apply.)

Table view

The Table item renders the contents of a Qt item-view / item-model as a table. It is useful for embedding a QAbstractItemModel-based model or a QTableView directly in the report.

XML syntax

<table></table>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`datasource`	data source ID		The name/ID of the data source the table is built from.
`model`	model ID		The ID of the item model to render.
`tableView`	view ID		The ID of the table view to render.
`showHeaderH`	`true`, `false`	`true`	Whether the horizontal (column) header is shown.
`showHeaderV`	`true`, `false`	`true`	Whether the vertical (row) header is shown.
`showBorder`	`true`, `false`	`true`	Whether the table border is shown.
`alternateRowBack`	`true`, `false`	`false`	If true, alternating row background colors are used.
`autoRowHeight`	`true`, `false`	`false`	If true, row heights are calculated automatically.
`cellPadding`	number (mm)	`0`	The cell padding.
`cellSpacing`	number (mm)	`0`	The spacing between cells.
`leftMargin`	number (mm)	`0`	The left margin of the table.
`rightMargin`	number (mm)	`0`	The right margin of the table.
`topMargin`	number (mm)	`0`	The top margin of the table.
`bottomMargin`	number (mm)	`0`	The bottom margin of the table.
`hiddenCols`	comma-separated integers		A comma-separated list of hidden column indexes.
`hiddenRows`	comma-separated integers		A comma-separated list of hidden row indexes.

datasource

data source ID

The name/ID of the data source the table is built from.

model

model ID

The ID of the item model to render.

tableView

view ID

The ID of the table view to render.

showHeaderH

true, false

true

Whether the horizontal (column) header is shown.

showHeaderV

true, false

true

Whether the vertical (row) header is shown.

showBorder

true, false

true

Whether the table border is shown.

alternateRowBack

true, false

false

If true, alternating row background colors are used.

autoRowHeight

true, false

false

If true, row heights are calculated automatically.

cellPadding

number (mm)

0

The cell padding.

cellSpacing

number (mm)

0

The spacing between cells.

leftMargin

number (mm)

0

The left margin of the table.

rightMargin

number (mm)

0

The right margin of the table.

topMargin

number (mm)

0

The top margin of the table.

bottomMargin

number (mm)

0

The bottom margin of the table.

hiddenCols

comma-separated integers

A comma-separated list of hidden column indexes.

hiddenRows

comma-separated integers

A comma-separated list of hidden row indexes.

(The common item properties also apply.)

Graph or custom item

The Graph/Custom item is a special member of the NCReport items. This option enables you to render special, custom-defined content in reports. The typical use case is using this feature to render graphs or similar content. To use this feature, you need to do the following:

Add a Graph (Custom) item to your report in the designer and specify the size and location of this object.
Set the class ID of the specified item.
If needed, add a static item definition for the object. If you set its resource to the data source and fill in the data source column, this information will come from the specified data source column.
Derive the NCReportAbstractItemRendering class, implementing its paintItem method. You may 'attach' this class to your graph or any kind of rendering class by multiple inheritance. The paintItem method receives the following parameters:

QPainter* painter

The painter pointer.

NCReportOutput* output

The output object pointer.

const QRectF& rect

The rectangle of the object in the specified output. The geometry of the rectangle depends on the output’s resolution.

const QString& itemdata

Item definition information that comes from the data source or report definition for custom purposes.
Set the string ID of your class for identification, using the setID(…) method.
Create your custom rendering object (it must be derived from the NCReportAbstractItemRendering class) and add it to the NCReport object using the addItemRenderingClass(…) method.

XML syntax

<graph></graph>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`classID`	text		Class ID text used to identify the custom item class.
`resource`	`static`, `datasource`		The source of the graph definition: static (the definition text is stored in the report definition) and datasource (the definition text is loaded from the data source).

classID

text

Class ID text used to identify the custom item class.

resource

static, datasource

The source of the graph definition: static (the definition text is stored in the report definition) and datasource (the definition text is loaded from the data source).

(The common item properties also apply.)

Graphics view item

The Graphics view item renders a custom Qt Graphics View / Graphics Scene into the report. Like the graph item, it is identified by a class ID and backed by a custom rendering class supplied from code.

XML syntax

<graphicsview></graphicsview>

Tag properties

Attribute Values Default Description

Attribute	Values	Default	Description
`classID`	text		Class ID text used to identify the custom graphics-view class.

classID

text

Class ID text used to identify the custom graphics-view class.

(The common item properties also apply.)

Chart

The Chart item renders a chart in the report. It is available only in builds compiled with the Highcharts integration enabled; when that integration is not present, the element is ignored.

XML syntax

<chart></chart>

Specification

Root element

XML syntax

Tag properties

Page options

XML syntax

Elements

Data sources

Common tag properties

SQL data source

XML syntax

Additional tag properties

Text data source

XML syntax

XML data source

Example

XML syntax

String list data source

XML syntax

Additional tag properties

Item model data source

XML syntax

Additional tag properties

Custom data source

XML syntax

Data source relations

Report Parameters

XML syntax

Tag properties

Variables

XML syntax

Tag properties

System Variables

Scripts

XML syntax

Tag properties

Expressions

References in expressions

Using a script expression in a field:

Report sections

Common section properties

Page header

XML syntax

Page footer

XML syntax

Report header

XML syntax

Report footer

XML syntax

Details

XML syntax

Tag properties

Group sections

XML syntax

Tag properties

Group header

XML syntax

Group footer

XML syntax

Report items

Common item properties

Text label

XML syntax

Tag properties

Field

XML syntax

Tag properties

HTML Text

XML syntax

Tag properties

Line

XML syntax

Tag properties

Rectangle

XML syntax

Tag properties

Ellipse

XML syntax

Tag properties

Image