Documentation for QML Surface

Task-number: QTRD-2397

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

4 files changed, 80 insertions, 4 deletions

diff --git a/examples/qmlsurface/doc/src/qmlsurface.qdoc b/examples/qmlsurface/doc/src/qmlsurface.qdoc
index dba40327..acbb2a85 100644
--- a/examples/qmlsurface/doc/src/qmlsurface.qdoc
+++ b/examples/qmlsurface/doc/src/qmlsurface.qdoc
@@ -22,10 +22,67 @@
     \ingroup qtdatavisualization_examples
     \brief Using Surface3D in a QML application.
 
-    The Qt Quick 2 surface example shows how to make a simple 3D surface plot using Q3DSurface with
+    The Qt Quick 2 surface example shows how to make a simple 3D surface plot using Surface3D with
     Qt Quick 2.
 
     \image qmlsurface-example.png
 
-    TODO
+    The focus in this example is on generating a surface graph from height data, so in this section
+    we skip explaining application creation. For more detailed QML example documentation,
+    see \l{Qt Quick 2 Scatter Example}.
+
+    \section1 Adding data to the graph
+
+    This example shows two method to set data to surface graph, using the HeightMapSurfaceDataProxy
+    and ItemModelSurfaceDataProxy. First we go through setting the data using height map specific
+    data proxy. It is done with the code snippet below. The \c heightMapFile property specifies the image
+    file containing the height data. The value properties defines the minimum and maximum values for
+    surface area width and depth. This example shows the terrain around Tycho crater at imaginary
+    position from 67 to 97 and from 30 to 60. Note that on the graph the scale on the Y dimension
+    exaggerates the height.
+
+    \snippet ../examples/qmlsurface/qml/qmlsurface/data.qml 0
+
+    The other method to set surface data used in this example is with model mapping. We do that by first
+    defining a ListModel containing the data for the surface:
+
+    \snippet ../examples/qmlsurface/qml/qmlsurface/data.qml 1
+    \dots 4
+
+    Then we set up a SurfaceDataMapping which maps the roles for columns, rows and values. In this
+    example the row holds values for longitude, column for latitude and the value is for height.
+
+    \snippet ../examples/qmlsurface/qml/qmlsurface/data.qml 2
+
+    The ItemModelSurfaceDataProxy is created to tie the model and the mapping together.
+
+    \snippet ../examples/qmlsurface/qml/qmlsurface/data.qml 3
+
+    \section1 Showing data
+
+    In the \c main.qml, we set up the Surface3D element to show the data and various UI elements
+    to illustrate few interesting features. First is the surface gradient, which can be defined
+    as seen in this code snippet. With the \c ColorGradient we set example colors from position 0.0 to
+    1.0. This element is set for \c gradient property in Surface3D.
+
+    \snippet ../examples/qmlsurface/qml/qmlsurface/main.qml 0
+
+    Other interesting features can be controlled with buttons. The first button is to toggle on and off
+    the surface grid, for which use the following code.
+
+    \snippet ../examples/qmlsurface/qml/qmlsurface/main.qml 1
+
+    Second button is for surface smooth status, which is controlled with this code.
+
+    \snippet ../examples/qmlsurface/qml/qmlsurface/main.qml 2
+
+    Third and fourth buttons are for controlling background features. The last button is for switching
+    between HeightMapSurfaceDataProxy and ItemModelSurfaceDataProxy, for which use the following
+    code. We also set the maximum value to 500 in model proxy to make the surface flatter and
+    250 on height map proxy to show exaggerated height. At the same time the color position
+    on the gradient is modified.
+
+    \snippet ../examples/qmlsurface/qml/qmlsurface/main.qml 3
+
+    \section1 Example contents
 */
diff --git a/examples/qmlsurface/main.cpp b/examples/qmlsurface/main.cpp
index 6b859158..ac9dda35 100644
--- a/examples/qmlsurface/main.cpp
+++ b/examples/qmlsurface/main.cpp
@@ -18,24 +18,27 @@
 
 #include <QtGui/QGuiApplication>
 #include "qtquick2applicationviewer.h"
+
 #ifdef Q_OS_ANDROID
 #include <QDir>
 #include <QQmlEngine>
 #endif
-#include <QDebug>
 
 int main(int argc, char *argv[])
 {
     QGuiApplication app(argc, argv);
 
     QtQuick2ApplicationViewer viewer;
+
 #ifdef Q_OS_ANDROID
     viewer.addImportPath(QString::fromLatin1("assets:/qml"));
     viewer.engine()->addPluginPath(QString::fromLatin1("%1/../%2").arg(QDir::homePath(),
                                                                        QString::fromLatin1("lib")));
 #endif
-    viewer.setTitle(QStringLiteral("Tycho crater on the Moon (height exaggerated)"));
+
     viewer.setSource(QUrl("qrc:/qml/main.qml"));
+
+    viewer.setTitle(QStringLiteral("Tycho crater on the Moon (height exaggerated)"));
     viewer.setResizeMode(QQuickView::SizeRootObjectToView);
     viewer.show();
 
diff --git a/examples/qmlsurface/qml/qmlsurface/data.qml b/examples/qmlsurface/qml/qmlsurface/data.qml
index 4adfd64f..80ed471a 100644
--- a/examples/qmlsurface/qml/qmlsurface/data.qml
+++ b/examples/qmlsurface/qml/qmlsurface/data.qml
@@ -25,6 +25,7 @@ Item {
     property alias proxy: modelProxy
     property alias heightProxy: heightMapProxy
 
+    //! [0]
     HeightMapSurfaceDataProxy {
         id: heightMapProxy
         heightMapFile: ":/heightmaps/image"
@@ -34,25 +35,32 @@ Item {
         minXValue: 67
         maxXValue: 97
     }
+    //! [0]
 
+    //! [2]
     SurfaceDataMapping {
         id: surfaceMapping
         rowRole: "longitude"
         columnRole: "latitude"
         valueRole: "height"
     }
+    //! [2]
 
+    //! [3]
     ItemModelSurfaceDataProxy {
         id: modelProxy
         activeMapping: surfaceMapping
         itemModel: dataModel
     }
+    //! [3]
 
+    //! [1]
     ListModel {
         id: dataModel
         ListElement{ longitude: "0"; latitude: "0"; height: "124"; }
         ListElement{ longitude: "0"; latitude: "1"; height: "125"; }
         ListElement{ longitude: "0"; latitude: "2"; height: "124"; }
+        //! [1]
         ListElement{ longitude: "0"; latitude: "3"; height: "118"; }
         ListElement{ longitude: "0"; latitude: "4"; height: "112"; }
         ListElement{ longitude: "0"; latitude: "5"; height: "111"; }
diff --git a/examples/qmlsurface/qml/qmlsurface/main.qml b/examples/qmlsurface/qml/qmlsurface/main.qml
index 3f69ce95..160fa9b6 100644
--- a/examples/qmlsurface/qml/qmlsurface/main.qml
+++ b/examples/qmlsurface/qml/qmlsurface/main.qml
@@ -36,12 +36,14 @@ Item {
         height: mainview.height
         anchors.right: mainview.right;
 
+        //! [0]
         ColorGradient {
             id: surfaceGradient
             ColorGradientStop { position: 0.0; color: "darkslategray" }
             ColorGradientStop { id: middleGradient; position: 0.55; color: "peru" }
             ColorGradientStop { position: 1.0; color: "red" }
         }
+        //! [0]
 
         Surface3D {
             id: surfaceplot
@@ -77,6 +79,7 @@ Item {
         anchors.left: parent.left
         width: 200
         text: "Show Surface Grid"
+        //! [1]
         onClicked: {
             if (surfaceplot.surfaceGridEnabled == false) {
                 surfaceplot.surfaceGridEnabled = true;
@@ -86,6 +89,7 @@ Item {
                 text = "Show Surface Grid"
             }
         }
+        //! [1]
     }
 
     NewButton {
@@ -93,6 +97,7 @@ Item {
         anchors.top: surfaceGridToggle.bottom
         width: surfaceGridToggle.width
         text: "Show Flat"
+        //! [2]
         onClicked: {
             if (surfaceplot.smoothSurfaceEnabled == true) {
                 surfaceplot.smoothSurfaceEnabled = false;
@@ -102,6 +107,7 @@ Item {
                 text = "Show Flat"
             }
         }
+        //! [2]
     }
 
     NewButton {
@@ -141,6 +147,7 @@ Item {
         anchors.top: gridToggle.bottom
         width: gridToggle.width
         text: "Switch to Item Model Proxy"
+        //! [3]
         onClicked: {
             if (surfaceplot.dataProxy === surfaceData.heightProxy) {
                 surfaceplot.axisY.max = 500.0
@@ -154,5 +161,6 @@ Item {
                 text = "Switch to Item Model Proxy"
             }
         }
+        //! [3]
     }
 }