KReport

KReportDesign.h
1 /* This file is part of the KDE project
2  * Copyright (C) 2007-2010 by Adam Pigg <[email protected]>
3  * Copyright (C) 2011-2015 JarosÅ‚aw Staniek <[email protected]>
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2.1 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
17  */
18 
19 #ifndef KREPORTDESIGN_H
20 #define KREPORTDESIGN_H
21 
22 #include "kreport_export.h"
23 #include "config-kreport.h"
24 #include "KReportSection.h"
25 
26 #include <QCoreApplication>
27 
28 class QPageSize;
29 class QMarginsF;
30 class QPageLayout;
31 class KReportElement;
32 
33 //! The KReportDesignReadStatus represents status of reading a report design in .kreport format.
34 /*! It is used by KReportDesign::setContent(). */
35 class KREPORT_EXPORT KReportDesignReadingStatus
36 {
37 public:
38  //! Creates an empty status object.
39  /*! For empty status objects isError() returns false. */
41 
45 
46  //! @return true if the status is error.
47  //! Equivalent of errorLineNumber() >= 0 && errorColumnNumber() >= 0.
48  bool isError() const;
49 
50  //! Error message suitable for displaying to the user, translated.
51  QString errorMessage() const;
52 
53  //! Detailed error message, partially translated.
54  QString errorDetails() const;
55 
56  //! Line number (counting from 0) in which the error occured. -1 if there is no error.
57  int errorLineNumber() const;
58 
59  //! Column number (counting from 0) in which the error occured. -1 if there is no error.
60  int errorColumnNumber() const;
61 
62  void setErrorMessage(const QString& msg);
63  void setErrorDetails(const QString& details);
64  void setErrorLineNumber(int line);
65  void setErrorColumnNumber(int column);
66 
67 private:
68  class Private;
69  Private * const d;
70 };
71 
72 //! Sends information about the reading status @a status to debug output @a dbg.
73 KREPORT_EXPORT QDebug operator<<(QDebug dbg, const KReportDesignReadingStatus& status);
74 
75 //! @brief The KReportDesign class represents a report design in .kreport format
76 class KREPORT_EXPORT KReportDesign
77 {
78  Q_DECLARE_TR_FUNCTIONS(KReportDesign)
79 public:
80  KReportDesign();
81 
82  ~KReportDesign();
83 
84  //! Reads the XML document in .kreport format from the string @a text
85  //! @return true if the content was successfully parsed
86  //! On failure false is returned and if @a status is provided, it is updated accordingly.
87  bool setContent(const QString &text, KReportDesignReadingStatus *status = nullptr);
88 
89  //! Converts the report document back to its textual representation.
90  QString toString(int indent = 1) const;
91 
92  //! @return title for this design
93  QString title() const;
94 
95  //! Sets title for this design to @a title
96  void setTitle(const QString &title);
97 
98  //! @return page layout for this design
99  QPageLayout pageLayout() const;
100 
101  //! Sets the page layout to @a pageLayout
102  //! @note Calling this method does not alter page layouts of existing KReportDesign objects.
103  void setPageLayout(const QPageLayout &pageLayout);
104 
105  //! @return true if this design has section defined of type @a type
106  bool hasSection(KReportSection::Type type) const;
107 
108  //! @return section of type @a type
109  KReportSection section(KReportSection::Type type) const;
110 
111  //! Add section @a section. Previous section of the same type is removed from this design.
112  void addSection(const KReportSection &section);
113 
114  //! Creates and returns report element of type @a typeName
115  //! On success @a errorMessage is cleared, on failure it is set to a nonempty value.
116  KReportElement createElement(const QString &typeName, QString *errorMessage);
117 
118  //! @return default page layout that is used for creating new report designs
119  /*! Attributes that are specified in the design format:
120  - margins: by default equal to equivalent of 1cm in points (QPageLayout::Point).
121  - mode: by default QPageLayout::StandardMode
122  - orientation: by default QPageLayout::Portrait
123  - pageSize: by default equal to default page size of the default printer
124  (QPrinterInfo::defaultPrinter().defaultPageSize()).
125  If there is no default printer, A4 size is used.
126  Passing invalid page size restores defaults explained in
127  documentation of QPageLayout defaultPageLayout().
128  @todo For KDE Plasma use information from the Locale by using
129  readConfigNumEntry("PageSize", QPrinter::A4, m_pageSize, QPrinter::PageSize)
130  from KLocalePrivate::initFormat() (klocale_kde.cpp)
131 
132  Other attributes are ignored by the design format.
133  In particular units for margins and pageSize are always QPageLayout::Point.
134  */
135  static QPageLayout defaultPageLayout();
136 
137  //! Sets default page layout to @a pageLayout
138  //! This information is used when a new report design is created.
139  static void setDefaultPageLayout(const QPageLayout &pageLayout);
140 
141 #ifdef KREPORT_SCRIPTING
142  //! @return text of the script program
143  QString script() const;
144 #endif
145 
146 private:
147  Q_DISABLE_COPY(KReportDesign)
148  class Private;
149  Private * const d;
150 };
151 
152 #endif // KREPORTDESIGN_H
The KReportSection class represents a section of a report design.
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
The KReportDesignReadStatus represents status of reading a report design in .kreport format.
Definition: KReportDesign.h:35
KCALUTILS_EXPORT QString errorMessage(const KCalendarCore::Exception &exception)
Q_SCRIPTABLE CaptureState status()
The KReportElement class represents a functional visual element of a report design.
The KReportDesign class represents a report design in .kreport format.
Definition: KReportDesign.h:76
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Sep 22 2023 04:10:42 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.