Report Outputs

The report engine renders the report onto an output. The output decides what the result is: pages in a preview window, a printed document, a PDF file, image or SVG files, an HTML page, an Excel compatible HTML file or a text file built from a template. The same report definition can be run to any of these outputs without changes.

Every output is a subclass of the abstract NCReportOutput class. You can either use one of the one-step NCReport::runReportTo…() functions, which create, configure and delete the right output object for you, or create an output object yourself, assign it with NCReport::setOutput() and start the report with NCReport::runReport().

Output types

The following table lists the output classes of the engine and the matching one-step functions of the NCReport class.

Output Class One-step function

Output	Class	One-step function
Preview	`NCReportPreviewOutput`	`runReportToPreview()`, `runReportToShowPreview()`
Preview dialog (Qt / modern)	`NCReportQtPreviewOutput`	`runReportToQtPreview()`, `runReportToModernPreview()`
Printer	`NCReportPrinterOutput` (`NCReportPrinterOutputV21`)	`runReportToPrinter()`, `runReportToPrinterNoDialog()`
PDF (QPrinter based)	`NCReportPdfOutput`	`runReportToPdf()`
PDF (QPdfWriter based)	`NCReportPdfWriterOutput`	`runReportToPdfWriter()`
SVG	`NCReportSvgOutput`	`runReportToSVG()`
Image	`NCReportImageOutput`	`runReportToImage()`
HTML	`NCReportHtmlOutput`	`runReportToHtml()` (or `runReportToHTML()`)
Excel (HTML based)	`NCReportExcelHtmlOutput`	`runReportToExcelHtml()`
Text (template based)	`NCReportTextOutput`	`runReportToText()`

Preview

NCReportPreviewOutput

runReportToPreview(), runReportToShowPreview()

Preview dialog (Qt / modern)

NCReportQtPreviewOutput

runReportToQtPreview(), runReportToModernPreview()

Printer

NCReportPrinterOutput (NCReportPrinterOutputV21)

runReportToPrinter(), runReportToPrinterNoDialog()

PDF (QPrinter based)

NCReportPdfOutput

runReportToPdf()

PDF (QPdfWriter based)

NCReportPdfWriterOutput

runReportToPdfWriter()

SVG

NCReportSvgOutput

runReportToSVG()

Image

NCReportImageOutput

runReportToImage()

HTML

NCReportHtmlOutput

runReportToHtml() (or runReportToHTML())

Excel (HTML based)

NCReportExcelHtmlOutput

runReportToExcelHtml()

Text (template based)

NCReportTextOutput

runReportToText()

The NCReportOutput::OutputType enumeration also contains values such as PostScript, Xml, Odf, ExcelXml, PlainText and Custom. Of these, only PostScript has an implementation, and only in builds with Qt 4 (see PDF output). The Null type is used internally by NCReportNullOutput for the first pass of double pass reports.

The runReportTo…() functions do not return a result. After they return, check the result with NCReport::hasError() and NCReport::lastErrorMsg().

Common output options

The NCReportOutput base class provides the following options for every output type.

setFileName( const QString& ): The name of the output file for file based outputs.
setPageRanges( const QString& ): Restricts the output to the given pages. The expression is a comma-separated list of page numbers and ranges, for example 1-3,5,8-10. When the report is run with NCReport::runReport(), the page range expression of the NCReport object is always passed to the output and replaces the output’s own setting, so set the page ranges with NCReport::setPageRanges().
setPageRange( int from, int to ), setPageFrom( int ), setPageTo( int ): Sets the page range by its first and last page.
setCopies( int ): The number of copies (printer output).
setShowPrintDialog( bool ): Whether the print dialog appears before printing (printer output).
setParentWidget( QWidget* ): The parent widget of dialogs opened by the output.
setAutoDelete( bool ): Whether the output object is deleted by the NCReport object. A preview output that is handed to a preview window must not be auto-deleted.
setResolution( int dpi ): The resolution of outputs that support it (printer, PDF).
setRotationAngle( int ): Rotates the output. NCReport::setRotationAngle() passes the angle to the outputs created by the one-step functions.
setBatchModePageBreakBetweenPages( bool ): Controls the page break between the reports of a batch. NCReport has a function with the same name.
hasError(), lastError(): The error state of the output.

Running the report with an output object

The one-step functions cover the most common needs. When you need more control, create the output object, configure it and run the report with runReport():

NCReport *report = new NCReport();
report->setReportFile("products.ncr");

NCReportOutput *output = new NCReportPdfWriterOutput("products.pdf");
report->setOutput(output);            (1)
report->setPageRanges("1-3");         (2)

bool ok = report->runReport();
if (!ok || report->hasError())
    qWarning() << report->lastErrorMsg();

1	The previous output object is deleted.
2	The page ranges are applied to the output by `runReport()`.

Preview output

NCReportPreviewOutput records the rendered pages in memory. It does not display anything by itself: after the report has run, the output object is passed to an NCReportPreviewWindow, which shows the pages and lets the user print them or save them to other formats.

runReportToPreview() runs the report into a new preview output (with auto delete disabled), and runReportToShowPreview( QWidget* parent = nullptr, bool maximized = false ) does the same and then opens the preview window:

// one step: run and show the preview window
report->runReportToShowPreview(this);

// or step by step
report->runReportToPreview();
if (!report->hasError()) {
    NCReportPreviewWindow *pv = new NCReportPreviewWindow();
    pv->setReport(report);
    pv->setOutput(static_cast<NCReportPreviewOutput*>(report->output()));
    pv->setAttribute(Qt::WA_DeleteOnClose);
    pv->exec();
}

Setting the report object with setReport() makes printing from the preview window run the report again to the printer, instead of printing the lower-quality preview pages. See the Previewing the report section of the Using the NCReport API chapter for details.

Preview dialogs: Qt print preview and modern preview

NCReportQtPreviewOutput is a printer based output that renders the report into a preview dialog.

runReportToQtPreview( QWidget* parent ): Shows Qt’s standard QPrintPreviewDialog (extended with a Close button).
runReportToModernPreview( int dpi, const QString& outputFileName, QWidget* parent ): Shows NCReport’s own preview dialog. If dpi is 0, the print resolution of the report is used.

Both functions open the dialog modally and delete the output when it is closed.

report->runReportToQtPreview(this);
// or
report->runReportToModernPreview(0, "products", this);

Printer output

NCReportPrinterOutput prints the report through a QPrinter. The printer is created with a print quality (NCReportPrinter::PrinterMode: ScreenResolution, PrinterResolution or HighResolution) and an optional resolution. If the print dialog is enabled, it is shown in initialize(), and cancelling it stops the report.

printer(): Returns the QPrinter object, so you can, for example, set the printer name or the document name.
setCopies( int ): Sets the number of copies on the printer.
customizePrinter( QPrinter* ) signal: Emitted while the printer is initialized, so the application can change printer settings. When the one-step functions are used, the signal is forwarded by NCReport::customizePrinter().

The one-step functions are:

// copies, show dialog, parent widget, printer name, document name
report->runReportToPrinter(1, true, this);

// print to a named printer without dialog
report->runReportToPrinterNoDialog(2, "HP_LaserJet", "Invoice");

The print quality used by runReportToPrinter() and runReportToPdf() can be set with NCReport::setPrintQuality().

NCReportPrinterOutputV21 is the printer output of NCReport version 2.21, kept for compatibility. It has the same interface. When the library is built with the p21 build mode (which defines NCREPORT_PRINTER_V21), runReportToPrinter() uses this class instead of NCReportPrinterOutput.

PDF output

There are two PDF outputs, built on two different Qt classes.

NCReportPdfOutput: A subclass of the printer output that prints into a QPrinter set to PDF format. It uses the print quality and resolution of the report, like the printer output. Its run function is runReportToPdf( const QString& filename, bool overwrite = true, PdfVersion version = Pdf1_4, const QString& creator = QString() ). In builds with Qt 4 the same class can also produce PostScript (runReportToPostScript()); with Qt 5 and later runReportToPostScript() does nothing.
NCReportPdfWriterOutput: Renders directly into a QPdfWriter (Qt 5 and later). It can write to a file or to any QIODevice (for example a QBuffer in memory), and it supports more document settings: setDpi( int ) (the default of the class is 120 dpi, the default of runReportToPdfWriter() is 600 dpi), setPdfVersion( NCReport::PdfVersion ), setCreator( const QString& ) (default: NCReport), setTitle( const QString& ) (default: the report name) and setXmpMetaData( const QByteArray& ) (applied with Qt 5.15 or later). This is the recommended way of PDF generation; the Designer also uses it with Qt 5 and later.

The PDF version (NCReport::PdfVersion) can be Pdf1_4 (default), PdfA1b or Pdf1_6. When overwrite is false and the file already exists, or when the file is not writable, the report is not run and an error is set.

// QPdfWriter based PDF, 300 dpi, PDF/A-1b
report->runReportToPdfWriter("report.pdf", 300, true, NCReport::PdfA1b,
                             "My Application", "Monthly report");

// PDF into memory
QBuffer buffer;
buffer.open(QIODevice::WriteOnly);
report->runReportToPdfWriter(&buffer);

// QPrinter based PDF
report->runReportToPdf("report.pdf");

SVG output

NCReportSvgOutput writes every page into a separate SVG file at 96 dpi. The page files are named after the given file name with a page suffix: running to report.svg produces report_p1.svg, report_p2.svg, and so on. The SVG title is the report name.

report->runReportToSVG("/tmp/report.svg");

Image output

NCReportImageOutput renders every page into a QImage and saves the pages as image files. The image format is determined by the extension of the file name (for example .png or .jpg), and the pages are saved as <name>_p1.<ext>, <name>_p2.<ext>, and so on.

When the report is in endless (continuous) mode, the output produces a single image instead, cut to the height of the rendered content and saved with the given file name. setMaximumHeight( int ) sets the maximum height of this image in pixels (default: 20000). The rendered images can also be accessed from code with page( int ) and, in endless mode, successiveResult().

report->runReportToImage("/tmp/report.png");   (1)

1	The pages are saved as `report_p1.png`, `report_p2.png`, and so on.

Markup language outputs: HTML and Excel

NCReportMarkupLanguageOutput is the common base class of the text based markup outputs. It collects the items of every rendered section, arranges them into table rows and cells, and writes the result as one document, in the encoding of the report. Subclasses only have to implement how the document, the sections, the rows and the cells are written (writeHeader(), writeFooter(), writeSectionStart(), writeRowStart(), cellStarts() and so on), which makes it a good starting point for custom markup outputs.

Its options are:

setStrategy( SpreadStrategy ): How sections are converted to tables. SectionOneTable (default): each section is translated as one table. SectionMultiTables: sections are always separated into multiple tables.
setStyleSheetFile( const QString& ): If empty (default), the generated CSS styles are embedded in the document. Otherwise the styles are written to the given CSS file and the document links to it. The special value @ means a CSS file with the same base name as the output file.

HTML output

NCReportHtmlOutput generates an HTML file. Images, barcodes and charts are embedded as PNG images. With setImageMode( NCReportHtmlOutput::File ) they are saved into a <filename>_files directory next to the HTML file instead of being embedded as Base64 data (NCReportHtmlOutput::Base64, the default).

The HTML document can be customized in the report definition:

htmlBodyStyle: Page option (Page settings dialog, HTML options, Body style options). CSS declarations for the body element. The marker {DEFAULT} (the default value) inserts the width, default font and margins of the report page.
htmlHead: Page option (General head options). Text inserted into the <head> element, for example additional <meta> or <link> tags.
htmlOptions: Item and section property. Additional CSS declarations for the table cell of the item or for the section.

HTML page options in the report definition

<options>
    ...
    <htmlBodyStyle>{DEFAULT}background-color:#f0f0f0;</htmlBodyStyle>
    <htmlHead>&lt;meta name="author" content="NCReport"&gt;</htmlHead>
</options>

runReportToHtml( const QString& filename, int strategy = 0, const QString& cssFile = QString() ) runs the report to HTML. strategy 0 means SectionOneTable, any other value SectionMultiTables.

report->runReportToHtml("report.html");                     (1)
report->runReportToHtml("report.html", 1, "report.css");    (2)

// or with an output object
NCReportHtmlOutput *html = new NCReportHtmlOutput();
html->setFileName("report.html");
html->setStrategy(NCReportHtmlOutput::SectionMultiTables);
html->setImageMode(NCReportHtmlOutput::File);
report->setOutput(html);
report->runReport();

1	Styles are embedded in the HTML file.
2	Multiple tables (`SectionMultiTables`), styles in an external CSS file.

Excel HTML output

NCReportExcelHtmlOutput is a variant of the HTML output that produces HTML markup in the format Microsoft Excel opens as a worksheet (application/vnd.ms-excel content type). All pages are stored in one file; the Designer offers the .xls extension for it.

report->runReportToExcelHtml("report.xls");

Text output

NCReportTextOutput generates any kind of text file (plain text, CSV, HTML, XML, …) from a text template, without graphical rendering. The template file defines the text of each report section. The template syntax is described in the General TEXT output chapter.

report->runReportToText("customers.csv", "templates/customers_csv.txt");

// or with an output object
NCReportTextOutput *txt = new NCReportTextOutput();
txt->setFileName("customers.csv");
txt->setTemplateFile("templates/customers_csv.txt");   // or setTemplate( templateText )
report->setOutput(txt);
report->runReport();

Custom outputs

To create your own output, subclass NCReportOutput and implement the pure virtual functions initialize(), cleanup(), begin(), end() and newPage(). Items are painted with the painter returned by painter(); for special rendering, renderItem(), renderSection(), sectionStarts() and sectionEnds() can be reimplemented. If initialize() returns false, the report is not run.

Selecting the output in the Designer

In the Designer, the Run report dialog lists the available outputs: New preview, Old preview, Qt print preview, Printer, PDF file, SVG file(s), Image file(s), HTML file, Excel file and Text file. For file based outputs the Designer asks for the output file name. The dialog also has a page range field and a Run reports in batch mode option for running all opened reports as a batch.

The outputs map to the engine as follows: New preview runs runReportToModernPreview(), Old preview runReportToShowPreview(), PDF file runReportToPdfWriter() (with Qt 5 and later), HTML file runReportToHTML() and so on.

Some output settings are taken from the Designer preferences:

Printer: Printer DPI (used by the new preview), Default printer name and Print without printer dialog.
HTML Output: Sections build from one table / Sections build from multiple tables (the HTML strategy) and CSS file.

Selecting the output in the command line tool

The command line tool selects the output with the -o (--output) option. Its values are preview (default), print, pdf, svg, html, image and excel. File based outputs need the output file name in -of (--output-file).

Option Meaning

Option	Meaning
`-o, --output`	Output type: `preview`, `print`, `pdf`, `svg`, `html`, `image`, `excel`
`-of, --output-file`	Output file name
`-n, --printer`	Name of the target printer
`--copies`	Number of copies for the printer output
`--nodialog`	Print without the printer dialog
`-hs, --htmlstrategy`	HTML strategy: `1` = one table per section (default), any other value = multiple tables
`-css, --css-file`	External CSS file for the HTML output

-o, --output

Output type: preview, print, pdf, svg, html, image, excel

-of, --output-file

Output file name

-n, --printer

Name of the target printer

--copies

Number of copies for the printer output

--nodialog

Print without the printer dialog

-hs, --htmlstrategy

HTML strategy: 1 = one table per section (default), any other value = multiple tables

-css, --css-file

External CSS file for the HTML output

NCReport -f products.ncr -o pdf -of products.pdf
NCReport -f products.ncr -o html -of products.html -hs 2 -css products.css
NCReport -f products.ncr -o print -n HP_LaserJet --copies 2 --nodialog

See the Command line client chapter for all options.