From 06179f33651d98fe658849459b41b74871744ad8 2012-05-29 12:30:33 From: Jani Honkonen Date: 2012-05-29 12:30:33 Subject: [PATCH] pieslice: update docs --- diff --git a/src/piechart/qpieslice.cpp b/src/piechart/qpieslice.cpp index 5615dfb..4f5ee06 100644 --- a/src/piechart/qpieslice.cpp +++ b/src/piechart/qpieslice.cpp @@ -31,17 +31,27 @@ QTCOMMERCIALCHART_BEGIN_NAMESPACE In addition to the obvious value and label properties the user can also control the visual appearance of a slice. By modifying the visual appearance also means that - the user is overriding the default appearance set by the theme. Even if the theme is - changed users settings will persist. + the user is overriding the default appearance set by the theme. - To enable user interaction customization with the slices some basic signals - are provided about clicking and hovering. + Note that if the user has customized slices and theme is changed all customizations will be lost. + + To enable user interaction with the pie some basic signals are provided about clicking and hovering. */ /*! \property QPieSlice::label Label of the slice. + + \sa labelVisible, labelPen, labelFont, labelArmLengthFactor +*/ + +/*! + \fn void QPieSlice::labelChanged() + + This signal emitted when the slice label has been changed. + + \sa label */ /*! @@ -53,212 +63,208 @@ QTCOMMERCIALCHART_BEGIN_NAMESPACE */ /*! - Constructs an empty slice with a \a parent. + \fn void QPieSlice::valueChanged() - \sa QPieSeries::append(), QPieSeries::insert() -*/ -QPieSlice::QPieSlice(QObject *parent) - :QObject(parent), - d_ptr(new QPieSlicePrivate(this)) -{ + This signal is emitted when the slice value changes. -} + \sa value +*/ /*! - Constructs an empty slice with given \a value, \a label and a \a parent. - \sa QPieSeries::append(), QPieSeries::insert() + \property QPieSlice::labelVisible + + Defienes the visibility of the slice label. + + Default is not visible. + + \sa label, labelPen, labelFont, labelArmLengthFactor */ -QPieSlice::QPieSlice(QString label, qreal value, QObject *parent) - :QObject(parent), - d_ptr(new QPieSlicePrivate(this)) -{ - d_ptr->m_data.m_value = value; - d_ptr->m_data.m_labelText = label; -} /*! - Destroys the slice. - User should not delete the slice if it has been added to the series. -*/ -QPieSlice::~QPieSlice() -{ + \fn void QPieSlice::labelVisibleChanged() -} + This signal emitted when visibility of the slice label has changed. -/*! - Gets the value of the slice. - Note that all values in the series - \sa setValue() + \sa labelVisible */ -qreal QPieSlice::value() const -{ - return d_ptr->m_data.m_value; -} /*! - Gets the label of the slice. - \sa setLabel() + \property QPieSlice::exploded + + Defines if the slice is exploded from the pie. + + \sa explodeDistanceFactor */ -QString QPieSlice::label() const -{ - return d_ptr->m_data.m_labelText; -} /*! - Returns true if label is set as visible. - \sa setLabelVisible() + \fn void QPieSlice::explodedChanged() + + This signal is emitted the the slice has been exploded from the pie or is returned back to the pie. + + \sa exploded */ -bool QPieSlice::isLabelVisible() const -{ - return d_ptr->m_data.m_isLabelVisible; -} /*! - Returns true if slice is exloded from the pie. - \sa setExploded(), explodeDistanceFactor(), setExplodeDistanceFactor() + \property QPieSlice::pen + + Pen used to draw the slice border. */ -bool QPieSlice::isExploded() const -{ - return d_ptr->m_data.m_isExploded; -} /*! - Returns the explode distance factor. + \fn void QPieSlice::penChanged() - The factor is relative to pie radius. For example: - 1.0 means the distance is the same as the radius. - 0.5 means the distance is half of the radius. + This signal is emitted when the pen of the slice has changed. + + \sa pen +*/ - Default value is 0.15. +/*! + \property QPieSlice::brush - \sa setExplodeDistanceFactor(), isExploded(), setExploded() + Brush used to draw the slice. */ -qreal QPieSlice::explodeDistanceFactor() const -{ - return d_ptr->m_data.m_explodeDistanceFactor; -} /*! - Returns the percentage of this slice compared to the sum of all slices in the same series. - The returned value ranges from 0 to 1.0. + \fn void QPieSlice::brushChanged() - Updated internally after the slice is added to the series. + This signal is emitted when the brush of the slice has changed. - \sa QPieSeries::sum() + \sa brush */ -qreal QPieSlice::percentage() const -{ - return d_ptr->m_data.m_percentage; -} /*! - Returns the starting angle of this slice in the series it belongs to. + \property QPieSlice::labelPen - Full pie is 360 degrees where 0 degrees is at 12 a'clock. + Pen used to draw label and label arm of the slice. - Updated internally after the slice is added to the series. + \sa label, labelVisible, labelFont, labelArmLengthFactor */ -qreal QPieSlice::startAngle() const -{ - return d_ptr->m_data.m_startAngle; -} /*! - Returns the end angle of this slice in the series it belongs to. + \fn void QPieSlice::labelPenChanged() - Full pie is 360 degrees where 0 degrees is at 12 a'clock. + This signal is emitted when the label pen of the slice has changed. - Updated internally after the slice is added to the series. + \sa labelPen */ -qreal QPieSlice::angleSpan() const -{ - return d_ptr->m_data.m_angleSpan; -} /*! - Returns the pen used to draw this slice. - \sa setPen() + \property QPieSlice::labelFont + + Font used for drawing label text. + + \sa label, labelVisible, labelArmLengthFactor */ -QPen QPieSlice::pen() const -{ - return d_ptr->m_data.m_slicePen; -} /*! - Returns the brush used to draw this slice. - \sa setBrush() + \fn void QPieSlice::labelFontChanged() + + This signal is emitted when the label font of the slice has changed. + + \sa labelFont */ -QBrush QPieSlice::brush() const -{ - return d_ptr->m_data.m_sliceBrush; -} /*! - Returns the pen used to draw the label in this slice. - \sa setLabelPen() + \property QPieSlice::labelArmLengthFactor + + Defines the length of the label arm. + + The factor is relative to pie radius. For example: + 1.0 means the length is the same as the radius. + 0.5 means the length is half of the radius. + + Default value is 0.15 + + \sa label, labelVisible, labelPen, labelFont */ -QPen QPieSlice::labelPen() const -{ - return d_ptr->m_data.m_labelPen; -} /*! - Returns the font used to draw label in this slice. - \sa setLabelFont() + \fn void QPieSlice::labelArmLengthFactorChanged() + + This signal is emitted when the label arm factor of the slice has changed. + + \sa labelArmLengthFactor */ -QFont QPieSlice::labelFont() const -{ - return d_ptr->m_data.m_labelFont; -} /*! - Gets the label arm length factor. + \property QPieSlice::explodeDistanceFactor + + When the slice is exploded this factor defines how far the slice is exploded away from the pie. The factor is relative to pie radius. For example: - 1.0 means the length is the same as the radius. - 0.5 means the length is half of the radius. + 1.0 means the distance is the same as the radius. + 0.5 means the distance is half of the radius. Default value is 0.15 - \sa setLabelArmLengthFactor() + \sa exploded */ -qreal QPieSlice::labelArmLengthFactor() const -{ - return d_ptr->m_data.m_labelArmLengthFactor; -} /*! - \fn void QPieSlice::labelChanged() + \fn void QPieSlice::explodeDistanceFactorChanged() - This signal is emitted when the slice label changes. + This signal is emitted when the explode distance factor of the slice has changed. - \sa setLabel() + \sa explodeDistanceFactor */ /*! - \fn void QPieSlice::valueChanged() + \property QPieSlice::percentage - This signal is emitted when the slice value changes. + Percentage of the slice compared to the sum of all slices in the series. + + The actual value ranges from 0.0 to 1.0. + + Updated automatically once the slice is added to the series. + + \sa value, QPieSeries::sum +*/ + +/*! + \fn void QPieSlice::percentageChanged() + + This signal is emitted when the percentage of the slice has changed. + + \sa percentage +*/ + +/*! + \property QPieSlice::startAngle + + Defines the starting angle of this slice in the series it belongs to. - \sa setValue() + Full pie is 360 degrees where 0 degrees is at 12 a'clock. + + Updated automatically once the slice is added to the series. */ /*! - \fn void QPieSlice::appearanceChanged() + \fn void QPieSlice::startAngleChanged() + + This signal is emitted when the starting angle f the slice has changed. + + \sa startAngle +*/ - This signal is emitted when visual appearance of the slice changes. +/*! + \property QPieSlice::angleSpan + + Span of the slice in degrees. + + Full pie is 360 degrees where 0 degrees is at 12 a'clock. - \sa setPen(), setBrush(), setLabelVisible(), setExploded() + Updated automatically once the slice is added to the series. */ /*! - \fn void QPieSlice::calculatedDataChanged() + \fn void QPieSlice::angleSpanChanged() - This signal is emitted when calculated data for this slice changes. + This signal is emitted when the angle span of the slice has changed. - \sa percentage(), startAngle(), endAngle() + \sa angleSpan */ + /*! \fn void QPieSlice::clicked() @@ -278,21 +284,38 @@ qreal QPieSlice::labelArmLengthFactor() const */ /*! - Sets the \a value of this slice. - \sa value() + Constructs an empty slice with a \a parent. + + \sa QPieSeries::append(), QPieSeries::insert() */ -void QPieSlice::setValue(qreal value) +QPieSlice::QPieSlice(QObject *parent) + :QObject(parent), + d_ptr(new QPieSlicePrivate(this)) { - if (!qFuzzyIsNull(d_ptr->m_data.m_value - value)) { - d_ptr->m_data.m_value = value; - emit valueChanged(); - } + } /*! - Sets the \a label of the slice. - \sa label() + Constructs an empty slice with given \a value, \a label and a \a parent. + \sa QPieSeries::append(), QPieSeries::insert() */ +QPieSlice::QPieSlice(QString label, qreal value, QObject *parent) + :QObject(parent), + d_ptr(new QPieSlicePrivate(this)) +{ + d_ptr->m_data.m_value = value; + d_ptr->m_data.m_labelText = label; +} + +/*! + Destroys the slice. + User should not delete the slice if it has been added to the series. +*/ +QPieSlice::~QPieSlice() +{ + +} + void QPieSlice::setLabel(QString label) { if (d_ptr->m_data.m_labelText != label) { @@ -301,10 +324,24 @@ void QPieSlice::setLabel(QString label) } } -/*! - Sets the label \a visible in this slice. - \sa isLabelVisible(), QPieSeries::setLabelsVisible() -*/ +QString QPieSlice::label() const +{ + return d_ptr->m_data.m_labelText; +} + +void QPieSlice::setValue(qreal value) +{ + if (!qFuzzyIsNull(d_ptr->m_data.m_value - value)) { + d_ptr->m_data.m_value = value; + emit valueChanged(); + } +} + +qreal QPieSlice::value() const +{ + return d_ptr->m_data.m_value; +} + void QPieSlice::setLabelVisible(bool visible) { if (d_ptr->m_data.m_isLabelVisible != visible) { @@ -313,13 +350,11 @@ void QPieSlice::setLabelVisible(bool visible) } } -/*! - Sets this slices \a exploded state. - - If the slice is exploded it is moved away from the pie center. The distance is defined by the explode distance factor. +bool QPieSlice::isLabelVisible() const +{ + return d_ptr->m_data.m_isLabelVisible; +} - \sa isExploded(), explodeDistanceFactor(), setExplodeDistanceFactor() -*/ void QPieSlice::setExploded(bool exploded) { if (d_ptr->m_data.m_isExploded != exploded) { @@ -328,84 +363,51 @@ void QPieSlice::setExploded(bool exploded) } } -/*! - Sets the explode distance \a factor. - - The factor is relative to pie radius. For example: - 1.0 means the distance is the same as the radius. - 0.5 means the distance is half of the radius. - - Default value is 0.15 - - \sa explodeDistanceFactor(), isExploded(), setExploded() -*/ -void QPieSlice::setExplodeDistanceFactor(qreal factor) +bool QPieSlice::isExploded() const { - if (!qFuzzyIsNull(d_ptr->m_data.m_explodeDistanceFactor - factor)) { - d_ptr->m_data.m_explodeDistanceFactor = factor; - emit explodeDistanceFactorChanged(); - } + return d_ptr->m_data.m_isExploded; } -/*! - Sets the \a pen used to draw this slice. - - Overrides the pen set by the theme. - - \sa pen() -*/ void QPieSlice::setPen(const QPen &pen) { d_ptr->setPen(pen, false); } -/*! - Sets the \a brush used to draw this slice. - - Overrides the brush set by the theme. +QPen QPieSlice::pen() const +{ + return d_ptr->m_data.m_slicePen; +} - \sa brush() -*/ void QPieSlice::setBrush(const QBrush &brush) { d_ptr->setBrush(brush, false); } -/*! - Sets the \a pen used to draw the label in this slice. - - Overrides the pen set by the theme. +QBrush QPieSlice::brush() const +{ + return d_ptr->m_data.m_sliceBrush; +} - \sa labelPen() -*/ void QPieSlice::setLabelPen(const QPen &pen) { d_ptr->setLabelPen(pen, false); } -/*! - Sets the \a font used to draw the label in this slice. - - Overrides the font set by the theme. +QPen QPieSlice::labelPen() const +{ + return d_ptr->m_data.m_labelPen; +} - \sa labelFont() -*/ void QPieSlice::setLabelFont(const QFont &font) { d_ptr->setLabelFont(font, false); } -/*! - Sets the label arm length \a factor. - - The factor is relative to pie radius. For example: - 1.0 means the length is the same as the radius. - 0.5 means the length is half of the radius. - - Default value is 0.15 +QFont QPieSlice::labelFont() const +{ + return d_ptr->m_data.m_labelFont; +} - \sa labelArmLengthFactor() -*/ void QPieSlice::setLabelArmLengthFactor(qreal factor) { if (!qFuzzyIsNull(d_ptr->m_data.m_labelArmLengthFactor - factor)) { @@ -414,6 +416,39 @@ void QPieSlice::setLabelArmLengthFactor(qreal factor) } } +qreal QPieSlice::labelArmLengthFactor() const +{ + return d_ptr->m_data.m_labelArmLengthFactor; +} + +void QPieSlice::setExplodeDistanceFactor(qreal factor) +{ + if (!qFuzzyIsNull(d_ptr->m_data.m_explodeDistanceFactor - factor)) { + d_ptr->m_data.m_explodeDistanceFactor = factor; + emit explodeDistanceFactorChanged(); + } +} + +qreal QPieSlice::explodeDistanceFactor() const +{ + return d_ptr->m_data.m_explodeDistanceFactor; +} + +qreal QPieSlice::percentage() const +{ + return d_ptr->m_data.m_percentage; +} + +qreal QPieSlice::startAngle() const +{ + return d_ptr->m_data.m_startAngle; +} + +qreal QPieSlice::angleSpan() const +{ + return d_ptr->m_data.m_angleSpan; +} + QPieSlicePrivate::QPieSlicePrivate(QPieSlice *parent) :QObject(parent), q_ptr(parent) diff --git a/src/piechart/qpieslice.h b/src/piechart/qpieslice.h index ba3a7df..e5b45e9 100644 --- a/src/piechart/qpieslice.h +++ b/src/piechart/qpieslice.h @@ -41,7 +41,7 @@ class QTCOMMERCIALCHART_EXPORT QPieSlice : public QObject Q_PROPERTY(QBrush brush READ brush WRITE setBrush NOTIFY brushChanged) Q_PROPERTY(QPen labelPen READ labelPen WRITE setLabelPen NOTIFY labelPenChanged) Q_PROPERTY(QFont labelFont READ labelFont WRITE setLabelFont NOTIFY labelFontChanged) - Q_PROPERTY(qreal LabelArmLengthFactor READ labelArmLengthFactor WRITE setLabelArmLengthFactor) + Q_PROPERTY(qreal labelArmLengthFactor READ labelArmLengthFactor WRITE setLabelArmLengthFactor) Q_PROPERTY(qreal explodeDistanceFactor READ explodeDistanceFactor WRITE setExplodeDistanceFactor) Q_PROPERTY(qreal percentage READ percentage NOTIFY percentageChanged) Q_PROPERTY(qreal startAngle READ startAngle NOTIFY startAngleChanged)