From 88014cb6ba401c505fb9d26bbd265424aacce18b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomi=20Korpip=C3=A4=C3=A4?= Date: Wed, 9 Oct 2013 13:50:06 +0300 Subject: Qmlscatter example documentation Task-number: QTRD-2396 Change-Id: I3fda90018122e92b388477189d95c9473103a4a3 Reviewed-by: Miikka Heikkinen --- .../qmlscatter/doc/images/qmlscatter-example.png | Bin 0 -> 121892 bytes .../doc/images/qmlscatter-newproject.png | Bin 0 -> 66490 bytes examples/qmlscatter/doc/src/qmlscatter.qdoc | 141 ++++++++++++++++++++- examples/qmlscatter/main.cpp | 4 + examples/qmlscatter/qml/qmlscatter/data.qml | 10 +- examples/qmlscatter/qml/qmlscatter/main.qml | 62 +++++---- 6 files changed, 191 insertions(+), 26 deletions(-) create mode 100644 examples/qmlscatter/doc/images/qmlscatter-example.png create mode 100644 examples/qmlscatter/doc/images/qmlscatter-newproject.png (limited to 'examples') diff --git a/examples/qmlscatter/doc/images/qmlscatter-example.png b/examples/qmlscatter/doc/images/qmlscatter-example.png new file mode 100644 index 00000000..07efff7d Binary files /dev/null and b/examples/qmlscatter/doc/images/qmlscatter-example.png differ diff --git a/examples/qmlscatter/doc/images/qmlscatter-newproject.png b/examples/qmlscatter/doc/images/qmlscatter-newproject.png new file mode 100644 index 00000000..87410ad0 Binary files /dev/null and b/examples/qmlscatter/doc/images/qmlscatter-newproject.png differ diff --git a/examples/qmlscatter/doc/src/qmlscatter.qdoc b/examples/qmlscatter/doc/src/qmlscatter.qdoc index e5bb10ad..4306ee61 100644 --- a/examples/qmlscatter/doc/src/qmlscatter.qdoc +++ b/examples/qmlscatter/doc/src/qmlscatter.qdoc @@ -23,9 +23,146 @@ \brief Using Scatter3D in a QML application. The Qt Quick 2 scatter example shows how to make a simple scatter graph visualization using - Q3DScatter and Qt Quick 2. + Scatter3D and Qt Quick 2. \image qmlscatter-example.png - TODO + \section1 Creating the application + + The application main is created by creating a new Qt Quick 2 Application project in QtCreator: + + \image qmlscatter-newproject.png + + We'll modify the generated \c main.cpp a bit, as we want to add our \c main.qml file as a + resource. We do it by replacing + + \code viewer.setMainQmlFile(QStringLiteral("qml/qmlscatter/main.qml")); \endcode + + with + + \snippet ../examples/qmlscatter/main.cpp 0 + + This will help us when deploying the application to Android. We'll also change the application + to be shown fullscreen by replacing + + \code viewer.showExpanded(); \endcode + + with + + \snippet ../examples/qmlscatter/main.cpp 1 + + We won't look into that any closer, as we'll change nothing in the generated + \c qtquick2applicationviewer files. + + Next we'll create new qml files for data (\c data.qml) and a QtQuick.Controls button + we want to modify a bit (\c newbutton.qml), and add them to the resource file, in addition to + main.qml: + + \code + + + qml/qmlscatter/main.qml + qml/qmlscatter/data.qml + qml/qmlscatter/newbutton.qml + + + \endcode + + Now the base for our application is done, and we can start setting up the graph. + + \section1 Setting up the graph + + Let's start modifying the generated \c {main.qml}. We can remove all previous content from it, + as it has nothing we need. + + First we'll import all the QML modules we need: + + \snippet ../examples/qmlscatter/qml/qmlscatter/main.qml 0 + + The last \c import just imports all the qml files in the same directory as our \c {main.qml}, + because that's where \c newbutton.qml and \c data.qml are. + + Then we create our main \c Item, call it \c mainView and set it visible: + + \snippet ../examples/qmlscatter/qml/qmlscatter/main.qml 1 + + Then we'll add another \c Item inside it, and call it \c dataView. This will be the item to hold + the \c Scatter3D graph. We'll anchor it to the parent bottom: + + \snippet ../examples/qmlscatter/qml/qmlscatter/main.qml 9 + + Next we're ready to add the \c Scatter3D graph itself. We'll add it inside the \c dataView and + name it \c {scatterGraph}. Let's make it fill the \c {dataView}: + + \snippet ../examples/qmlscatter/qml/qmlscatter/main.qml 2 + + Now the graph is ready to use, but has no data. It also has the default proxy, axes and visual + properties. + + Let's modify some visual properties first by adding the following inside \c {scatterGraph}: + + \snippet ../examples/qmlscatter/qml/qmlscatter/main.qml 3 + + We changed the font, theme and shadow quality. We're happy with the other visual properties, + so we won't change them. + + Then it's time to start feeding the graph some data. + + \section1 Adding data to the graph + + Let's create a \c Data item inside the \c mainView and name it \c {graphData}: + + \snippet ../examples/qmlscatter/qml/qmlscatter/main.qml 4 + + This is the component that holds our data in \c {data.qml}. It has an \c Item as the main + component. + + In the main component we'll add the data itself in a \c ListModel and name it + \c {dataModel}: + + \snippet ../examples/qmlscatter/qml/qmlscatter/data.qml 0 + \dots + + That itself doesn't do us much good, so we'll create a \c ScatterDataMapping and name it + \c {scatterMapping}: + + \snippet ../examples/qmlscatter/qml/qmlscatter/data.qml 1 + + In \c scatterMapping we need to define axis roles to match the roles in the \c ListElement + items of the \c {dataModel}. + + We'll still need a data proxy, so we'll create a \c ItemModelScatterDataProxy and call it + \c {modelProxy}: + + \snippet ../examples/qmlscatter/qml/qmlscatter/data.qml 2 + + We set \c scatterMapping as the active mapping and \c dataModel as the item model. + + We still need to expose the proxy to be usable from \c {main.qml}. We do this by defining it as + an alias in the main data component: + + \snippet ../examples/qmlscatter/qml/qmlscatter/data.qml 3 + + Now we can use the data from \c data.qml with \c scatterGraph in \c {main.qml}. We'll just set + \c proxy as the \c dataProxy for the graph: + + \snippet ../examples/qmlscatter/qml/qmlscatter/main.qml 5 + + We'll set up selection label format and the axes in \c scatterGraph as well: + + \snippet ../examples/qmlscatter/qml/qmlscatter/main.qml 6 + + After that we'll add a few buttons to the \c mainView to control the graph. We'll only show one + as an example: + + \snippet ../examples/qmlscatter/qml/qmlscatter/main.qml 7 + + Then we'll modify \c dataView to make room for the buttons at the top: + + \snippet ../examples/qmlscatter/qml/qmlscatter/main.qml 8 + \dots + + And we're done! + + \section1 Example contents */ diff --git a/examples/qmlscatter/main.cpp b/examples/qmlscatter/main.cpp index 150a36a6..d339924b 100644 --- a/examples/qmlscatter/main.cpp +++ b/examples/qmlscatter/main.cpp @@ -37,9 +37,13 @@ int main(int argc, char *argv[]) viewer.addImportPath(QString::fromLatin1("%1/%2").arg(QCoreApplication::applicationDirPath(), QString::fromLatin1("qml"))); #endif + //! [0] viewer.setSource(QUrl("qrc:/qml/main.qml")); + //! [0] viewer.setResizeMode(QQuickView::SizeRootObjectToView); + //! [1] viewer.showFullScreen(); + //! [1] return app.exec(); } diff --git a/examples/qmlscatter/qml/qmlscatter/data.qml b/examples/qmlscatter/qml/qmlscatter/data.qml index 8a6ada45..37b0dc61 100644 --- a/examples/qmlscatter/qml/qmlscatter/data.qml +++ b/examples/qmlscatter/qml/qmlscatter/data.qml @@ -20,26 +20,32 @@ import QtQuick 2.1 import com.digia.QtDataVisualization 1.0 Item { - property alias mapping: scatterMapping - property alias model: dataModel + //! [3] property alias proxy: modelProxy + //! [3] + //! [1] ScatterDataMapping { id: scatterMapping xPosRole: "xPos" yPosRole: "yPos" zPosRole: "zPos" } + //! [1] + //! [2] ItemModelScatterDataProxy { id: modelProxy activeMapping: scatterMapping itemModel: dataModel } + //! [2] + //! [0] ListModel { id: dataModel ListElement{ xPos: -10.0; yPos: 5.0; zPos: -5.0 } + //! [0] ListElement{ xPos: -9.0; yPos: 3.0; zPos: -4.5 } ListElement{ xPos: -8.5; yPos: 4.1; zPos: -4.0 } ListElement{ xPos: -8.0; yPos: 4.75; zPos: -3.9 } diff --git a/examples/qmlscatter/qml/qmlscatter/main.qml b/examples/qmlscatter/qml/qmlscatter/main.qml index 333dfadd..8384625f 100644 --- a/examples/qmlscatter/qml/qmlscatter/main.qml +++ b/examples/qmlscatter/qml/qmlscatter/main.qml @@ -16,34 +16,49 @@ ** ****************************************************************************/ +//! [0] import QtQuick 2.1 import com.digia.QtDataVisualization 1.0 import "." +//! [0] +//! [1] Item { - id: mainview + id: mainView visible: true + //! [1] + //! [4] Data { id: graphData } + //! [4] + //! [8] + //! [9] Item { id: dataView - width: parent.width - height: parent.height - shadowToggle.height anchors.bottom: parent.bottom + //! [9] + height: parent.height - shadowToggle.height + //! [8] + //! [2] Scatter3D { - id: testscatter + id: scatterGraph width: dataView.width height: dataView.height + //! [2] + //! [3] font.family: "Lucida Handwriting" font.pointSize: 40 - dataProxy: graphData.proxy theme: Scatter3D.ThemeIsabelle shadowQuality: Scatter3D.ShadowQualitySoftLow - selectionMode: Scatter3D.SelectionModeItem + //! [3] + //! [5] + dataProxy: graphData.proxy + //! [5] + //! [6] itemLabelFormat: "X:@xLabel Y:@yLabel Z:@zLabel" axisX.segmentCount: 3 axisX.subSegmentCount: 2 @@ -54,23 +69,26 @@ Item { axisY.segmentCount: 2 axisY.subSegmentCount: 2 axisY.labelFormat: "%.2f" + //! [6] } } + //! [7] NewButton { id: shadowToggle - width: parent.width / 6 + width: parent.width / 6 // We're adding 6 buttons and want to divide them equally text: "Hide Shadows" onClicked: { - if (testscatter.shadowQuality === Scatter3D.ShadowQualityNone) { - testscatter.shadowQuality = Scatter3D.ShadowQualitySoftLow; + if (scatterGraph.shadowQuality === Scatter3D.ShadowQualityNone) { + scatterGraph.shadowQuality = Scatter3D.ShadowQualitySoftLow; text = "Hide Shadows"; } else { - testscatter.shadowQuality = Scatter3D.ShadowQualityNone; + scatterGraph.shadowQuality = Scatter3D.ShadowQualityNone; text = "Show Shadows"; } } } + //! [7] NewButton { id: smoothToggle @@ -78,12 +96,12 @@ Item { text: "Use Smooth Dots" anchors.left: shadowToggle.right onClicked: { - if (testscatter.objectSmoothingEnabled === false) { + if (scatterGraph.objectSmoothingEnabled === false) { text = "Use Flat Dots"; - testscatter.objectSmoothingEnabled = true; + scatterGraph.objectSmoothingEnabled = true; } else { text = "Use Smooth Dots" - testscatter.objectSmoothingEnabled = false; + scatterGraph.objectSmoothingEnabled = false; } } } @@ -94,10 +112,10 @@ Item { text: "Change Camera Placement" anchors.left: smoothToggle.right onClicked: { - if (testscatter.cameraPreset === Scatter3D.CameraPresetFront) { - testscatter.cameraPreset = Scatter3D.CameraPresetIsometricRightHigh; + if (scatterGraph.scene.activeCamera.cameraPreset === Scatter3D.CameraPresetFront) { + scatterGraph.scene.activeCamera.cameraPreset = Scatter3D.CameraPresetIsometricRightHigh; } else { - testscatter.cameraPreset = Scatter3D.CameraPresetFront; + scatterGraph.scene.activeCamera.cameraPreset = Scatter3D.CameraPresetFront; } } } @@ -108,10 +126,10 @@ Item { text: "Change Theme" anchors.left: cameraToggle.right onClicked: { - if (testscatter.theme === Scatter3D.ThemeArmyBlue) { - testscatter.theme = Scatter3D.ThemeIsabelle; + if (scatterGraph.theme === Scatter3D.ThemeArmyBlue) { + scatterGraph.theme = Scatter3D.ThemeIsabelle; } else { - testscatter.theme = Scatter3D.ThemeArmyBlue; + scatterGraph.theme = Scatter3D.ThemeArmyBlue; } } } @@ -122,11 +140,11 @@ Item { text: "Hide Background" anchors.left: themeToggle.right onClicked: { - if (testscatter.backgroundVisible === true) { - testscatter.backgroundVisible = false; + if (scatterGraph.backgroundVisible === true) { + scatterGraph.backgroundVisible = false; text = "Show Background"; } else { - testscatter.backgroundVisible = true; + scatterGraph.backgroundVisible = true; text = "Hide Background"; } } -- cgit v1.2.3