KChart

KChartEnums.h
Go to the documentation of this file.
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  */
90  GranularitySequence_10_20,
91  GranularitySequence_10_50,
92  GranularitySequence_25_50,
93  GranularitySequence_125_25,
94  GranularitySequenceIrregular
95  };
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  */
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  };
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  */
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  };
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  */
223  MeasureCalculationModeAbsolute,
224  MeasureCalculationModeRelative,
225  MeasureCalculationModeAuto,
226  MeasureCalculationModeAutoArea,
227  MeasureCalculationModeAutoOrientation
228  };
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  */
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  */
294  MeasureOrientationAuto,
295  MeasureOrientationHorizontal,
296  MeasureOrientationVertical,
297  MeasureOrientationMinimum,
298  MeasureOrientationMaximum
299  };
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  */
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
Q_ENUM(...)
PositionValue
Numerical values of the static KChart::Position instances, for using a Position::value() with a switc...
Definition: KChartEnums.h:191
MeasureCalculationMode
Measure calculation mode: the way how the absolute value of a KChart::Measure is determined during KC...
Definition: KChartEnums.h:222
Project global class providing some enums needed both by KChartParams and by KChartCustomBox.
Definition: KChartEnums.h:37
static MeasureOrientation stringToMeasureOrientation(const QString &string)
Converts the specified string to a measure orientation enum value.
Definition: KChartEnums.h:333
Class only listed here to document inheritance of some KChart classes.
TextLayoutPolicy
Text layout policy: what to do if text that is to be drawn would cover neighboring text or neighborin...
Definition: KChartEnums.h:158
Contains KChart macros.
MeasureOrientation
Measure orientation mode: the way how the absolute value of a KChart::Measure is determined during KC...
Definition: KChartEnums.h:293
GranularitySequence
GranularitySequence specifies the values, that may be applied, to determine a step width within a giv...
Definition: KChartEnums.h:89
static MeasureCalculationMode stringToMeasureCalculationMode(const QString &string)
Converts the specified string to a measure calculation mode enum value.
Definition: KChartEnums.h:262
QString fromLatin1(const char *str, int size)
static GranularitySequence stringToGranularitySequence(const QString &string)
Converts the specified string to a granularity sequence enum value.
Definition: KChartEnums.h:130
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Apr 10 2021 22:36:39 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.