|
KD Reports 1.4
|
|
KD Reports 1.4
|
#include <KDReportsReport.h>
Public Member Functions | |
| Report (QObject *parent=0) | |
| ~Report () | |
| void | setReportMode (ReportMode reportMode) |
| ReportMode | reportMode () const |
| void | setDefaultFont (const QFont &font) |
| QFont | defaultFont () const |
| MainTable * | mainTable () const |
| void | addInlineElement (const Element &element) |
| void | addElement (const Element &element, Qt::AlignmentFlag horizontalAlignment=Qt::AlignLeft, const QColor &backgroundColor=QColor()) |
| void | addVerticalSpacing (qreal space) |
| void | addFragment (const QTextDocumentFragment &fragment) |
| void | addPageBreak () |
| void | setTabPositions (const QList< QTextOption::Tab > &tabs) |
| QTextOption::Tab | rightAlignedTab () const |
| QTextOption::Tab | middleAlignedTab () const |
| void | setParagraphMargins (qreal left, qreal top, qreal right, qreal bottom) |
| void | setPageSize (const QPrinter::PageSize &size) |
| void | setPaperSize (const QSizeF &paperSize, QPrinter::Unit unit) |
| QPrinter::PageSize | pageSize () const |
| void | setOrientation (QPrinter::Orientation orientation) |
| QPrinter::Orientation | orientation () const |
| void | setWidthForEndlessPrinter (qreal widthMM) |
| void | setMargins (qreal top, qreal left, qreal bottom, qreal right) |
| void | getMargins (qreal *top, qreal *left, qreal *bottom, qreal *right) const |
| void | setTopPageMargin (qreal top) |
| qreal | topPageMargins () const |
| void | setLeftPageMargin (qreal left) |
| qreal | leftPageMargins () const |
| void | setRightPageMargin (qreal right) |
| qreal | rightPageMargins () const |
| void | setBottomPageMargin (qreal bottom) |
| qreal | bottomPageMargins () const |
| void | setHeaderBodySpacing (qreal spacing) |
| qreal | headerBodySpacing () const |
| void | setFooterBodySpacing (qreal spacing) |
| qreal | footerBodySpacing () const |
| Header & | header (HeaderLocations hl=AllPages) |
| Footer & | footer (HeaderLocations hl=AllPages) |
| void | associateModel (const QString &modelKey, QAbstractItemModel *model) |
| void | associateTextValue (const QString &id, const QString &value) |
| void | associateImageValue (const QString &id, const QPixmap &value) |
| void | associateImageValue (const QString &id, const QImage &value) |
| bool | loadFromXML (QIODevice *iodevice, ErrorDetails *details=0) |
| bool | loadFromXML (const QDomDocument &doc, ErrorDetails *details=0) |
| void | setXmlElementHandler (KDReports::XmlElementHandler *handler) |
| void | setCurrentRow (const QAbstractItemModel *model, int row) |
| bool | printWithDialog (QWidget *parent) |
| bool | print (QPrinter *printer, QWidget *parent=0) |
| bool | exportToFile (const QString &fileName, QWidget *parent=0) |
| bool | exportToImage (const QSize &size, const QString &fileName, const char *format) |
| bool | exportToHtml (const QString &fileName) |
| void | paintPage (int pageNumber, QPainter &painter) |
| void | setFirstPageNumber (int num) |
| int | firstPageNumber () const |
| int | numberOfPages () const |
| void | setTableBreakingEnabled (bool tableBreakingEnabled) |
| Enable breaking of tables across multiple pages. | |
| bool | isTableBreakingEnabled () const |
| void | setTableBreakingPageOrder (TableBreakingPageOrder pageOrder) |
| TableBreakingPageOrder | tableBreakingPageOrder () const |
| void | setFontScalingFactor (qreal factor) |
| Scale the fonts in the document by a given factor. | |
| qreal | fontScalingFactor () const |
| void | scaleTo (int numPagesHorizontally, int numPagesVertically) |
| Ensure that the report fits into a number of pages. | |
| int | maximumNumberOfPagesForHorizontalScaling () const |
| int | maximumNumberOfPagesForVerticalScaling () const |
| QList < KDReports::AutoTableElement * > | autoTableElements () const |
| void | regenerateAutoTables () |
| void | regenerateAutoTableForModel (QAbstractItemModel *model) |
| void | setWatermarkText (const QString &text, int rotation=0, const QColor &color=QColor(204, 204, 204), const QFont &font=QFont(QLatin1String("Helvetica"), 48)) |
| QString | watermarkText () const |
| int | watermarkRotation () const |
| QColor | watermarkColor () const |
| QFont | watermarkFont () const |
| void | setWatermarkPixmap (const QPixmap &pixmap, bool autoGrayOut=true) |
| QPixmap | watermarkPixmap () const |
| void | setWatermarkImage (const QImage &image) |
| QImage | watermarkImage () const |
| KDReports::HeaderLocations | headerLocation (Header *header) const |
| KDReports::HeaderLocations | footerLocation (KDReports::Footer *footer) const |
| void | setHeaderLocation (HeaderLocations hl, Header *header) |
| void | setFooterLocation (HeaderLocations hl, Footer *footer) |
The Report class represents a report.
Initially the report is empty. Content can be added to the report using the addElement API, or using loadFromXML to load an equivalent definition from an XML file.
The report can then be previewed with PreviewDialog, printed, exported to PDF, or exported to an image.
| KDReports::Report::Report | ( | QObject * | parent = 0 | ) |
Constructs a report.
| parent | optional parent object, for memory management |
| KDReports::Report::~Report | ( | ) |
Destroys the report.
| void KDReports::Report::addElement | ( | const Element & | element, |
| Qt::AlignmentFlag | horizontalAlignment = Qt::AlignLeft, |
||
| const QColor & | backgroundColor = QColor() |
||
| ) |
Adds an element to the report, creating a new paragraph for it. You can specify the alignment of that paragraph.
An element defines what is added to the report. The report does not store the element, though. For this reason, any changes to the element after insertion will have no effect on the report. Set all settings in the element before calling addElement.
| element | the definition of what to add to the report |
| horizontalAlignment | the alignment of the paragraph created for this element |
| backgroundColor | the background color of the paragraph created for this element The difference with Element::setBackground is that it affects the whole paragraph, including any inline elements as well as the unused area up to the right margin of the page. |
| void KDReports::Report::addFragment | ( | const QTextDocumentFragment & | fragment | ) |
Adds a piece of formatted text from a QTextDocument. This method is an optimization for the case where the initial text is in a QTextDocument (e.g. in a QTextEdit). In general you probably want to use addElement(HtmlElement()) instead.
| void KDReports::Report::addInlineElement | ( | const Element & | element | ) |
Adds an element to the report, next to the previous element, in the same paragraph.
An element defines what is added to the report. The report does not store the element, though. For this reason, any changes to the element after insertion will have no effect on the report. Set all settings in the element before calling addInlineElement.
| void KDReports::Report::addPageBreak | ( | ) |
Adds a page break to the report. The next element added to the report will be at the top of a page.
Note that you cannot call addPageBreak twice in a row, it will only insert one page break. To get a completely empty page you need to insert an empty text element between both calls to addPageBreak.
Also note that exporting to an image, or using an endless printer, will remove all page breaks in the report.
| void KDReports::Report::addVerticalSpacing | ( | qreal | space | ) |
Adds vertical spacing between paragraphs. Make sure to call addElement after that, not addInlineElement.
| space | the space in millimeters |
| void KDReports::Report::associateImageValue | ( | const QString & | id, |
| const QPixmap & | value | ||
| ) |
Associate a pixmap with the id of an image element.
| id | the id of the image element, specified using id="foo" in the XML, or using ImageElement::setId(). |
| value | the pixmap to use in the report. If associateImageValue was already called with the id id, the new value replaces the old one. |
| void KDReports::Report::associateImageValue | ( | const QString & | id, |
| const QImage & | value | ||
| ) |
Associate an image with the id of an image element. This is only used if the report description is going to be loaded from an XML file, using loadFromXML. This method needs to be called before loadFromXML is called.
| id | the id of the image element, specified using id="foo" in the XML. |
| value | the pixmap to use in the report. If associateImageValue was already called with the id id, the new value replaces the old one. |
This overload is especially useful in threads.
| void KDReports::Report::associateModel | ( | const QString & | modelKey, |
| QAbstractItemModel * | model | ||
| ) |
Associates a model with a model key. This is only used if the report description is going to be loaded from an XML file, using loadFromXML. This method needs to be called before loadFromXML is called.
| void KDReports::Report::associateTextValue | ( | const QString & | id, |
| const QString & | value | ||
| ) |
Associate a text string with the id of a text or html element.
| id | the id of the text or html element, specified using id="foo" in the XML, or using TextElement::setId(). |
| value | the text for this element, which will appear in the report. The value can include newlines. If associateTextValue was already called with the id id, the new value replaces the old one. |
| QList<KDReports::AutoTableElement *> KDReports::Report::autoTableElements | ( | ) | const |
Returns a list of the auto-table elements that were used to create this report. You wouldn't normally need this method; this is only to be able to change some settings like showing table headers or table borders at runtime.
Note: use mainTable() instead, in spreadsheet mode
| qreal KDReports::Report::bottomPageMargins | ( | ) | const |
| QFont KDReports::Report::defaultFont | ( | ) | const |
| bool KDReports::Report::exportToFile | ( | const QString & | fileName, |
| QWidget * | parent = 0 |
||
| ) |
Export the whole report to a PS or PDF file. If the file name has the suffix ".ps" then PostScript is automatically selected as output format. If the file name has the ".pdf" suffix PDF is generated.
| bool KDReports::Report::exportToHtml | ( | const QString & | fileName | ) |
Export the whole report to HTML. Note that HTML export does not include headers and footers, nor watermark.
Images are saved into separate files.
| bool KDReports::Report::exportToImage | ( | const QSize & | size, |
| const QString & | fileName, | ||
| const char * | format | ||
| ) |
Export the whole report to an image file.
| size | size of the image in pixels |
| fileName | the name of the image file |
| format | format of the image, for instance: BMP, JPG, PNG. |
| int KDReports::Report::firstPageNumber | ( | ) | const |
| qreal KDReports::Report::fontScalingFactor | ( | ) | const |
| Footer& KDReports::Report::footer | ( | HeaderLocations | hl = AllPages | ) |
Specify the contents of the footer by calling Footer::addElement.
| qreal KDReports::Report::footerBodySpacing | ( | ) | const |
| KDReports::HeaderLocations KDReports::Report::footerLocation | ( | KDReports::Footer * | footer | ) | const |
| void KDReports::Report::getMargins | ( | qreal * | top, |
| qreal * | left, | ||
| qreal * | bottom, | ||
| qreal * | right | ||
| ) | const |
| Header& KDReports::Report::header | ( | HeaderLocations | hl = AllPages | ) |
Returns a reference to a header object. Calling this method makes the report have a header on the specified pages.
Calling the method with different sets of intersecting flags leads to undefined behavior. For instance header(EvenPages|FirstPage) and header(OddPages) is fine, but header(EvenPages|FirstPage) and header(FirstPage) leads to two headers being defined for the first page, anyone of the two could be picked. Calling the method with the same set multiple times, for instance header(EvenPages|FirstPage), is ok though: the same header instance will be returned every time.
Note that all headers will occupy the same height: the height of the tallest header.
Specify the contents of the header by calling Header::addElement.
| qreal KDReports::Report::headerBodySpacing | ( | ) | const |
| KDReports::HeaderLocations KDReports::Report::headerLocation | ( | Header * | header | ) | const |
| bool KDReports::Report::isTableBreakingEnabled | ( | ) | const |
| qreal KDReports::Report::leftPageMargins | ( | ) | const |
| bool KDReports::Report::loadFromXML | ( | QIODevice * | iodevice, |
| ErrorDetails * | details = 0 |
||
| ) |
Loads a report definition from an XML document. Notice that if the report definition contains Chart or Table elements, you need to call associate for each such element. iodevice needs to be open and readable. If you have any chart or table elements in your report, you must associate the models using associateModel() first, otherwise these elements will stay empty.
| bool KDReports::Report::loadFromXML | ( | const QDomDocument & | doc, |
| ErrorDetails * | details = 0 |
||
| ) |
This is an overloaded member function, provided for convenience. With this method you can modify the QDomDocument before giving it to KDReports.
Note: if the QDomDocument is simply created with a file or QIODevice as argument, it will ignore whitespace-only nodes like <text> </text>. The other loadFromXML takes care of this, while this overload requires that the QDomDocument has been properly set up.
| MainTable* KDReports::Report::mainTable | ( | ) | const |
Spreadsheet mode: returns the main table of the report.
| int KDReports::Report::maximumNumberOfPagesForHorizontalScaling | ( | ) | const |
| int KDReports::Report::maximumNumberOfPagesForVerticalScaling | ( | ) | const |
| QTextOption::Tab KDReports::Report::middleAlignedTab | ( | ) | const |
Returns a tab position that is always center-aligned to the middle of the paper. This is convenient for having left-aligned, center-aligned (and potentially right-aligned) text on the same line.
| int KDReports::Report::numberOfPages | ( | ) | const |
| QPrinter::Orientation KDReports::Report::orientation | ( | ) | const |
| QPrinter::PageSize KDReports::Report::pageSize | ( | ) | const |
| void KDReports::Report::paintPage | ( | int | pageNumber, |
| QPainter & | painter | ||
| ) |
Paints a given page of the report into the painter. Note that this method can be used for printing and for on-screen rendering so it doesn't fill the background with white, the caller has do to that.
| bool KDReports::Report::print | ( | QPrinter * | printer, |
| QWidget * | parent = 0 |
||
| ) |
Print directly using the setup values from a preexisting QPrinter object. Notice that this will only change settings like page sizes or orientation temporarily, during this particular print operation. After the operation, these values will be reset to their previous values.
Returns false if cancelled (not possible yet).
| printer | the printer to use for printing |
| parent | the parent widget for the progress dialog that appears when printing |
| bool KDReports::Report::printWithDialog | ( | QWidget * | parent | ) |
Show the print dialog to let the user choose a printer, and print.
| parent | the parent widget for the progress dialog that appears when printing |
| void KDReports::Report::regenerateAutoTableForModel | ( | QAbstractItemModel * | model | ) |
Regenerate the contents of a single auto table. This can be useful if the data in this specific model changes frequently, to save time compared to recreating the full report.
| void KDReports::Report::regenerateAutoTables | ( | ) |
Regenerate the contents of auto tables. This can be useful if the data in the item model changes frequently, to save time compared to recreating the full report.
| ReportMode KDReports::Report::reportMode | ( | ) | const |
Returns the mode set with setReportMode();
| QTextOption::Tab KDReports::Report::rightAlignedTab | ( | ) | const |
Returns a tab position that is always right-aligned to the right edge of the paper. This is convenient for having left-aligned and right-aligned text on the same line.
| qreal KDReports::Report::rightPageMargins | ( | ) | const |
| void KDReports::Report::scaleTo | ( | int | numPagesHorizontally, |
| int | numPagesVertically | ||
| ) |
Ensure that the report fits into a number of pages.
By default tables are layouted so that all columns fit into the page width, but for large tables this can wrap the text too much. This method allows to scale the report so that it fits into a number of pages horizontally and vertically. For instance, 3 pages horizontally means that tables columns can span over 3 pages, arranged side by side. This is a maximum number of pages; if the table is really small it will still occupy only a single page.
Scaling also means that the font sizes can be reduced (similar to what setFontScalingFactor does) so that the report fits into the number of pages specified by this method.
NOTE: this is mutually exclusive with setTableBreakingEnabled.
| numPagesHorizontally | number of pages in the horizontal direction, 1 for no table breaking in the horizontal direction. |
| numPagesVertically | number of pages in the vertical direction, 0 for no limit |
| void KDReports::Report::setBottomPageMargin | ( | qreal | bottom | ) |
Sets the bottom page margins in mm. The default margin is 20 mm.
| void KDReports::Report::setCurrentRow | ( | const QAbstractItemModel * | model, |
| int | row | ||
| ) |
Sets the current row for the given model. When this value is set, it overrides the values of the 'row' attributes within XML tags
| void KDReports::Report::setDefaultFont | ( | const QFont & | font | ) |
Sets the default font used for text in this report.
| void KDReports::Report::setFirstPageNumber | ( | int | num | ) |
Sets the number of the first page, so that the variable PageNumber starts at another value than 1. This is useful when splitting a large report into smaller documents.
| void KDReports::Report::setFontScalingFactor | ( | qreal | factor | ) |
Scale the fonts in the document by a given factor.
Scale all the fonts used in the main part of the report (not headers and footers) by the given amount. Therefore setFontScalingFactor(1.0) is a no-op.
| void KDReports::Report::setFooterBodySpacing | ( | qreal | spacing | ) |
Sets the margin between the footer and the body of the report, in mm. This margin is 0 by default, i.e. the footer starts immediately under the body.
| void KDReports::Report::setFooterLocation | ( | HeaderLocations | hl, |
| Footer * | footer | ||
| ) |
Set the footer location
| void KDReports::Report::setHeaderBodySpacing | ( | qreal | spacing | ) |
Sets the margin between the header and the body of the report, in mm. This margin is 0 by default, i.e. the body starts immediately under the header.
| void KDReports::Report::setHeaderLocation | ( | HeaderLocations | hl, |
| Header * | header | ||
| ) |
Set the header location
| void KDReports::Report::setLeftPageMargin | ( | qreal | left | ) |
Sets the left page margins in mm. The default margin is 20 mm.
| void KDReports::Report::setMargins | ( | qreal | top, |
| qreal | left, | ||
| qreal | bottom, | ||
| qreal | right | ||
| ) |
Sets the page margins in mm. The default margins are 20 mm.
| void KDReports::Report::setOrientation | ( | QPrinter::Orientation | orientation | ) |
Sets the orientation, QPrinter::Portrait or QPrinter::Landscape.
| void KDReports::Report::setPageSize | ( | const QPrinter::PageSize & | size | ) |
Sets the page size of the report. Example: setPageSize(QPrinter::A4) or setPageSize(QPrinter::Letter); Note that for performance reasons, it is recommended to do this after adding all the elements to the report rather than before.
| void KDReports::Report::setPaperSize | ( | const QSizeF & | paperSize, |
| QPrinter::Unit | unit | ||
| ) |
Sets a custom paper size for the report. This feature requires Qt 4.4 or newer. Supported units are DevicePixel, Millimeter, Point and Inch.
| void KDReports::Report::setParagraphMargins | ( | qreal | left, |
| qreal | top, | ||
| qreal | right, | ||
| qreal | bottom | ||
| ) |
Sets the paragraph margins for all paragraph elements to be created from now on. The default margins are 0,0,0,0.
| void KDReports::Report::setReportMode | ( | ReportMode | reportMode | ) |
Sets the main mode of the report: word-processing or spread-sheet (one large table). The word-processing mode is the most generic one, where text, images, tables etc. can be mixed into a single report. The spread-sheet mode is specific to "one large table", which gives additional features like table breaking over multiple pages horizontally. This is very similar to the difference between word processors and spreadsheets in most office suites.
A note about tables: in word-processing mode, the text of table cells can wrap, if the table is too wide for the page. In spread-sheet mode, table cells do not wrap. Instead, the font is adapted so that the table fits. In spread-sheet mode, the same font is used for all table cells, for layouting and performance reasons.
It is very important to set the mode of the report before doing anything else with the report.
| void KDReports::Report::setRightPageMargin | ( | qreal | right | ) |
Sets the right page margins in mm. The default margin is 20 mm.
| void KDReports::Report::setTableBreakingEnabled | ( | bool | tableBreakingEnabled | ) |
Enable breaking of tables across multiple pages.
By default tables are layouted so that all columns fit into the page width, but for large tables this can wrap the text too much. Table breaking ensures that no wrapping occurs in table cells, the tables span over as many pages as needed horizontally.
Table breaking works best for the case where the document consists of a single table. Otherwise, text after the table might still be after the end of the table, i.e. not where expected.
Calling setTableBreakingEnabled(true) is logically equivalent to calling scaleTo(infinity, 0), i.e. enabling table breaking without a limit on the number of pages.
NOTE: this is mutually exclusive with scaleTo, since scaleTo enables table breaking as well, but with different parameters.
| void KDReports::Report::setTableBreakingPageOrder | ( | TableBreakingPageOrder | pageOrder | ) |
Sets the page order to use when breaking tables. This method is kept for compatibility, use mainTable()->setTableBreakingPageOrder() in new code, instead.
| void KDReports::Report::setTabPositions | ( | const QList< QTextOption::Tab > & | tabs | ) |
Set the list of tabs (tabulations) to use when adding paragraph elements. Those tabs will be set for any paragraph element that is added from now on, until calling this method again.
This method allows to align numbers based on their decimal separator, for instance. Example:
QList<QTextOption::Tab> tabs;
QTextOption::Tab tab;
tab.position = 50; // in mm
tab.type = QTextOption::DelimiterTab;
tab.delimiter = QLatin1Char( '.' );
tabs.append( tab );
report.setTabPositions( tabs );
Then insert text using a tab, like TextElement("\t123.456").
| void KDReports::Report::setTopPageMargin | ( | qreal | top | ) |
Sets the top page margins in mm. The default margin is 20 mm.
| void KDReports::Report::setWatermarkImage | ( | const QImage & | image | ) |
Same as setWatermarkPixmap but with a QImage. Especially useful in threads.
| void KDReports::Report::setWatermarkPixmap | ( | const QPixmap & | pixmap, |
| bool | autoGrayOut = true |
||
| ) |
Sets the pixmap to be used as a watermark. By default, the image will be "grayed out" much like QIcon does for disabled pixmaps. If you do not want this behavior, set autoGrayOut to false. However, you need to ensure then that the image does prevent the legibility of the report. The pixmap will not be scaled, it will be centered on the page. You can set both a watermark text and a watermark image, but the two will overwrite each other so this is not recommended.
| void KDReports::Report::setWatermarkText | ( | const QString & | text, |
| int | rotation = 0, |
||
| const QColor & | color = QColor(204, 204, 204), |
||
| const QFont & | font = QFont(QLatin1String("Helvetica"), 48) |
||
| ) |
Sets the text to be used as a watermark. By default, the text will be displayed with 0 degrees rotation, in a light gray, in a 48pt Helvetica font, centered on the page. You can set both a watermark text and a watermark image, but the two will overwrite each other so this is not recommended. Also notice that if you choose a watermark color that is too dark, this will make the reports less legible.
| void KDReports::Report::setWidthForEndlessPrinter | ( | qreal | widthMM | ) |
Set a custom page size for an endless printer. The page width is known, the document is laid out without pagination within that width. The page height is set automatically so that the entire document fits within one page.
When calling setWidthForEndlessPrinter you don't have to call setPageSize or setOrientation.
Call setWidthForEndlessPrinter(0) to reset to normal (pagesize-dependent) behavior.
NOTE: with Qt-4.3, this feature only works reliably on Unix, using Qt compiled with CUPS support. With Qt-4.4, there is no such limitation and this feature should work everywhere.
| void KDReports::Report::setXmlElementHandler | ( | KDReports::XmlElementHandler * | handler | ) |
Sets an xml element handler. The report does not take ownership of the xml element handler.
If you want it to be deleted with the report, derive from both QObject and XmlElementHandler and give the report as parent QObject.
| TableBreakingPageOrder KDReports::Report::tableBreakingPageOrder | ( | ) | const |
| qreal KDReports::Report::topPageMargins | ( | ) | const |
| QColor KDReports::Report::watermarkColor | ( | ) | const |
| QFont KDReports::Report::watermarkFont | ( | ) | const |
| QImage KDReports::Report::watermarkImage | ( | ) | const |
| QPixmap KDReports::Report::watermarkPixmap | ( | ) | const |
| int KDReports::Report::watermarkRotation | ( | ) | const |
| QString KDReports::Report::watermarkText | ( | ) | const |