← Back to branch summary

~ubuntu-branches/ubuntu/precise/koffice/precise

« back to all changes in this revision

Viewing changes to plugins/chartshape/kdchart/src/KDChartChart.h

  • Committer: Bazaar Package Importer
  • Author(s): Alessandro Ghersi
  • Date: 2010-10-27 17:52:57 UTC
  • mfrom: (0.12.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20101027175257-s04zqqk5bs8ckm9o
Tags: 1:2.2.83-0ubuntu1
* Merge with Debian git remaining changes:
 - Add build-deps on librcps-dev, opengtl-dev, libqtgtl-dev, freetds-dev,
   create-resources, libspnav-dev
 - Remove needless build-dep on libwv2-dev
 - koffice-libs recommends create-resources
 - krita recommends pstoedit
 - Keep our patches
* New upstream release 2.3 beta 3
  - Remove debian/patches fixed by upstream
  - Update install files

Show diffs side-by-side

added added

removed removed

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