Documentation for surface example

Task-number: QTRD-2347

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

5 files changed, 136 insertions, 38 deletions

diff --git a/examples/surface/doc/images/surface-example.png b/examples/surface/doc/images/surface-example.png
new file mode 100644
index 00000000..ea64f47c
--- /dev/null
+++ b/examples/surface/doc/images/surface-example.png
diff --git a/examples/surface/doc/src/surface.qdoc b/examples/surface/doc/src/surface.qdoc
index 7810c543..4a0ce794 100644
--- a/examples/surface/doc/src/surface.qdoc
+++ b/examples/surface/doc/src/surface.qdoc
@@ -23,9 +23,88 @@
     \brief Using Q3DSurface in a widget application.
 
     The surface example shows how to make a simple 3D surface graph using Q3DSurface and
-    combining the use of widgets for adjusting several adjustable qualities.
+    combining the use of widgets for adjusting several adjustable qualities. This example
+    demonstrates the following features:
 
+    \list
+        \li How to set up a basic QSurfaceDataProxy and set data for it.
+        \li How to use QHeightMapSurfaceDataProxy for showing 3D height maps.
+        \li Three different selection modes for studying the graph.
+        \li Axis range usage for selecting slices from the graph.
+        \li Theme usage on the surface graph.
+        \li How to set a custom surface gradient.
+    \endlist
     \image surface-example.png
 
-    TODO
+    \section1 Setting up proxies and setting the data
+
+    First we instantiate a new QSurfaceDataProxy:
+
+    \snippet ../examples/surface/surfacegraph.cpp 0
+
+    Then we fill it with a simple square root and sin wave data. This is done by
+    creating a new QSurfaceDataArray instance and adding QSurfaceDataRow elements.
+    The created QSurfaceDataArray is set to be a the data array for the QSurfaceDataProxy.
+
+    \snippet ../examples/surface/surfacegraph.cpp 1
+
+    The height map is created by instantiating a QHeightMapSurfaceDataProxy with
+    a QImage containing the height data. The method setValueRanges is used to define
+    the value range of the map. In our example the map is from imaginary position of
+    34.0\unicode 0x00B0 N - 40.0\unicode 0x00B0 N and 18.0\unicode 0x00B0 E - 24.0\unicode 0x00B0 E.
+    These values are used to show and position the map to the axis.
+
+    \snippet ../examples/surface/surfacegraph.cpp 2
+
+    For demonstrating different proxies this example has two radio buttons which
+    the user can use to switch between active proxies. When the user selects the
+    Sqrt&Sin radio button the selected proxy is activated with the following
+    code. First we set the decorative issues like enable the grid for the surface and
+    select the flat surface mode. Next lines define the axis label format and value
+    ranges. Since the algorithm studies the value variation between -8.0 and 8.0 we
+    set these values for X and Z coordinates. The value itself varies between 0.0 and
+    2.0. The method setActiveDataProxy sets the basic data proxy to be active.
+
+    \snippet ../examples/surface/surfacegraph.cpp 3
+
+    When the Height Map radio button is activated, the following code sets the proxy on.
+    First the surface grid is turned off and the smooth mode is activated. The axis label
+    format is set to show N and E letters and ranges are set to the imaginary coordinates.
+    Finally the height map proxy is set to be active.
+
+    \snippet ../examples/surface/surfacegraph.cpp 4
+
+    \section1 Selection modes
+
+    Q3Dsurface supports three different selection modes and these are demonstrated on the
+    example with radio buttons which the user can use to activate suitable selection mode.
+    Following inline methods are connected to radio buttons to activate the selected mode.
+
+    \snippet ../examples/surface/surfacegraph.h 0
+
+    \section1 Axis ranges for studying the graph
+
+    The example has four slider controls for adjusting the min and max values for X and Z
+    axis. When selecting the proxy these sliders are adjusted so that one step on the slider
+    moves the range by one segment step. The example has some code to keep the sliders on
+    valid positions, like when the X axis minimum exceeds the maximum the maximum is increased
+    and so on. Finally the ranges are set for the graph like this:
+
+    \snippet ../examples/surface/surfacegraph.cpp 5
+
+    \section1 Themes
+
+    Q3Dsurface supports all the themes QtDatavisualization has. The example has a pull
+    down menu for selecting the theme and the following code snippet is connected to the menu to
+    activate the selected theme.
+
+    \snippet ../examples/surface/surfacegraph.cpp 6
+
+    \section1 Custom surface gradients
+
+    The example demonstrates the custom surface gradients with two push buttons. The gradient
+    can be defined with QLinearGradient where the desired colors are set to positions. Following
+    snippet shows how to create an example gradient and set it to the graph.
+
+    \snippet ../examples/surface/surfacegraph.cpp 7
 */
diff --git a/examples/surface/main.cpp b/examples/surface/main.cpp
index 2583b21a..cd26eb8d 100644
--- a/examples/surface/main.cpp
+++ b/examples/surface/main.cpp
@@ -56,7 +56,7 @@ int main(int argc, char **argv)
     QGroupBox *modelGroupBox = new QGroupBox(QStringLiteral("Model"));
 
     QRadioButton *sqrtSinModelRB = new QRadioButton(widget);
-    sqrtSinModelRB->setText(QStringLiteral("Sqrt Sin"));
+    sqrtSinModelRB->setText(QStringLiteral("Sqrt&Sin"));
     sqrtSinModelRB->setChecked(false);
 
     QRadioButton *heightMapModelRB = new QRadioButton(widget);
diff --git a/examples/surface/surfacegraph.cpp b/examples/surface/surfacegraph.cpp
index 251f4643..cb405eb8 100644
--- a/examples/surface/surfacegraph.cpp
+++ b/examples/surface/surfacegraph.cpp
@@ -37,14 +37,18 @@ SurfaceGraph::SurfaceGraph(Q3DSurface *surface)
     m_graph->setAxisZ(new Q3DValueAxis);
     m_graph->setLabelStyle(QDataVis::LabelStyleFromTheme);
 
+    //! [0]
+    sqrtSinProxy = new QSurfaceDataProxy();
+    //! [0]
+    fillSqrtSinProxy();
+
+    //! [2]
     QImage heightMapImage(":/maps/map");
     m_heightMapProxy = new QHeightMapSurfaceDataProxy(heightMapImage);
     m_heightMapProxy->setValueRanges(34.0, 40.0, 18.0, 24.0);
+    //! [2]
     m_heightMapWidth = heightMapImage.width();
     m_heightMapHeight = heightMapImage.height();
-
-    sqrtSinProxy = new QSurfaceDataProxy();
-    fillSqrtSinProxy();
 }
 
 SurfaceGraph::~SurfaceGraph()
@@ -52,6 +56,7 @@ SurfaceGraph::~SurfaceGraph()
     delete m_graph;
 }
 
+//! [1]
 void SurfaceGraph::fillSqrtSinProxy()
 {
     qreal stepX = 16.0 / qreal(sampleCountX);
@@ -72,9 +77,41 @@ void SurfaceGraph::fillSqrtSinProxy()
 
     sqrtSinProxy->resetArray(dataArray);
 }
+//! [1]
+
+void SurfaceGraph::enableSqrtSinModel()
+{
+    //! [3]
+    m_graph->setSurfaceGridEnabled(true);
+    m_graph->setSmoothSurfaceEnabled(false);
+
+    m_graph->axisX()->setLabelFormat("%.2f");
+    m_graph->axisZ()->setLabelFormat("%.2f");
+    m_graph->axisX()->setRange(-8.0, 8.0);
+    m_graph->axisY()->setRange(0.0, 2.0);
+    m_graph->axisZ()->setRange(-8.0, 8.0);
+
+    m_graph->setActiveDataProxy(sqrtSinProxy);
+    //! [3]
+
+    // Reset range sliders for Sqrt&Sin
+    m_rangeMinX = -8.0;
+    m_rangeMinZ = -8.0;
+    m_stepX = 16.0 / qreal(sampleCountX - 1);
+    m_stepZ = 16.0 / qreal(sampleCountZ - 1);
+    m_axisMinSliderX->setMaximum(sampleCountX - 3);
+    m_axisMinSliderX->setValue(0);
+    m_axisMaxSliderX->setMaximum(sampleCountX - 1);
+    m_axisMaxSliderX->setValue(sampleCountX - 1);
+    m_axisMinSliderZ->setMaximum(sampleCountZ - 3);
+    m_axisMinSliderZ->setValue(0);
+    m_axisMaxSliderZ->setMaximum(sampleCountZ - 1);
+    m_axisMaxSliderZ->setValue(sampleCountZ - 1);
+}
 
 void SurfaceGraph::enableHeightMapModel()
 {
+    //! [4]
     m_graph->setSurfaceGridEnabled(false);
     m_graph->setSmoothSurfaceEnabled(true);
 
@@ -85,6 +122,7 @@ void SurfaceGraph::enableHeightMapModel()
     m_graph->axisZ()->setRange(18.0, 24.0);
 
     m_graph->setActiveDataProxy(m_heightMapProxy);
+    //! [4]
 
     // Reset range sliders for height map
     int mapGridCountX = m_heightMapWidth / heightMapGridStepX;
@@ -103,34 +141,6 @@ void SurfaceGraph::enableHeightMapModel()
     m_axisMaxSliderZ->setValue(mapGridCountZ - 1);
 }
 
-void SurfaceGraph::enableSqrtSinModel()
-{
-    m_graph->setSurfaceGridEnabled(true);
-    m_graph->setSmoothSurfaceEnabled(false);
-
-    m_graph->axisX()->setLabelFormat("%.2f");
-    m_graph->axisZ()->setLabelFormat("%.2f");
-    m_graph->axisX()->setRange(-8.0, 8.0);
-    m_graph->axisY()->setRange(0.0, 2.0);
-    m_graph->axisZ()->setRange(-8.0, 8.0);
-
-    m_graph->setActiveDataProxy(sqrtSinProxy);
-
-    // Reset range sliders for Sqrt&Sin
-    m_rangeMinX = -8.0;
-    m_rangeMinZ = -8.0;
-    m_stepX = 16.0 / qreal(sampleCountX - 1);
-    m_stepZ = 16.0 / qreal(sampleCountZ - 1);
-    m_axisMinSliderX->setMaximum(sampleCountX - 3);
-    m_axisMinSliderX->setValue(0);
-    m_axisMaxSliderX->setMaximum(sampleCountX - 1);
-    m_axisMaxSliderX->setValue(sampleCountX - 1);
-    m_axisMinSliderZ->setMaximum(sampleCountZ - 3);
-    m_axisMinSliderZ->setValue(0);
-    m_axisMaxSliderZ->setMaximum(sampleCountZ - 1);
-    m_axisMaxSliderZ->setValue(sampleCountZ - 1);
-}
-
 void SurfaceGraph::adjustXMin(int min)
 {
     qreal minX = m_stepX * qreal(min) + m_rangeMinX;
@@ -187,6 +197,7 @@ void SurfaceGraph::adjustZMax(int max)
     setAxisZRange(minX, maxX);
 }
 
+//! [5]
 void SurfaceGraph::setAxisXRange(qreal min, qreal max)
 {
     m_graph->axisX()->setRange(min, max);
@@ -196,9 +207,18 @@ void SurfaceGraph::setAxisZRange(qreal min, qreal max)
 {
     m_graph->axisZ()->setRange(min, max);
 }
+//! [5]
+
+//! [6]
+void SurfaceGraph::changeTheme(int theme)
+{
+    m_graph->setTheme((QDataVis::Theme)theme);
+}
+//! [6]
 
 void SurfaceGraph::setBlackToYellowGradient()
 {
+    //! [7]
     QLinearGradient gr;
     gr.setColorAt(0.0, Qt::black);
     gr.setColorAt(0.33, Qt::blue);
@@ -206,6 +226,7 @@ void SurfaceGraph::setBlackToYellowGradient()
     gr.setColorAt(1.0, Qt::yellow);
 
     m_graph->setGradient(gr);
+    //! [7]
 }
 
 void SurfaceGraph::setGreenToRedGradient()
@@ -219,7 +240,3 @@ void SurfaceGraph::setGreenToRedGradient()
     m_graph->setGradient(gr);
 }
 
-void SurfaceGraph::changeTheme(int theme)
-{
-    m_graph->setTheme((QDataVis::Theme)theme);
-}
diff --git a/examples/surface/surfacegraph.h b/examples/surface/surfacegraph.h
index 8da84e38..ac297bf6 100644
--- a/examples/surface/surfacegraph.h
+++ b/examples/surface/surfacegraph.h
@@ -36,10 +36,12 @@ public:
     void enableHeightMapModel();
     void enableSqrtSinModel();
 
+    //! [0]
     void toggleModeNone() { m_graph->setSelectionMode(QDataVis::SelectionModeNone); }
     void toggleModeItem() { m_graph->setSelectionMode(QDataVis::SelectionModeItem); }
     void toggleModeSliceRow() { m_graph->setSelectionMode(QDataVis::SelectionModeSliceRow); }
     void toggleModeSliceColumn() { m_graph->setSelectionMode(QDataVis::SelectionModeSliceColumn); }
+    //! [0]
 
     void setBlackToYellowGradient();
     void setGreenToRedGradient();