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
19namespace 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 */
43class KCHART_EXPORT RelativePosition
44{
45public:
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
189private:
190 KCHART_DECLARE_PRIVATE_BASE_VALUE( RelativePosition )
191};
192
193inline bool RelativePosition::operator!=( const RelativePosition & other ) const { return !operator==( other ); }
194}
195
196#if !defined(QT_NO_DEBUG_STREAM)
197KCHART_EXPORT QDebug operator<<(QDebug, const KChart::RelativePosition& );
198#endif /* QT_NO_DEBUG_STREAM */
199
200KCHART_DECLARE_SWAP_SPECIALISATION( KChart::RelativePosition )
201
202QT_BEGIN_NAMESPACE
203Q_DECLARE_TYPEINFO( KChart::RelativePosition, Q_MOVABLE_TYPE );
204QT_END_NAMESPACE
205
206Q_DECLARE_METATYPE( KChart::RelativePosition )
207
208#endif // KCHARTRELATIVEPOSITION_H
Contains KChart macros.
Measure is used to specify relative and absolute sizes in KChart, e.g.
Stores the absolute target points of a Position.
Defines a position, using compass terminology.
Defines relative position information: reference area, position in this area (reference position),...
QDebug operator<<(QDebug dbg, const PerceptualColor::LchaDouble &value)
typedef Alignment
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:14:24 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.