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  */
26 class KCHART_EXPORT KChartEnums :public QObject
27 {
28  Q_OBJECT
29 
30 public:
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
Project global class providing some enums needed both by KChartParams and by KChartCustomBox.
Definition: KChartEnums.h:26
static GranularitySequence stringToGranularitySequence(const QString &string)
Converts the specified string to a granularity sequence enum value.
Definition: KChartEnums.h:119
Q_ENUM(...)
MeasureCalculationMode
Measure calculation mode: the way how the absolute value of a KChart::Measure is determined during KC...
Definition: KChartEnums.h:211
MeasureOrientation
Measure orientation mode: the way how the absolute value of a KChart::Measure is determined during KC...
Definition: KChartEnums.h:282
GranularitySequence
GranularitySequence specifies the values, that may be applied, to determine a step width within a giv...
Definition: KChartEnums.h:78
static MeasureOrientation stringToMeasureOrientation(const QString &string)
Converts the specified string to a measure orientation enum value.
Definition: KChartEnums.h:322
TextLayoutPolicy
Text layout policy: what to do if text that is to be drawn would cover neighboring text or neighborin...
Definition: KChartEnums.h:147
static MeasureCalculationMode stringToMeasureCalculationMode(const QString &string)
Converts the specified string to a measure calculation mode enum value.
Definition: KChartEnums.h:251
QString fromLatin1(const char *str, int size)
PositionValue
Numerical values of the static KChart::Position instances, for using a Position::value() with a switc...
Definition: KChartEnums.h:180
Contains KChart macros.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Dec 11 2023 03:52:09 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.