Documentation for Q3DSurface and QSurfaceDataProxy

Task-number: QTRD-2284

Change-Id: I1488e420656eab9e622f82860c896b55f87d7596
Reviewed-by: Tomi Korpipää <tomi.korpipaa@digia.com>
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@digia.com>

7 files changed, 201 insertions, 59 deletions

diff --git a/src/datavisualization/data/qsurfacedataproxy.cpp b/src/datavisualization/data/qsurfacedataproxy.cpp
index 1c753242..b3f50659 100644
--- a/src/datavisualization/data/qsurfacedataproxy.cpp
+++ b/src/datavisualization/data/qsurfacedataproxy.cpp
@@ -31,9 +31,33 @@ const qreal defaultMaxValue = 10.0;
  * \brief Proxy class for Q3DSurface.
  * \since 1.0.0
  *
- * QSurfaceDataProxy takes care of surface related data handling.
+ * QSurfaceDataProxy takes care of surface related data handling. The QSurfaceDataProxy handles the data
+ * in rows and for this it provides two auxiliary typedefs. QSurfaceDataArray is a QList for
+ * controlling the rows. For rows there is a QVector typedef QSurfaceDataRow which takes in qreal
+ * values. See Q3DSurface documentation and basic sample code there how to feed the data for the
+ * QSurfaceDataProxy.
+ *
+ * All rows must have same number of values.
+ *
+ * QSurfaceDataProxy supports the following format tags for QAbstractDataProxy::setItemLabelFormat():
+ * \table
+ *   \row
+ *     \li @xTitle    \li Title from X axis
+ *   \row
+ *     \li @yTitle    \li Title from Y axis
+ *   \row
+ *     \li @zTitle    \li Title from Z axis
+ *   \row
+ *     \li @xLabel    \li Item value formatted using the same format as the X axis attached to the graph uses,
+ *                            see \l{Q3DValueAxis::setLabelFormat()} for more information.
+ *   \row
+ *     \li @yLabel    \li Item value formatted using the same format as the Y axis attached to the graph uses,
+ *                            see \l{Q3DValueAxis::setLabelFormat()} for more information.
+ *   \row
+ *     \li @zLabel    \li Item value formatted using the same format as the Z axis attached to the graph uses,
+ *                            see \l{Q3DValueAxis::setLabelFormat()} for more information.
+ * \endtable
  *
- * Make sure that amount of items on QSurfaceDataRow is the same for all rows.
  */
 
 /*!
@@ -45,8 +69,41 @@ const qreal defaultMaxValue = 10.0;
  */
 
 /*!
- * \qmlproperty int SurfaceDataProxy::itemCount
- * Item count in the array.
+ * \qmlproperty int SurfaceDataProxy::rowCount
+ * Number of the rows in the array.
+ */
+
+/*!
+ * \qmlproperty int SurfaceDataProxy::columnCount
+ * Number of the columns in the array.
+ */
+
+/*!
+ * \qmlproperty qreal QSurfaceDataProxy::minValueRows
+ *
+ * The minimum value of the range in rows. For instance if function z value varies between -8.0
+ * and 8.0 set this property to -8.0.
+ */
+
+/*!
+ * \qmlproperty qreal QSurfaceDataProxy::maxValueRows
+ *
+ * The maximum value of the range in rows. For instance if function z value varies between -8.0
+ * and 8.0 set this property to 8.0.
+ */
+
+/*!
+ * \qmlproperty qreal QSurfaceDataProxy::minValueColumns
+ *
+ * The minimum value of the range in columns. For instance if function x value varies between -8.0
+ * and 8.0 set this property to -8.0.
+ */
+
+/*!
+ * \qmlproperty qreal QSurfaceDataProxy::maxValueColumns
+ *
+ * The maximum value of the range in columns. For instance if function x value varies between -8.0
+ * and 8.0 set this property to 8.0.
  */
 
 /*!
@@ -163,7 +220,8 @@ const QSurfaceDataProxyPrivate *QSurfaceDataProxy::dptrc() const
  */
 
 /*!
- * Sets the value range for rows from \a min to \a max.
+ * Sets the value range for rows from \a min to \a max. For instance if function z value varies between -8.0
+ * and 8.0 set \a min to -8.0 and \a max to 8.0.
  * When setting the range, the max is adjusted if necessary, to ensure that the range remains valid.
  */
 void QSurfaceDataProxy::setValueRangeRows(qreal min, qreal max)
@@ -172,7 +230,8 @@ void QSurfaceDataProxy::setValueRangeRows(qreal min, qreal max)
 }
 
 /*!
- * Sets the value range for columns from \a min to \a max.
+ * Sets the value range for columns from \a min to \a max. For instance if function x value varies between -8.0
+ * and 8.0 set \a min to -8.0 and \a max to 8.0.
  * When setting the range, the max is adjusted if necessary, to ensure that the range remains valid.
  */
 void QSurfaceDataProxy::setValueRangeColumns(qreal min, qreal max)
@@ -183,7 +242,8 @@ void QSurfaceDataProxy::setValueRangeColumns(qreal min, qreal max)
 /*!
  * \property QSurfaceDataProxy::minValueRows
  *
- * Defines the minimum value of the range for rows.
+ * Defines the minimum value of the range for rows. For instance if function z value varies between -8.0
+ * and 8.0 set this property to -8.0.
  * When setting this property the max is adjusted if necessary, to ensure that the range remains
  * valid.
  */
@@ -200,7 +260,8 @@ qreal QSurfaceDataProxy::minValueRows() const
 /*!
  * \property QSurfaceDataProxy::maxValueRows
  *
- * Defines the maximum value of the range for rows.
+ * Defines the maximum value of the range for rows. For instance if function z value varies between -8.0
+ * and 8.0 set this property to 8.0.
  * When setting this property the min is adjusted if necessary, to ensure that the range remains
  * valid.
  */
@@ -217,7 +278,8 @@ qreal QSurfaceDataProxy::maxValueRows() const
 /*!
  * \property QSurfaceDataProxy::minValueColumns
  *
- * Defines the minimum value of the range for columns.
+ * Defines the minimum value of the range for columns. For instance if function x value varies between -8.0
+ * and 8.0 set this property to -8.0.
  * When setting this property the min is adjusted if necessary, to ensure that the range remains
  * valid.
  */
@@ -234,7 +296,8 @@ qreal QSurfaceDataProxy::minValueColumns() const
 /*!
  * \property QSurfaceDataProxy::maxValueColumns
  *
- * Defines the maximum value of the range for columns.
+ * Defines the maximum value of the range for columns. For instance if function x value varies between -8.0
+ * and 8.0 set this property to 8.0.
  * When setting this property the min is adjusted if necessary, to ensure that the range remains
  * valid.
  */
diff --git a/src/datavisualization/doc/images/q3dsurface-minimal.png b/src/datavisualization/doc/images/q3dsurface-minimal.png
new file mode 100644
index 00000000..119cdfb9
--- /dev/null
+++ b/src/datavisualization/doc/images/q3dsurface-minimal.png
diff --git a/src/datavisualization/doc/snippets/doc_src_q3dsurface_construction.cpp b/src/datavisualization/doc/snippets/doc_src_q3dsurface_construction.cpp
new file mode 100644
index 00000000..33b6cf37
--- /dev/null
+++ b/src/datavisualization/doc/snippets/doc_src_q3dsurface_construction.cpp
@@ -0,0 +1,50 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+//! [5]
+#include <QtDataVisualization>
+
+using namespace QtDataVisualization;
+
+int main(int argc, char **argv)
+{
+    QGuiApplication app(argc, argv);
+
+    //! [0]
+    Q3DSurface surface;
+    //! [0]
+    //! [1]
+    QSurfaceDataArray *data = new QSurfaceDataArray;
+    QSurfaceDataRow *dataRow = new QSurfaceDataRow;
+    //! [1]
+
+    //! [2]
+    *dataRow << 0.1 << 1.8 << 0.4;
+    *data << dataRow;
+    //! [2]
+
+    //! [3]
+    surface.activeDataProxy()->resetArray(data);
+    //! [3]
+    //! [4]
+    surface.show();
+    //! [4]
+
+    return app.exec();
+}
+//! [5]
diff --git a/src/datavisualization/engine/q3dbars.cpp b/src/datavisualization/engine/q3dbars.cpp
index e892367e..d2f8e396 100644
--- a/src/datavisualization/engine/q3dbars.cpp
+++ b/src/datavisualization/engine/q3dbars.cpp
@@ -41,6 +41,14 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * reset to default camera view by clicking mouse wheel. In touch devices rotation is done
  * by tap-and-move, selection by tap-and-hold and zoom by pinch.
  *
+ * If no axes are explicitly set to Q3DBars, temporary default axes with no labels are created.
+ * These default axes can be modified via axis accessors, but as soon any axis is explicitly
+ * set for the orientation, the default axis for that orientation is destroyed.
+ *
+ * Data proxies work similarly: If no data proxy is explicitly set, Q3DBars creates a default
+ * proxy. If any other proxy is set as active data proxy later, the default proxy and all data
+ * added to it is destroyed.
+ *
  * Methods are provided for changing bar types, themes, bar selection modes and so on. See the
  * methods for more detailed descriptions.
  *
@@ -77,14 +85,6 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * familiarizing yourself with the examples provided, like the \l{Rainfall Example} or
  * the \l{Widget Example}.
  *
- * If no axes are explicitly set to Q3DBars, temporary default axes with no labels are created.
- * These default axes can be modified via axis accessors, but as soon any axis is explicitly
- * set for the orientation, the default axis for that orientation is destroyed.
- *
- * Data proxies work similarly: If no data proxy is explicitly set, Q3DBars creates a default
- * proxy. If any other proxy is set as active data proxy later, the default proxy and all data
- * added to it is destroyed.
- *
  * \sa Q3DScatter, Q3DSurface, {Qt Data Visualization C++ Classes}
  */
 
diff --git a/src/datavisualization/engine/q3dscatter.cpp b/src/datavisualization/engine/q3dscatter.cpp
index bac9a38d..a3503ef1 100644
--- a/src/datavisualization/engine/q3dscatter.cpp
+++ b/src/datavisualization/engine/q3dscatter.cpp
@@ -40,6 +40,14 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * reset to default camera view by clicking mouse wheel. In touch devices rotation is done
  * by tap-and-move, selection by tap-and-hold and zoom by pinch.
  *
+ * If no axes are explicitly set to Q3DScatter, temporary default axes with no labels are created.
+ * These default axes can be modified via axis accessors, but as soon any axis is explicitly
+ * set for the orientation, the default axis for that orientation is destroyed.
+ *
+ * Data proxies work similarly: If no data proxy is explicitly set, Q3DScatter creates a default
+ * proxy. If any other proxy is set as active data proxy later, the default proxy and all data
+ * added to it is destroyed.
+ *
  * Methods are provided for changing item styles, themes, item selection modes and so on. See the
  * methods for more detailed descriptions.
  *
@@ -69,14 +77,6 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * code example. You can learn more by familiarizing yourself with the examples provided, like
  * the \l{Scatter Chart Example}.
  *
- * If no axes are explicitly set to Q3DScatter, temporary default axes with no labels are created.
- * These default axes can be modified via axis accessors, but as soon any axis is explicitly
- * set for the orientation, the default axis for that orientation is destroyed.
- *
- * Data proxies work similarly: If no data proxy is explicitly set, Q3DScatter creates a default
- * proxy. If any other proxy is set as active data proxy later, the default proxy and all data
- * added to it is destroyed.
- *
  * \sa Q3DBars, Q3DSurface, {Qt Data Visualization C++ Classes}
  */
 
diff --git a/src/datavisualization/engine/q3dsurface.cpp b/src/datavisualization/engine/q3dsurface.cpp
index f61b35d4..fe4d4b61 100644
--- a/src/datavisualization/engine/q3dsurface.cpp
+++ b/src/datavisualization/engine/q3dsurface.cpp
@@ -31,7 +31,63 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * \brief The Q3DSurface class provides methods for rendering 3D surface plots.
  * \since 1.0.0
  *
- * DOCUMENTATION GOES HERE
+ * This class enables developers to render 3D surface plots and to view them by rotating the scene
+ * freely. The class provides configurable gradient texture to illustrate the height on the data. The
+ * surface plotting includes also gridline that can be set on or off. The visual appearance of the
+ * surface can be changed by controlling the smooth status.
+ *
+ * The Q3DSurface supports selection by showing a highlighted ball on the data point where the user has clicked
+ * with left mouse button (when default input handler is in use). The selection pointer is accompanied with
+ * a label which in default case shows the value of the data point and the coordinates of the point.
+ *
+ * The value range and the label format shown on the axis can be controlled through Q3DValueAxis.
+ * The Q3DSurface supports only a grid with fixed steps, so when setting ranges set a value that matches
+ * the grid step. To calculate the steps divide the whole data range with the number of segments.
+ *
+ * To rotate the graph, hold down the right mouse button and move the mouse. Zooming is done using mouse
+ * wheel. Both assume the default input handler is in use.
+ *
+ * If no axes are explicitly set to Q3DSurface, temporary default axes with no labels are created.
+ * These default axes can be modified via axis accessors, but as soon any axis is explicitly
+ * set for the orientation, the default axis for that orientation is destroyed.
+ *
+ * Data proxies work similarly: If no data proxy is explicitly set, Q3DSurface creates a default
+ * proxy. If any other proxy is set as active data proxy later, the default proxy and all data
+ * added to it is destroyed.
+ *
+ * \section1 How to construct a minimal Q3DSurface chart
+ *
+ * First, construct Q3DSurface:
+ *
+ * \snippet doc_src_q3dsurface_construction.cpp 0
+ *
+ * Now Q3DSurface is ready to receive data to be rendered. Create data elements to receive values:
+ *
+ * \snippet doc_src_q3dsurface_construction.cpp 1
+ *
+ * First feed the data to the row element and then add it's pointer to the data element:
+ *
+ * \snippet doc_src_q3dsurface_construction.cpp 2
+ *
+ * For the active data proxy set pointer of the data element:
+ *
+ * \snippet doc_src_q3dsurface_construction.cpp 3
+ *
+ * Finally you will need to set it visible:
+ *
+ * \snippet doc_src_q3dsurface_construction.cpp 4
+ *
+ * The complete code needed to create and display this chart is:
+ *
+ * \snippet doc_src_q3dsurface_construction.cpp 5
+ *
+ * And this is what those few lines of code produce:
+ *
+ * \image q3dsurface-minimal.png
+ *
+ * The scene can be rotated and zoomed into, but no other interaction is included in this minimal
+ * code example.
+ *
  *
  * \sa Q3DBars, Q3DScatter, {Qt Data Visualization C++ Classes}
  */
@@ -91,11 +147,6 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  */
 
 /*!
- * \qmlproperty Surface3D.SelectionMode Surface3D::selectionMode
- * Bar selection mode.
- */
-
-/*!
  * \qmlproperty Surface3D.LabelTransparency Surface3D::labelTransparency
  * Label transparency.
  */
@@ -112,7 +163,7 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
 
 /*!
  * \qmlproperty Surface3D.ColorTheme Surface3D::theme
- * Theme of the graph. Theme affects bar colors, label colors, text color, background color, window
+ * Theme of the graph. Theme affects label colors, text color, background color, window
  * color and grid color. Lighting is also adjusted by themes.
  */
 
@@ -268,8 +319,6 @@ bool Q3DSurface::isBackgroundVisible() const
  * default. Theme affects label colors, text color, background color, window color and
  * grid color. Lighting is also adjusted by themes.
  *
- * \sa setObjectColor()
- *
  * \warning This method is subject to change.
  */
 void Q3DSurface::setTheme(QDataVis::ColorTheme theme)
@@ -301,6 +350,9 @@ QDataVis::ShadowQuality Q3DSurface::shadowQuality() const
  * \property Q3DSurface::smoothSurfaceEnabled
  *
  * Sets surface smoothing to \a enabled. It is preset to \c false by default.
+ * When enabled the normals on the surface are interpolated making edges looking round. If turned
+ * off the normals are kept same on a triangle making the color of the triangle solid. This makes
+ * the data more readable from the model.
  */
 void Q3DSurface::setSmoothSurfaceEnabled(bool enabled)
 {
@@ -359,24 +411,6 @@ QDataVis::LabelTransparency Q3DSurface::labelTransparency() const
 }
 
 /*!
- * Sets window \a width.
- */
-void Q3DSurface::setWidth(const int width)
-{
-    d_ptr->m_shared->setWidth(width);
-    QWindow::setWidth(width);
-}
-
-/*!
- * Sets window \a height.
- */
-void Q3DSurface::setHeight(const int height)
-{
-    d_ptr->m_shared->setHeight(height);
-    QWindow::setHeight(height);
-}
-
-/*!
  * Sets a user-defined X-axis. Implicitly calls addAxis() to transfer ownership
  * of the \a axis to this graph.
  *
@@ -549,7 +583,7 @@ QList<QSurfaceDataProxy *> Q3DSurface::dataProxies() const
 
 
 /*!
- * Sets gradient color to \a color at \a pos.
+ * Modifies the current surface gradient. Sets gradient color to \a color at \a pos.
  */
 void Q3DSurface::setGradientColorAt(qreal pos, const QColor &color)
 {
diff --git a/src/datavisualization/engine/q3dsurface.h b/src/datavisualization/engine/q3dsurface.h
index cfcc1deb..82eee7ae 100644
--- a/src/datavisualization/engine/q3dsurface.h
+++ b/src/datavisualization/engine/q3dsurface.h
@@ -91,11 +91,6 @@ public:
     void setLabelTransparency(QDataVis::LabelTransparency transparency);
     QDataVis::LabelTransparency labelTransparency() const;
 
-    // TODO: Do these need to be public? Where are they called from?
-    // Size
-    void setWidth(const int width);
-    void setHeight(const int height);
-
 protected:
     void render();