From 9957a05c82116af75a0299a8885328a7a6bdb53d 2012-02-24 11:05:18 From: Jani Honkonen Date: 2012-02-24 11:05:18 Subject: [PATCH] Add documentation to pie --- diff --git a/src/piechart/qpieseries.cpp b/src/piechart/qpieseries.cpp index 2c167eb..9a52326 100644 --- a/src/piechart/qpieseries.cpp +++ b/src/piechart/qpieseries.cpp @@ -7,6 +7,24 @@ QTCOMMERCIALCHART_BEGIN_NAMESPACE +/*! + \enum QPieSeries::PiePosition + + This enum describes pie position within its bounding rectangle + + \value PiePositionMaximized + \value PiePositionTopLeft + \value PiePositionTopRight + \value PiePositionBottomLeft + \value PiePositionBottomRight +*/ + +/*! + \class QPieSeries + \brief QtCommercial charts pie series API. + +*/ + void QPieSeries::ChangeSet::appendAdded(QPieSlice* slice) { if (!m_added.contains(slice)) @@ -31,21 +49,37 @@ void QPieSeries::ChangeSet::appendRemoved(QPieSlice* slice) m_removed << slice; } +/*! + Returns a list of slices that have been added to the series. + \sa QPieSeries::changed() +*/ QList QPieSeries::ChangeSet::added() const { return m_added; } +/*! + Returns a list of slices that have been changed in the series. + \sa QPieSeries::changed() +*/ QList QPieSeries::ChangeSet::changed() const { return m_changed; } +/*! + Returns a list of slices that have been removed from the series. + \sa QPieSeries::changed() +*/ QList QPieSeries::ChangeSet::removed() const { return m_removed; } + +/*! + Returns true if there are no added/changed or removed slices in the change set. +*/ bool QPieSeries::ChangeSet::isEmpty() const { if (m_added.count() || m_changed.count() || m_removed.count()) @@ -53,22 +87,39 @@ bool QPieSeries::ChangeSet::isEmpty() const return true; } - +/*! + Constructs a series object which is a child of \a parent. +*/ QPieSeries::QPieSeries(QObject *parent) : QChartSeries(parent), m_sizeFactor(1.0), m_position(PiePositionMaximized), m_pieStartAngle(0), - m_pieSpan(360) + m_pieAngleSpan(360) { } +/*! + Destroys the object. Note that adding series to QChart transfers the ownership to the chart. +*/ QPieSeries::~QPieSeries() { } +/*! + Returns the type of the series which is always QChartSeries::SeriesTypePie. +*/ +QChartSeries::QChartSeriesType QPieSeries::type() const +{ + return QChartSeries::SeriesTypePie; +} + +/*! + Sets an array of values to the series. + TO BE REMOVED +*/ bool QPieSeries::setData(QList data) { // TODO: remove this function @@ -79,12 +130,20 @@ bool QPieSeries::setData(QList data) return true; } +/*! + Sets an array of \a slices to the series. + Slice ownership is passed to the series. +*/ void QPieSeries::set(QList slices) { clear(); add(slices); } +/*! + Adds an array of slices to the series. + Slice ownership is passed to the series. +*/ void QPieSeries::add(QList slices) { ChangeSet changeSet; @@ -106,11 +165,20 @@ void QPieSeries::add(QList slices) emit changed(changeSet); } +/*! + Adds a single \a slice to the series. + Slice ownership is passed to the series. +*/ void QPieSeries::add(QPieSlice* slice) { add(QList() << slice); } + +/*! + Adds a single slice to the series with give \a value and \a name. + Slice ownership is passed to the series. +*/ QPieSlice* QPieSeries::add(qreal value, QString name) { QPieSlice* slice = new QPieSlice(value, name); @@ -118,6 +186,10 @@ QPieSlice* QPieSeries::add(qreal value, QString name) return slice; } +/*! + Removes a single \a slice from the series and deletes the slice. + Do not reference this pointer after this call. +*/ void QPieSeries::remove(QPieSlice* slice) { if (!m_slices.removeOne(slice)) { @@ -135,6 +207,9 @@ void QPieSeries::remove(QPieSlice* slice) updateDerivativeData(); } +/*! + Clears all slices from the series. +*/ void QPieSeries::clear() { if (m_slices.count() == 0) @@ -150,6 +225,28 @@ void QPieSeries::clear() updateDerivativeData(); } +/*! + Counts the number of the slices in this series. +*/ +int QPieSeries::count() const +{ + return m_slices.count(); +} + +/*! + Returns a list of slices that belong to this series. +*/ +QList QPieSeries::slices() const +{ + return m_slices; +} + +/*! + Sets the size \a factor of the pie. 1.0 is the default value. + Note that the pie will not grow beyond its absolute maximum size. + In practice its use is to make the pie appear smaller. + \sa sizeFactor() +*/ void QPieSeries::setSizeFactor(qreal factor) { if (factor < 0.0) @@ -161,6 +258,19 @@ void QPieSeries::setSizeFactor(qreal factor) } } +/*! + Gets the size factor of the pie. + \sa setSizeFactor() +*/ +qreal QPieSeries::sizeFactor() const +{ + return m_sizeFactor; +} + +/*! + Sets the \a position of the pie within its bounding rectangle. + \sa PiePosition, position() +*/ void QPieSeries::setPosition(PiePosition position) { if (m_position != position) { @@ -169,22 +279,47 @@ void QPieSeries::setPosition(PiePosition position) } } -void QPieSeries::setSpan(qreal startAngle, qreal span) +/*! + Gets the position of the pie within its bounding rectangle. + \sa PiePosition, setPosition() +*/ +QPieSeries::PiePosition QPieSeries::position() const +{ + return m_position; +} + + +/*! + Sets the \a startAngle and \a angleSpan of this series. + + \sa +*/ +void QPieSeries::setSpan(qreal startAngle, qreal angleSpan) { if (startAngle >= 0 && startAngle < 360 && - span > 0 && span <= 360) { + angleSpan > 0 && angleSpan <= 360) { m_pieStartAngle = startAngle; - m_pieSpan = span; + m_pieAngleSpan = angleSpan; updateDerivativeData(); } } +/*! + Sets the all the slice labels \a visible or invisible. + + \sa QPieSlice::isLabelVisible(), QPieSlice::setLabelVisible() +*/ void QPieSeries::setLabelsVisible(bool visible) { foreach (QPieSlice* s, m_slices) s->setLabelVisible(visible); } +/*! + Convenience method for exploding a slice when user clicks the pie. + + \sa QPieSlice::isExploded(), QPieSlice::setExploded() +*/ void QPieSeries::enableClickExplodes(bool enable) { if (enable) @@ -193,6 +328,13 @@ void QPieSeries::enableClickExplodes(bool enable) disconnect(this, SLOT(toggleExploded(QPieSlice*))); } +/*! + Convenience method for highlighting a slice when user hovers over the slice. + It changes the slice color to be lighter and shows the label of the slice. + + \sa QPieSlice::isExploded(), QPieSlice::setExploded() +*/ + void QPieSeries::enableHoverHighlight(bool enable) { if (enable) { @@ -204,6 +346,55 @@ void QPieSeries::enableHoverHighlight(bool enable) } } +/*! + \fn void QPieSeries::changed(const QPieSeries::ChangeSet& changeSet) + + This signal emitted when something has changed in the series. + The \a changeSet contains the details of which slices have been added, changed or removed. + + \sa QPieSeries::ChangeSet, QPieSlice::changed() +*/ + +/*! + \fn void QPieSeries::clicked(QPieSlice* slice) + + This signal is emitted when a \a slice has been clicked. + + \sa QPieSlice::clicked() +*/ + +/*! + \fn void QPieSeries::hoverEnter(QPieSlice* slice) + + This signal is emitted when user has hovered over a \a slice. + + \sa QPieSlice::hoverEnter() +*/ + +/*! + \fn void QPieSeries::hoverLeave(QPieSlice* slice) + + This signal is emitted when user has hovered away from a \a slice. + + \sa QPieSlice::hoverLeave() +*/ + +/*! + \fn void QPieSeries::sizeFactorChanged() + + This signal is emitted when size factor has been changed. + + \sa sizeFactor(), setSizeFactor() +*/ + +/*! + \fn void QPieSeries::positionChanged() + + This signal is emitted when position of the pie has been changed. + + \sa position(), setPosition() +*/ + void QPieSeries::sliceChanged() { QPieSlice* slice = qobject_cast(sender()); @@ -286,7 +477,7 @@ void QPieSeries::updateDerivativeData() changed = true; } - qreal sliceSpan = m_pieSpan * percentage; + qreal sliceSpan = m_pieAngleSpan * percentage; if (s->m_angleSpan != sliceSpan) { s->m_angleSpan = sliceSpan; changed = true; diff --git a/src/piechart/qpieseries.h b/src/piechart/qpieseries.h index 977af05..5804be3 100644 --- a/src/piechart/qpieseries.h +++ b/src/piechart/qpieseries.h @@ -31,6 +31,8 @@ public: class ChangeSet { public: + + // TODO: these should not really be exposed to the public API void appendAdded(QPieSlice* slice); void appendAdded(QList slices); void appendChanged(QPieSlice* slice); @@ -53,7 +55,7 @@ public: virtual ~QPieSeries(); public: // from QChartSeries - QChartSeriesType type() const { return QChartSeries::SeriesTypePie; } + QChartSeriesType type() const; virtual bool setData(QList data); // TODO: remove this public: @@ -64,17 +66,17 @@ public: void remove(QPieSlice* slice); void clear(); - int count() const { return m_slices.count(); } + int count() const; - QList slices() const { return m_slices; } + QList slices() const; void setSizeFactor(qreal sizeFactor); - qreal sizeFactor() const { return m_sizeFactor; } + qreal sizeFactor() const; void setPosition(PiePosition position); - PiePosition position() const { return m_position; } + PiePosition position() const; - void setSpan(qreal startAngle, qreal span); + void setSpan(qreal startAngle, qreal angleSpan); void setLabelsVisible(bool visible); void enableClickExplodes(bool enable); @@ -123,7 +125,7 @@ private: PiePosition m_position; qreal m_total; qreal m_pieStartAngle; - qreal m_pieSpan; + qreal m_pieAngleSpan; }; QTCOMMERCIALCHART_END_NAMESPACE diff --git a/src/piechart/qpieslice.cpp b/src/piechart/qpieslice.cpp index ede577f..c0c17e9 100644 --- a/src/piechart/qpieslice.cpp +++ b/src/piechart/qpieslice.cpp @@ -4,9 +4,32 @@ QTCOMMERCIALCHART_BEGIN_NAMESPACE #define DEFAULT_PEN_COLOR Qt::black #define DEFAULT_BRUSH_COLOR Qt::white -#define DEFAULT_LABEL_ARM_LENGTH 50 +#define DEFAULT_LABEL_ARM_LENGTH 40 #define DEFAULT_EXPOLODE_DISTANCE 20 +/*! + \class QPieSlice + \brief QtCommercial charts pie series API. + +*/ + +/*! + \property QPieSlice::label + + Label of the slice. +*/ + +/*! + \property QPieSlice::value + + Value of the slice. +*/ + +/*! + Constructs an empty slice with a \a parent. + Note that QPieSeries takes ownership of the slice when it is set/added. + \sa QPieSeries::set(), QPieSeries::add() +*/ QPieSlice::QPieSlice(QObject *parent) :QObject(parent), m_value(0), @@ -24,11 +47,16 @@ QPieSlice::QPieSlice(QObject *parent) } -QPieSlice::QPieSlice(qreal value, QString label, bool labelVisible, QObject *parent) +/*! + Constructs an empty slice with given \a value, \a label and a \a parent. + Note that QPieSeries takes ownership of the slice when it is set/added. + \sa QPieSeries::set(), QPieSeries::add() +*/ +QPieSlice::QPieSlice(qreal value, QString label, QObject *parent) :QObject(parent), m_value(value), m_label(label), - m_isLabelVisible(labelVisible), + m_isLabelVisible(false), m_isExploded(false), m_explodeDistance(DEFAULT_EXPOLODE_DISTANCE), m_percentage(0), @@ -42,76 +70,171 @@ QPieSlice::QPieSlice(qreal value, QString label, bool labelVisible, QObject *par } +/*! + Destroys the slice. + User should not delete the slice if it has been added to the series. +*/ QPieSlice::~QPieSlice() { } +/*! + Gets the value of the slice. + Note that all values in the series + \sa setValue() +*/ qreal QPieSlice::value() const { return m_value; } +/*! + Gets the label of the slice. + \sa setLabel() +*/ QString QPieSlice::label() const { return m_label; } +/*! + Returns true if label is set as visible. + \sa setLabelVisible() +*/ bool QPieSlice::isLabelVisible() const { return m_isLabelVisible; } +/*! + Returns true if slice is exloded from the pie. + \sa setExploded() +*/ bool QPieSlice::isExploded() const { return m_isExploded; } +/*! + Returns the explosion distance of the slice. + Default value is 20. + \sa setExplodeDistance() +*/ qreal QPieSlice::explodeDistance() const { return m_explodeDistance; } +/*! + Returns the percentage of this slice compared to all slices in the same series. + Updated internally after the slice is added to the series. +*/ qreal QPieSlice::percentage() const { return m_percentage; } +/*! + Returns the starting angle of this slice in the series it belongs to. + Updated internally after the slice is added to the series. +*/ qreal QPieSlice::angle() const { return m_angle; } +/*! + Returns the angle span of this slice in the series it belongs to. + Updated internally after the slice is added to the series. +*/ qreal QPieSlice::angleSpan() const { return m_angleSpan; } +/*! + Returns the pen used to draw this slice. + \sa setPen() +*/ QPen QPieSlice::pen() const { return m_pen; } +/*! + Returns the brush used to draw this slice. + \sa setBrush() +*/ QBrush QPieSlice::brush() const { return m_brush; } +/*! + Returns the pen used to draw label in this slice. + \sa setLabelPen() +*/ QPen QPieSlice::labelPen() const { return m_labelPen; } +/*! + Returns the font used to draw label in this slice. + \sa setLabelFont() +*/ QFont QPieSlice::labelFont() const { return m_labelFont; } +/*! + Returns the label arm lenght used in this slice. + Default value is 40 pixels. + \sa setLabelArmLength() +*/ qreal QPieSlice::labelArmLength() const { return m_labelArmLength; } +/*! + \fn void QPieSlice::clicked() + + This signal is emitted when user has clicked the slice. + + \sa QPieSeries::clicked() +*/ + +/*! + \fn void QPieSlice::hoverEnter() + + This signal is emitted when user has hovered over the slice. + + \sa QPieSeries::hoverEnter() +*/ + +/*! + \fn void QPieSlice::hoverLeave() + + This signal is emitted when user has hovered away from the slice. + + \sa QPieSeries::hoverLeave() +*/ + +/*! + \fn void QPieSlice::changed() + + This signal emitted when something has changed in the slice. + + \sa QPieSeries::changed() +*/ + +/*! + Sets the value of this slice. + \sa value() +*/ void QPieSlice::setValue(qreal value) { if (m_value != value) { @@ -120,6 +243,10 @@ void QPieSlice::setValue(qreal value) } } +/*! + Sets the \a label of the slice. + \sa label() +*/ void QPieSlice::setLabel(QString label) { if (m_label != label) { @@ -128,6 +255,10 @@ void QPieSlice::setLabel(QString label) } } +/*! + Sets the label \a visible in this slice. + \sa isLabelVisible(), QPieSeries::setLabelsVisible() +*/ void QPieSlice::setLabelVisible(bool visible) { if (m_isLabelVisible != visible) { @@ -136,6 +267,10 @@ void QPieSlice::setLabelVisible(bool visible) } } +/*! + Sets this slice \a exploded. + \sa isExploded(), setExplodeDistance(), QPieSeries::enableClickExplodes() +*/ void QPieSlice::setExploded(bool exploded) { if (m_isExploded != exploded) { @@ -144,6 +279,11 @@ void QPieSlice::setExploded(bool exploded) } } +/*! + Sets the explosion \a distance of this slice. + It is the distance the slice is moved away from the pie center. + \sa explodeDistance(), isExploded(), QPieSeries::enableClickExplodes() +*/ void QPieSlice::setExplodeDistance(qreal distance) { if (m_explodeDistance != distance) { @@ -152,6 +292,11 @@ void QPieSlice::setExplodeDistance(qreal distance) } } +/*! + Sets the \a pen used to draw this slice. + Note that applying a theme will override this. + \sa pen() +*/ void QPieSlice::setPen(QPen pen) { if (m_pen != pen) { @@ -160,6 +305,11 @@ void QPieSlice::setPen(QPen pen) } } +/*! + Sets the \a brush used to draw this slice. + Note that applying a theme will override this. + \sa brush() +*/ void QPieSlice::setBrush(QBrush brush) { if (m_brush != brush) { @@ -168,26 +318,40 @@ void QPieSlice::setBrush(QBrush brush) } } -void QPieSlice::setLabelFont(QFont font) +/*! + Sets the \a pen used to draw the label in this slice. + Note that applying a theme will override this. + \sa labelPen() +*/ +void QPieSlice::setLabelPen(QPen pen) { - if (m_labelFont != font) { - m_labelFont = font; + if (m_labelPen != pen) { + m_labelPen = pen; emit changed(); } } -void QPieSlice::setLabelPen(QPen pen) +/*! + Sets the \a font used to draw the label in this slice. + Note that applying a theme will override this. + \sa labelFont() +*/ +void QPieSlice::setLabelFont(QFont font) { - if (m_labelPen != pen) { - m_labelPen = pen; + if (m_labelFont != font) { + m_labelFont = font; emit changed(); } } -void QPieSlice::setLabelArmLength(qreal len) +/*! + Sets the label arm \a length used to draw the label in this slice. + \sa labelArmLength() +*/ +void QPieSlice::setLabelArmLength(qreal length) { - if (m_labelArmLength != len) { - m_labelArmLength = len; + if (m_labelArmLength != length) { + m_labelArmLength = length; emit changed(); } } diff --git a/src/piechart/qpieslice.h b/src/piechart/qpieslice.h index 3e5010d..3bb6425 100644 --- a/src/piechart/qpieslice.h +++ b/src/piechart/qpieslice.h @@ -12,12 +12,12 @@ QTCOMMERCIALCHART_BEGIN_NAMESPACE class QTCOMMERCIALCHART_EXPORT QPieSlice : public QObject { Q_OBJECT - Q_PROPERTY(QString label READ label WRITE setLabel /*NOTIFY dataYChanged*/) - Q_PROPERTY(qreal value READ value WRITE setValue /*NOTIFY dataXChanged*/) + Q_PROPERTY(QString label READ label WRITE setLabel NOTIFY changed) + Q_PROPERTY(qreal value READ value WRITE setValue NOTIFY changed) public: QPieSlice(QObject *parent = 0); - QPieSlice(qreal value, QString label, bool labelVisible = false, QObject *parent = 0); + QPieSlice(qreal value, QString label, QObject *parent = 0); virtual ~QPieSlice(); // data