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 | |
29 | class QBrush; |
30 | class QPainter; |
31 | class QPen; |
32 | class QPointF; |
33 | class KPlotWidget; |
34 | class 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 | */ |
53 | class KDEUI_EXPORT KPlotObject{ |
54 | public: |
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 | |
272 | private: |
273 | class Private; |
274 | Private * const d; |
275 | |
276 | Q_DISABLE_COPY( KPlotObject ) |
277 | }; |
278 | Q_DECLARE_OPERATORS_FOR_FLAGS( KPlotObject::PlotTypes ) |
279 | |
280 | #endif |
281 | |