Qmlscatter example documentation

Task-number: QTRD-2396

Change-Id: I3fda90018122e92b388477189d95c9473103a4a3
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@digia.com>

6 files changed, 191 insertions, 26 deletions

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
--- /dev/null
+++ b/examples/qmlscatter/doc/images/qmlscatter-example.png
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
--- /dev/null
+++ b/examples/qmlscatter/doc/images/qmlscatter-newproject.png
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
+    <RCC>
+        <qresource prefix="/qml">
+            <file alias="main.qml">qml/qmlscatter/main.qml</file>
+            <file alias="Data.qml">qml/qmlscatter/data.qml</file>
+            <file alias="NewButton.qml">qml/qmlscatter/newbutton.qml</file>
+        </qresource>
+    </RCC>
+    \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";
             }
         }