From 7b988086e9976b78d0f1ff433dcec205c6d33478 Mon Sep 17 00:00:00 2001 From: Miikka Heikkinen Date: Mon, 2 Sep 2013 14:24:02 +0300 Subject: Improve data mapping documentation. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task-number: QTRD-2133 Change-Id: I8f25fc7a3d15712060a1d100ec4d9895cc4b6637 Reviewed-by: Tomi Korpipää --- src/datavis3d/data/qabstractdatamapping.cpp | 12 +++++- src/datavis3d/data/qabstractdatamapping.h | 2 - src/datavis3d/data/qitemmodelbardatamapping.cpp | 26 ++++++++--- src/datavis3d/data/qitemmodelbardataproxy.cpp | 25 +++++++++-- src/datavis3d/data/qitemmodelmapdataproxy.cpp | 7 ++- .../data/qitemmodelscatterdatamapping.cpp | 50 +++++++++++----------- src/datavis3d/data/qitemmodelscatterdatamapping.h | 10 +---- src/datavis3d/data/qitemmodelscatterdataproxy.cpp | 18 +++++++- src/datavis3d/doc/snippets/doc_src_qtdatavis3d.cpp | 40 +++++++++++++++++ 9 files changed, 139 insertions(+), 51 deletions(-) diff --git a/src/datavis3d/data/qabstractdatamapping.cpp b/src/datavis3d/data/qabstractdatamapping.cpp index ab5bdf5b..f85983ec 100644 --- a/src/datavis3d/data/qabstractdatamapping.cpp +++ b/src/datavis3d/data/qabstractdatamapping.cpp @@ -23,10 +23,12 @@ QT_DATAVIS3D_BEGIN_NAMESPACE /*! * \class QAbstractDataMapping * \inmodule QtDataVis3D - * \brief Abstract base class for data mappings + * \brief Abstract base class for QtDataVis3D data mapping classes. * \since 1.0.0 * - * Data mapping classes provide a way to map data from one data source to another. + * Data mapping classes provide a way to map data from an external data source to one of + * QtDataVis3D data proxies. + * \sa QItemModelBarDataMapping, QItemModelScatterDataMapping */ /*! @@ -45,6 +47,12 @@ QAbstractDataMapping::~QAbstractDataMapping() { } +/*! + * \fn void QAbstractDataMapping::mappingChanged() + * + * Emitted when any mapping has changed. + */ + // QItemModelBarDataMappingPrivate QAbstractDataMappingPrivate::QAbstractDataMappingPrivate(QAbstractDataMapping *q, diff --git a/src/datavis3d/data/qabstractdatamapping.h b/src/datavis3d/data/qabstractdatamapping.h index edc4b8ee..7f91c7ae 100644 --- a/src/datavis3d/data/qabstractdatamapping.h +++ b/src/datavis3d/data/qabstractdatamapping.h @@ -34,8 +34,6 @@ public: explicit QAbstractDataMapping(QAbstractDataMappingPrivate *d, QObject *parent = 0); virtual ~QAbstractDataMapping(); - QAbstractDataProxy::DataType type() const; - signals: void mappingChanged(); diff --git a/src/datavis3d/data/qitemmodelbardatamapping.cpp b/src/datavis3d/data/qitemmodelbardatamapping.cpp index 6bc92f2c..d9b8403b 100644 --- a/src/datavis3d/data/qitemmodelbardatamapping.cpp +++ b/src/datavis3d/data/qitemmodelbardatamapping.cpp @@ -26,10 +26,22 @@ QT_DATAVIS3D_BEGIN_NAMESPACE * \brief Data model mapping for Q3DBars. * \since 1.0.0 * - * QItemModelBarDataMapping is used to define roles for mapping data in QAbstractItemModel to - * Q3DBars. + * QItemModelBarDataMapping is used to map roles of QAbstractItemModel to rows, columns, and values + * of Q3DBars. There are two ways to use QItemModelBarDataMapping: * - * TO BE CHECKED (add more explanations and/or example) + * 1) By default, the QItemModelBarDataMapping will map the rows and columns of QAbstractItemModel + * to rows and columns of Q3DBars, and uses the value returned for Qt::DisplayRole as bar value. + * The value role to be used can be redefined if Qt::DisplayRole is not suitable. + * + * 2) For models that do not have data already neatly sorted into rows and columns, such as + * QAbstractListModel based models, you can define a list of categories for both rows and columns, + * and define a role to map for each of row, column and value. + * For example, assume that you have a custom QAbstractItemModel for storing various monthly values + * related to a business. + * Each item in the model has roles "year", "month", "income", and "expenses". + * You could do the following to display the data in a bar chart: + * + * \snippet doc_src_qtdatavis3d.cpp 3 * * \sa QItemModelBarDataProxy */ @@ -160,8 +172,6 @@ QStringList QItemModelBarDataMapping::columnCategories() const /*! * Changes \a rowRole, \a columnRole, \a valueRole, \a rowCategories and \a columnCategories to the * mapping. - * - * Emits mappingChanged() signal after remapping. */ void QItemModelBarDataMapping::remap(const QString &rowRole, const QString &columnRole, @@ -178,11 +188,17 @@ void QItemModelBarDataMapping::remap(const QString &rowRole, emit mappingChanged(); } +/*! + * \internal + */ QItemModelBarDataMappingPrivate *QItemModelBarDataMapping::dptr() { return static_cast(d_ptr.data()); } +/*! + * \internal + */ const QItemModelBarDataMappingPrivate *QItemModelBarDataMapping::dptrc() const { return static_cast(d_ptr.data()); diff --git a/src/datavis3d/data/qitemmodelbardataproxy.cpp b/src/datavis3d/data/qitemmodelbardataproxy.cpp index 6cd3b027..8a25f123 100644 --- a/src/datavis3d/data/qitemmodelbardataproxy.cpp +++ b/src/datavis3d/data/qitemmodelbardataproxy.cpp @@ -29,7 +29,10 @@ QT_DATAVIS3D_BEGIN_NAMESPACE * \since 1.0.0 * * QItemModelBarDataProxy allows you to use QAbstractItemModel derived models as a data source - * for Q3DBars. It maps roles defined in QItemModelBarDataMapping to roles in the model. + * for Q3DBars. It uses QItemModelBarDataMapping instance to map data from the model to Q3DBars + * graph. + * + * \sa QItemModelBarDataMapping */ /*! @@ -77,10 +80,10 @@ const QAbstractItemModel *QItemModelBarDataProxy::itemModel() const } /*! - * \property QItemModelBarDataProxy::mapping + * \property QItemModelBarDataProxy::activeMapping * - * Defines data mapping. Does not take ownership of the mapping, but does connect to it to listen - * for changes. Modifying a mapping that is set to the proxy will trigger data set re-resolving. + * Defines data mapping. Proxy takes ownership of the \a mapping. + * Modifying a mapping that is set to the proxy will trigger data set re-resolving. */ void QItemModelBarDataProxy::setActiveMapping(QItemModelBarDataMapping *mapping) { @@ -92,16 +95,27 @@ QItemModelBarDataMapping *QItemModelBarDataProxy::activeMapping() const return static_cast(dptrc()->m_itemModelHandler->activeMapping()); } +/*! + * Transfers the ownership of the \a mapping to this proxy. The mapping is not taken to use yet. + * \sa setActiveMapping(), releaseMapping() + */ void QItemModelBarDataProxy::addMapping(QItemModelBarDataMapping *mapping) { dptr()->m_itemModelHandler->addMapping(mapping); } +/*! + * Releases the ownership of the \a mapping back to the caller. If the mapping was the currently + * active one, no mapping remains active after this call. + */ void QItemModelBarDataProxy::releaseMapping(QItemModelBarDataMapping *mapping) { dptr()->m_itemModelHandler->releaseMapping(mapping); } +/*! + * \return list of mappings owned by the proxy. + */ QList QItemModelBarDataProxy::mappings() const { QList retList; @@ -120,6 +134,9 @@ QItemModelBarDataProxyPrivate *QItemModelBarDataProxy::dptr() return static_cast(d_ptr.data()); } +/*! + * \internal + */ const QItemModelBarDataProxyPrivate *QItemModelBarDataProxy::dptrc() const { return static_cast(d_ptr.data()); diff --git a/src/datavis3d/data/qitemmodelmapdataproxy.cpp b/src/datavis3d/data/qitemmodelmapdataproxy.cpp index 9d607645..6288d979 100644 --- a/src/datavis3d/data/qitemmodelmapdataproxy.cpp +++ b/src/datavis3d/data/qitemmodelmapdataproxy.cpp @@ -77,8 +77,8 @@ const QAbstractItemModel *QItemModelMapDataProxy::itemModel() const /*! * \property QItemModelMapDataProxy::activeMapping * - * Defines data mapping. Does not take ownership of the mapping, but does connect to it to listen - * for changes. Modifying a mapping that is set to the proxy will trigger data set re-resolving. + * Defines data mapping. Proxy takes ownership of the \a mapping. + * Modifying a mapping that is set to the proxy will trigger data set re-resolving. */ void QItemModelMapDataProxy::setActiveMapping(QItemModelMapDataMapping *mapping) { @@ -98,6 +98,9 @@ QItemModelMapDataProxyPrivate *QItemModelMapDataProxy::dptr() return static_cast(d_ptr.data()); } +/*! + * \internal + */ const QItemModelMapDataProxyPrivate *QItemModelMapDataProxy::dptrc() const { return static_cast(d_ptr.data()); diff --git a/src/datavis3d/data/qitemmodelscatterdatamapping.cpp b/src/datavis3d/data/qitemmodelscatterdatamapping.cpp index dca02bbf..db8dff9e 100644 --- a/src/datavis3d/data/qitemmodelscatterdatamapping.cpp +++ b/src/datavis3d/data/qitemmodelscatterdatamapping.cpp @@ -26,10 +26,18 @@ QT_DATAVIS3D_BEGIN_NAMESPACE * \brief Data model mapping for Q3DScatter. * \since 1.0.0 * - * QItemModelScatterDataMapping is used to define roles for mapping data in QAbstractItemModel to - * Q3DScatter. + * QItemModelScatterDataMapping is used to map roles of QAbstractItemModel to the XYZ-values + * of Q3DScatter points. * - * TO BE CHECKED (add more explanations and/or example) + * QItemModelScatterDataMapping ignores rows and columns of the QAbstractItemModel and treats + * all items equally. It requires the model to provide at least three roles for the data items + * that can be mapped to X, Y, and Z-values for the scatter points. + * + * For example, assume that you have a custom QAbstractItemModel for storing various measurements + * done on material samples, providing data for roles such as "density", "hardness" and + * "conductivity". You could visualize these properties on a scatter chart: + * + * \snippet doc_src_qtdatavis3d.cpp 4 * * \sa QItemModelScatterDataProxy */ @@ -43,21 +51,18 @@ QItemModelScatterDataMapping::QItemModelScatterDataMapping(QObject *parent) } /*! - * Constructs QItemModelScatterDataMapping with \a xPosRole, \a yPosRole, \a zPosRole, - * \a valueRole and the given \a parent. + * Constructs QItemModelScatterDataMapping with \a xPosRole, \a yPosRole, \a zPosRole + * and the given \a parent. */ QItemModelScatterDataMapping::QItemModelScatterDataMapping(const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, - const QString &valueRole, QObject *parent) : QAbstractDataMapping(new QItemModelScatterDataMappingPrivate(this), parent) { - Q_UNUSED(valueRole); dptr()->m_xPosRole = xPosRole; dptr()->m_yPosRole = yPosRole; dptr()->m_zPosRole = zPosRole; - //d_ptr->m_valueRole = valueRole; } /*! @@ -70,7 +75,7 @@ QItemModelScatterDataMapping::~QItemModelScatterDataMapping() /*! * \property QItemModelScatterDataMapping::xPosRole * - * Defines the x position role for the mapping. + * Defines the X position role for the mapping. */ void QItemModelScatterDataMapping::setXPosRole(const QString &role) { @@ -86,7 +91,7 @@ QString QItemModelScatterDataMapping::xPosRole() const /*! * \property QItemModelScatterDataMapping::yPosRole * - * Defines the y position role for the mapping. + * Defines the Y position role for the mapping. */ void QItemModelScatterDataMapping::setYPosRole(const QString &role) { @@ -102,7 +107,7 @@ QString QItemModelScatterDataMapping::yPosRole() const /*! * \property QItemModelScatterDataMapping::zPosRole * - * Defines the z position role for the mapping. + * Defines the Z position role for the mapping. */ void QItemModelScatterDataMapping::setZPosRole(const QString &role) { @@ -115,39 +120,32 @@ QString QItemModelScatterDataMapping::zPosRole() const return dptrc()->m_zPosRole; } -//void QItemModelScatterDataMapping::setValueRole(const QString &role) -//{ -// d_ptr->m_valueRole = role; -// emit mappingChanged(); -//} - -//QString QItemModelScatterDataMapping::valueRole() const -//{ -// return d_ptr->m_valueRole; -//} - /*! - * Changes \a xPosRole, \a yPosRole, \a zPosRole and \a valueRole to the mapping. + * Changes \a xPosRole, \a yPosRole and \a zPosRole to the mapping. * * Emits mappingChanged() signal after remapping. */ void QItemModelScatterDataMapping::remap(const QString &xPosRole, const QString &yPosRole, - const QString &zPosRole, const QString &valueRole) + const QString &zPosRole) { - Q_UNUSED(valueRole); dptr()->m_xPosRole = xPosRole; dptr()->m_yPosRole = yPosRole; dptr()->m_zPosRole = zPosRole; - //d_ptr->m_valueRole = valueRole; emit mappingChanged(); } +/*! + * \internal + */ QItemModelScatterDataMappingPrivate *QItemModelScatterDataMapping::dptr() { return static_cast(d_ptr.data()); } +/*! + * \internal + */ const QItemModelScatterDataMappingPrivate *QItemModelScatterDataMapping::dptrc() const { return static_cast(d_ptr.data()); diff --git a/src/datavis3d/data/qitemmodelscatterdatamapping.h b/src/datavis3d/data/qitemmodelscatterdatamapping.h index 1a162b57..2f64f38c 100644 --- a/src/datavis3d/data/qitemmodelscatterdatamapping.h +++ b/src/datavis3d/data/qitemmodelscatterdatamapping.h @@ -33,13 +33,11 @@ class QT_DATAVIS3D_EXPORT QItemModelScatterDataMapping : public QAbstractDataMap Q_PROPERTY(QString xPosRole READ xPosRole WRITE setXPosRole) Q_PROPERTY(QString yPosRole READ yPosRole WRITE setYPosRole) Q_PROPERTY(QString zPosRole READ zPosRole WRITE setZPosRole) - //Q_PROPERTY(QString valueRole READ valueRole WRITE setValueRole) public: explicit QItemModelScatterDataMapping(QObject *parent = 0); QItemModelScatterDataMapping(const QString &xPosRole, const QString &yPosRole, - const QString &zPosRole, const QString &valueRole, - QObject *parent = 0); + const QString &zPosRole, QObject *parent = 0); virtual ~QItemModelScatterDataMapping(); void setXPosRole(const QString &role); @@ -48,12 +46,8 @@ public: QString yPosRole() const; void setZPosRole(const QString &role); QString zPosRole() const; - // TODO: This is a placeholder for scatter item size - //void setValueRole(const QString &role); - //QString valueRole() const; - void remap(const QString &xPosRole, const QString &yPosRole, const QString &zPosRole, - const QString &valueRole); + void remap(const QString &xPosRole, const QString &yPosRole, const QString &zPosRole); protected: QItemModelScatterDataMappingPrivate *dptr(); diff --git a/src/datavis3d/data/qitemmodelscatterdataproxy.cpp b/src/datavis3d/data/qitemmodelscatterdataproxy.cpp index c802d91d..dfd10d8d 100644 --- a/src/datavis3d/data/qitemmodelscatterdataproxy.cpp +++ b/src/datavis3d/data/qitemmodelscatterdataproxy.cpp @@ -78,8 +78,8 @@ const QAbstractItemModel *QItemModelScatterDataProxy::itemModel() const /*! * \property QItemModelScatterDataProxy::activeMapping * - * Defines data mapping. Does not take ownership of the mapping, but does connect to it to listen - * for changes. Modifying a mapping that is set to the proxy will trigger data set re-resolving. + * Defines data mapping. Proxy takes ownership of the \a mapping. + * Modifying a mapping that is set to the proxy will trigger data set re-resolving. */ void QItemModelScatterDataProxy::setActiveMapping(QItemModelScatterDataMapping *mapping) { @@ -91,16 +91,27 @@ QItemModelScatterDataMapping *QItemModelScatterDataProxy::activeMapping() const return static_cast(dptrc()->m_itemModelHandler->activeMapping()); } +/*! + * Transfers the ownership of the \a mapping to this proxy. The mapping is not taken to use yet. + * \sa setActiveMapping(), releaseMapping() + */ void QItemModelScatterDataProxy::addMapping(QItemModelScatterDataMapping *mapping) { dptr()->m_itemModelHandler->addMapping(mapping); } +/*! + * Releases the ownership of the \a mapping back to the caller. If the mapping was the currently + * active one, no mapping remains active after this call. + */ void QItemModelScatterDataProxy::releaseMapping(QItemModelScatterDataMapping *mapping) { dptr()->m_itemModelHandler->releaseMapping(mapping); } +/*! + * \return list of mappings owned by the proxy. + */ QList QItemModelScatterDataProxy::mappings() const { QList retList; @@ -119,6 +130,9 @@ QItemModelScatterDataProxyPrivate *QItemModelScatterDataProxy::dptr() return static_cast(d_ptr.data()); } +/*! + * \internal + */ const QItemModelScatterDataProxyPrivate *QItemModelScatterDataProxy::dptrc() const { return static_cast(d_ptr.data()); diff --git a/src/datavis3d/doc/snippets/doc_src_qtdatavis3d.cpp b/src/datavis3d/doc/snippets/doc_src_qtdatavis3d.cpp index b4a2b152..269ea520 100644 --- a/src/datavis3d/doc/snippets/doc_src_qtdatavis3d.cpp +++ b/src/datavis3d/doc/snippets/doc_src_qtdatavis3d.cpp @@ -27,3 +27,43 @@ proxy->setItemLabelFormat(QStringLiteral("@valueTitle for (@rowLabel, @colLabel) //! [2] proxy->setItemLabelFormat(QStringLiteral("@xTitle: @xValue, @yTitle: @yValue, @zTitle: @zValue")); //! [2] + +//! [3] +// By defining row and column categories, you tell the mapping which row and column each item +// belongs to. The categories must match the data stored in the model in the roles you define +// for row and column mapping. In this example we expect "year" role to return four digit year +// and "month" to return three letter designation for the month. +// +// An example of an item in model would be: +// Requested role -> Returned data +// "year" -> "2006" // Matches the first row category, so this item is added to the first row. +// "month" -> "jan" // Matches the first column category, so this item is added as first item in the row. +// "income" -> "12.1" +// "expenses" -> "9.2" +QStringList years; +QStringList months; +years << "2006" << "2007" << "2008" << "2009" << "2010" << "2011" << "2012"; +months << "jan" << "feb" << "mar" << "apr" << "may" << "jun" << "jul" << "aug" << "sep" << "oct" << "nov" << "dec"; + +QItemModelBarDataMapping *mapping = new QItemModelBarDataMapping(QStringLiteral("year"), // Row role + QStringLiteral("month"), // Column role + QStringLiteral("income"), // Value role + years, // Row categories + months); // Column categories + +QItemModelBarDataProxy *proxy = new QItemModelBarDataProxy(customModel, mapping); + +//... + +// To display different data later, you can simply change the mapping of the current +// mapping object, or set another mapping object. +proxy->activeMapping()->setValueRole(QStringLiteral("expenses")); +//! [3] + +//! [4] +// Map "density" value to X-axis, "hardness" to Y-axis and "conductivity" to Z-axis. +QItemModelScatterDataMapping *mapping = new QItemModelScatterDataMapping(QStringLiteral("density"), + QStringLiteral("hardness"), + QStringLiteral("conductivity")) +QItemModelScatterDataProxy *proxy = new QItemModelScatterDataProxy(customModel, mapping); +//! [4] -- cgit v1.2.3