QMLCustomInput example documentation.

Task-id: QTRD-2634

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

3 files changed, 112 insertions, 12 deletions

diff --git a/examples/qmlcustominput/doc/images/qmlcustominput-example.png b/examples/qmlcustominput/doc/images/qmlcustominput-example.png
new file mode 100644
index 00000000..436f4da5
--- /dev/null
+++ b/examples/qmlcustominput/doc/images/qmlcustominput-example.png
diff --git a/examples/qmlcustominput/doc/src/qmlcustominput.qdoc b/examples/qmlcustominput/doc/src/qmlcustominput.qdoc
new file mode 100644
index 00000000..14943aa0
--- /dev/null
+++ b/examples/qmlcustominput/doc/src/qmlcustominput.qdoc
@@ -0,0 +1,79 @@
+/****************************************************************************
+**
+** 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 qmlcustominput
+    \title Qt Quick Custom Input Example
+    \ingroup qtdatavisualization_examples
+    \brief Customizing input in a Qt Quick application.
+
+    The Qt Quick Custom Input example shows how to customize the 3D graph controls from Qt Quick using the MouseArea to capture and process mouse events in Qt Quick.
+    Custom input handling code in this example shows how the camera is now controlled by using NumberAnimation to animate the camera and item selection
+    is done on mouseover rather than clicking any mouse buttons. Also the code shows how to implement similar zoom with mouse wheel functionality as the default
+    input handler implements.
+
+    \image qmlcustominput-example.png
+
+    \section1 Removing default input handling
+
+    The default input handling mechanism is disabled by setting the inputHandler property to null.
+
+    \snippet ../examples/qmlcustominput/qml/qmlcustominput/main.qml 0
+    \dots 0
+    \snippet ../examples/qmlcustominput/qml/qmlcustominput/main.qml 1
+    \dots 0
+
+    \section1 Implementing custom selection handling
+
+    The on mouseover selection handling is implemented using standard MouseArea to capture the mouse events.
+    The mouse area is configured to capture hover events and has two custom properties for \c mouseX and \c mouseY
+    to store the last known mouse coordinates.
+
+    \snippet ../examples/qmlcustominput/qml/qmlcustominput/main.qml 2
+
+    Whenever a pointer movement related signal is received the code updates the \c mouseX and \c mouseY properties.
+
+    \snippet ../examples/qmlcustominput/qml/qmlcustominput/main.qml 3
+
+    As the selection is one shot, and is cleared each time a 3D frame is rendered, a timer is setup to retrigger selection so that the selection moves to the item
+    currently under the mouse cursor as the camera animates around the graph even when the mouse cursor is not moving.
+
+    \snippet ../examples/qmlcustominput/qml/qmlcustominput/main.qml 4
+
+    \section1 Implementing custom zoom handling
+
+    The camera has a zoom factor that represents amount of zoom in percentages. In this example the zoom range is limited
+    between 10% and 500%. This range is then divided to four subranges where angleDelta is scaled to different amount of zoom change
+    based on the current subrange.
+
+    \dots
+    \snippet ../examples/qmlcustominput/qml/qmlcustominput/main.qml 5
+    \dots
+
+    \section1 Implementing custom camera handling
+
+    The camera is animated to constantly rotate around the graph with two animations. The rotation around the graph is done with
+    a simple NumberAnimation that just increments during 20 seconds from 0 degrees to 360 degrees and sets the \l Q3DCamera::xRotation property.
+
+    \snippet ../examples/qmlcustominput/qml/qmlcustominput/main.qml 6
+
+    The camera movement up and down is implemented with a SequentialAnimation that varies the \l Q3DCamera::yRotation property of the camera
+    from 5 degrees to 45 degrees and back with in and out easing.
+
+    \snippet ../examples/qmlcustominput/qml/qmlcustominput/main.qml 7
+*/
diff --git a/examples/qmlcustominput/qml/qmlcustominput/main.qml b/examples/qmlcustominput/qml/qmlcustominput/main.qml
index 2ab39ca8..fb95f09f 100644
--- a/examples/qmlcustominput/qml/qmlcustominput/main.qml
+++ b/examples/qmlcustominput/qml/qmlcustominput/main.qml
@@ -36,7 +36,9 @@ Item {
         width: parent.width
         height: parent.height - shadowToggle.height
 
+        //! [0]
         Scatter3D {
+            //! [0]
             id: scatterGraph
             width: dataView.width
             height: dataView.height
@@ -44,7 +46,9 @@ Item {
             shadowQuality: AbstractGraph3D.ShadowQualitySoftMedium
             scene.activeCamera.yRotation: 30.0
             objectType: AbstractGraph3D.MeshStyleCubes
+            //! [1]
             inputHandler: null
+            //! [1]
 
             Scatter3DSeries {
                 id: scatterSeries
@@ -59,25 +63,24 @@ Item {
             }
         }
 
+        //! [2]
         MouseArea {
             id: inputArea
             anchors.fill: parent
             hoverEnabled: true
             acceptedButtons: Qt.LeftButton | Qt.RightButton
+            property int mouseX: -1
+            property int mouseY: -1
+            //! [2]
 
-            onPressed: {
-                scatterGraph.scene.selectionQueryPosition = Qt.point(mouse.x, mouse.y);
-            }
-
-            onReleased: {
-                scatterGraph.scene.selectionQueryPosition = Qt.point(mouse.x, mouse.y);
-            }
-
+            //! [3]
             onPositionChanged: {
-                // Do selection on mouse hover
-                scatterGraph.scene.selectionQueryPosition = Qt.point(mouse.x, mouse.y);
+                mouseX = mouse.x;
+                mouseY = mouse.y;
             }
+            //! [3]
 
+            //! [5]
             onWheel: {
                 // Adjust zoom level based on what zoom range we're in.
                 var zoomLevel = scatterGraph.scene.activeCamera.zoomLevel;
@@ -94,9 +97,23 @@ Item {
 
                 scatterGraph.scene.activeCamera.zoomLevel = zoomLevel;
             }
+            //! [5]
         }
+
+        //! [4]
+        Timer {
+            id: reselectTimer
+            interval: 10
+            running: true
+            repeat: true
+            onTriggered: {
+                scatterGraph.scene.selectionQueryPosition = Qt.point(inputArea.mouseX, inputArea.mouseY);
+            }
+        }
+        //! [4]
     }
 
+    //! [6]
     NumberAnimation {
         id: cameraAnimationX
         loops: Animation.Infinite
@@ -107,7 +124,10 @@ Item {
         to: 360.0
         duration: 20000
     }
+    //! [6]
+
 
+    //! [7]
     SequentialAnimation {
         id: cameraAnimationY
         loops: Animation.Infinite
@@ -119,7 +139,7 @@ Item {
             from: 5.0
             to: 45.0
             duration: 9000
-            easing: Easing.InOutSine
+            easing.type: Easing.InOutSine
         }
 
         NumberAnimation {
@@ -128,9 +148,10 @@ Item {
             from: 45.0
             to: 5.0
             duration: 9000
-            easing: Easing.InOutSine
+            easing.type: Easing.InOutSine
         }
     }
+    //! [7]
 
     NewButton {
         id: shadowToggle