Documentation for surface example

Task-number: QTRD-2347

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

2 files changed, 81 insertions, 2 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
 */