File indexing completed on 2024-05-19 15:27:23
0001 /* 0002 * Copyright (C) 2001-2015 Klaralvdalens Datakonsult AB. All rights reserved. 0003 * 0004 * This file is part of the KD Chart library. 0005 * 0006 * This program is free software; you can redistribute it and/or 0007 * modify it under the terms of the GNU General Public License as 0008 * published by the Free Software Foundation; either version 2 of 0009 * the License, or (at your option) any later version. 0010 * 0011 * This program is distributed in the hope that it will be useful, 0012 * but WITHOUT ANY WARRANTY; without even the implied warranty of 0013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 0014 * GNU General Public License for more details. 0015 * 0016 * You should have received a copy of the GNU General Public License 0017 * along with this program. If not, see <https://www.gnu.org/licenses/>. 0018 */ 0019 0020 #ifndef KCHARTCHART_H 0021 #define KCHARTCHART_H 0022 0023 #include <QWidget> 0024 0025 #include "kchart_export.h" 0026 #include "KChartGlobal.h" 0027 0028 /* 0029 Simplified(*) overview of object ownership in a chart: 0030 0031 Chart is-a QWidget 0032 | 0033 n CoordinatePlanes is-a AbstractArea is-a AbstractLayoutItem is-a QLayoutItem 0034 | 0035 n Diagrams is-a QAbstractItemView is-a QWidget 0036 / | \ 0037 AbstractGrid | Axes (can be shared between diagrams) is-a AbstractArea is-a... QLayoutItem 0038 (no base class) | 0039 Legends is-a AbstractAreaWidget is-a QWidget 0040 0041 (*) less important classes, including base classes, removed. 0042 0043 0044 Layout rules: 0045 0046 In principle, every size or existence change in one of the objects listed above must be propagated 0047 to all other objects. This could change their size. 0048 There are also settings changes that invalidate the size of other components, where the size changes 0049 are detected and propagated. 0050 0051 0052 Painting call tree (simplified): 0053 0054 Chart::paint() (from users) / paintEvent() (from framework) 0055 ChartPrivate::paintAll()-----------------------------------------------\ 0056 CoordinatePlane::paintAll() (from AbstractArea)--------\ Axis::paintAll()-\ 0057 CoordinatePlane::paint() (from AbstractLayoutItem) Grid::drawGrid() Axis::paint() 0058 Diagram::paint( PaintContext* paintContext ) 0059 0060 Note that grids are painted from the coordinate plane, not from the diagram as ownership would suggest. 0061 0062 */ 0063 0064 namespace KChart { 0065 0066 class BackgroundAttributes; 0067 class FrameAttributes; 0068 class AbstractDiagram; 0069 class AbstractCoordinatePlane; 0070 class HeaderFooter; 0071 class Legend; 0072 0073 typedef QList<AbstractCoordinatePlane*> CoordinatePlaneList; 0074 typedef QList<HeaderFooter*> HeaderFooterList; 0075 typedef QList<Legend*> LegendList; 0076 0077 0078 /** 0079 * @class Chart KChartChart.h KChartChart 0080 * @brief A chart with one or more diagrams. 0081 * 0082 * The Chart class represents a drawing consisting of one or more diagrams 0083 * and various optional elements such as legends, axes, text boxes, headers 0084 * or footers. It takes ownership of all these elements when they are assigned 0085 * to it. Each diagram is associated with a coordinate plane, of which the chart 0086 * can have more than one. The coordinate planes (and thus the associated diagrams) 0087 * can be laid out in various ways. 0088 * 0089 * The Chart class makes heavy use of the Qt Interview framework for model/view 0090 * programming, and thus requires data to be presented to it in a QAbstractItemModel 0091 * compatible way. For many simple charts, especially if the visualized data is 0092 * static, KChart::Widget provides an abstracted interface, that hides the complexity 0093 * of Interview to a large extent. 0094 */ 0095 class KCHART_EXPORT Chart : public QWidget 0096 { 0097 Q_OBJECT 0098 // KD Chart 3.0: leading is inter-line distance of text. this here is MARGIN or SPACING. 0099 Q_PROPERTY( int globalLeadingTop READ globalLeadingTop WRITE setGlobalLeadingTop ) 0100 Q_PROPERTY( int globalLeadingBottom READ globalLeadingBottom WRITE setGlobalLeadingBottom ) 0101 Q_PROPERTY( int globalLeadingLeft READ globalLeadingLeft WRITE setGlobalLeadingLeft ) 0102 Q_PROPERTY( int globalLeadingRight READ globalLeadingRight WRITE setGlobalLeadingRight ) 0103 Q_PROPERTY( bool useNewLayoutSystem READ useNewLayoutSystem WRITE setUseNewLayoutSystem ) 0104 0105 KCHART_DECLARE_PRIVATE_BASE_POLYMORPHIC_QWIDGET( Chart ) 0106 0107 public: 0108 explicit Chart ( QWidget* parent = nullptr ); 0109 ~Chart(); 0110 0111 /** 0112 * @brief useNewLayoutSystem 0113 * Be very careful activating the new layout system, 0114 * its still experimental and works only if the user knows 0115 * what he is doing. The reason is that the system does not prevent 0116 * the user from creating sharing graphs that are not layoutable in a 0117 * plane and still needs assistance from the user. 0118 */ 0119 bool useNewLayoutSystem() const; 0120 void setUseNewLayoutSystem( bool value ); 0121 0122 /** 0123 \brief Specify the frame attributes to be used, by default is it a thin black line. 0124 0125 To hide the frame line, you could do something like this: 0126 \verbatim 0127 KChart::FrameAttributes frameAttrs( my_chart->frameAttributes() ); 0128 frameAttrs.setVisible( false ); 0129 my_chart->setFrameAttributes( frameAttrs ); 0130 \endverbatim 0131 0132 \sa setBackgroundAttributes 0133 */ 0134 void setFrameAttributes( const FrameAttributes &a ); 0135 FrameAttributes frameAttributes() const; 0136 0137 /** 0138 \brief Specify the background attributes to be used, by default there is no background. 0139 0140 To set a light blue background, you could do something like this: 0141 \verbatim 0142 KChart::BackgroundAttributes backgroundAttrs( my_chart->backgroundAttributes() ); 0143 backgroundAttrs.setVisible( true ); 0144 backgroundAttrs.setBrush( QColor(0xd0,0xd0,0xff) ); 0145 my_chart->setBackgroundAttributes( backgroundAttrs ); 0146 \endverbatim 0147 0148 \sa setFrameAttributes 0149 */ 0150 void setBackgroundAttributes( const BackgroundAttributes &a ); 0151 BackgroundAttributes backgroundAttributes() const; 0152 0153 /** 0154 * Each chart must have at least one coordinate plane. 0155 * Initially a default CartesianCoordinatePlane is created. 0156 * Use replaceCoordinatePlane() to replace it with a different 0157 * one, such as a PolarCoordinatePlane. 0158 * @return The first coordinate plane of the chart. 0159 */ 0160 AbstractCoordinatePlane* coordinatePlane(); 0161 0162 /** 0163 * The list of coordinate planes. 0164 * @return The list of coordinate planes. 0165 */ 0166 CoordinatePlaneList coordinatePlanes(); 0167 0168 /** 0169 * Adds a coordinate plane to the chart. The chart takes ownership. 0170 * @param plane The coordinate plane to add. 0171 * 0172 * \sa replaceCoordinatePlane, takeCoordinatePlane 0173 */ 0174 void addCoordinatePlane( AbstractCoordinatePlane* plane ); 0175 0176 /** 0177 * Inserts a coordinate plane to the chart at index @p index. 0178 * The chart takes ownership. 0179 * 0180 * @param index The index where to add the plane 0181 * @param plane The coordinate plane to add. 0182 * 0183 * \sa replaceCoordinatePlane, takeCoordinatePlane 0184 */ 0185 void insertCoordinatePlane( int index, AbstractCoordinatePlane* plane ); 0186 0187 /** 0188 * Replaces the old coordinate plane, or appends the 0189 * plane, it there is none yet. 0190 * 0191 * @param plane The coordinate plane to be used instead of the old plane. 0192 * This parameter must not be zero, or the method will do nothing. 0193 * 0194 * @param oldPlane The coordinate plane to be removed by the new plane. This 0195 * plane will be deleted automatically. If the parameter is omitted, 0196 * the very first coordinate plane will be replaced. In case, there was no 0197 * plane yet, the new plane will just be added. 0198 * 0199 * \note If you want to re-use the old coordinate plane, call takeCoordinatePlane and 0200 * addCoordinatePlane, instead of using replaceCoordinatePlane. 0201 * 0202 * \sa addCoordinatePlane, takeCoordinatePlane 0203 */ 0204 void replaceCoordinatePlane( AbstractCoordinatePlane* plane, 0205 AbstractCoordinatePlane* oldPlane = nullptr ); 0206 0207 /** 0208 * Removes the coordinate plane from the chart, without deleting it. 0209 * 0210 * The chart no longer owns the plane, so it is 0211 * the caller's responsibility to delete the plane. 0212 * 0213 * \sa addCoordinatePlane, takeCoordinatePlane 0214 */ 0215 void takeCoordinatePlane( AbstractCoordinatePlane* plane ); 0216 0217 /** 0218 * Set the coordinate plane layout that should be used as model for 0219 * the internal used layout. The layout needs to be an instance of 0220 * QHBoxLayout or QVBoxLayout. 0221 */ 0222 void setCoordinatePlaneLayout( QLayout * layout ); 0223 QLayout* coordinatePlaneLayout(); 0224 0225 /** 0226 * The first header or footer of the chart. By default there is none. 0227 * @return The first header or footer of the chart or 0 if there was none 0228 * added to the chart. 0229 */ 0230 HeaderFooter* headerFooter(); 0231 0232 /** 0233 * The list of headers and footers associated with the chart. 0234 * @return The list of headers and footers associated with the chart. 0235 */ 0236 HeaderFooterList headerFooters(); 0237 0238 /** 0239 * Adds a header or a footer to the chart. The chart takes ownership. 0240 * @param headerFooter The header (or footer, resp.) to add. 0241 * 0242 * \sa replaceHeaderFooter, takeHeaderFooter 0243 */ 0244 void addHeaderFooter( HeaderFooter* headerFooter ); 0245 0246 /** 0247 * Replaces the old header (or footer, resp.), or appends the 0248 * new header or footer, it there is none yet. 0249 * 0250 * @param headerFooter The header or footer to be used instead of the old one. 0251 * This parameter must not be zero, or the method will do nothing. 0252 * 0253 * @param oldHeaderFooter The header or footer to be removed by the new one. This 0254 * header or footer will be deleted automatically. If the parameter is omitted, 0255 * the very first header or footer will be replaced. In case, there was no 0256 * header and no footer yet, the new header or footer will just be added. 0257 * 0258 * \note If you want to re-use the old header or footer, call takeHeaderFooter and 0259 * addHeaderFooter, instead of using replaceHeaderFooter. 0260 * 0261 * \sa addHeaderFooter, takeHeaderFooter 0262 */ 0263 void replaceHeaderFooter ( HeaderFooter* headerFooter, 0264 HeaderFooter* oldHeaderFooter = nullptr ); 0265 0266 /** 0267 * Removes the header (or footer, resp.) from the chart, without deleting it. 0268 * 0269 * The chart no longer owns the header or footer, so it is 0270 * the caller's responsibility to delete the header or footer. 0271 * 0272 * \sa addHeaderFooter, replaceHeaderFooter 0273 */ 0274 void takeHeaderFooter( HeaderFooter* headerFooter ); 0275 0276 /** 0277 * The first legend of the chart or 0 if there was none added to the chart. 0278 * @return The first legend of the chart or 0 if none exists. 0279 */ 0280 Legend* legend(); 0281 0282 /** 0283 * The list of all legends associated with the chart. 0284 * @return The list of all legends associated with the chart. 0285 */ 0286 LegendList legends(); 0287 0288 /** 0289 * Add the given legend to the chart. The chart takes ownership. 0290 * @param legend The legend to add. 0291 * 0292 * \sa replaceLegend, takeLegend 0293 */ 0294 void addLegend( Legend* legend ); 0295 0296 /** 0297 * Replaces the old legend, or appends the 0298 * new legend, it there is none yet. 0299 * 0300 * @param legend The legend to be used instead of the old one. 0301 * This parameter must not be zero, or the method will do nothing. 0302 * 0303 * @param oldLegend The legend to be removed by the new one. This 0304 * legend will be deleted automatically. If the parameter is omitted, 0305 * the very first legend will be replaced. In case, there was no 0306 * legend yet, the new legend will just be added. 0307 * 0308 * If you want to re-use the old legend, call takeLegend and 0309 * addLegend, instead of using replaceLegend. 0310 * 0311 * \note Whenever addLegend is called the font sizes used by the 0312 * Legend are set to relative and they get coupled to the Chart's size, 0313 * with their relative values being 20 for the item texts and 24 to the 0314 * title text. So if you want to use custom font sizes for the Legend 0315 * make sure to set them after calling addLegend. 0316 * 0317 * \sa addLegend, takeLegend 0318 */ 0319 void replaceLegend ( Legend* legend, Legend* oldLegend = nullptr ); 0320 0321 /** 0322 * Removes the legend from the chart, without deleting it. 0323 * 0324 * The chart no longer owns the legend, so it is 0325 * the caller's responsibility to delete the legend. 0326 * 0327 * \sa addLegend, takeLegend 0328 */ 0329 void takeLegend( Legend* legend ); 0330 0331 /** 0332 * Set the padding between the margin of the widget and the area that 0333 * the contents are drawn into. 0334 * @param left The padding on the left side. 0335 * @param top The padding at the top. 0336 * @param right The padding on the left hand side. 0337 * @param bottom The padding on the bottom. 0338 * 0339 * \note Using previous versions of KD Chart you might have called 0340 * setGlobalLeading() to make room for long Abscissa labels (or for an 0341 * overlapping top label of an Ordinate axis, resp.) that would not fit 0342 * into the normal axis area. This is \em no \em longer \em needed 0343 * because KD Chart now is using hidden auto-spacer items reserving 0344 * as much free space as is needed for axes with overlaping content 0345 * at the respective sides. 0346 * 0347 * \sa setGlobalLeadingTop, setGlobalLeadingBottom, setGlobalLeadingLeft, setGlobalLeadingRight 0348 * \sa globalLeadingTop, globalLeadingBottom, globalLeadingLeft, globalLeadingRight 0349 */ 0350 void setGlobalLeading( int left, int top, int right, int bottom ); 0351 0352 /** 0353 * Set the padding between the start of the widget and the start 0354 * of the area that is used for drawing on the left. 0355 * @param leading The padding value. 0356 * 0357 * \sa setGlobalLeading 0358 */ 0359 void setGlobalLeadingLeft( int leading ); 0360 0361 /** 0362 * The padding between the start of the widget and the start 0363 * of the area that is used for drawing on the left. 0364 * @return The padding between the start of the widget and the start 0365 * of the area that is used for drawing on the left. 0366 * 0367 * \sa setGlobalLeading 0368 */ 0369 int globalLeadingLeft() const; 0370 0371 /** 0372 * Set the padding between the start of the widget and the start 0373 * of the area that is used for drawing at the top. 0374 * @param leading The padding value. 0375 * 0376 * \sa setGlobalLeading 0377 */ 0378 void setGlobalLeadingTop( int leading ); 0379 0380 /** 0381 * The padding between the start of the widget and the start 0382 * of the area that is used for drawing at the top. 0383 * @return The padding between the start of the widget and the start 0384 * of the area that is used for drawing at the top. 0385 * 0386 * \sa setGlobalLeading 0387 */ 0388 int globalLeadingTop() const; 0389 0390 /** 0391 * Set the padding between the start of the widget and the start 0392 * of the area that is used for drawing on the right. 0393 * @param leading The padding value. 0394 * 0395 * \sa setGlobalLeading 0396 */ 0397 void setGlobalLeadingRight( int leading ); 0398 0399 /** 0400 * The padding between the start of the widget and the start 0401 * of the area that is used for drawing on the right. 0402 * @return The padding between the start of the widget and the start 0403 * of the area that is used for drawing on the right. 0404 * 0405 * \sa setGlobalLeading 0406 */ 0407 int globalLeadingRight() const; 0408 0409 /** 0410 * Set the padding between the start of the widget and the start 0411 * of the area that is used for drawing on the bottom. 0412 * @param leading The padding value. 0413 * 0414 * \sa setGlobalLeading 0415 */ 0416 void setGlobalLeadingBottom( int leading ); 0417 0418 /** 0419 * The padding between the start of the widget and the start 0420 * of the area that is used for drawing at the bottom. 0421 * @return The padding between the start of the widget and the start 0422 * of the area that is used for drawing at the bottom. 0423 * 0424 * \sa setGlobalLeading 0425 */ 0426 int globalLeadingBottom() const; 0427 0428 /** 0429 * Paints all the contents of the chart. Use this method to make KChart 0430 * draw into your QPainter. 0431 * 0432 * \note Any global leading settings will be used by the paint method too, 0433 * so make sure to set them to zero, if you want the drawing to have the exact 0434 * size of the target rectangle. 0435 * 0436 * \param painter The painter to be drawn into. 0437 * \param rect The rectangle to be filled by the Chart's drawing. 0438 * 0439 * \sa setGlobalLeading 0440 */ 0441 void paint( QPainter* painter, const QRect& rect ); 0442 0443 void reLayoutFloatingLegends(); 0444 0445 Q_SIGNALS: 0446 /** Emitted upon change of a property of the Chart or any of its components. */ 0447 void propertiesChanged(); 0448 void finishedDrawing(); 0449 0450 protected: 0451 /** 0452 * Adjusts the internal layout when the chart is resized. 0453 */ 0454 /* reimp */ void resizeEvent ( QResizeEvent * event ) override; 0455 0456 /** 0457 * @brief Draws the background and frame, then calls paint(). 0458 * 0459 * In most cases there is no need to override this method in a derived 0460 * class, but if you do, do not forget to call paint(). 0461 * @sa paint 0462 */ 0463 /* reimp */ void paintEvent( QPaintEvent* event ) override; 0464 0465 /** reimp */ 0466 void mousePressEvent( QMouseEvent* event ) override; 0467 /** reimp */ 0468 void mouseDoubleClickEvent( QMouseEvent* event ) override; 0469 /** reimp */ 0470 void mouseMoveEvent( QMouseEvent* event ) override; 0471 /** reimp */ 0472 void mouseReleaseEvent( QMouseEvent* event ) override; 0473 /** reimp */ 0474 bool event( QEvent* event ) override; 0475 0476 private: 0477 // TODO move this to the private class 0478 void addLegendInternal( Legend *legend, bool setMeasures ); 0479 }; 0480 0481 // Here we have a few docu block to be included into the API documentation: 0482 /** 0483 * \dir src 0484 * \brief Implementation directory of KChart. 0485 * 0486 * This directory contains the header files and the source files of both, 0487 * the private and the public classes. 0488 * 0489 * \note Only classes that have an include wrapper in the \c $KCHARTDIR/include 0490 * directory are part of the supported API. 0491 * All other classes are to be considered as implemntation details, they 0492 * could be changed in future versions of KChart without notice. 0493 * 0494 * In other words: No class that is not mentioned in the \c $KCHARTDIR/include 0495 * directory may be directly used by your application. 0496 * 0497 * The recommended way to include classes of the KChart API is including 0498 * them by class name, so instead of including KChartChart.h you would say: 0499 * 0500 \verbatim 0501 #include <KChartChart> 0502 \endverbatim 0503 * 0504 * When following this there is no reason to include the \c $KCHARTDIR/src 0505 * directory, it is sufficient to include \c $KCHARTDIR/include 0506 */ 0507 } 0508 /** 0509 * @class QAbstractItemView "(do not include)" 0510 * @brief Class only listed here to document inheritance of some KChart classes. 0511 * 0512 * Please consult the respective Qt documentation for details: 0513 * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A> 0514 */ 0515 /** 0516 * @class QAbstractProxyModel "(do not include)" 0517 * @brief Class only listed here to document inheritance of some KChart classes. 0518 * 0519 * Please consult the respective Qt documentation for details: 0520 * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A> 0521 */ 0522 /** 0523 * @class QFrame "(do not include)" 0524 * @brief Class only listed here to document inheritance of some KChart classes. 0525 * 0526 * Please consult the respective Qt documentation for details: 0527 * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A> 0528 */ 0529 /** 0530 * @class QObject "(do not include)" 0531 * @brief Class only listed here to document inheritance of some KChart classes. 0532 * 0533 * Please consult the respective Qt documentation for details: 0534 * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A> 0535 */ 0536 /** 0537 * @class QSortFilterProxyModel "(do not include)" 0538 * @brief Class only listed here to document inheritance of some KChart classes. 0539 * 0540 * Please consult the respective Qt documentation for details: 0541 * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A> 0542 */ 0543 /** 0544 * @class QWidget "(do not include)" 0545 * @brief Class only listed here to document inheritance of some KChart classes. 0546 * 0547 * Please consult the respective Qt documentation for details: 0548 * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A> 0549 */ 0550 /** 0551 * @class QTextDocument "(do not include)" 0552 * @brief Class only listed here to document inheritance of some KChart classes. 0553 * 0554 * Please consult the respective Qt documentation for details: 0555 * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A> 0556 */ 0557 /** 0558 * @class QLayoutItem "(do not include)" 0559 * @brief Class only listed here to document inheritance of some KChart classes. 0560 * 0561 * Please consult the respective Qt documentation for details: 0562 * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A> 0563 */ 0564 /** 0565 * @class QGraphicsPolygonItem "(do not include)" 0566 * @brief Class only listed here to document inheritance of some KChart classes. 0567 * 0568 * Please consult the respective Qt documentation for details: 0569 * <A HREF="http://doc.trolltech.com/">http://doc.trolltech.com/</A> 0570 */ 0571 0572 0573 #endif