KChart

KChartChart.h
1 /*
2  * Copyright (C) 2001-2015 Klaralvdalens Datakonsult AB. All rights reserved.
3  *
4  * This file is part of the KD Chart library.
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License as
8  * published by the Free Software Foundation; either version 2 of
9  * the License, or (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program. If not, see <https://www.gnu.org/licenses/>.
18  */
19 
20 #ifndef KCHARTCHART_H
21 #define KCHARTCHART_H
22 
23 #include <QWidget>
24 
25 #include "kchart_export.h"
26 #include "KChartGlobal.h"
27 
28 /*
29 Simplified(*) overview of object ownership in a chart:
30 
31  Chart is-a QWidget
32  |
33  n CoordinatePlanes is-a AbstractArea is-a AbstractLayoutItem is-a QLayoutItem
34  |
35  n Diagrams is-a QAbstractItemView is-a QWidget
36  / | \
37  AbstractGrid | Axes (can be shared between diagrams) is-a AbstractArea is-a... QLayoutItem
38  (no base class) |
39  Legends is-a AbstractAreaWidget is-a QWidget
40 
41 (*) less important classes, including base classes, removed.
42 
43 
44 Layout rules:
45 
46 In principle, every size or existence change in one of the objects listed above must be propagated
47 to all other objects. This could change their size.
48 There are also settings changes that invalidate the size of other components, where the size changes
49 are detected and propagated.
50 
51 
52 Painting call tree (simplified):
53 
54 Chart::paint() (from users) / paintEvent() (from framework)
55 ChartPrivate::paintAll()-----------------------------------------------\
56 CoordinatePlane::paintAll() (from AbstractArea)--------\ Axis::paintAll()-\
57 CoordinatePlane::paint() (from AbstractLayoutItem) Grid::drawGrid() Axis::paint()
58 Diagram::paint( PaintContext* paintContext )
59 
60 Note that grids are painted from the coordinate plane, not from the diagram as ownership would suggest.
61 
62 */
63 
64 namespace KChart {
65 
66  class BackgroundAttributes;
67  class FrameAttributes;
68  class AbstractDiagram;
69  class AbstractCoordinatePlane;
70  class HeaderFooter;
71  class Legend;
72 
73  typedef QList<AbstractCoordinatePlane*> CoordinatePlaneList;
74  typedef QList<HeaderFooter*> HeaderFooterList;
75  typedef QList<Legend*> LegendList;
76 
77 
78  /**
79  * @class Chart KChartChart.h KChartChart
80  * @brief A chart with one or more diagrams.
81  *
82  * The Chart class represents a drawing consisting of one or more diagrams
83  * and various optional elements such as legends, axes, text boxes, headers
84  * or footers. It takes ownership of all these elements when they are assigned
85  * to it. Each diagram is associated with a coordinate plane, of which the chart
86  * can have more than one. The coordinate planes (and thus the associated diagrams)
87  * can be laid out in various ways.
88  *
89  * The Chart class makes heavy use of the Qt Interview framework for model/view
90  * programming, and thus requires data to be presented to it in a QAbstractItemModel
91  * compatible way. For many simple charts, especially if the visualized data is
92  * static, KChart::Widget provides an abstracted interface, that hides the complexity
93  * of Interview to a large extent.
94  */
95  class KCHART_EXPORT Chart : public QWidget
96  {
97  Q_OBJECT
98  // KD Chart 3.0: leading is inter-line distance of text. this here is MARGIN or SPACING.
99  Q_PROPERTY( int globalLeadingTop READ globalLeadingTop WRITE setGlobalLeadingTop )
100  Q_PROPERTY( int globalLeadingBottom READ globalLeadingBottom WRITE setGlobalLeadingBottom )
101  Q_PROPERTY( int globalLeadingLeft READ globalLeadingLeft WRITE setGlobalLeadingLeft )
102  Q_PROPERTY( int globalLeadingRight READ globalLeadingRight WRITE setGlobalLeadingRight )
103  Q_PROPERTY( bool useNewLayoutSystem READ useNewLayoutSystem WRITE setUseNewLayoutSystem )
104 
105  KCHART_DECLARE_PRIVATE_BASE_POLYMORPHIC_QWIDGET( Chart )
106 
107  public:
108  explicit Chart ( QWidget* parent = nullptr );
109  ~Chart();
110 
111  /**
112  * @brief useNewLayoutSystem
113  * Be very careful activating the new layout system,
114  * its still experimental and works only if the user knows
115  * what he is doing. The reason is that the system does not prevent
116  * the user from creating sharing graphs that are not layoutable in a
117  * plane and still needs assistance from the user.
118  */
119  bool useNewLayoutSystem() const;
120  void setUseNewLayoutSystem( bool value );
121 
122  /**
123  \brief Specify the frame attributes to be used, by default is it a thin black line.
124 
125  To hide the frame line, you could do something like this:
126  \verbatim
127  KChart::FrameAttributes frameAttrs( my_chart->frameAttributes() );
128  frameAttrs.setVisible( false );
129  my_chart->setFrameAttributes( frameAttrs );
130  \endverbatim
131 
132  \sa setBackgroundAttributes
133  */
134  void setFrameAttributes( const FrameAttributes &a );
135  FrameAttributes frameAttributes() const;
136 
137  /**
138  \brief Specify the background attributes to be used, by default there is no background.
139 
140  To set a light blue background, you could do something like this:
141  \verbatim
142  KChart::BackgroundAttributes backgroundAttrs( my_chart->backgroundAttributes() );
143  backgroundAttrs.setVisible( true );
144  backgroundAttrs.setBrush( QColor(0xd0,0xd0,0xff) );
145  my_chart->setBackgroundAttributes( backgroundAttrs );
146  \endverbatim
147 
148  \sa setFrameAttributes
149  */
150  void setBackgroundAttributes( const BackgroundAttributes &a );
151  BackgroundAttributes backgroundAttributes() const;
152 
153  /**
154  * Each chart must have at least one coordinate plane.
155  * Initially a default CartesianCoordinatePlane is created.
156  * Use replaceCoordinatePlane() to replace it with a different
157  * one, such as a PolarCoordinatePlane.
158  * @return The first coordinate plane of the chart.
159  */
160  AbstractCoordinatePlane* coordinatePlane();
161 
162  /**
163  * The list of coordinate planes.
164  * @return The list of coordinate planes.
165  */
166  CoordinatePlaneList coordinatePlanes();
167 
168  /**
169  * Adds a coordinate plane to the chart. The chart takes ownership.
170  * @param plane The coordinate plane to add.
171  *
172  * \sa replaceCoordinatePlane, takeCoordinatePlane
173  */
174  void addCoordinatePlane( AbstractCoordinatePlane* plane );
175 
176  /**
177  * Inserts a coordinate plane to the chart at index @p index.
178  * The chart takes ownership.
179  *
180  * @param index The index where to add the plane
181  * @param plane The coordinate plane to add.
182  *
183  * \sa replaceCoordinatePlane, takeCoordinatePlane
184  */
185  void insertCoordinatePlane( int index, AbstractCoordinatePlane* plane );
186 
187  /**
188  * Replaces the old coordinate plane, or appends the
189  * plane, it there is none yet.
190  *
191  * @param plane The coordinate plane to be used instead of the old plane.
192  * This parameter must not be zero, or the method will do nothing.
193  *
194  * @param oldPlane The coordinate plane to be removed by the new plane. This
195  * plane will be deleted automatically. If the parameter is omitted,
196  * the very first coordinate plane will be replaced. In case, there was no
197  * plane yet, the new plane will just be added.
198  *
199  * \note If you want to re-use the old coordinate plane, call takeCoordinatePlane and
200  * addCoordinatePlane, instead of using replaceCoordinatePlane.
201  *
202  * \sa addCoordinatePlane, takeCoordinatePlane
203  */
204  void replaceCoordinatePlane( AbstractCoordinatePlane* plane,
205  AbstractCoordinatePlane* oldPlane = nullptr );
206 
207  /**
208  * Removes the coordinate plane from the chart, without deleting it.
209  *
210  * The chart no longer owns the plane, so it is
211  * the caller's responsibility to delete the plane.
212  *
213  * \sa addCoordinatePlane, takeCoordinatePlane
214  */
215  void takeCoordinatePlane( AbstractCoordinatePlane* plane );
216 
217  /**
218  * Set the coordinate plane layout that should be used as model for
219  * the internal used layout. The layout needs to be an instance of
220  * QHBoxLayout or QVBoxLayout.
221  */
222  void setCoordinatePlaneLayout( QLayout * layout );
223  QLayout* coordinatePlaneLayout();
224 
225  /**
226  * The first header or footer of the chart. By default there is none.
227  * @return The first header or footer of the chart or 0 if there was none
228  * added to the chart.
229  */
230  HeaderFooter* headerFooter();
231 
232  /**
233  * The list of headers and footers associated with the chart.
234  * @return The list of headers and footers associated with the chart.
235  */
236  HeaderFooterList headerFooters();
237 
238  /**
239  * Adds a header or a footer to the chart. The chart takes ownership.
240  * @param headerFooter The header (or footer, resp.) to add.
241  *
242  * \sa replaceHeaderFooter, takeHeaderFooter
243  */
244  void addHeaderFooter( HeaderFooter* headerFooter );
245 
246  /**
247  * Replaces the old header (or footer, resp.), or appends the
248  * new header or footer, it there is none yet.
249  *
250  * @param headerFooter The header or footer to be used instead of the old one.
251  * This parameter must not be zero, or the method will do nothing.
252  *
253  * @param oldHeaderFooter The header or footer to be removed by the new one. This
254  * header or footer will be deleted automatically. If the parameter is omitted,
255  * the very first header or footer will be replaced. In case, there was no
256  * header and no footer yet, the new header or footer will just be added.
257  *
258  * \note If you want to re-use the old header or footer, call takeHeaderFooter and
259  * addHeaderFooter, instead of using replaceHeaderFooter.
260  *
261  * \sa addHeaderFooter, takeHeaderFooter
262  */
263  void replaceHeaderFooter ( HeaderFooter* headerFooter,
264  HeaderFooter* oldHeaderFooter = nullptr );
265 
266  /**
267  * Removes the header (or footer, resp.) from the chart, without deleting it.
268  *
269  * The chart no longer owns the header or footer, so it is
270  * the caller's responsibility to delete the header or footer.
271  *
272  * \sa addHeaderFooter, replaceHeaderFooter
273  */
274  void takeHeaderFooter( HeaderFooter* headerFooter );
275 
276  /**
277  * The first legend of the chart or 0 if there was none added to the chart.
278  * @return The first legend of the chart or 0 if none exists.
279  */
280  Legend* legend();
281 
282  /**
283  * The list of all legends associated with the chart.
284  * @return The list of all legends associated with the chart.
285  */
286  LegendList legends();
287 
288  /**
289  * Add the given legend to the chart. The chart takes ownership.
290  * @param legend The legend to add.
291  *
292  * \sa replaceLegend, takeLegend
293  */
294  void addLegend( Legend* legend );
295 
296  /**
297  * Replaces the old legend, or appends the
298  * new legend, it there is none yet.
299  *
300  * @param legend The legend to be used instead of the old one.
301  * This parameter must not be zero, or the method will do nothing.
302  *
303  * @param oldLegend The legend to be removed by the new one. This
304  * legend will be deleted automatically. If the parameter is omitted,
305  * the very first legend will be replaced. In case, there was no
306  * legend yet, the new legend will just be added.
307  *
308  * If you want to re-use the old legend, call takeLegend and
309  * addLegend, instead of using replaceLegend.
310  *
311  * \note Whenever addLegend is called the font sizes used by the
312  * Legend are set to relative and they get coupled to the Chart's size,
313  * with their relative values being 20 for the item texts and 24 to the
314  * title text. So if you want to use custom font sizes for the Legend
315  * make sure to set them after calling addLegend.
316  *
317  * \sa addLegend, takeLegend
318  */
319  void replaceLegend ( Legend* legend, Legend* oldLegend = nullptr );
320 
321  /**
322  * Removes the legend from the chart, without deleting it.
323  *
324  * The chart no longer owns the legend, so it is
325  * the caller's responsibility to delete the legend.
326  *
327  * \sa addLegend, takeLegend
328  */
329  void takeLegend( Legend* legend );
330 
331  /**
332  * Set the padding between the margin of the widget and the area that
333  * the contents are drawn into.
334  * @param left The padding on the left side.
335  * @param top The padding at the top.
336  * @param right The padding on the left hand side.
337  * @param bottom The padding on the bottom.
338  *
339  * \note Using previous versions of KD Chart you might have called
340  * setGlobalLeading() to make room for long Abscissa labels (or for an
341  * overlapping top label of an Ordinate axis, resp.) that would not fit
342  * into the normal axis area. This is \em no \em longer \em needed
343  * because KD Chart now is using hidden auto-spacer items reserving
344  * as much free space as is needed for axes with overlaping content
345  * at the respective sides.
346  *
347  * \sa setGlobalLeadingTop, setGlobalLeadingBottom, setGlobalLeadingLeft, setGlobalLeadingRight
348  * \sa globalLeadingTop, globalLeadingBottom, globalLeadingLeft, globalLeadingRight
349  */
350  void setGlobalLeading( int left, int top, int right, int bottom );
351 
352  /**
353  * Set the padding between the start of the widget and the start
354  * of the area that is used for drawing on the left.
355  * @param leading The padding value.
356  *
357  * \sa setGlobalLeading
358  */
359  void setGlobalLeadingLeft( int leading );
360 
361  /**
362  * The padding between the start of the widget and the start
363  * of the area that is used for drawing on the left.
364  * @return The padding between the start of the widget and the start
365  * of the area that is used for drawing on the left.
366  *
367  * \sa setGlobalLeading
368  */
369  int globalLeadingLeft() const;
370 
371  /**
372  * Set the padding between the start of the widget and the start
373  * of the area that is used for drawing at the top.
374  * @param leading The padding value.
375  *
376  * \sa setGlobalLeading
377  */
378  void setGlobalLeadingTop( int leading );
379 
380  /**
381  * The padding between the start of the widget and the start
382  * of the area that is used for drawing at the top.
383  * @return The padding between the start of the widget and the start
384  * of the area that is used for drawing at the top.
385  *
386  * \sa setGlobalLeading
387  */
388  int globalLeadingTop() const;
389 
390  /**
391  * Set the padding between the start of the widget and the start
392  * of the area that is used for drawing on the right.
393  * @param leading The padding value.
394  *
395  * \sa setGlobalLeading
396  */
397  void setGlobalLeadingRight( int leading );
398 
399  /**
400  * The padding between the start of the widget and the start
401  * of the area that is used for drawing on the right.
402  * @return The padding between the start of the widget and the start
403  * of the area that is used for drawing on the right.
404  *
405  * \sa setGlobalLeading
406  */
407  int globalLeadingRight() const;
408 
409  /**
410  * Set the padding between the start of the widget and the start
411  * of the area that is used for drawing on the bottom.
412  * @param leading The padding value.
413  *
414  * \sa setGlobalLeading
415  */
416  void setGlobalLeadingBottom( int leading );
417 
418  /**
419  * The padding between the start of the widget and the start
420  * of the area that is used for drawing at the bottom.
421  * @return The padding between the start of the widget and the start
422  * of the area that is used for drawing at the bottom.
423  *
424  * \sa setGlobalLeading
425  */
426  int globalLeadingBottom() const;
427 
428  /**
429  * Paints all the contents of the chart. Use this method to make KChart
430  * draw into your QPainter.
431  *
432  * \note Any global leading settings will be used by the paint method too,
433  * so make sure to set them to zero, if you want the drawing to have the exact
434  * size of the target rectangle.
435  *
436  * \param painter The painter to be drawn into.
437  * \param rect The rectangle to be filled by the Chart's drawing.
438  *
439  * \sa setGlobalLeading
440  */
441  void paint( QPainter* painter, const QRect& rect );
442 
443  void reLayoutFloatingLegends();
444 
445  Q_SIGNALS:
446  /** Emitted upon change of a property of the Chart or any of its components. */
447  void propertiesChanged();
448  void finishedDrawing();
449 
450  protected:
451  /**
452  * Adjusts the internal layout when the chart is resized.
453  */
454  /* reimp */ void resizeEvent ( QResizeEvent * event ) override;
455 
456  /**
457  * @brief Draws the background and frame, then calls paint().
458  *
459  * In most cases there is no need to override this method in a derived
460  * class, but if you do, do not forget to call paint().
461  * @sa paint
462  */
463  /* reimp */ void paintEvent( QPaintEvent* event ) override;
464 
465  /** reimp */
466  void mousePressEvent( QMouseEvent* event ) override;
467  /** reimp */
468  void mouseDoubleClickEvent( QMouseEvent* event ) override;
469  /** reimp */
470  void mouseMoveEvent( QMouseEvent* event ) override;
471  /** reimp */
472  void mouseReleaseEvent( QMouseEvent* event ) override;
473  /** reimp */
474  bool event( QEvent* event ) override;
475 
476  private:
477  // TODO move this to the private class
478  void addLegendInternal( Legend *legend, bool setMeasures );
479  };
480 
481 // Here we have a few docu block to be included into the API documentation:
482 /**
483  * \dir src
484  * \brief Implementation directory of KChart.
485  *
486  * This directory contains the header files and the source files of both,
487  * the private and the public classes.
488  *
489  * \note Only classes that have an include wrapper in the \c $KCHARTDIR/include
490  * directory are part of the supported API.
491  * All other classes are to be considered as implemntation details, they
492  * could be changed in future versions of KChart without notice.
493  *
494  * In other words: No class that is not mentioned in the \c $KCHARTDIR/include
495  * directory may be directly used by your application.
496  *
497  * The recommended way to include classes of the KChart API is including
498  * them by class name, so instead of including KChartChart.h you would say:
499  *
500  \verbatim
501 #include <KChartChart>
502  \endverbatim
503  *
504  * When following this there is no reason to include the \c $KCHARTDIR/src
505  * directory, it is sufficient to include \c $KCHARTDIR/include
506  */
507 }
508 /**
509  * @class QAbstractItemView "(do not include)"
510  * @brief Class only listed here to document inheritance of some KChart classes.
511  *
512  * Please consult the respective Qt documentation for details:
513  * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A>
514  */
515 /**
516  * @class QAbstractProxyModel "(do not include)"
517  * @brief Class only listed here to document inheritance of some KChart classes.
518  *
519  * Please consult the respective Qt documentation for details:
520  * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A>
521  */
522 /**
523  * @class QFrame "(do not include)"
524  * @brief Class only listed here to document inheritance of some KChart classes.
525  *
526  * Please consult the respective Qt documentation for details:
527  * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A>
528  */
529 /**
530  * @class QObject "(do not include)"
531  * @brief Class only listed here to document inheritance of some KChart classes.
532  *
533  * Please consult the respective Qt documentation for details:
534  * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A>
535  */
536 /**
537  * @class QSortFilterProxyModel "(do not include)"
538  * @brief Class only listed here to document inheritance of some KChart classes.
539  *
540  * Please consult the respective Qt documentation for details:
541  * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A>
542  */
543 /**
544  * @class QWidget "(do not include)"
545  * @brief Class only listed here to document inheritance of some KChart classes.
546  *
547  * Please consult the respective Qt documentation for details:
548  * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A>
549  */
550 /**
551  * @class QTextDocument "(do not include)"
552  * @brief Class only listed here to document inheritance of some KChart classes.
553  *
554  * Please consult the respective Qt documentation for details:
555  * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A>
556  */
557 /**
558  * @class QLayoutItem "(do not include)"
559  * @brief Class only listed here to document inheritance of some KChart classes.
560  *
561  * Please consult the respective Qt documentation for details:
562  * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A>
563  */
564 /**
565  * @class QGraphicsPolygonItem "(do not include)"
566  * @brief Class only listed here to document inheritance of some KChart classes.
567  *
568  * Please consult the respective Qt documentation for details:
569  * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A>
570  */
571 
572 
573 #endif
Class only listed here to document inheritance of some KChart classes.
Legend defines the interface for the legend drawing class.
Definition: KChartLegend.h:52
Contains KChart macros.
Base class common for all coordinate planes, CartesianCoordinatePlane, PolarCoordinatePlane, TernaryCoordinatePlane.
Set of attributes usable for background pixmaps.
A header or footer displaying text above or below charts.
A chart with one or more diagrams.
Definition: KChartChart.h:95
Global namespace.
A set of attributes for frames around items.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu May 13 2021 22:36:32 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.