KReport

KReportUnit.h
1 /* This file is part of the KDE project
2  Copyright (C) 1998 1999 Reginald Stadlbauer <[email protected]>
3  Copyright (C) 1998 1999 Torben Weis <[email protected]>
4  Copyright (C) 2004 Nicolas GOUTTE <[email protected]>
5  Copyright (C) 2010 Thomas Zander <[email protected]>
6  Copyright (C) 2012 Friedrich W. H. Kossebau <[email protected]>
7  Copyright (C) 2017 JarosÅ‚aw Staniek <[email protected]>
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  */
70 class KREPORT_EXPORT KReportUnit
71 {
72  Q_DECLARE_TR_FUNCTIONS(KReportUnit)
73 public:
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  */
93  KReportUnit();
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 
333 private:
334  class Private;
335  Private * const d;
336 };
337 
338 #ifndef QT_NO_DEBUG_STREAM
339 KREPORT_EXPORT QDebug operator<<(QDebug, const KReportUnit &);
340 #endif
341 
342 Q_DECLARE_METATYPE(KReportUnit)
343 
344 #endif
static qreal toCicero(qreal ptValue)
Prepare ptValue to be displayed in cicero This method will round to 0.00001 precision,...
Definition: KReportUnit.h:216
Converts between different units.
Definition: KReportUnit.h:70
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
qreal fromUserValue(const QString &value, bool *ok=nullptr) const
Equal to convertToPoint(), use convertToPoint() instead for clarity.
Definition: KReportUnit.h:287
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...
Definition: KReportUnit.h:178
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...
Definition: KReportUnit.h:187
Type
Length units supported by KReport.
Definition: KReportUnit.h:75
static qreal toPoint(qreal ptValue)
Prepare ptValue to be displayed in pt This method will round to 0.001 precision.
Definition: KReportUnit.h:158
qreal fromUserValue(qreal value) const
Equal to convertToPoint(), use convertToPoint() instead for clarity.
Definition: KReportUnit.h:271
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...
Definition: KReportUnit.h:168
static qreal toPica(qreal ptValue)
Prepare ptValue to be displayed in pica This method will round to 0.00001 precision,...
Definition: KReportUnit.h:206
QString toString() const
Equal to symbol(): returns the symbol string of the unit.
Definition: KReportUnit.h:302
static qreal toInch(qreal ptValue)
Prepare ptValue to be displayed in inch This method will round to 0.00001 precision,...
Definition: KReportUnit.h:196
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat May 28 2022 04:32:51 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.