KChart

KChartRelativePosition.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 KCHARTRELATIVEPOSITION_H
10 #define KCHARTRELATIVEPOSITION_H
11 
12 #include <QDebug>
13 #include <QMetaType>
14 #include <Qt>
15 #include <QPointF>
16 #include <QSizeF>
17 #include "KChartGlobal.h"
18 
19 namespace KChart {
20 
21  class Position;
22  class PositionPoints;
23  class Measure;
24 
25 /**
26  \class RelativePosition KChartRelativePosition.h
27  \brief Defines relative position information: reference area, position
28  in this area (reference position), horizontal / vertical padding, and rotation.
29 
30  See detailed description of \a KChart::Position for an illustration of the
31  different possible reference positions.
32 
33  Using RelativePosition you can specify the relative parts
34  of some position information, and you can specify the absolute parts:
35  the reference area, and the position in this area.
36 
37  \note To get an absolute position, you have three options:
38  \li either you declare both, the relative and the absolute parts,
39  using setReferenceArea for the latter,
40  \li or you specify a set of points, using setReferencePoints,
41  \li or you don't use either, leaving it to KChart to find a suitable reference area.
42  */
43 class KCHART_EXPORT RelativePosition
44 {
45 public:
48 
49  RelativePosition & operator=( const RelativePosition & other );
50 
52 
53  /**
54  * \brief Set the reference area to be used to find the anchor point.
55  *
56  * The reference area's type can be either a QWidget subclass or a KChart::AbstractArea subclass.
57  *
58  * \note Usage of reference area and reference points is mutually exclusive:
59  * Only one can be used, so any previously set reference points are cleared
60  * when you call setReferenceArea.
61  *
62  * Also note: In a few cases KChart will ignore your area (or points, resp.) settings!
63  * Relative positioning of data value texts is an example: For these
64  * the reference area is always taken to be the data area.
65  *
66  * \sa setReferencePosition, setAlignment, setHorizontalPadding, setVerticalPadding
67  */
68  void setReferenceArea( QObject* area );
69  QObject* referenceArea() const;
70 
71  /**
72  * \brief Set a set of points from which the anchor point will be selected.
73  *
74  * \note Usage of reference area and reference points is mutually exclusive:
75  * Only one can be used, so any previously set reference area is cleared
76  * when you call setReferencePoints.
77  *
78  * Also note: In a few cases KChart will ignore your points (or area, resp.) settings!
79  * Relative positioning of data value texts is an example: For these
80  * the reference area is always taken to be the data area.
81  *
82  * \sa setReferenceArea, setReferencePosition, setAlignment, setHorizontalPadding, setVerticalPadding
83  */
84  void setReferencePoints( const PositionPoints& points );
85  const PositionPoints referencePoints() const;
86 
87  /**
88  * \brief Set the position of the anchor point.
89  *
90  * The anchor point of a RelativePosition may be one of the pre-defined
91  * points of it's reference area - for details see KChart::Position.
92  *
93  * See detailed description of \a KChart::Position for an illustration of the
94  * different possible reference positions.
95  *
96  * \sa resetReferencePosition, setReferenceArea, setAlignment, setHorizontalPadding, setVerticalPadding, KChart::Position
97  */
98  void setReferencePosition( Position position );
99 
100  /**
101  * \brief Resets the position of the anchor point to the built-in default.
102  *
103  * If the anchor point of a RelativePosition is reset (or never changed from the
104  * default setting) KChart will choose an appropriate Position at run-time.
105  *
106  * e.g. BarDiagrams will use Position::North / Position::South for positive / negative values.
107  *
108  * \sa setReferencePosition, setReferenceArea, setAlignment, setHorizontalPadding, setVerticalPadding, KChart::Position
109  */
110  void resetReferencePosition();
111  Position referencePosition() const;
112 
113  /**
114  * Set the alignment of the content placed by this RelativePosition.
115  *
116  * Padding is applied first to obtain the final reference point
117  * for the content's alignment
118  *
119  * \note To print centered content, besides calling setAlignment( Qt::AlignCenter )
120  * you might also want to set zero padding to have your text centered more precisely.
121  *
122  * \sa setReferencePosition, setReferenceArea, setHorizontalPadding, setVerticalPadding
123  */
124  void setAlignment( Qt::Alignment flags );
125  Qt::Alignment alignment() const;
126 
127  /**
128  * Set the width of the horizontal padding between the anchor point and the content
129  * placed by this RelativePosition.
130  *
131  * \note When printing data value texts this Measure is used to find the alignment
132  * point for this text, then alignment() is use to determine how to align the text
133  * relative to that point.
134  * The font height is used as reference size for both horizontal and vertical padding
135  * if the respective padding's Measure is using automatic reference area detection.
136  *
137  * \sa setVerticalPadding, setReferencePosition, setReferenceArea
138  */
139  void setHorizontalPadding( const Measure& padding );
140  Measure horizontalPadding() const;
141 
142  /**
143  * Set the height of the vertical padding between the anchor point and the content
144  * placed by this RelativePosition.
145  *
146  * \note When printing data value texts this Measure is used to find the alignment
147  * point for this text, then alignment() is use to determine how to align the text
148  * relative to that point.
149  * The font height is used as reference size for both horizontal and vertical padding
150  * if the respective padding's Measure is using automatic reference area detection.
151  *
152  * \sa setHorizontalPadding, setReferencePosition, setReferenceArea
153  */
154  void setVerticalPadding( const Measure& padding );
155  Measure verticalPadding() const;
156 
157  void setRotation( qreal rot );
158  qreal rotation() const;
159 
160  /**
161  * \brief Return the reference point, according to the reference area/position, and ignoring padding.
162  *
163  * This method is called at drawing time.
164  * The returned point is used to test if the label of a data value is to be printed: a label
165  * is printed only if its reference point is inside or touching the coordinate plane.
166  *
167  * If polarDegrees is set, the degree information will be returned that was stored for the
168  * respective point. This is used by the PieDiagram class to determine how vertical/horizontal
169  * padding settings should affect the position of the data value texts' reference points.
170  * \sa calculatedPoint, setReferenceArea, setReferencePosition, setHorizontalPadding, setVerticalPadding
171  */
172  const QPointF referencePoint(qreal* polarDegrees = nullptr) const;
173 
174  /**
175  * \brief Calculate a point, accordin to the reference area/position and the padding.
176  *
177  * This method is called at drawing time: The returned point is used as anchor point.
178  * Note that it is the task of the calling code to place the content, taking the alignment
179  * property into account. This class does not know the size of the content so it
180  * cannot place it.
181  *
182  * \sa referencePoint, setReferenceArea, setReferencePosition, setHorizontalPadding, setVerticalPadding
183  */
184  const QPointF calculatedPoint( const QSizeF& autoSize ) const;
185 
186  bool operator==( const RelativePosition& ) const;
187  bool operator!=( const RelativePosition & other ) const;
188 
189 private:
190  KCHART_DECLARE_PRIVATE_BASE_VALUE( RelativePosition )
191 };
192 
193 inline bool RelativePosition::operator!=( const RelativePosition & other ) const { return !operator==( other ); }
194 }
195 
196 #if !defined(QT_NO_DEBUG_STREAM)
197 KCHART_EXPORT QDebug operator<<(QDebug, const KChart::RelativePosition& );
198 #endif /* QT_NO_DEBUG_STREAM */
199 
200 KCHART_DECLARE_SWAP_SPECIALISATION( KChart::RelativePosition )
201 
202 QT_BEGIN_NAMESPACE
203 Q_DECLARE_TYPEINFO( KChart::RelativePosition, Q_MOVABLE_TYPE );
204 QT_END_NAMESPACE
205 
206 Q_DECLARE_METATYPE( KChart::RelativePosition )
207 
208 #endif // KCHARTRELATIVEPOSITION_H
Defines a position, using compass terminology.
typedef Alignment
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
Stores the absolute target points of a Position.
Measure is used to specify relative and absolute sizes in KChart, e.g. font sizes.
Definition: KChartMeasure.h:37
Defines relative position information: reference area, position in this area (reference position),...
Contains KChart macros.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Feb 6 2023 04:05:18 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.