1/* -*- C++ -*-
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2003 Jason Harris <kstars@30doradus.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KPLOTOBJECT_H
9#define KPLOTOBJECT_H
10
11#include <kplotting_export.h>
12
13#include <QColor>
14#include <QString>
15
16#include <memory>
17
18class QBrush;
19class QPainter;
20class QPen;
21class QPointF;
22class KPlotWidget;
23class KPlotPoint;
24
25/*!
26 * \class KPlotObject
27 * \inmodule KPlotting
28 *
29 * \brief Encapsulates a data set to be plotted in a KPlotWidget.
30 *
31 * Think of a KPlotObject as a set of data displayed as a group in the plot.
32 * Each KPlotObject consists of a list of KPlotPoints, a "type" controlling
33 * how the data points are displayed (some combination of Points, Lines, or
34 * Bars), a color, and a size. There is also a parameter which controls the
35 * shape of the points used to display the KPlotObject.
36 *
37 * \note KPlotObject will take care of the points added to it, so when clearing
38 * the points list (eg with clearPoints()) any previous reference to a KPlotPoint
39 * already added to a KPlotObject will be invalid.
40 */
41class KPLOTTING_EXPORT KPlotObject
42{
43public:
44 /*!
45 * The type classification of the KPlotObject.
46 *
47 * These are bitmask values that can be OR'd together, so that a set
48 * of points can be represented in the plot in multiple ways.
49 *
50 * \note points should be added in order of increasing x-coordinate
51 * when using Bars.
52 *
53 * \value UnknownType
54 * \value Points Each KPlotPoint is represented with a drawn point
55 * \value Lines Each KPlotPoint is connected with a line
56 * \value Bars Each KPlotPoint is shown as a vertical bar
57 */
58 enum PlotType {
59 UnknownType = 0,
60 Points = 1,
61 Lines = 2,
62 Bars = 4,
63 };
64 Q_DECLARE_FLAGS(PlotTypes, PlotType)
65
66 /*!
67 * The available shape styles for plotted points.
68 *
69 * \value NoPoints
70 * \value Circle
71 * \value Letter
72 * \value Triangle
73 * \value Square
74 * \value Pentagon
75 * \value Hexagon
76 * \value Asterisk
77 * \value Star
78 * \value UnknownPoint
79 */
80 enum PointStyle {
81 NoPoints = 0,
82 Circle = 1,
83 Letter = 2,
84 Triangle = 3,
85 Square = 4,
86 Pentagon = 5,
87 Hexagon = 6,
88 Asterisk = 7,
89 Star = 8,
90 UnknownPoint,
91 };
92
93 /*!
94 * Constructor.
95 *
96 * \a color The color for plotting this object. By default this sets
97 * the color for Points, Lines and Bars, but there are functions to
98 * override any of these.
99 *
100 * \a otype the PlotType for this object (Points, Lines or Bars)
101 *
102 * \a size the size to use for plotted points, in pixels
103 *
104 * \a ps The PointStyle describing the shape for plotted points
105 */
106 explicit KPlotObject(const QColor &color = Qt::white, PlotType otype = Points, double size = 2.0, PointStyle ps = Circle);
107
108 ~KPlotObject();
109
110 /*!
111 * Returns the plot flags of the object
112 */
113 PlotTypes plotTypes() const;
114
115 /*!
116 * Set whether points will be drawn for this object
117 *
118 * \a b if true, points will be drawn
119 */
120 void setShowPoints(bool b);
121
122 /*!
123 * Set whether lines will be drawn for this object
124 *
125 * \a b if true, lines will be drawn
126 */
127 void setShowLines(bool b);
128
129 /*!
130 * Set whether bars will be drawn for this object
131 *
132 * \a b if true, bars will be drawn
133 */
134 void setShowBars(bool b);
135
136 /*!
137 * Returns the size of the plotted points in this object, in pixels
138 */
139 double size() const;
140
141 /*!
142 * Set the size for plotted points in this object, in pixels
143 *
144 * \a s the new size
145 */
146 void setSize(double s);
147
148 /*!
149 * Returns the style used for drawing the points in this object
150 */
151 PointStyle pointStyle() const;
152
153 /*!
154 * Set a new style for drawing the points in this object
155 *
156 * \a p the new style
157 */
158 void setPointStyle(PointStyle p);
159
160 /*!
161 * Returns the default pen for this Object.
162 *
163 * If no other pens are set, this pen will be used for
164 * points, lines, bars and labels (this pen is always used for points).
165 */
166 const QPen &pen() const;
167
168 /*!
169 * Set the default pen for this object
170 *
171 * \a p the pen to use
172 */
173 void setPen(const QPen &p);
174
175 /*!
176 * Returns the pen to use for drawing lines for this Object.
177 */
178 const QPen &linePen() const;
179
180 /*!
181 * Set the pen to use for drawing lines for this object
182 *
183 * \a p the pen to use
184 */
185 void setLinePen(const QPen &p);
186
187 /*!
188 * Returns the pen to use for drawing bars for this Object.
189 */
190 const QPen &barPen() const;
191
192 /*!
193 * Set the pen to use for drawing bars for this object
194 *
195 * \a p the pen to use
196 */
197 void setBarPen(const QPen &p);
198
199 /*!
200 * Returns the pen to use for drawing labels for this Object.
201 */
202 const QPen &labelPen() const;
203
204 /*!
205 * Set the pen to use for labels for this object
206 *
207 * \a p the pen to use
208 */
209 void setLabelPen(const QPen &p);
210
211 /*!
212 * Returns the default Brush to use for this Object.
213 */
214 const QBrush brush() const;
215
216 /*!
217 * Set the default brush to use for this object
218 *
219 * \a b the brush to use
220 */
221 void setBrush(const QBrush &b);
222
223 /*!
224 * Returns the brush to use for filling bars for this Object.
225 */
226 const QBrush barBrush() const;
227
228 /*!
229 * Set the brush to use for drawing bars for this object
230 *
231 * \a b the brush to use
232 */
233 void setBarBrush(const QBrush &b);
234
235 /*!
236 * Returns the list of KPlotPoints that make up this object
237 */
238 QList<KPlotPoint *> points() const;
239
240 /*!
241 * Add a point to the object's list of points, using input data to construct a KPlotPoint.
242 *
243 * \a p the QPointF to add.
244 *
245 * \a label the optional text label for this point
246 *
247 * \a barWidth the width of the bar, if this object is to be drawn with bars
248 *
249 * \note if \a barWidth is left at its default value of 0.0, then the width will be
250 * automatically set to the distance between this point and the one to its right.
251 */
252 void addPoint(const QPointF &p, const QString &label = QString(), double barWidth = 0.0);
253
254 /*!
255 * Add a given KPlotPoint to the object's list of points.
256 *
257 * \overload
258 *
259 * \a p pointer to the KPlotPoint to add.
260 */
261 void addPoint(KPlotPoint *p);
262
263 /*!
264 * Add a point to the object's list of points, using input data to construct a KPlotPoint.
265 *
266 * \overload
267 *
268 * \a x the X-coordinate of the point to add.
269 *
270 * \a y the Y-coordinate of the point to add.
271 *
272 * \a label the optional text label
273 *
274 * \a barWidth the width of the bar, if this object is to be drawn with bars
275 *
276 * \note if \a barWidth is left at its default value of 0.0, then the width will be
277 * automatically set to the distance between this point and the one to its right.
278 */
279 void addPoint(double x, double y, const QString &label = QString(), double barWidth = 0.0);
280
281 /*!
282 * Remove the QPointF at position index from the list of points
283 *
284 * \a index the index of the point to be removed.
285 */
286 void removePoint(int index);
287
288 /*!
289 * Remove and destroy the points of this object
290 */
291 void clearPoints();
292
293 /*!
294 * Draw this KPlotObject on the given QPainter
295 *
296 * \a p The QPainter to draw on
297 *
298 * \a pw the KPlotWidget to draw on (this is needed
299 * for the KPlotWidget::mapToWidget() function)
300 */
301 void draw(QPainter *p, KPlotWidget *pw);
302
303private:
304 class Private;
305 std::unique_ptr<Private> const d;
306
307 Q_DISABLE_COPY(KPlotObject)
308};
309Q_DECLARE_OPERATORS_FOR_FLAGS(KPlotObject::PlotTypes)
310
311#endif
312

source code of kplotting/src/kplotobject.h