1 /* -*- mode: C++ ; c-file-style: "stroustrup" -*- *****************************
2  * Qwt Widget Library
3  * Copyright (C) 1997   Josef Wilgen
4  * Copyright (C) 2002   Uwe Rathmann
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the Qwt License, Version 1.0
8  *****************************************************************************/
9 
10 #ifndef QWT_PLOT_ITEM_H
11 #define QWT_PLOT_ITEM_H
12 
13 #include "qwt_global.h"
14 #include "qwt_text.h"
15 #include "qwt_legend_data.h"
16 #include "qwt_graphic.h"
17 #include <qrect.h>
18 #include <qlist.h>
19 #include <qmetatype.h>
20 
21 class QPainter;
22 class QwtScaleMap;
23 class QwtScaleDiv;
24 class QwtPlot;
25 
26 /*!
27   \brief Base class for items on the plot canvas
28 
29   A plot item is "something", that can be painted on the plot canvas,
30   or only affects the scales of the plot widget. They can be categorized as:
31 
32   - Representator\n
33     A "Representator" is an item that represents some sort of data
34     on the plot canvas. The different representator classes are organized
35     according to the characteristics of the data:
36     - QwtPlotMarker
37       Represents a point or a horizontal/vertical coordinate
38     - QwtPlotCurve
39       Represents a series of points
40     - QwtPlotSpectrogram ( QwtPlotRasterItem )
41       Represents raster data
42     - ...
43 
44   - Decorators\n
45     A "Decorator" is an item, that displays additional information, that
46     is not related to any data:
47     - QwtPlotGrid
48     - QwtPlotScaleItem
49     - QwtPlotSvgItem
50     - ...
51 
52   Depending on the QwtPlotItem::ItemAttribute flags, an item is included
53   into autoscaling or has an entry on the legend.
54 
55   Before misusing the existing item classes it might be better to
56   implement a new type of plot item
57   ( don't implement a watermark as spectrogram ).
58   Deriving a new type of QwtPlotItem primarily means to implement
59   the YourPlotItem::draw() method.
60 
61   \sa The cpuplot example shows the implementation of additional plot items.
62 */
63 
64 class QWT_EXPORT QwtPlotItem
65 {
66 public:
67     /*!
68         \brief Runtime type information
69 
70         RttiValues is used to cast plot items, without
71         having to enable runtime type information of the compiler.
72      */
73     enum RttiValues
74     {
75         //! Unspecific value, that can be used, when it doesn't matter
76         Rtti_PlotItem = 0,
77 
78         //! For QwtPlotGrid
79         Rtti_PlotGrid,
80 
81         //! For QwtPlotScaleItem
82         Rtti_PlotScale,
83 
84         //! For QwtPlotLegendItem
85         Rtti_PlotLegend,
86 
87         //! For QwtPlotMarker
88         Rtti_PlotMarker,
89 
90         //! For QwtPlotCurve
91         Rtti_PlotCurve,
92 
93         //! For QwtPlotSpectroCurve
94         Rtti_PlotSpectroCurve,
95 
96         //! For QwtPlotIntervalCurve
97         Rtti_PlotIntervalCurve,
98 
99         //! For QwtPlotHistogram
100         Rtti_PlotHistogram,
101 
102         //! For QwtPlotSpectrogram
103         Rtti_PlotSpectrogram,
104 
105         //! For QwtPlotSvgItem
106         Rtti_PlotSVG,
107 
108         //! For QwtPlotTradingCurve
109         Rtti_PlotTradingCurve,
110 
111         //! For QwtPlotBarChart
112         Rtti_PlotBarChart,
113 
114         //! For QwtPlotMultiBarChart
115         Rtti_PlotMultiBarChart,
116 
117         //! For QwtPlotShapeItem
118         Rtti_PlotShape,
119 
120         //! For QwtPlotTextLabel
121         Rtti_PlotTextLabel,
122 
123         //! For QwtPlotZoneItem
124         Rtti_PlotZone,
125 
126         /*!
127            Values >= Rtti_PlotUserItem are reserved for plot items
128            not implemented in the Qwt library.
129          */
130         Rtti_PlotUserItem = 1000
131     };
132 
133     /*!
134        \brief Plot Item Attributes
135 
136        Various aspects of a plot widget depend on the attributes of
137        the attached plot items. If and how a single plot item
138        participates in these updates depends on its attributes.
139 
140        \sa setItemAttribute(), testItemAttribute(), ItemInterest
141      */
142     enum ItemAttribute
143     {
144         //! The item is represented on the legend.
145         Legend = 0x01,
146 
147         /*!
148            The boundingRect() of the item is included in the
149            autoscaling calculation as long as its width or height
150            is >= 0.0.
151          */
152         AutoScale = 0x02,
153 
154         /*!
155            The item needs extra space to display something outside
156            its bounding rectangle.
157            \sa getCanvasMarginHint()
158          */
159         Margins = 0x04
160     };
161 
162     //! Plot Item Attributes
163     typedef QFlags<ItemAttribute> ItemAttributes;
164 
165     /*!
166        \brief Plot Item Interests
167 
168        Plot items might depend on the situation of the corresponding
169        plot widget. By enabling an interest the plot item will be
170        notified, when the corresponding attribute of the plot widgets
171        has changed.
172 
173        \sa setItemAttribute(), testItemAttribute(), ItemInterest
174      */
175     enum ItemInterest
176     {
177         /*!
178            The item is interested in updates of the scales
179            \sa updateScaleDiv()
180          */
181         ScaleInterest = 0x01,
182 
183         /*!
184            The item is interested in updates of the legend ( of other items )
185            This flag is intended for items, that want to implement a legend
186            for displaying entries of other plot item.
187 
188            \note If the plot item wants to be represented on a legend
189                  enable QwtPlotItem::Legend instead.
190 
191            \sa updateLegend()
192          */
193         LegendInterest = 0x02
194     };
195 
196     //! Plot Item Interests
197     typedef QFlags<ItemInterest> ItemInterests;
198 
199     //! Render hints
200     enum RenderHint
201     {
202         //! Enable antialiasing
203         RenderAntialiased = 0x1
204     };
205 
206     //! Render hints
207     typedef QFlags<RenderHint> RenderHints;
208 
209     explicit QwtPlotItem( const QwtText &title = QwtText() );
210     virtual ~QwtPlotItem();
211 
212     void attach( QwtPlot *plot );
213     void detach();
214 
215     QwtPlot *plot() const;
216 
217     void setTitle( const QString &title );
218     void setTitle( const QwtText &title );
219     const QwtText &title() const;
220 
221     virtual int rtti() const;
222 
223     void setItemAttribute( ItemAttribute, bool on = true );
224     bool testItemAttribute( ItemAttribute ) const;
225 
226     void setItemInterest( ItemInterest, bool on = true );
227     bool testItemInterest( ItemInterest ) const;
228 
229     void setRenderHint( RenderHint, bool on = true );
230     bool testRenderHint( RenderHint ) const;
231 
232     void setRenderThreadCount( uint numThreads );
233     uint renderThreadCount() const;
234 
235     void setLegendIconSize( const QSize & );
236     QSize legendIconSize() const;
237 
238     double z() const;
239     void setZ( double z );
240 
241     void show();
242     void hide();
243     virtual void setVisible( bool );
244     bool isVisible () const;
245 
246     void setAxes( int xAxis, int yAxis );
247 
248     void setXAxis( int axis );
249     int xAxis() const;
250 
251     void setYAxis( int axis );
252     int yAxis() const;
253 
254     virtual void itemChanged();
255     virtual void legendChanged();
256 
257     /*!
258       \brief Draw the item
259 
260       \param painter Painter
261       \param xMap Maps x-values into pixel coordinates.
262       \param yMap Maps y-values into pixel coordinates.
263       \param canvasRect Contents rect of the canvas in painter coordinates
264     */
265     virtual void draw( QPainter *painter,
266         const QwtScaleMap &xMap, const QwtScaleMap &yMap,
267         const QRectF &canvasRect ) const = 0;
268 
269     virtual QRectF boundingRect() const;
270 
271     virtual void getCanvasMarginHint(
272         const QwtScaleMap &xMap, const QwtScaleMap &yMap,
273         const QRectF &canvasRect,
274         double &left, double &top, double &right, double &bottom) const;
275 
276     virtual void updateScaleDiv(
277         const QwtScaleDiv&, const QwtScaleDiv& );
278 
279     virtual void updateLegend( const QwtPlotItem *,
280         const QList<QwtLegendData> & );
281 
282     QRectF scaleRect( const QwtScaleMap &, const QwtScaleMap & ) const;
283     QRectF paintRect( const QwtScaleMap &, const QwtScaleMap & ) const;
284 
285     virtual QList<QwtLegendData> legendData() const;
286 
287     virtual QwtGraphic legendIcon( int index, const QSizeF  & ) const;
288 
289 protected:
290     QwtGraphic defaultIcon( const QBrush &, const QSizeF & ) const;
291 
292 private:
293     // Disabled copy constructor and operator=
294     QwtPlotItem( const QwtPlotItem & );
295     QwtPlotItem &operator=( const QwtPlotItem & );
296 
297     class PrivateData;
298     PrivateData *d_data;
299 };
300 
301 Q_DECLARE_OPERATORS_FOR_FLAGS( QwtPlotItem::ItemAttributes )
302 Q_DECLARE_OPERATORS_FOR_FLAGS( QwtPlotItem::ItemInterests )
303 Q_DECLARE_OPERATORS_FOR_FLAGS( QwtPlotItem::RenderHints )
304 
305 Q_DECLARE_METATYPE( QwtPlotItem * )
306 
307 #endif
308