KChart

KChartPosition.h
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 KCHARTPOSITION_H
10 #define KCHARTPOSITION_H
11 
12 #include <QDebug>
13 #include <Qt>
14 #include <QMetaType>
15 #include <QCoreApplication>
16 #include "KChartGlobal.h"
17 #include "KChartEnums.h"
18 #include <QStringList>
19 QT_BEGIN_NAMESPACE
20 
21 class QByteArray;
22 template <typename T> class QList;
23 QT_END_NAMESPACE
24 
25 namespace KChart {
26 
27 /**
28  * \class Position KChartPosition.h
29  * \brief Defines a position, using compass terminology.
30  *
31  * Using KChart::Position you can specify one of nine
32  * pre-defined, logical points (see the \c static \c const getter
33  * methods below), in a similar way, as you would use a
34  * compass to navigate on a map.
35  *
36  * For each piece (slice/bar, etc.) of a chart for example, you can specify the position of the value
37  * labels. Figure 1 illustrates which cardinal points refer to which points
38  * on a pie or bar chart, resp. In the graphic, "N" stands for North, "S" for South, etc.
39  *
40  * \image html position-alignments.png "Figure 1: Different interpretations of KChart::Position within KChart"
41  *
42  * \note Often you will declare a \c Position together with the
43  * RelativePosition class, to specify a logical point,
44  * which then will be used to layout your chart at runtime,
45  * e.g. for specifying the location of a floating Legend box.
46  *
47  * For comparing a Position's value with a switch () statement,
48  * you can use numeric values defined in KChartEnums, like this:
49 \verbatim
50 switch ( yourPosition().value() ) {
51  case KChartEnums::PositionNorthWest:
52  // your code ...
53  break;
54  case KChartEnums::PositionNorth:
55  // your code ...
56  break;
57 }
58 \endverbatim
59  * \sa RelativePosition, KChartEnums::PositionValue
60  */
61 class KCHART_EXPORT Position
62 {
63  Q_DECLARE_TR_FUNCTIONS( Position )
64  Position( int value );
65 public:
66  Position();
67  Position( KChartEnums::PositionValue value ); // intentionally non-explicit
68 
69  KChartEnums::PositionValue value() const;
70 
71  const char *name() const;
72  QString printableName() const;
73 
74  bool isUnknown() const;
75 
76  bool isWestSide() const;
77  bool isNorthSide() const;
78  bool isEastSide() const;
79  bool isSouthSide() const;
80 
81  bool isCorner() const;
82  bool isPole() const;
83 
84  bool isFloating() const;
85 
86  static const Position& Unknown;
87  static const Position& Center;
88  static const Position& NorthWest;
89  static const Position& North;
90  static const Position& NorthEast;
91  static const Position& East;
92  static const Position& SouthEast;
93  static const Position& South;
94  static const Position& SouthWest;
95  static const Position& West;
96 
97  static const Position& Floating;
98 
99  // boolean flags: 1, 2, 4, 8, ...
100  enum Option {
101  IncludeCenter = 0x1,
102  IncludeFloating = 0x2 };
103  Q_DECLARE_FLAGS( Options, Option )
104 
105  // Unfortunately the following typecast from int to Options is needed
106  // as the | operator is not defined yet, this will be done by
107  // the macro Q_DECLARE_OPERATORS_FOR_FLAGS( KChart::Position::Options )
108  // at the bottom of this file.
109  static QList<QByteArray> names( Options options = Options(IncludeCenter | IncludeFloating) );
110  static QStringList printableNames( Options options = Options(IncludeCenter | IncludeFloating) );
111 
112  static Position fromName(const char * name);
113  static Position fromName(const QByteArray & name);
114 
115  bool operator==( const Position& ) const;
116  bool operator==( int ) const;
117  bool operator!=( const Position& ) const;
118  bool operator!=( int ) const;
119 
120 private:
121  int m_value;
122 }; // End of class Position
123 
124 inline bool Position::operator!=( const Position & other ) const { return !operator==( other ); }
125 inline bool Position::operator!=( int other ) const { return !operator==( other ); }
126 
127 /**
128  * @brief Stores the absolute target points of a Position
129  * \internal
130  */
131 class KCHART_EXPORT PositionPoints
132 {
133  public:
134  PositionPoints() {} // all points get initialized with the default automatically
135 
137  QPointF center,
138  QPointF northWest,
139  QPointF north,
140  QPointF northEast,
141  QPointF east,
142  QPointF southEast,
143  QPointF south,
144  QPointF southWest,
145  QPointF west )
146  : mPositionCenter( center )
147  , mPositionNorthWest( northWest )
148  , mPositionNorth( north )
149  , mPositionNorthEast( northEast )
150  , mPositionEast( east )
151  , mPositionSouthEast( southEast )
152  , mPositionSouth( south )
153  , mPositionSouthWest( southWest )
154  , mPositionWest( west )
155  {}
157  const QPointF& onePointForAllPositions )
158  : mPositionCenter( onePointForAllPositions )
159  , mPositionNorthWest( onePointForAllPositions )
160  , mPositionNorth( onePointForAllPositions )
161  , mPositionNorthEast( onePointForAllPositions )
162  , mPositionEast( onePointForAllPositions )
163  , mPositionSouthEast( onePointForAllPositions )
164  , mPositionSouth( onePointForAllPositions )
165  , mPositionSouthWest( onePointForAllPositions )
166  , mPositionWest( onePointForAllPositions )
167  {}
169  const QRectF& rect )
170  {
171  const QRectF r( rect.normalized() );
172  mPositionCenter = r.center();
173  mPositionNorthWest = r.topLeft();
174  mPositionNorth = QPointF(r.center().x(), r.top());
175  mPositionNorthEast = r.topRight();
176  mPositionEast = QPointF(r.right(), r.center().y());
177  mPositionSouthEast = r.bottomRight();
178  mPositionSouth = QPointF(r.center().x(), r.bottom());
179  mPositionSouthWest = r.bottomLeft();
180  mPositionWest = QPointF(r.left(), r.center().y());
181  }
183  QPointF northWest,
184  QPointF northEast,
185  QPointF southEast,
186  QPointF southWest )
187  : mPositionCenter( (northWest + southEast) / 2.0 )
188  , mPositionNorthWest( northWest )
189  , mPositionNorth( (northWest + northEast) / 2.0 )
190  , mPositionNorthEast( northEast )
191  , mPositionEast( (northEast + southEast) / 2.0 )
192  , mPositionSouthEast( southEast )
193  , mPositionSouth( (southWest + southEast) / 2.0 )
194  , mPositionSouthWest( southWest )
195  , mPositionWest( (northWest + southWest) / 2.0 )
196  {}
197 
198  void setDegrees( KChartEnums::PositionValue pos, qreal degrees )
199  {
200  mapOfDegrees[pos] = degrees;
201  }
202 
203 #if defined(Q_COMPILER_MANGLES_RETURN_TYPE)
204  const qreal degrees( KChartEnums::PositionValue pos ) const
205 #else
206  qreal degrees( KChartEnums::PositionValue pos ) const
207 #endif
208  {
209  if ( mapOfDegrees.contains(pos) )
210  return mapOfDegrees[pos];
211  return 0.0;
212  }
213 
214 #if defined(Q_COMPILER_MANGLES_RETURN_TYPE)
215  const QPointF point( Position position ) const
216 #else
217  QPointF point( Position position ) const
218 #endif
219  {
220  //qDebug() << "point( " << position.name() << " )";
221  if ( position == Position::Center)
222  return mPositionCenter;
223  if ( position == Position::NorthWest)
224  return mPositionNorthWest;
225  if ( position == Position::North)
226  return mPositionNorth;
227  if ( position == Position::NorthEast)
228  return mPositionNorthEast;
229  if ( position == Position::East)
230  return mPositionEast;
231  if ( position == Position::SouthEast)
232  return mPositionSouthEast;
233  if ( position == Position::South)
234  return mPositionSouth;
235  if ( position == Position::SouthWest)
236  return mPositionSouthWest;
237  if ( position == Position::West)
238  return mPositionWest;
239  return mPositionUnknown;
240  }
241 
242  bool isNull() const
243  {
244  return
245  mPositionUnknown.isNull() &&
246  mPositionCenter.isNull() &&
247  mPositionNorthWest.isNull() &&
248  mPositionNorth.isNull() &&
249  mPositionNorthEast.isNull() &&
250  mPositionEast.isNull() &&
251  mPositionSouthEast.isNull() &&
252  mPositionSouth.isNull() &&
253  mPositionSouthWest.isNull() &&
254  mPositionWest.isNull();
255  }
256 
257  QPointF mPositionUnknown;
258  QPointF mPositionCenter;
259  QPointF mPositionNorthWest;
260  QPointF mPositionNorth;
261  QPointF mPositionNorthEast;
262  QPointF mPositionEast;
263  QPointF mPositionSouthEast;
264  QPointF mPositionSouth;
265  QPointF mPositionSouthWest;
266  QPointF mPositionWest;
268 
269 }; // End of class PositionPoints
270 
271 
272 }
273 
274 
275 #if !defined(QT_NO_DEBUG_STREAM)
276 KCHART_EXPORT QDebug operator<<(QDebug, const KChart::Position& );
277 #endif /* QT_NO_DEBUG_STREAM */
278 
279 QT_BEGIN_NAMESPACE
280 Q_DECLARE_TYPEINFO( KChart::Position, Q_MOVABLE_TYPE );
281 Q_DECLARE_OPERATORS_FOR_FLAGS( KChart::Position::Options )
282 QT_END_NAMESPACE
283 
284 Q_DECLARE_METATYPE( KChart::Position )
285 
286 #endif // KCHARTPOSITION_H
Defines a position, using compass terminology.
qreal left() const const
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
QPointF bottomLeft() const const
QPointF topLeft() const const
QPointF bottomRight() const const
qreal bottom() const const
Stores the absolute target points of a Position.
Definition of global enums.
qreal top() const const
qreal right() const const
QPointF center() const const
qreal x() const const
qreal y() const const
QRectF normalized() const const
PositionValue
Numerical values of the static KChart::Position instances, for using a Position::value() with a switc...
Definition: KChartEnums.h:180
bool isNull() const const
QPointF topRight() const const
Contains KChart macros.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Sep 29 2023 03:58:52 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.