KReport

KReportUnit.h
1/* This file is part of the KDE project
2 Copyright (C) 1998 1999 Reginald Stadlbauer <reggie@kde.org>
3 Copyright (C) 1998 1999 Torben Weis <weis@kde.org>
4 Copyright (C) 2004 Nicolas GOUTTE <goutte@kde.org>
5 Copyright (C) 2010 Thomas Zander <zander@kde.org>
6 Copyright (C) 2012 Friedrich W. H. Kossebau <kossebau@kde.org>
7 Copyright (C) 2017 Jarosław Staniek <staniek@kde.org>
8
9 This library is free software; you can redistribute it and/or
10 modify it under the terms of the GNU Library General Public
11 License as published by the Free Software Foundation; either
12 version 2 of the License, or (at your option) any later version.
13
14 This library is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 Library General Public License for more details.
18
19 You should have received a copy of the GNU Library General Public License
20 along with this library; see the file COPYING.LIB. If not, write to
21 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
22 * Boston, MA 02110-1301, USA.
23*/
24
25#ifndef KREPORTUNIT_H
26#define KREPORTUNIT_H
27
28#include <math.h> // for floor
29
30#include <QCoreApplication>
31#include <QString>
32#include <QDebug>
33#include <QMetaType>
34
35#include "kreport_export.h"
36
37// 1 inch ^= 72 pt
38// 1 inch ^= 25.399956 mm (-pedantic ;p)
39// 1 pt = 1/12 pi
40// 1 pt ^= 0.0077880997 cc
41// 1 cc = 12 dd
42// Note: I don't use division but multiplication with the inverse value
43// because it's faster ;p (Werner)
44#define POINT_TO_MM(px) qreal((px)*0.352777167)
45#define MM_TO_POINT(mm) qreal((mm)*2.83465058)
46#define POINT_TO_CM(px) qreal((px)*0.0352777167)
47#define CM_TO_POINT(cm) qreal((cm)*28.3465058)
48#define POINT_TO_DM(px) qreal((px)*0.00352777167)
49#define DM_TO_POINT(dm) qreal((dm)*283.465058)
50#define POINT_TO_INCH(px) qreal((px)*0.01388888888889)
51#define INCH_TO_POINT(inch) qreal((inch)*72.0)
52#define MM_TO_INCH(mm) qreal((mm)*0.039370147)
53#define INCH_TO_MM(inch) qreal((inch)*25.399956)
54#define POINT_TO_PI(px) qreal((px)*0.083333333)
55#define POINT_TO_CC(px) qreal((px)*0.077880997)
56#define PI_TO_POINT(pi) qreal((pi)*12)
57#define CC_TO_POINT(cc) qreal((cc)*12.840103)
58
59/*!
60 * @brief Converts between different units
61 *
62 * KReportUnit stores everything in pt (using "qreal") internally.
63 * When displaying a value to the user, the value is converted to the user's unit
64 * of choice, and rounded to a reasonable precision to avoid 0.999999
65 *
66 * For implementing the selection of a unit type in the UI use the allTypes() method.
67 * it ensure the same order of the unit types in all places, with the order not
68 * bound to the order in the enum so ABI-compatible extension is possible.
69 */
70class KREPORT_EXPORT KReportUnit
71{
72 Q_DECLARE_TR_FUNCTIONS(KReportUnit)
73public:
74 /** Length units supported by %KReport. */
75 enum class Type {
76 Invalid,
77 Millimeter,
78 Centimeter,
79 Decimeter,
80 Inch,
81 Pica,
82 Cicero,
83 Point, ///< Postscript point, 1/72th of an Inco
84 Pixel,
85 Last = Pixel ///< internal
86 };
87
88 /**
89 * @brief Constructs invalid unit
90 *
91 * @since 3.1
92 */
94
95 /** Construct unit with given type and factor. */
96 explicit KReportUnit(Type type, qreal factor = 1.0);
97
98 KReportUnit(const KReportUnit &other);
99
100 ~KReportUnit();
101
102 /// Assigns specified type and factor 1.0 to the object
103 /// @param unit Type of unit
104 KReportUnit& operator=(Type type);
105
106 KReportUnit& operator=(const KReportUnit& other);
107
108 bool operator!=(const KReportUnit &other) const;
109
110 bool operator==(const KReportUnit &other) const;
111
112 /**
113 * @brief Returns true if type of this unit is valid
114 *
115 * @since 3.1
116 */
117 bool isValid() const;
118
119 /**
120 * @brief Returns list of all supported types (without Invalid)
121 *
122 * @since 3.1
123 */
124 static QList<Type> allTypes();
125
126 /** Returns the type of this unit */
127 KReportUnit::Type type() const;
128
129 /**
130 * @brief Returns (translated) description string for type of this unit
131 *
132 * @since 3.1
133 */
134 QString description() const;
135
136 /**
137 * @brief Returns (translated) description string for given unit type
138 *
139 * @since 3.1
140 */
141 static QString description(KReportUnit::Type type);
142
143 /**
144 * @brief Returns the list of (translated) description strings for given list of types
145 *
146 * @since 3.1
147 */
148 static QStringList descriptions(const QList<Type> &types);
149
150 void setFactor(qreal factor);
151
152 qreal factor() const;
153
154 /**
155 * Prepare ptValue to be displayed in pt
156 * This method will round to 0.001 precision
157 */
158 static inline qreal toPoint(qreal ptValue)
159 {
160 // No conversion, only rounding (to 0.001 precision)
161 return floor(ptValue * 1000.0) / 1000.0;
162 }
163
164 /**
165 * Prepare ptValue to be displayed in mm
166 * This method will round to 0.0001 precision, use POINT_TO_MM() for lossless conversion.
167 */
168 static inline qreal toMillimeter(qreal ptValue)
169 {
170 // "mm" values are rounded to 0.0001 millimeters
171 return floor(POINT_TO_MM(ptValue) * 10000.0) / 10000.0;
172 }
173
174 /**
175 * Prepare ptValue to be displayed in cm
176 * This method will round to 0.0001 precision, use POINT_TO_CM() for lossless conversion.
177 */
178 static inline qreal toCentimeter(qreal ptValue)
179 {
180 return floor(POINT_TO_CM(ptValue) * 10000.0) / 10000.0;
181 }
182
183 /**
184 * Prepare ptValue to be displayed in dm
185 * This method will round to 0.0001 precision, use POINT_TO_DM() for lossless conversion.
186 */
187 static inline qreal toDecimeter(qreal ptValue)
188 {
189 return floor(POINT_TO_DM(ptValue) * 10000.0) / 10000.0;
190 }
191
192 /**
193 * Prepare ptValue to be displayed in inch
194 * This method will round to 0.00001 precision, use POINT_TO_INCH() for lossless conversion.
195 */
196 static inline qreal toInch(qreal ptValue)
197 {
198 // "in" values are rounded to 0.00001 inches
199 return floor(POINT_TO_INCH(ptValue) * 100000.0) / 100000.0;
200 }
201
202 /**
203 * Prepare ptValue to be displayed in pica
204 * This method will round to 0.00001 precision, use POINT_TO_PI() for lossless conversion.
205 */
206 static inline qreal toPica(qreal ptValue)
207 {
208 // "pi" values are rounded to 0.00001 inches
209 return floor(POINT_TO_PI(ptValue) * 100000.0) / 100000.0;
210 }
211
212 /**
213 * Prepare ptValue to be displayed in cicero
214 * This method will round to 0.00001 precision, use POINT_TO_CC() for lossless conversion.
215 */
216 static inline qreal toCicero(qreal ptValue)
217 {
218 // "cc" values are rounded to 0.00001 inches
219 return floor(POINT_TO_CC(ptValue) * 100000.0) / 100000.0;
220 }
221
222 /**
223 * convert the given value directly from one unit to another with high accuracy
224 */
225 static qreal convertFromUnitToUnit(qreal value, const KReportUnit &fromUnit,
226 const KReportUnit &toUnit, qreal factor = 1.0);
227
228 /**
229 * convert the given value directly from one unit to another with high accuracy
230 */
231 static QPointF convertFromUnitToUnit(const QPointF &value,
232 const KReportUnit &fromUnit,
233 const KReportUnit &toUnit);
234
235 /**
236 * convert the given value directly from one unit to another with high accuracy
237 */
238 static QSizeF convertFromUnitToUnit(const QSizeF &value, const KReportUnit &fromUnit,
239 const KReportUnit &toUnit);
240
241 /**
242 * This method is the one to use to display a value in a dialog
243 * \return the value @a ptValue converted to unit and rounded, ready to be displayed
244 */
245 qreal toUserValue(qreal ptValue) const;
246
247 /**
248 * Convert the value @a ptValue to a given unit @a unit
249 * Unlike KReportUnit::ptToUnit the return value remains unrounded, so that it can be used in complex calculation
250 * \return the converted value
251 */
252 static qreal ptToUnit(qreal ptValue, const KReportUnit &unit);
253
254 /// This method is the one to use to display a value in a dialog
255 /// @return the value @a ptValue converted the unit and rounded, ready to be displayed
256 QString toUserStringValue(qreal ptValue) const;
257
258 //! @return the value converted to points with high accuracy
259 qreal convertToPoint(qreal value) const;
260
261 //! @return the value converted from points to the actual unit with high accuracy
262 qreal convertFromPoint(qreal ptValue) const;
263
264 //! @return the value converted from points to the actual unit with high accuracy
265 QPointF convertFromPoint(const QPointF &ptValue) const;
266
267 //! @return the value converted from points to the actual unit with high accuracy
268 QSizeF convertFromPoint(const QSizeF &ptValue) const;
269
270 //! Equal to convertToPoint(), use convertToPoint() instead for clarity
271 inline qreal fromUserValue(qreal value) const { return convertToPoint(value); }
272
273 /// @return the value converted to points with high accuracy
274 QPointF convertToPoint(const QPointF &value) const;
275
276 /// @return the value converted to points with high accuracy
277 QSizeF convertToPoint(const QSizeF &value) const;
278
279 /// @return the value converted to points with high accuracy
280 /// @param value value entered by the user
281 /// @param ok if set, the pointed bool is set to true if the value could be
282 /// converted to a qreal, and to false otherwise.
283 /// @return the value converted to points for internal use
284 qreal convertToPoint(const QString &value, bool *ok = nullptr) const;
285
286 //! Equal to convertToPoint(), use convertToPoint() instead for clarity
287 inline qreal fromUserValue(const QString &value, bool *ok = nullptr) const {
288 return convertToPoint(value, ok);
289 }
290
291 //! Returns the symbol string of given unit type
292 //! Symbol for Invalid type is empty string.
293 static QString symbol(KReportUnit::Type type);
294
295 //! Returns the symbol string of the unit
296 //! Symbol for Invalid type is empty string.
297 QString symbol() const;
298
299 /**
300 * Equal to symbol(): returns the symbol string of the unit.
301 */
302 inline QString toString() const
303 {
304 return symbol();
305 }
306
307 /**
308 * @brief Returns a unit symbol string to type
309 *
310 * @param symbol symbol to convert, must be lowercase
311 * @return Invalid type for unsupported symbol
312 *
313 * @since 3.1
314 */
315 static KReportUnit::Type symbolToType(const QString &symbol);
316
317 /**
318 * @brief Returns the list of unit symbols for the given types
319 *
320 * @since 3.1
321 */
322 static QStringList symbols(const QList<Type> &types);
323
324 /// Parses common %KReport and ODF values, like "10cm", "5mm" to pt.
325 /// If no unit is specified, pt is assumed.
326 /// @a defaultVal is in Points
327 static qreal parseValue(const QString &value, qreal defaultVal = 0.0);
328
329 /// parse an angle to its value in degrees
330 /// @a defaultVal is in degrees
331 static qreal parseAngle(const QString &value, qreal defaultVal = 0.0);
332
333private:
334 class Private;
335 Private * const d;
336};
337
338#ifndef QT_NO_DEBUG_STREAM
339KREPORT_EXPORT QDebug operator<<(QDebug, const KReportUnit &);
340#endif
341
342Q_DECLARE_METATYPE(KReportUnit)
343
344#endif
Converts between different units.
Definition KReportUnit.h:71
QString toString() const
Equal to symbol(): returns the symbol string of the unit.
qreal fromUserValue(const QString &value, bool *ok=nullptr) const
Equal to convertToPoint(), use convertToPoint() instead for clarity.
static qreal toCicero(qreal ptValue)
Prepare ptValue to be displayed in cicero This method will round to 0.00001 precision,...
static qreal toPica(qreal ptValue)
Prepare ptValue to be displayed in pica This method will round to 0.00001 precision,...
Type
Length units supported by KReport.
Definition KReportUnit.h:75
qreal fromUserValue(qreal value) const
Equal to convertToPoint(), use convertToPoint() instead for clarity.
static qreal toDecimeter(qreal ptValue)
Prepare ptValue to be displayed in dm This method will round to 0.0001 precision, use POINT_TO_DM() f...
static qreal toCentimeter(qreal ptValue)
Prepare ptValue to be displayed in cm This method will round to 0.0001 precision, use POINT_TO_CM() f...
static qreal toPoint(qreal ptValue)
Prepare ptValue to be displayed in pt This method will round to 0.001 precision.
static qreal toInch(qreal ptValue)
Prepare ptValue to be displayed in inch This method will round to 0.00001 precision,...
static qreal toMillimeter(qreal ptValue)
Prepare ptValue to be displayed in mm This method will round to 0.0001 precision, use POINT_TO_MM() f...
QDebug operator<<(QDebug dbg, const PerceptualColor::MultiSpinBoxSection &value)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 18 2024 12:19:58 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.