KReport/API Changes: Difference between revisions

Latest revision as of 00:25, 1 August 2015

Note

This is a design document

Design creation

Started: Jstaniek (talk) 08:59, 29 July 2015 (UTC)
Task: https://phabricator.kde.org/T517
Code: ssh://[email protected]/clones/kreport/staniek/work branch nonvisual-T517-staniek

The goal: Make it possible to create, modify, open and save KReport designs without touching the Designer's and Previewer's API and dependencies (QWidget, QGraphicsView).

New classes and relations between them proposed:

KReportDesign: setContent(xml) loads, toString() saves, modelled after
- We don't use KReportDocument name for this because actual document is: design+data
- Addressed issue: .kreport format loading happened in KoReportDesigner's ctor without proper error reporting
KReportDocument: design+data so it's more or less takes KReportDesign and KReportData args.
- KReportDocument can be rendered on a KReportWriter
KReportWriter is equivalent of QImageWriter, can use files or QIODevices
- Inherit KReportWriter to implement what we so far call 'renderers'
- KReportDocument+KReportWriter is like QPainter+QPaintDevice
- Current API solutions are not the best, e.g. see KoReportRendererContext

[KReportDesign]
              >--builds-[KReportDocument]-->-is-used-in-[KReportWriter]--writes-to--[File/Screen/Printer]
[ KReportData ]

Usage in unit tests: KReportDesign, KReportDocument, KReportWriter (impl.) are first classes for autotesting. See Autotests for scenarios.

Headeless mode

The designer-independent APIs can lead us to a headless mode for report generation. Example command line for a kreport tool takes report design from file design.kreport employs the PDF renderer, receives data from data.csv, and outputs the PDF to file report.pdf:

% kreport --format PDF design.kreport --out report.pdf < data.csv

Qt Quick mode

Like for the headless mode, lack of QWidget/QGraphicsView dependencies is good for Qt Quick bindings and suitable APIs. This opens opportunity of supporting touch applications.

TODO

+KReportTextStyle
+KReportLineStyle
Rename KoReportReportData, it's not about data

Notes

During the API changes we have opportunity to rename Ko* prefixes to KReport too

@@ Line 1: / Line 1: @@
 {{Note|This is a design document}}
+__TOC__
+==Design creation==
+*Started: [[User:Jstaniek|Jstaniek]] ([[User talk:Jstaniek|talk]]) 08:59, 29 July 2015 (UTC)
+*Task: https://phabricator.kde.org/T517
+*Code: ssh://[email protected]/clones/kreport/staniek/work branch nonvisual-T517-staniek
-==Design creation==
-Goal Make it possible to create, modify, open and save KReport designs without touching the designer API.
-New classes proposed:
+The goal: Make it possible to create, modify, open and save KReport designs without touching the Designer's and Previewer's API and dependencies (QWidget, QGraphicsView).
+New classes and relations between them proposed:
 *KReportDesign: setContent(xml) loads, toString() saves, modelled after
-**We don't use KReportDocument name because actual document is: design+data
+**We don't use KReportDocument name for this because actual document is: design+data
+**Addressed issue: .kreport format loading happened in KoReportDesigner's ctor without proper error reporting
+*KReportDocument: design+data so it's more or less takes KReportDesign and KReportData args.
+**KReportDocument can be rendered on a KReportWriter
+*KReportWriter is equivalent of QImageWriter, can use files or QIODevices
+**Inherit KReportWriter to implement what we so far call 'renderers'
+**KReportDocument+KReportWriter is like QPainter+QPaintDevice
+**Current API solutions are not the best, e.g. see KoReportRendererContext
+<pre>
+[KReportDesign]
+              >--builds-[KReportDocument]-->-is-used-in-[KReportWriter]--writes-to--[File/Screen/Printer]
+[ KReportData ]
+</pre>
+Usage in unit tests: KReportDesign, KReportDocument, KReportWriter (impl.) are first classes for autotesting. See [[../Autotests/]] for scenarios.
+==Headeless mode==
+The designer-independent APIs can lead us to a headless mode for report generation. Example command line for a ''kreport'' tool takes report design from file ''design.kreport'' employs the PDF renderer, receives data from ''data.csv'', and outputs the PDF to file ''report.pdf'':
+ % kreport --format PDF design.kreport --out report.pdf < data.csv
+==Qt Quick mode==
+Like for the headless mode, lack of QWidget/QGraphicsView dependencies is good for Qt Quick bindings and suitable APIs. This opens opportunity of supporting touch applications.
+==TODO==
+*+KReportTextStyle
+*+KReportLineStyle
+*Rename KoReportReportData, it's not about data
+==Notes==
+*During the API changes we have opportunity to rename Ko* prefixes to KReport too