From 625c56c7d323c8acc938ada28ce9ea17240cd4ec 2012-02-24 10:51:43 From: sauimone Date: 2012-02-24 10:51:43 Subject: [PATCH] Documentation for bar charts --- diff --git a/src/barchart/qbarcategory.cpp b/src/barchart/qbarcategory.cpp index 976b446..ef1cc21 100644 --- a/src/barchart/qbarcategory.cpp +++ b/src/barchart/qbarcategory.cpp @@ -4,12 +4,14 @@ QTCOMMERCIALCHART_BEGIN_NAMESPACE /*! \class QBarCategory - \brief QtCommercial chart API. + \brief part of QtCommercial chart API. QBarCategory is a container for labels of various bar charts. Before the bar chart can be constructed, the categories must be defined. This is done by creating a QBarCategory class and appending the labels of categories to it. - The QBarCategory is then given to QBarSeries class. + The QBarCategory is then given to bar chart series class. + + \sa QBarChartSeries, QStackedBarChartSeries, QPercentBarChartSeries */ /*! diff --git a/src/barchart/qbarchartseries.cpp b/src/barchart/qbarchartseries.cpp index 2a93a76..a4a0d49 100644 --- a/src/barchart/qbarchartseries.cpp +++ b/src/barchart/qbarchartseries.cpp @@ -7,47 +7,117 @@ QTCOMMERCIALCHART_BEGIN_NAMESPACE +/*! + \class QBarChartSeries + \brief part of QtCommercial chart API. + + QBarChartSeries represents a series of data shown as bars. One QBarChartSeries can contain multible + QBarSet data sets. QBarChartSeries groups the data from sets to categories, which are defined + by QBarCategory class. + + \sa QBarCategory, QBarSet, QStackedBarChartSeries, QPercentBarChartSeries +*/ + +/*! + \fn virtual QChartSeriesType QBarChartSeries::type() const + \brief Returns type of series. + \sa QChartSeries, QChartSeriesType +*/ +/*! + \fn void QBarChartSeries::changed(int index) + \brief INTERNAL \a index +*/ +/*! + \fn void QBarChartSeries::floatingValuesEnabled(bool enabled) + \brief INTERNAL \a enabled +*/ +/*! + \fn void QBarChartSeries::toolTipEnabled(bool enabled) + \brief INTERNAL \a enabled +*/ +/*! + \fn void QBarChartSeries::separatorsEnabled(bool enabled) + \brief INTERNAL \a enabled +*/ +/*! + \fn void QBarChartSeries::showToolTip(QPoint pos, QString tip) + \brief INTERNAL \a pos \a tip +*/ + +/*! + Constructs empty QBarChartSeries. Parameter \a category defines the categories for chart. + QBarChartSeries is QObject which is a child of a\a parent. +*/ QBarChartSeries::QBarChartSeries(QBarCategory *category, QObject *parent) : QChartSeries(parent) ,mModel(new BarChartModel(category, this)) { } +/*! + Adds a set of bars to series. Takes ownership of \a set +*/ void QBarChartSeries::addBarSet(QBarSet *set) { mModel->addBarSet(set); } +/*! + Removes a set of bars from series. Releases ownership of \a set. Doesnt delete \a set. +*/ void QBarChartSeries::removeBarSet(QBarSet *set) { mModel->removeBarSet(set); } +/*! + Returns number of sets in series. +*/ int QBarChartSeries::countSets() { return mModel->countSets(); } +/*! + Simple iterator for set. Returns pointer to next set in series. + Returns first set, if \a getFirst is true. If series is empty, returns 0. +*/ QBarSet* QBarChartSeries::nextSet(bool getFirst) { return mModel->nextSet(getFirst); } +/*! + Returns set indexed by \a index. Doesn't check for index bounds. + Assumes that \a index is between 0 and number of sets. Use countSets() to get valid index bound. + \sa countSets() +*/ QBarSet* QBarChartSeries::setAt(int index) { return mModel->setAt(index); } +/*! + Returns legend of series. Legend is a list of set names in series. +*/ QList QBarChartSeries::legend() { return mModel->legend(); } +/*! + INTERNAL \a category +*/ QString QBarChartSeries::label(int category) { return mModel->label(category); } +/*! + Enables or disables floating values depending on parameter \a enabled. + Floating values are bar values, that are displayed on top of each bar. + Calling without parameter \a enabled, enables the floating values +*/ void QBarChartSeries::enableFloatingValues(bool enabled) { if (enabled) { @@ -63,6 +133,11 @@ void QBarChartSeries::enableFloatingValues(bool enabled) } } +/*! + Enables or disables tooltip depending on parameter \a enabled. + Tooltip shows the name of set, when mouse is hovering on top of bar. + Calling without parameter \a enabled, enables the tooltip +*/ void QBarChartSeries::enableToolTip(bool enabled) { if (enabled) { @@ -78,46 +153,75 @@ void QBarChartSeries::enableToolTip(bool enabled) } } +/*! + Enables or disables separators depending on parameter \a enabled. + Separators are visual elements that are drawn between categories. + Calling without parameter \a enabled, enables the separators +*/ void QBarChartSeries::enableSeparators(bool enabled) { emit separatorsEnabled(enabled); } +/*! + INTERNAL +*/ int QBarChartSeries::countCategories() { return mModel->countCategories(); } +/*! + INTERNAL +*/ qreal QBarChartSeries::min() { return mModel->min(); } +/*! + INTERNAL +*/ qreal QBarChartSeries::max() { return mModel->max(); } +/*! + INTERNAL \a set \a category +*/ qreal QBarChartSeries::valueAt(int set, int category) { return mModel->valueAt(set,category); } +/*! + INTERNAL \a set \a category +*/ qreal QBarChartSeries::percentageAt(int set, int category) { return mModel->percentageAt(set,category); } +/*! + INTERNAL \a category +*/ qreal QBarChartSeries::categorySum(int category) { return mModel->categorySum(category); } +/*! + INTERNAL +*/ qreal QBarChartSeries::maxCategorySum() { return mModel->maxCategorySum(); } +/*! + INTERNAL +*/ BarChartModel& QBarChartSeries::model() { return *mModel; diff --git a/src/barchart/qbarchartseries.h b/src/barchart/qbarchartseries.h index bc0ea76..5262ed2 100644 --- a/src/barchart/qbarchartseries.h +++ b/src/barchart/qbarchartseries.h @@ -25,12 +25,12 @@ public: QBarSet *setAt(int index); QList legend(); // Returns legend of series (ie. names of all sets in series) - QString label(int category); public: // TODO: Functions below this are not part of api and will be moved // to private implementation, when we start using it // TODO: TO PIMPL ---> + QString label(int category); int countCategories(); qreal min(); qreal max(); diff --git a/src/barchart/qbarset.cpp b/src/barchart/qbarset.cpp index f27523b..b347503 100644 --- a/src/barchart/qbarset.cpp +++ b/src/barchart/qbarset.cpp @@ -4,62 +4,133 @@ QTCOMMERCIALCHART_BEGIN_NAMESPACE +/*! + \class QBarSet + \brief part of QtCommercial chart API. + + QBarSet represents one set of bars. Set of bars contains one data value for each category. + First value of set is assumed to belong to first category, second to second category and so on. + If set has fewer values than there are categories, then the missing values are assumed to be + at the end of set. For missing values in middle of a set, numerical value of zero is used. + + \sa QBarCategory, QBarChartSeries, QStackedBarChartSeries, QPercentBarChartSeries +*/ + +/*! + \fn void QBarSet::clicked() + \brief signals that set has been clicked +*/ +/*! + \fn void QBarSet::hoverEnter(QPoint pos) + \brief signals that mouse has entered over the set at position \a pos. +*/ +/*! + \fn void QBarSet::hoverLeave() + \brief signals that mouse has left from the set. +*/ +/*! + \fn void QBarSet::toggleFloatingValues() + \brief INTERNAL +*/ +/*! + \fn void QBarSet::showToolTip(QPoint pos, QString tip) + \brief INTERNAL \a pos \a tip +*/ + + +/*! + Constructs QBarSet with a name of \a name and with parent of \a parent +*/ QBarSet::QBarSet(QString name, QObject *parent) : QObject(parent) ,mName(name) { } +/*! + Sets new \a name for set. +*/ void QBarSet::setName(QString name) { mName = name; } + +/*! + Returns name of the set. +*/ QString QBarSet::name() { return mName; } +/*! + Appends new value \a value to the end of set. +*/ QBarSet& QBarSet::operator << (const qreal &value) { mValues.append(value); return *this; } +/*! + Returns count of values in set. +*/ int QBarSet::count() { return mValues.count(); } +/*! + Returns value of set indexed by \a index +*/ qreal QBarSet::valueAt(int index) { return mValues.at(index); } +/*! + Sets a new value \a value to set, indexed by \a index +*/ void QBarSet::setValue(int index, qreal value) { mValues.replace(index,value); } +/*! + Sets pen for set. Bars of this set are drawn using \a pen +*/ void QBarSet::setPen(const QPen& pen) { mPen = pen; } +/*! + Returns pen of the set. +*/ const QPen& QBarSet::pen() const { return mPen; } +/*! + Sets brush for the set. Bars of this set are drawn using \a brush +*/ void QBarSet::setBrush(const QBrush& brush) { mBrush = brush; } +/*! + Returns brush of the set. +*/ const QBrush& QBarSet::brush() const { return mBrush; } +/*! + INTERNAL +*/ void QBarSet::barClicked() { // qDebug() << "QBarset::barClicked" << this; @@ -68,12 +139,18 @@ void QBarSet::barClicked() emit clicked(); // Notify that set has been clicked } +/*! + INTERNAL \a pos +*/ void QBarSet::barHoverEntered(QPoint pos) { emit showToolTip(pos, mName); emit hoverEnter(pos); } +/*! + INTERNAL +*/ void QBarSet::barHoverLeaved() { // qDebug() << "QBarset::barHoverLeaved" << this; diff --git a/src/barchart/qpercentbarchartseries.cpp b/src/barchart/qpercentbarchartseries.cpp index eaeccec..5982882 100644 --- a/src/barchart/qpercentbarchartseries.cpp +++ b/src/barchart/qpercentbarchartseries.cpp @@ -2,6 +2,27 @@ QTCOMMERCIALCHART_BEGIN_NAMESPACE +/*! + \class QPercentBarChartSeries + \brief part of QtCommercial chart API. + + QPercentBarChartSeries represents a series of data shown as bars. Each bar of QBarSet is shown as percentage + of all bars in category. One QPercentBarChartSeries can contain multible QBarSet data sets. + QBarChartSeries groups the data from sets to categories, which are defined by QBarCategory class. + + \sa QBarCategory, QBarSet, QStackedBarChartSeries, QBarChartSeries +*/ + +/*! + \fn virtual QChartSeriesType QPercentBarChartSeries::type() const + \brief Returns type of series. + \sa QChartSeries, QChartSeriesType +*/ + +/*! + Constructs empty QPercentBarChartSeries. Parameter \a category defines the categories for chart. + QPercentBarChartSeries is QObject which is a child of a\a parent. +*/ QPercentBarChartSeries::QPercentBarChartSeries(QBarCategory *category, QObject *parent) : QBarChartSeries(category, parent) { diff --git a/src/barchart/qstackedbarchartseries.cpp b/src/barchart/qstackedbarchartseries.cpp index 71d1196..2044b34 100644 --- a/src/barchart/qstackedbarchartseries.cpp +++ b/src/barchart/qstackedbarchartseries.cpp @@ -2,6 +2,27 @@ QTCOMMERCIALCHART_BEGIN_NAMESPACE +/*! + \class QStackedBarChartSeries + \brief part of QtCommercial chart API. + + QStackedBarChartSeries represents a series of data shown as bars. All bars in same category are + stacked on top of each other. One QStackedBarChartSeries can contain multible QBarSet data sets. + QStackedBarChartSeries groups the data from sets to categories, which are defined by QBarCategory class. + + \sa QBarCategory, QBarSet, QPercentBarChartSeries, QBarChartSeries +*/ + +/*! + \fn virtual QChartSeriesType QStackedBarChartSeries::type() const + \brief Returns type of series. + \sa QChartSeries, QChartSeriesType +*/ + +/*! + Constructs empty QStackedBarChartSeries. Parameter \a category defines the categories for chart. + QStackedBarChartSeries is QObject which is a child of a\a parent. +*/ QStackedBarChartSeries::QStackedBarChartSeries(QBarCategory *category, QObject *parent) : QBarChartSeries(category, parent) {