1 files changed, 154 insertions, 15 deletions

diff --git a/src/datavisualization/data/qitemmodelsurfacedatamapping.cpp b/src/datavisualization/data/qitemmodelsurfacedatamapping.cpp
index 79f310ea..2fd66b30 100644
--- a/src/datavisualization/data/qitemmodelsurfacedatamapping.cpp
+++ b/src/datavisualization/data/qitemmodelsurfacedatamapping.cpp
@@ -26,7 +26,30 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * \brief Data model mapping for Q3DSurface.
  * \since 1.0.0
  *
- * DOCUMENTATION GOES HERE
+ * QItemModelSurfaceDataMapping is used to map roles of QAbstractItemModel to rows, columns, and values
+ * of Q3DSurface. There are three ways to use QItemModelSurfaceDataMapping:
+ *
+ * 1) If useModelCategories property is set to true, QItemModelSurfaceDataMapping will map rows and
+ *    columns of QAbstractItemModel to rows and columns of Q3DSurface, and uses the value returned for
+ *    Qt::DisplayRole as bar value by default.
+ *    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 role from the model to map for each of row,
+ *    column and value.
+ *
+ * 3) If you do not want to include all data contained in the model, or the autogenerated rows and
+ *    columns are not ordered as you wish, you can specify which rows and columns should be included
+ *    and in which order by defining an explicit list of categories for either or both of rows and
+ *    columns.
+ *
+ *    For example, assume that you have a custom QAbstractItemModel storing surface topography data.
+ *    Each item in the model has roles "longitude", "latitude" and "height". The item model already
+ *    contains the data properly sorted so that longitudes and latitudes are first encountered in
+ *    correct order, which enables us to utilize the row and column category autogeneration.
+ *    You could do the following to display the data in a surface graph:
+ *
+ *    \snippet doc_src_qtdatavisualization.cpp 5
  *
  * \sa QItemModelSurfaceDataProxy
  */
@@ -71,6 +94,26 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  */
 
 /*!
+ * \qmlproperty list SurfaceDataMapping::useModelCategories
+ * When set to true, the mapping ignores row and column roles and categories, and uses
+ * the rows and columns from the model instead. Defaults to false.
+ */
+
+/*!
+ * \qmlproperty list SurfaceDataMapping::autoRowCategories
+ * When set to true, the mapping ignores any explicitly set row categories
+ * and overwrites them with automatically generated ones whenever the
+ * data from model is resolved. Defaults to true.
+ */
+
+/*!
+ * \qmlproperty list SurfaceDataMapping::autoColumnCategories
+ * When set to true, the mapping ignores any explicitly set column categories
+ * and overwrites them with automatically generated ones whenever the
+ * data from model is resolved. Defaults to true.
+ */
+
+/*!
  * Constructs QItemModelSurfaceDataMapping with the given \a parent.
  */
 QItemModelSurfaceDataMapping::QItemModelSurfaceDataMapping(QObject *parent)
@@ -80,16 +123,35 @@ QItemModelSurfaceDataMapping::QItemModelSurfaceDataMapping(QObject *parent)
 
 /*!
  * Constructs QItemModelSurfaceDataMapping with \a valueRole and the given \a parent.
+ * This constructor is meant to be used with models that have data properly sorted
+ * in rows and columns already, so it also sets useModelCategories property to true.
  */
 QItemModelSurfaceDataMapping::QItemModelSurfaceDataMapping(const QString &valueRole, QObject *parent)
     : QAbstractDataMapping(new QItemModelSurfaceDataMappingPrivate(this), parent)
 {
     dptr()->m_valueRole = valueRole;
+    dptr()->m_useModelCategories = true;
+}
+
+/*!
+ * Constructs QItemModelSurfaceDataMapping with \a rowRole, \a columnRole, \a valueRole
+ * and the given \a parent.
+ */
+QItemModelSurfaceDataMapping::QItemModelSurfaceDataMapping(const QString &rowRole,
+                                                   const QString &columnRole,
+                                                   const QString &valueRole,
+                                                   QObject *parent)
+    : QAbstractDataMapping(new QItemModelSurfaceDataMappingPrivate(this), parent)
+{
+    dptr()->m_rowRole = rowRole;
+    dptr()->m_columnRole = columnRole;
+    dptr()->m_valueRole = valueRole;
 }
 
 /*!
  * Constructs QItemModelSurfaceDataMapping with \a rowRole, \a columnRole, \a valueRole,
- * \a rowCategories, \a columnCategories and the given \a parent.
+ * \a rowCategories, \a columnCategories and the given \a parent. This constructor
+ * also sets autoRowCategories and autoColumnCategories to false.
  */
 QItemModelSurfaceDataMapping::QItemModelSurfaceDataMapping(const QString &rowRole,
                                                            const QString &columnRole,
@@ -104,6 +166,8 @@ QItemModelSurfaceDataMapping::QItemModelSurfaceDataMapping(const QString &rowRol
     dptr()->m_valueRole = valueRole;
     dptr()->m_rowCategories = rowCategories;
     dptr()->m_columnCategories = columnCategories;
+    dptr()->m_autoRowCategories = false;
+    dptr()->m_autoColumnCategories = false;
 }
 
 /*!
@@ -120,8 +184,10 @@ QItemModelSurfaceDataMapping::~QItemModelSurfaceDataMapping()
  */
 void QItemModelSurfaceDataMapping::setRowRole(const QString &role)
 {
-    dptr()->m_rowRole = role;
-    emit mappingChanged();
+    if (dptr()->m_rowRole != role) {
+        dptr()->m_rowRole = role;
+        emit mappingChanged();
+    }
 }
 
 QString QItemModelSurfaceDataMapping::rowRole() const
@@ -136,8 +202,10 @@ QString QItemModelSurfaceDataMapping::rowRole() const
  */
 void QItemModelSurfaceDataMapping::setColumnRole(const QString &role)
 {
-    dptr()->m_columnRole = role;
-    emit mappingChanged();
+    if (dptr()->m_columnRole != role) {
+        dptr()->m_columnRole = role;
+        emit mappingChanged();
+    }
 }
 
 QString QItemModelSurfaceDataMapping::columnRole() const
@@ -152,8 +220,10 @@ QString QItemModelSurfaceDataMapping::columnRole() const
  */
 void QItemModelSurfaceDataMapping::setValueRole(const QString &role)
 {
-    dptr()->m_valueRole = role;
-    emit mappingChanged();
+    if (dptr()->m_valueRole != role) {
+        dptr()->m_valueRole = role;
+        emit mappingChanged();
+    }
 }
 
 QString QItemModelSurfaceDataMapping::valueRole() const
@@ -168,8 +238,10 @@ QString QItemModelSurfaceDataMapping::valueRole() const
  */
 void QItemModelSurfaceDataMapping::setRowCategories(const QStringList &categories)
 {
-    dptr()->m_rowCategories = categories;
-    emit mappingChanged();
+    if (dptr()->m_rowCategories != categories) {
+        dptr()->m_rowCategories = categories;
+        emit mappingChanged();
+    }
 }
 
 QStringList QItemModelSurfaceDataMapping::rowCategories() const
@@ -184,8 +256,10 @@ QStringList QItemModelSurfaceDataMapping::rowCategories() const
  */
 void QItemModelSurfaceDataMapping::setColumnCategories(const QStringList &categories)
 {
-    dptr()->m_columnCategories = categories;
-    emit mappingChanged();
+    if (dptr()->m_columnCategories != categories) {
+        dptr()->m_columnCategories = categories;
+        emit mappingChanged();
+    }
 }
 
 QStringList QItemModelSurfaceDataMapping::columnCategories() const
@@ -194,6 +268,65 @@ QStringList QItemModelSurfaceDataMapping::columnCategories() const
 }
 
 /*!
+ * \property QItemModelSurfaceDataMapping::useModelCategories
+ *
+ * When set to true, the mapping ignores row and column roles and categories, and uses
+ * the rows and columns from the model instead. Defaults to false.
+ */
+void QItemModelSurfaceDataMapping::setUseModelCategories(bool enable)
+{
+    if (dptr()->m_useModelCategories != enable) {
+        dptr()->m_useModelCategories = enable;
+        emit mappingChanged();
+    }
+}
+
+bool QItemModelSurfaceDataMapping::useModelCategories() const
+{
+    return dptrc()->m_useModelCategories;
+}
+
+/*!
+ * \property QItemModelSurfaceDataMapping::autoRowCategories
+ *
+ * When set to true, the mapping ignores any explicitly set row categories
+ * and overwrites them with automatically generated ones whenever the
+ * data from model is resolved. Defaults to true.
+ */
+void QItemModelSurfaceDataMapping::setAutoRowCategories(bool enable)
+{
+    if (dptr()->m_autoRowCategories != enable) {
+        dptr()->m_autoRowCategories = enable;
+        emit mappingChanged();
+    }
+}
+
+bool QItemModelSurfaceDataMapping::autoRowCategories() const
+{
+    return dptrc()->m_autoRowCategories;
+}
+
+/*!
+ * \property QItemModelSurfaceDataMapping::autoColumnCategories
+ *
+ * When set to true, the mapping ignores any explicitly set column categories
+ * and overwrites them with automatically generated ones whenever the
+ * data from model is resolved. Defaults to true.
+ */
+void QItemModelSurfaceDataMapping::setAutoColumnCategories(bool enable)
+{
+    if (dptr()->m_autoColumnCategories != enable) {
+        dptr()->m_autoColumnCategories = enable;
+        emit mappingChanged();
+    }
+}
+
+bool QItemModelSurfaceDataMapping::autoColumnCategories() const
+{
+    return dptrc()->m_autoColumnCategories;
+}
+
+/*!
  * Changes \a rowRole, \a columnRole, \a valueRole, \a rowCategories and \a columnCategories to the
  * mapping.
  */
@@ -214,7 +347,9 @@ void QItemModelSurfaceDataMapping::remap(const QString &rowRole,
 
 /*!
  * /return index of the specified \a category in row categories list.
- * If the category is not found, -1 is returned.
+ * If the row categories list is empty, -1 is returned.
+ * \note If the automatic row categories generation is in use, this method will
+ * not return valid index before the data in the model is resolved for the first time.
  */
 int QItemModelSurfaceDataMapping::rowCategoryIndex(const QString &category)
 {
@@ -223,7 +358,8 @@ int QItemModelSurfaceDataMapping::rowCategoryIndex(const QString &category)
 
 /*!
  * /return index of the specified \a category in column categories list.
- * If the category is not found, -1 is returned.
+ * \note If the automatic column categories generation is in use, this method will
+ * not return valid index before the data in the model is resolved for the first time.
  */
 int QItemModelSurfaceDataMapping::columnCategoryIndex(const QString &category)
 {
@@ -249,7 +385,10 @@ const QItemModelSurfaceDataMappingPrivate *QItemModelSurfaceDataMapping::dptrc()
 // QItemModelSurfaceDataMappingPrivate
 
 QItemModelSurfaceDataMappingPrivate::QItemModelSurfaceDataMappingPrivate(QItemModelSurfaceDataMapping *q)
-    : QAbstractDataMappingPrivate(q, QAbstractDataProxy::DataTypeSurface)
+    : QAbstractDataMappingPrivate(q, QAbstractDataProxy::DataTypeSurface),
+    m_useModelCategories(false),
+    m_autoRowCategories(true),
+    m_autoColumnCategories(true)
 {
 }