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