path: root/examples/datavisualization/surface/doc
diff options
authorMiikka Heikkinen <>2014-02-13 09:59:52 +0200
committerMiikka Heikkinen <>2014-02-13 10:09:17 +0200
commit88cd10aa7b3559b092cf5575b0a17d002dc100ae (patch)
tree9d6e7efdec49419558bb4ef4a9bc02ae3cb1cfc4 /examples/datavisualization/surface/doc
parentecabd51692b476567dc42a745f51996ec665b385 (diff)
Fix examples installation
Had to add one folder to the examples structure so installation works correctly. Change-Id: Ic92dfe9997413a6243abcf5eeba12744ba9e938c Reviewed-by: Tomi Korpipää <>
Diffstat (limited to 'examples/datavisualization/surface/doc')
-rw-r--r--examples/datavisualization/surface/doc/images/surface-example.pngbin0 -> 149046 bytes
2 files changed, 136 insertions, 0 deletions
diff --git a/examples/datavisualization/surface/doc/images/surface-example.png b/examples/datavisualization/surface/doc/images/surface-example.png
new file mode 100644
index 00000000..c323df78
--- /dev/null
+++ b/examples/datavisualization/surface/doc/images/surface-example.png
Binary files differ
diff --git a/examples/datavisualization/surface/doc/src/surface.qdoc b/examples/datavisualization/surface/doc/src/surface.qdoc
new file mode 100644
index 00000000..5397b503
--- /dev/null
+++ b/examples/datavisualization/surface/doc/src/surface.qdoc
@@ -0,0 +1,136 @@
+** Copyright (C) 2014 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at
+** 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
+ \example surface
+ \title Surface Example
+ \ingroup qtdatavisualization_examples
+ \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. 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 displaying selected portions of the graph.
+ \li Changing theme.
+ \li How to set a custom surface gradient.
+ \endlist
+ For instructions about how to interact with the graph, see \l{Qt Data Visualization Interacting with Data}{this page}.
+ \image surface-example.png
+ \section1 Creating the application
+ First, in \c main.cpp, we create a QApplication, instantiate Q3DSurface, and a window container
+ for it:
+ \snippet ../examples/surface/main.cpp 0
+ The call to QWidget::createWindowContainer is required, as all data visualization types
+ (Q3DBars, Q3DScatter, and Q3DSurface) inherit QWindow. Any class inheriting QWindow cannot be used
+ as a widget any other way.
+ Then we'll create horizontal and vertical layouts. We'll add the graph with the container and
+ the vertical layout into the horizontal one:
+ \snippet ../examples/surface/main.cpp 1
+ The rest of the code in \c main.cpp is creating control widgets for features in Q3DSurface. We
+ have separated code for changing these features into \c surfacegraph.cpp and only connect
+ signals from widgets into methods in \c surfacegraph.cpp. Next chapter explains more
+ about using Q3DSurface.
+ \section1 Setting up proxies and data
+ First we instantiate a new QSurfaceDataProxy and attach it to a new QSurface3DSeries:
+ \snippet ../examples/surface/surfacegraph.cpp 0
+ Then we fill the proxy with a simple square root and sine wave data. This is done by
+ creating a new \c QSurfaceDataArray instance and adding \c QSurfaceDataRow elements to it.
+ The created \c QSurfaceDataArray is set to be 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 QHeightMapSurfaceDataProxy::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 the series. When the user selects the
+ \c {Sqrt & Sin} radio button, the selected series is activated with the following
+ code. First we set the decorative issues like enable the grid for the surface and
+ select the flat shading mode. Next lines define the axis label format and value
+ ranges. Finally we make sure the correct series is added to the
+ graph:
+ \snippet ../examples/surface/surfacegraph.cpp 3
+ When the \c{Height Map} radio button is activated, the following code sets the correct series active.
+ The axis label format is set to show N and E letters and ranges are set to the imaginary coordinates.
+ Auto adjusting Y-axis range is fine for our height map surface, so we ensure it is set.
+ \snippet ../examples/surface/surfacegraph.cpp 4
+ \section1 Selection modes
+ Q3Dsurface supports three different selection modes. These are demonstrated in the
+ example with radio buttons, which the user can use to activate a suitable selection mode.
+ The 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:
+ \snippet ../examples/surface/surfacegraph.cpp 8
+ The ranges are set for the axes like this:
+ \snippet ../examples/surface/surfacegraph.cpp 5
+ \section1 Themes
+ Q3DSurface supports all the themes Qt Data Visualization has. The example has a pull
+ down menu for selecting the theme. The following method is connected to the
+ menu to activate the selected theme. The theme type is changed to another predefined theme,
+ which overwrites all theme properties to predefined values:
+ \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. The following
+ code shows how to create an example gradient and set it to the series. Note that you also need
+ to change the color style to Q3DTheme::ColorStyleRangeGradient to actually use the gradient.
+ \snippet ../examples/surface/surfacegraph.cpp 7