KReport

KReport is a framework for the creation and generation of reports in multiple formats. The KReport framework implements reporting functionality for creation of reports in MS Access style. They are also similar to SAP Crystal Reports and FileMaker reports.

Reports can be created interactively and programmatically. They can be previewed on screen, printed, and saved in a variety of formats such as HTML, PDF and OpenDocument. Reports of this kind offer a way to view, format, and summarize the information. For example a simple report of contact phone numbers can be prepared, or a more complex report on sales for different products, regions, and periods of time.

Use Cases

A report is often filled with information from a database. There are many use cases:

• The data can be displayed, summarized, sorted and grouped
• Totals can be computed and displayed
• Single or multiple records of data can be placed on a page
• Details for individual data records can be placed in a layout
• Labels can be created
• The various report sections, such as title, header or footer, can be sized to suit
• Reports can be generated on demand, thus eliminating saving them in files for further use

Concepts

There are three main concepts in KReport: designer, data sources, and rendering objects. The report designer is a visual tool to create report templates by placing items, such as labels or fields, and setting their properties; data sources provide the data needed to render the report from its template; and rendering objects define how to layout and render the report to output devices, such as the screen or a printer.

Designer

A report design defines the page size, its margins, and one or more sections that hold items, the smallest unit that tell the engine what data to use and how to render it. Report designs are saved as XML documents, and can be stored on any medium, for instance files or as part of a KEXI database project, for re-use and transfer. KReportDesigner is based on the Qt Graphics View framework.

Internally, it uses the following classes to manipulate the report’s design:

• KReportDesigner
• KReportDesignerSection
• KReportDesignerSectionDetail
• KReportDesignerSectionDetailGroup
• KReportSectionData
• KReportUnit

Items, the classes that convert data from sources to rendering objects, are provided through the plugin system, for extensibility, and implement one or more of the following interfaces:

• KReportAsyncItemBase
• KReportDesignerItemBase
• KReportDesignerItemRectBase
• KReportItemBase
• KReportPluginInterface

See How to Implement a Type Plugin for more information on how to implement a plugin for a new item.

Data Sources

Data sources are classes that adapt data from external sources to something that KReport can work with. They are somewhat similar in concept to Qt’s QAbstractItemModel, but they instead have to implement one of the following interfaces:

• KReportDataSource
• KReportScriptSource

KReport does not provide any public implementation of data sources and applications must do it themselves. See How to Implement a Data Source for more information on how to implement a new data source.

Rendering Objects

The items placed when designing the report’s XML are kind of cookie cutters that define how a particular data is to be rendered on the report’s output. However, the actual placement and styling of data on a rendered document is done by the following classes:

• OROCheckBox
• ORODocument
• OROEllipse
• OROImage
• OROLine
• OROPage
• OROPicture
• OROPrimitive
• ORORect
• OROSection
• OROTextBox

There is a class that takes an XML document with the report’s design from one end, a data source from another, and creates a ORODocument with all rendering object correctly placed inside:

• KReportPreRenderer

The actual rendering to an output device, be it the screen or a file, it is performed by classes that inherit from KReportRendererBase, using an instance of KReportRendererContext to pass any information that the renderer requires. The access to instances of KReportRendererBase it is necessary to use the following class:

• KReportRendererFactory

Simple Example

The following example loads a report design from an XML file named report.xml, pre-renders the report using the data source class in the examples directory and, finally, renders the final document to a PDF file named report.pdf.

#include "KReportExampleDataSource.h"
#include <KReportDocument>
#include <KReportPreRenderer>
#include <KReportRenderObjects>
#include <KReportRendererBase>
#include <QApplication>
#include <QDomDocument>
#include <QDomElement>
#include <QFile>
#include <QPainter>
#include <QPdfWriter>
 
int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
 
    QFile file("report.xml");
    if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) {
        return EXIT_FAILURE;
    }
    QDomDocument doc;
    doc.setContent(QString::fromUtf8(file.readAll()));
    QDomElement root = doc.documentElement();
 
    KReportPreRenderer preRenderer(root.firstChildElement());
    if (!preRenderer.isValid()) {
        return EXIT_FAILURE;
    }
    preRenderer.setDataSource(new KReportExampleDataSource);
    preRenderer.setName("kreport");
    if (!preRenderer.generateDocument()) {
        return EXIT_FAILURE;
    }
 
    KReportRendererFactory factory;
    KReportRendererBase *renderer = factory.createInstance("screen");
    if (!renderer) {
        return EXIT_FAILURE;
    }
 
    const KReportDocument *document = preRenderer.reportData();
    QPdfWriter pdfWriter("report.pdf");
    pdfWriter.setResolution(96);
    pdfWriter.setPageLayout(document->pageLayout());
 
    QPainter painter(&pdfWriter);
    KReportRendererContext context;
    context.setPainter(&painter);
 
    ORODocument *preRenderedDocument = preRenderer.document();
    int numPages = preRenderedDocument->pageCount();
    for (int p = 0; p < numPages; p++) {
        if (p > 0) {
            pdfWriter.newPage();
        }
        if (!renderer->render(context, preRenderedDocument, p)) {
            return EXIT_FAILURE;
        }
    }
    return EXIT_SUCCESS;
}

The XML could be something like this:

<!DOCTYPE kexireport>
<kexireport>
 <report:content xmlns:svg="urn:oasis:names:tc:opendocument:xmlns:svg-compatible:1.0"
                 xmlns:report="http://kexi-project.org/report/2.0"
                 xmlns:fo="urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0">
  <report:title>Report</report:title>
  <report:grid report:grid-divisions="4"
               report:grid-visible="1"
               report:page-unit="cm"
               report:grid-snap="1" />
  <report:page-style report:print-orientation="portrait"
                     fo:margin-right="28.346505829687491pt"
                     fo:margin-left="28.346505829687491pt"
                     report:page-size="A4"
                     fo:margin-top="28.346505829687491pt"
                     fo:margin-bottom="28.346505829687491pt"
  >predefined</report:page-style>
  <report:body>
   <report:detail>
    <report:section fo:background-color="#ffffff"
                    report:section-type="detail"
                    svg:height="28.346505829689765pt">
     <report:field report:item-data-source="project"
                   report:z-index="0"
                   report:vertical-align="center"
                   report:name="field26"
                   report:value=""
                   svg:width="327.750000343254840pt"
                   report:word-wrap="1"
                   svg:x="92.250000096614059pt"
                   svg:y="6.750000007069322pt"
                   svg:height="12.750000013353164pt"
                   report:can-grow="1"
                   report:horizontal-align="left">
      <report:text-style fo:background-color="#ffffff"
                         fo:background-opacity="0%"
                         fo:letter-spacing="0%"
                         fo:font-size="9"
                         fo:font-family="Sans Serif"
                         fo:foreground-color="#000000"
                         style:letter-kerning="true"/>
      <report:line-style report:line-style="nopen"
                         report:line-weight="1"
                         report:line-color="#000000"/>
     </report:field>
    </report:section>
   </report:detail>
  </report:body>
 </report:content>
</kexireport>

Project's home page: https://community.kde.org/KReport

Author(s)

• Adam Pigg adam@.nosp@m.pigg.nosp@m.z.co..nosp@m.uk - Maintainer
• Jarosław Staniek stani.nosp@m.ek@k.nosp@m.de.or.nosp@m.g - Developer
• Wojciech Kosowicz pcell.nosp@m.ix@g.nosp@m.mail..nosp@m.com - improvements
• Shreya Pandit shrey.nosp@m.a@sh.nosp@m.reyap.nosp@m.andi.nosp@m.t.com - Web page element
• Radoslaw Wicik rockf.nosp@m.ord@.nosp@m.wicik.nosp@m..pl - Map element
• OpenMFG, LLC http://xtuple.com/contact - original code

Contributors:

• Friedrich W. H. Kossebau kosse.nosp@m.bau@.nosp@m.kde.o.nosp@m.rg - cleanups

• Dag Andersen dande.nosp@m.rs@g.nosp@m.et2ne.nosp@m.t.dk - cleanups

  License(s)

  LGPLv2