KChart

KChartEnums.h
Go to the documentation of this file.
1/*
2 * SPDX-FileCopyrightText: 2001-2015 Klaralvdalens Datakonsult AB. All rights reserved.
3 *
4 * This file is part of the KD Chart library.
5 *
6 * SPDX-License-Identifier: GPL-2.0-or-later
7 */
8
9#ifndef __KChartEnums_H__
10#define __KChartEnums_H__
11
12#include "KChartGlobal.h"
13
14#include <QRectF>
15#include <QObject>
16#include <QVector>
17
18/** \file KChartEnums.h
19 \brief Definition of global enums.
20 */
21
22/**
23 Project global class providing some enums needed both by KChartParams
24 and by KChartCustomBox.
25 */
26class KCHART_EXPORT KChartEnums :public QObject
27{
28 Q_OBJECT
29
30public:
31 /**
32 GranularitySequence specifies the values, that may be applied,
33 to determine a step width within a given data range.
34
35 \note Granularity with can be set for Linear axis calculation mode only,
36 there is no way to specify a step width for Logarithmic axes.
37
38 Value occurring in the GranularitySequence names only are showing
39 their respective relation ship. For real data they will most times not
40 be used directly, but be multiplied by positive (or negative, resp.)
41 powers of ten.
42
43 A granularity sequence is a sequence of values from the following set:
44 1, 1.25, 2, 2.5, 5.
45
46 The reason for using one of the following three pre-defined granularity
47 sequences (instead of just using the best matching step width) is to
48 follow a simple rule: If scaling becomes finer (== smaller step width)
49 no value, that has been on a grid line before, shall loose its line
50 and be NOT on a grid line anymore!
51
52 This means: Smaller step width may not remove any grid lines, but it
53 may add additional lines in between.
54
55 \li \c GranularitySequence_10_20 Step widths can be 1, or 2, but they never can be 2.5 nor 5, nor 1.25.
56 \li \c GranularitySequence_10_50 Step widths can be 1, or 5, but they never can be 2, nor 2.5, nor 1.25.
57 \li \c GranularitySequence_25_50 Step widths can be 2.5, or 5, but they never can be 1, nor 2, nor 1.25.
58 \li \c GranularitySequence_125_25 Step widths can be 1.25 or 2.5 but they never can be 1, nor 2, nor 5.
59 \li \c GranularitySequenceIrregular Step widths can be all of these values: 1, or 1.25, or 2, or 2.5, or 5.
60
61 \note When ever possible, try to avoid using GranularitySequenceIrregular!
62 Allowing all possible step values, using this granularity sequence involves a
63 serious risk: Your users might be irritated due to 'jumping' grid lines, when step size
64 is changed from 2.5 to 2 (or vice versa, resp.).
65 In case you still want to use GranularitySequenceIrregular just make sure to NOT draw
66 any sub-grid lines, because in most cases you will get not-matching step widths for
67 the sub-grid.
68 In short: GranularitySequenceIrregular can safely be used if your data range is not
69 changing at all AND (b) you will not allow the coordinate plane to be zoomed
70 AND (c) you are not displaying any sub-grid lines.
71
72 Since you probably like having the value 1 as an allowed step width,
73 the granularity sequence decision boils down to a boolean question:
74 \li To get ten divided by five you use GranularitySequence_10_20, while
75 \li for having it divided by two GranularitySequence_10_50 is your choice.
76
77 */
79 GranularitySequence_10_20,
80 GranularitySequence_10_50,
81 GranularitySequence_25_50,
82 GranularitySequence_125_25,
83 GranularitySequenceIrregular
84 };
85 Q_ENUM(GranularitySequence)
86
87
88 /**
89 Converts the specified granularity sequence enum to a
90 string representation.
91
92 \param sequence the granularity sequence enum to convert
93 \return the string representation of the granularity sequence
94 */
95 static QString granularitySequenceToString( GranularitySequence sequence ) {
96 switch ( sequence ) {
97 case GranularitySequence_10_20:
98 return QString::fromLatin1("GranularitySequence_10_20");
99 case GranularitySequence_10_50:
100 return QString::fromLatin1("GranularitySequence_10_50");
101 case GranularitySequence_25_50:
102 return QString::fromLatin1("GranularitySequence_25_50");
103 case GranularitySequence_125_25:
104 return QString::fromLatin1("GranularitySequence_125_25");
105 case GranularitySequenceIrregular:
106 return QString::fromLatin1("GranularitySequenceIrregular");
107 }
108 Q_ASSERT( !"Unknown GranularitySequenceValue" );
109 return QString::fromLatin1("GranularitySequence_10_20");
110 }
111
112
113 /**
114 Converts the specified string to a granularity sequence enum value.
115
116 \param string the string to convert
117 \return the granularity sequence enum value
118 */
120 if ( string == QString::fromLatin1("GranularitySequence_10_20") )
121 return GranularitySequence_10_20;
122 if ( string == QString::fromLatin1("GranularitySequence_10_50") )
123 return GranularitySequence_10_50;
124 if ( string == QString::fromLatin1("GranularitySequence_25_50") )
125 return GranularitySequence_25_50;
126 if ( string == QString::fromLatin1("GranularitySequence_125") )
127 return GranularitySequence_125_25;
128 if ( string == QString::fromLatin1("GranularitySequenceIrregular") )
129 return GranularitySequenceIrregular;
130 // default, should not happen
131 return GranularitySequence_10_20;
132 }
133
134
135 /**
136 Text layout policy: what to do if text that is to be drawn would
137 cover neighboring text or neighboring areas.
138
139 \li \c LayoutJustOverwrite Just ignore the layout collision and write the text nevertheless.
140 \li \c LayoutPolicyRotate Try counter-clockwise rotation to make the text fit into the space.
141 \li \c LayoutPolicyShiftVertically Shift the text baseline upwards (or downwards, resp.) and draw a connector line between the text and its anchor.
142 \li \c LayoutPolicyShiftHorizontally Shift the text baseline to the left (or to the right, resp.) and draw a connector line between the text and its anchor.
143 \li \c LayoutPolicyShrinkFontSize Reduce the text font size.
144
145 \sa KChartParams::setPrintDataValues
146 */
147 enum TextLayoutPolicy { LayoutJustOverwrite,
148 LayoutPolicyRotate,
149 LayoutPolicyShiftVertically,
150 LayoutPolicyShiftHorizontally,
151 LayoutPolicyShrinkFontSize
152 };
153 Q_ENUM( TextLayoutPolicy )
154
155 /**
156 Converts the specified text layout policy enum to a
157 string representation.
158
159 \param type the text layout policy to convert
160 \return the string representation of the text layout policy enum
161 */
162 static QString layoutPolicyToString( TextLayoutPolicy type );
163
164
165 /**
166 Converts the specified string to a text layout policy enum value.
167
168 \param string the string to convert
169 \return the text layout policy enum value
170 */
171 static TextLayoutPolicy stringToLayoutPolicy( const QString& string );
172
173
174 /**
175 Numerical values of the static KChart::Position instances,
176 for using a Position::value() with a switch () statement.
177
178 \sa Position
179 */
181 PositionUnknown = 0,
182 PositionCenter = 1,
183 PositionNorthWest = 2,
184 PositionNorth = 3,
185 PositionNorthEast = 4,
186 PositionEast = 5,
187 PositionSouthEast = 6,
188 PositionSouth = 7,
189 PositionSouthWest = 8,
190 PositionWest = 9,
191 PositionFloating =10
192 };
193 Q_ENUM( PositionValue )
194
195
196 /**
197 Measure calculation mode: the way how the absolute value of a KChart::Measure is determined during KChart's internal geometry calculation time.
198
199 KChart::Measure values either are relative (calculated in relation to a given AbstractArea), or they are absolute (used as fixed values).
200
201 Values stored in relative measure always are interpreted as per-mille of a reference area's height (or width, resp.) depending on the orientation set for the KChart::Measure.
202
203 \li \c MeasureCalculationModeAbsolute Value set by setValue() is absolute, to be used unchanged.
204 \li \c MeasureCalculationModeRelative Value is relative, the reference area is specified by setReferenceArea(), and orientation specified by setOrientation().
205 \li \c MeasureCalculationModeAuto Value is relative, KChart will automatically determine which reference area to use, and it will determine the orientation too.
206 \li \c MeasureCalculationModeAutoArea Value is relative, Orientation is specified by setOrientation(), and KChart will automatically determine which reference area to use.
207 \li \c MeasureCalculationModeAutoOrientation Value is relative, Area is specified by setReferenceArea(), and KChart will automatically determine which orientation to use.
208
209 \sa KChart::Measure::setCalculationMode
210 */
212 MeasureCalculationModeAbsolute,
213 MeasureCalculationModeRelative,
214 MeasureCalculationModeAuto,
215 MeasureCalculationModeAutoArea,
216 MeasureCalculationModeAutoOrientation
217 };
218 Q_ENUM( MeasureCalculationMode )
219
220 /**
221 Converts the specified measure calculation mode enum to a
222 string representation.
223
224 \param mode the measure calculation mode to convert
225 \return the string representation of the Measure calculation mode enum
226 */
227 static QString measureCalculationModeToString( MeasureCalculationMode mode ) {
228 switch ( mode ) {
229 case MeasureCalculationModeAbsolute:
230 return QString::fromLatin1("MeasureCalculationModeAbsolute");
231 case MeasureCalculationModeAuto:
232 return QString::fromLatin1("MeasureCalculationModeAuto");
233 case MeasureCalculationModeAutoArea:
234 return QString::fromLatin1("MeasureCalculationModeAutoArea");
235 case MeasureCalculationModeAutoOrientation:
236 return QString::fromLatin1("MeasureCalculationModeAutoOrientation");
237 case MeasureCalculationModeRelative:
238 return QString::fromLatin1("MeasureCalculationModeRelative");
239 }
240 Q_ASSERT( !"unhandled MeasureCalculationMode" );
241 return QString::fromLatin1("MeasureCalculationModeAuto");
242 }
243
244
245 /**
246 Converts the specified string to a measure calculation mode enum value.
247
248 \param string the string to convert
249 \return the measure calculation mode enum value
250 */
252 if ( string == QString::fromLatin1("MeasureCalculationModeAbsolute") )
253 return MeasureCalculationModeAbsolute;
254 if ( string == QString::fromLatin1("MeasureCalculationModeAuto") )
255 return MeasureCalculationModeAuto;
256 if ( string == QString::fromLatin1("MeasureCalculationModeAutoArea") )
257 return MeasureCalculationModeAutoArea;
258 if ( string == QString::fromLatin1("MeasureCalculationModeAutoOrientation") )
259 return MeasureCalculationModeAutoOrientation;
260 if ( string == QString::fromLatin1("MeasureCalculationModeRelative") )
261 return MeasureCalculationModeRelative;
262 // default, should not happen
263 return MeasureCalculationModeAuto;
264 }
265
266 /**
267 Measure orientation mode: the way how the absolute value of a KChart::Measure is determined during KChart's internal geometry calculation time.
268
269 KChart::Measure values either are relative (calculated in relation to a given AbstractArea), or they are absolute (used as fixed values).
270
271 Values stored in relative measure take into account the width (and/or the height, resp.) of a so-called reference area,
272 that is either specified by KChart::Measure::setReferenceArea, or determined by KChart automatically, respectively.
273
274 \li \c MeasureOrientationAuto Value is calculated, based upon the width (or on the height, resp.) of the reference area: KChart will automatically determie an appropriate way.
275 \li \c MeasureOrientationHorizontal Value is calculated, based upon the width of the reference area.
276 \li \c MeasureOrientationVertical Value is calculated, based upon the height of the reference area.
277 \li \c MeasureOrientationMinimum Value is calculated, based upon the width (or on the height, resp.) of the reference area - which ever is smaller.
278 \li \c MeasureOrientationMaximum Value is calculated, based upon the width (or on the height, resp.) of the reference area - which ever is smaller.
279
280 \sa KChart::Measure::setOrientationMode
281 */
283 MeasureOrientationAuto,
284 MeasureOrientationHorizontal,
285 MeasureOrientationVertical,
286 MeasureOrientationMinimum,
287 MeasureOrientationMaximum
288 };
289 Q_ENUM( MeasureOrientation )
290
291 /**
292 Converts the specified measure orientation enum to a
293 string representation.
294
295 \param mode the measure orientation to convert
296 \return the string representation of the measure orientation enum
297 */
298 static QString measureOrientationToString( MeasureOrientation mode ) {
299 switch ( mode ) {
300 case MeasureOrientationAuto:
301 return QString::fromLatin1("MeasureOrientationAuto");
302 case MeasureOrientationHorizontal:
303 return QString::fromLatin1("MeasureOrientationHorizontal");
304 case MeasureOrientationVertical:
305 return QString::fromLatin1("MeasureOrientationVertical");
306 case MeasureOrientationMinimum:
307 return QString::fromLatin1("MeasureOrientationMinimum");
308 case MeasureOrientationMaximum:
309 return QString::fromLatin1("MeasureOrientationMaximum");
310 }
311 Q_ASSERT( !"Unknown MeasureOrientation value" );
312 return QString::fromLatin1("MeasureOrientationAuto");
313 }
314
315
316 /**
317 Converts the specified string to a measure orientation enum value.
318
319 \param string the string to convert
320 \return the measure orientation enum value
321 */
323 if ( string == QString::fromLatin1("MeasureOrientationAuto") )
324 return MeasureOrientationAuto;
325 if ( string == QString::fromLatin1("MeasureOrientationHorizontal") )
326 return MeasureOrientationHorizontal;
327 if ( string == QString::fromLatin1("MeasureOrientationVertical") )
328 return MeasureOrientationVertical;
329 if ( string == QString::fromLatin1("MeasureOrientationMinimum") )
330 return MeasureOrientationMinimum;
331 if ( string == QString::fromLatin1("MeasureOrientationMaximum") )
332 return MeasureOrientationMaximum;
333 // default, should not happen
334 return MeasureOrientationAuto;
335 }
336
337
338};
339
340
341#endif
Contains KChart macros.
Project global class providing some enums needed both by KChartParams and by KChartCustomBox.
Definition KChartEnums.h:27
static GranularitySequence stringToGranularitySequence(const QString &string)
Converts the specified string to a granularity sequence enum value.
GranularitySequence
GranularitySequence specifies the values, that may be applied, to determine a step width within a giv...
Definition KChartEnums.h:78
MeasureCalculationMode
Measure calculation mode: the way how the absolute value of a KChart::Measure is determined during KC...
TextLayoutPolicy
Text layout policy: what to do if text that is to be drawn would cover neighboring text or neighborin...
static MeasureCalculationMode stringToMeasureCalculationMode(const QString &string)
Converts the specified string to a measure calculation mode enum value.
PositionValue
Numerical values of the static KChart::Position instances, for using a Position::value() with a switc...
static MeasureOrientation stringToMeasureOrientation(const QString &string)
Converts the specified string to a measure orientation enum value.
MeasureOrientation
Measure orientation mode: the way how the absolute value of a KChart::Measure is determined during KC...
Q_ENUM(...)
T qobject_cast(QObject *object)
QString fromLatin1(QByteArrayView str)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 14 2024 11:59:21 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.