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