KChart

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

KDE's Doxygen guidelines are available online.