Improve documentation on data handling

Change-Id: Ie1acb5b12eeb9b59815b7482042edc8adc0250d8
Reviewed-by: Tomi Korpipää <tomi.korpipaa@digia.com>

7 files changed, 117 insertions, 6 deletions

diff --git a/src/datavisualization/data/qitemmodelbardatamapping.cpp b/src/datavisualization/data/qitemmodelbardatamapping.cpp
index 54cb0708..fc6f8f54 100644
--- a/src/datavisualization/data/qitemmodelbardatamapping.cpp
+++ b/src/datavisualization/data/qitemmodelbardatamapping.cpp
@@ -88,12 +88,14 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
 
 /*!
  * \qmlproperty list BarDataMapping::rowCategories
- * The row categories of the mapping.
+ * The row categories of the mapping. Only items with row roles that are found in this list are
+ * included when data is resolved. The rows are ordered in the same order as they are in this list.
  */
 
 /*!
  * \qmlproperty list BarDataMapping::columnCategories
- * The column categories of the mapping.
+ * The column categories of the mapping. Only items with column roles that are found in this list are
+ * included when data is resolved. The columns are ordered in the same order as they are in this list.
  */
 
 /*!
diff --git a/src/datavisualization/data/qitemmodelbardataproxy.cpp b/src/datavisualization/data/qitemmodelbardataproxy.cpp
index 85fd8bf9..b0fa74b6 100644
--- a/src/datavisualization/data/qitemmodelbardataproxy.cpp
+++ b/src/datavisualization/data/qitemmodelbardataproxy.cpp
@@ -32,6 +32,9 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * for Q3DBars. It uses QItemModelBarDataMapping instance to map data from the model to Q3DBars
  * graph.
  *
+ * Data is resolved asynchronously whenever the mapping or the model changes.
+ * QBarDataProxy::arrayReset() is emitted when the data has been resolved.
+ *
  * \sa QItemModelBarDataMapping, {Qt Data Visualization Data Handling}
  */
 
@@ -46,6 +49,9 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  *
  * This type allows you to use AbstractItemModel derived models as a data source for Bars3D.
  *
+ * Data is resolved asynchronously whenever the mapping or the model changes.
+ * QBarDataProxy::arrayReset() is emitted when the data has been resolved.
+ *
  * Usage example:
  *
  * \snippet doc_src_qmldatavisualization.cpp 7
diff --git a/src/datavisualization/data/qitemmodelscatterdataproxy.cpp b/src/datavisualization/data/qitemmodelscatterdataproxy.cpp
index 7527f87e..b037d4d1 100644
--- a/src/datavisualization/data/qitemmodelscatterdataproxy.cpp
+++ b/src/datavisualization/data/qitemmodelscatterdataproxy.cpp
@@ -31,6 +31,9 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * QItemModelScatterDataProxy allows you to use QAbstractItemModel derived models as a data source
  * for Q3DScatter. It maps roles defined in QItemModelScatterDataMapping to roles in the model.
  *
+ * Data is resolved asynchronously whenever the mapping or the model changes.
+ * QScatterDataProxy::arrayReset() is emitted when the data has been resolved.
+ *
  * /sa {Qt Data Visualization Data Handling}
  */
 
@@ -45,6 +48,9 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  *
  * This type allows you to use AbstractItemModel derived models as a data source for Scatter3D.
  *
+ * Data is resolved asynchronously whenever the mapping or the model changes.
+ * QScatterDataProxy::arrayReset() is emitted when the data has been resolved.
+ *
  * Usage example:
  *
  * \snippet doc_src_qmldatavisualization.cpp 8
diff --git a/src/datavisualization/data/qitemmodelsurfacedatamapping.cpp b/src/datavisualization/data/qitemmodelsurfacedatamapping.cpp
index 0b7c74c9..5388ec18 100644
--- a/src/datavisualization/data/qitemmodelsurfacedatamapping.cpp
+++ b/src/datavisualization/data/qitemmodelsurfacedatamapping.cpp
@@ -89,12 +89,14 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
 
 /*!
  * \qmlproperty list SurfaceDataMapping::rowCategories
- * The row categories of the mapping.
+ * The row categories of the mapping. Only items with row roles that are found in this list are
+ * included when data is resolved. The rows are ordered in the same order as they are in this list.
  */
 
 /*!
  * \qmlproperty list SurfaceDataMapping::columnCategories
- * The column categories of the mapping.
+ * The column categories of the mapping. Only items with column roles that are found in this list are
+ * included when data is resolved. The columns are ordered in the same order as they are in this list.
  */
 
 /*!
diff --git a/src/datavisualization/data/qitemmodelsurfacedataproxy.cpp b/src/datavisualization/data/qitemmodelsurfacedataproxy.cpp
index 22271c2e..f6403e9b 100644
--- a/src/datavisualization/data/qitemmodelsurfacedataproxy.cpp
+++ b/src/datavisualization/data/qitemmodelsurfacedataproxy.cpp
@@ -33,6 +33,9 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * QItemModelSurfaceDataProxy allows you to use QAbstractItemModel derived models as a data source
  * for Q3DSurface. It maps roles defined in QItemModelSurfaceDataMapping to roles in the model.
  *
+ * Data is resolved asynchronously whenever the mapping or the model changes.
+ * QSurfaceDataProxy::arrayReset() is emitted when the data has been resolved.
+ *
  * /sa {Qt Data Visualization Data Handling}
  */
 
@@ -47,6 +50,9 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  *
  * This type allows you to use AbstractItemModel derived models as a data source for Surface3D.
  *
+ * Data is resolved asynchronously whenever the mapping or the model changes.
+ * QSurfaceDataProxy::arrayReset() is emitted when the data has been resolved.
+ *
  * Usage example:
  *
  * \snippet doc_src_qmldatavisualization.cpp 9
diff --git a/src/datavisualization/doc/snippets/doc_src_qtdatavisualization.cpp b/src/datavisualization/doc/snippets/doc_src_qtdatavisualization.cpp
index b64755e1..2f3d6a98 100644
--- a/src/datavisualization/doc/snippets/doc_src_qtdatavisualization.cpp
+++ b/src/datavisualization/doc/snippets/doc_src_qtdatavisualization.cpp
@@ -99,3 +99,20 @@ make
 Q3DBars *graph = new Q3DBars();
 QWidget *container = QWidget::createWindowContainer(graph);
 //! [9]
+
+//! [10]
+Q3DBars graph;
+QBarDataProxy *newProxy = new QBarDataProxy;
+
+QBarDataArray *dataArray = new QBarDataArray;
+dataArray->reserve(10);
+for (int i = 0; i < 10; i++) {
+    QBarDataRow *dataRow = new QBarDataRow(5);
+    for (int j = 0; j < 5; j++)
+        (*dataRow)[j].setValue(myData->getValue(i, j));
+    dataArray->append(dataRow);
+}
+
+newProxy->resetArray(dataArray);
+graph->setActiveDataProxy(newProxy);
+//! [10]
diff --git a/src/datavisualization/doc/src/qtdatavisualization.qdoc b/src/datavisualization/doc/src/qtdatavisualization.qdoc
index ba158d27..7c4bcd2e 100644
--- a/src/datavisualization/doc/src/qtdatavisualization.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization.qdoc
@@ -98,11 +98,83 @@
 
     \section1 Data proxies
 
-    TODO
+    The data users wish to visualize comes in many formats, all of which cannot obviously be
+    directly supported. Therefore Qt Data Visualization implements data proxies into which
+    user can feed their data in a known format. Each visualization type has a basic proxy type,
+    which takes data in a format suitable for that visualization.
+    For example, the basic proxy for Q3DBars is QBarDataProxy, which stores rows of QBarDataItem
+    objects. Each QBarDataItem stores a single bar value. Additional typedefs are provided for
+    QBarDataArray and QBarDataRow containers.
+
+    This code snipped shows how to use basic proxy when your data is stored in some hypothetical
+    \c myData object:
+
+    \snippet doc_src_qtdatavisualization.cpp 10
+
+    \note The graph objects can own more than one data proxy, but only one proxy can be
+    active at a time. If you need to switch back and forth between two different sets of data,
+    it may be more efficient to store each set in different proxy and just change the active
+    proxy, rather than reset the data in one proxy every time you need to switch.
 
     \section1 Item models and data mapping
 
-    TODO
+    For common use cases, Qt Data Visualization offers specialized proxies. One such case is having
+    data in an item model (QAbstractItemModel subclass), which is a common way to store data in
+    Qt applications. Each of the visualization types offers a special proxy and a corresponding mapping
+    class for this purpose, e.g. QItemModelBarDataProxy and QItemModelBarDataMapping for Q3DBars.
+    These proxies are simple to use - just give them a pointer to the item model containing the
+    data and the mapping object containing rules how to map the data into format the basic proxy can
+    digest.
+
+    Mapping objects work with item model roles. Each data item in the model can have different
+    values for different roles. For example, with QItemModelBarDataMapping you can specify which
+    role is used to determine which row the item belongs to, which role does the same for columns,
+    and which role specifies the value of the item. When the proxy resolves the data from the model,
+    it uses these mappings to generate the rows and columns of the bar graph.
+
+    Depending on the visualization type, mapping classes may support other functionality as well,
+    such as QItemModelBarDataMapping optionally mapping QAbstractItemModel rows and columns directly
+    into bar graph rows and columns. See individual mapping classes for more information and examples
+    how to use them: QItemModelBarDataMapping, QItemModelScatterDataMapping, and
+    QItemModelSurfaceDataMapping.
+
+    \section1 Other custom proxies
+
+    QHeightMapSurfaceDataProxy is a specialized proxy for generating a surface graph from a
+    heightmap image. See QHeightMapSurfaceDataProxy documentation for more information.
+
+    The \l{Rainfall Example}{Rainfall} example shows how a custom proxy can be created. It defines
+    a custom data set based on variant lists and an extension of the basic proxy to resolve that
+    data with an associated mapper.
+
+    \section1 Dealing with real-time data
+
+    When you have a data set that updates rapidly, it is important to handle data properly to
+    ensure good performance. Since memory allocation is a costly operation, always use
+    QList::reserve() and QVector::resize() where possible to avoid reallocations when constructing
+    the array to give to the proxy. If you need to change the entire data set for each frame,
+    it is in most cases best to re-use the existing array - especially if the array dimensions do not
+    change. If you need to add, insert, remove, or change several rows or items for each frame, it
+    is always more efficient to do it with one method call instead of multiple calls affecting
+    a single row or item each. For example, adding ten rows with a single QBarDataProxy::addRows() call
+    is much more efficient than ten separate QBarDataProxy::addRow() calls.
+
+    Bars renderer is optimized to access only data that is within data window and thus should not
+    suffer noticeable slowdown even if more data is continually added to the proxy.
+
+    Due to the unsorted nature of the scatter data, any change in the data window ranges requires
+    all data points to be checked for visibility, which can cause increasing slowdown if data is
+    continually added to the proxy.
+
+    Surface data, while on item level similar to scatter data, is already assigned into rows and
+    columns, so the surface renderer can do some optimization by making assumption that the data in
+    rows and columns is sorted along their respective axes, but it is nowhere near as efficient
+    as in bars case. Surface rendering can suffer significant slowdown if the data size grows unchecked.
+
+    For the best performance with the scatter and surface graphs, only keep the data you need in the
+    proxy.
+
+    \note Data handling is not yet fully optimized in the technology preview version.
 */
 
 /*!