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