From d1aadc60ba556a091e34c7601fd2da3abbfcebed Mon Sep 17 00:00:00 2001 From: Mika Salmela Date: Fri, 11 Oct 2013 12:17:03 +0300 Subject: Documentation for QML Surface MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task-number: QTRD-2397 Change-Id: I916d416fe14712df5b5b44d8a4806cc1562f3fca Reviewed-by: Tomi Korpipää --- examples/qmlsurface/doc/src/qmlsurface.qdoc | 61 ++++++++++++++++++++++++++++- examples/qmlsurface/main.cpp | 7 +++- examples/qmlsurface/qml/qmlsurface/data.qml | 8 ++++ examples/qmlsurface/qml/qmlsurface/main.qml | 8 ++++ 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 #include "qtquick2applicationviewer.h" + #ifdef Q_OS_ANDROID #include #include #endif -#include 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] } } -- cgit v1.2.3