diff options
Diffstat (limited to 'examples/surface/doc/src/surface.qdoc')
-rw-r--r-- | examples/surface/doc/src/surface.qdoc | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/examples/surface/doc/src/surface.qdoc b/examples/surface/doc/src/surface.qdoc new file mode 100644 index 00000000..12271fb8 --- /dev/null +++ b/examples/surface/doc/src/surface.qdoc @@ -0,0 +1,131 @@ +/**************************************************************************** +** +** 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 +** +****************************************************************************/ + +/*! + \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 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 + + \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, 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: + + \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 +*/ |