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

source code of kplotting/src/kplotobject.h