More example docs

MouseArea, Threading and TouchInteraction

Change-Id: I9ca812d20a6c87d68ef91066ae0a4b9bc8829478
Reviewed-by: Michael Brasser <michael.brasser@nokia.com>

10 files changed, 60 insertions, 8 deletions

diff --git a/examples/quick/mousearea/mousearea.qml b/examples/quick/mousearea/mousearea.qml
index df26e05a3c..cdc2364b1f 100644
--- a/examples/quick/mousearea/mousearea.qml
+++ b/examples/quick/mousearea/mousearea.qml
@@ -47,6 +47,17 @@ import QtQuick 2.0
     \image qml-mousearea-example.png
 
     This example shows you how to respond to clicks and drags with a MouseArea.
+
+    When you click inside the red square, the Text element will list several properties
+    of that click which are available to QML.
+
+    Signals are emitted by the MouseArea when clicks or other discrete operations occur within it
+    \snippet examples/quick/mousearea/mousearea.qml clicks
+
+    The MouseArea can also be used to drag elements around. By setting the parameters of the drag property,
+    the target item will be dragged around if the user starts to drag within the MouseArea.
+    \snippet examples/quick/mousearea/mousearea.qml drag
+
 */
 
 Rectangle {
@@ -141,9 +152,11 @@ Rectangle {
                 posInfo.text = ''
             }
 
+            //! [clicks]
             onPressAndHold: btn.text = 'Press and hold'
             onClicked: btn.text = 'Clicked (wasHeld=' + mouse.wasHeld + ')'
             onDoubleClicked: btn.text = 'Double clicked'
+            //! [clicks]
         }
     }
 
@@ -157,12 +170,14 @@ Rectangle {
 
         MouseArea {
             anchors.fill: parent
+            //! [drag]
             drag.target: blueSquare
             drag.axis: Drag.XandYAxis
             drag.minimumX: 0
             drag.maximumX: box.width - parent.width
             drag.minimumY: 0
             drag.maximumY: box.height - parent.width
+            //! [drag]
         }
     }
 
diff --git a/examples/quick/threading/threadedlistmodel/timedisplay.qml b/examples/quick/threading/threadedlistmodel/timedisplay.qml
index 48d0f659e5..266534a57c 100644
--- a/examples/quick/threading/threadedlistmodel/timedisplay.qml
+++ b/examples/quick/threading/threadedlistmodel/timedisplay.qml
@@ -38,7 +38,6 @@
 **
 ****************************************************************************/
 
-// ![0]
 import QtQuick 2.0
 
 Rectangle {
@@ -60,6 +59,7 @@ Rectangle {
             source: "dataloader.js"
         }
 
+// ![0]
         Timer {
             id: timer
             interval: 2000; repeat: true
@@ -71,6 +71,6 @@ Rectangle {
                 worker.sendMessage(msg);
             }
         }
+// ![0]
     }
 }
-// ![0]
diff --git a/examples/quick/threading/threading.qml b/examples/quick/threading/threading.qml
index b96c6975ac..cff4dd83b9 100644
--- a/examples/quick/threading/threading.qml
+++ b/examples/quick/threading/threading.qml
@@ -48,8 +48,20 @@ import "../../shared" as Examples
     \image qml-threading-example.png
 
     Threaded ListModel contains a ListView and a ListModel. The ListModel is updated asynchronusly in another thread, and the results propagate back to the main thread.
+    A timer requests updates from the worker thread periodically:
+    \snippet examples/threading/threadedlistmodel/timedisplay.qml 0
+
+    Inside the worker thread, the ListModel is synchronized once the data is finished loading:
+    \snippet examples/threading/threadedlistmodel/dataloader.js 0
 
     WorkerScript contains an example of using a WorkerScript to offload expensive calculations into another thread. This keeps the UI from being blocked. This example calculates numbers in Pascal's Triangle, and not in a very optimal way, so it will often take several seconds to complete the calculation. By doing this in a WorkerScript in another thread, the UI is not blocked during this time.
+
+    When the UI needs another value, a request is sent to the WorkerScript:
+    \snippet examples/threading/workerscript/workerscript.qml 0
+    The workerscript then is free to take a really long time to calculate it:
+    \snippet examples/threading/workerscript/workerscript.js 0
+    When it's done, the result returns to the main scene via the WorkerScript element:
+    \snippet examples/threading/workerscript/workerscript.qml 1
 */
 
 Item {
diff --git a/examples/quick/threading/workerscript/workerscript.js b/examples/quick/threading/workerscript/workerscript.js
index ada3d82589..67fbd8af9a 100644
--- a/examples/quick/threading/workerscript/workerscript.js
+++ b/examples/quick/threading/workerscript/workerscript.js
@@ -12,7 +12,7 @@ function triangle(row, column) {
         return 1;
     return triangle(row-1, column-1) + triangle(row-1, column);
 }
-
+//! [0]
 WorkerScript.onMessage = function(message) {
     //Calculate result (may take a while, using a naive algorithm)
     var calculatedResult = triangle(message.row, message.column);
@@ -21,4 +21,4 @@ WorkerScript.onMessage = function(message) {
                                 column: message.column,
                                 result: calculatedResult} );
 }
-
+//! [0]
diff --git a/examples/quick/threading/workerscript/workerscript.qml b/examples/quick/threading/workerscript/workerscript.qml
index 640df0b483..d66628e79e 100644
--- a/examples/quick/threading/workerscript/workerscript.qml
+++ b/examples/quick/threading/workerscript/workerscript.qml
@@ -43,6 +43,7 @@ import QtQuick 2.0
 Rectangle {
     width: 320; height: 480
 
+//! [1]
     WorkerScript {
         id: myWorker
         source: "workerscript.js"
@@ -56,10 +57,12 @@ Rectangle {
             }
         }
     }
+//! [1]
     Row {
         y: 24
         spacing: 24
         anchors.horizontalCenter: parent.horizontalCenter
+//! [0]
         Spinner {
             id: rowSpinner
             label: "Row"
@@ -68,6 +71,7 @@ Rectangle {
                 myWorker.sendMessage( { row: rowSpinner.value, column: columnSpinner.value } );
             }
         }
+//! [0]
 
         Spinner {
             id: columnSpinner
diff --git a/examples/quick/touchinteraction/flickable/basic-flickable.qml b/examples/quick/touchinteraction/flickable/basic-flickable.qml
index 58650d7334..dd64be4910 100644
--- a/examples/quick/touchinteraction/flickable/basic-flickable.qml
+++ b/examples/quick/touchinteraction/flickable/basic-flickable.qml
@@ -40,6 +40,7 @@
 
 import QtQuick 2.0
 
+    //![0]
 Rectangle {
     width: 320
     height: 480
@@ -50,6 +51,7 @@ Rectangle {
         Rectangle {
             width: 1000
             height: 1000
+    //![0]
             x: 100
             y: 100
             radius: 128
diff --git a/examples/quick/touchinteraction/multipointtouch/content/AugmentedTouchPoint.qml b/examples/quick/touchinteraction/multipointtouch/content/AugmentedTouchPoint.qml
index aede1a8f4e..74da7f1f37 100644
--- a/examples/quick/touchinteraction/multipointtouch/content/AugmentedTouchPoint.qml
+++ b/examples/quick/touchinteraction/multipointtouch/content/AugmentedTouchPoint.qml
@@ -40,6 +40,7 @@
 import QtQuick 2.0
 import QtQuick.Particles 2.0
 
+//! [0]
 TouchPoint {
     id: container
     property ParticleSystem system
@@ -68,3 +69,4 @@ TouchPoint {
         goalState: "falling"
     }
 }
+//! [0]
diff --git a/examples/quick/touchinteraction/multipointtouch/multiflame.qml b/examples/quick/touchinteraction/multipointtouch/multiflame.qml
index 72a0ce21f8..90640baaa4 100644
--- a/examples/quick/touchinteraction/multipointtouch/multiflame.qml
+++ b/examples/quick/touchinteraction/multipointtouch/multiflame.qml
@@ -45,6 +45,7 @@ Rectangle {
     height: 480
     color: "black"
 
+//! [0]
     MultiPointTouchArea {
         anchors.fill: parent
         minimumTouchPoints: 1
@@ -57,13 +58,16 @@ Rectangle {
             TouchPoint { id: touch31 }
         ]
     }
+//! [0]
 
+//! [1]
     ParticleFlame {
         color: "red"
         x: touch1.x
         y: touch1.y
         emitting: touch1.pressed
     }
+//! [1]
     ParticleFlame {
         color: "green"
         x: touch2.x
diff --git a/examples/quick/touchinteraction/pincharea/flickresize.qml b/examples/quick/touchinteraction/pincharea/flickresize.qml
index 037766e4a0..f5fb77c7ee 100644
--- a/examples/quick/touchinteraction/pincharea/flickresize.qml
+++ b/examples/quick/touchinteraction/pincharea/flickresize.qml
@@ -57,6 +57,7 @@ Rectangle {
 
             property real initialWidth
             property real initialHeight
+            //![0]
             onPinchStarted: {
                 initialWidth = flick.contentWidth
                 initialHeight = flick.contentHeight
@@ -75,6 +76,7 @@ Rectangle {
                 // Move its content within bounds.
                 flick.returnToBounds()
             }
+            //![0]
 
             Rectangle {
                 width: flick.contentWidth
diff --git a/examples/quick/touchinteraction/touchinteraction.qml b/examples/quick/touchinteraction/touchinteraction.qml
index e64c145714..c8285438ef 100644
--- a/examples/quick/touchinteraction/touchinteraction.qml
+++ b/examples/quick/touchinteraction/touchinteraction.qml
@@ -49,15 +49,26 @@ import "../../shared"
 
     This is a collection of small QML examples relating to touch interaction methods.
 
-    Multipoint Flames demonstrates distinguishing different fingers in a MultiPointTouchArea, by assignning a different colored flame to each touch point.
+    Multipoint Flames demonstrates distinguishing different fingers in a MultiPointTouchArea, by assigning a different colored flame to each touch point.
+    The MultipointTouchArea sets up multiple touch points:
+    \snippet examples/quick/touchinteraction/multipointtouch/multiflame.qml 0
+    The flames are then simply bound to the coordiates of the touch point, and whether it is currently pressed, like so:
+    \snippet examples/quick/touchinteraction/multipointtouch/multiflame.qml 1
 
-    Bear-Whack demonstrates using a MultiPointTouchArea to add multiple finger support to a simple game.
+    Bear-Whack demonstrates using a MultiPointTouchArea to add multiple finger support to a simple game. The interaction with the game
+    is done through a SpriteGoal that follows the TouchPoint. The TouchPoints added to the MultiPointTouchArea are a component with all
+    this logic embedded into it:
+    \snippet examples/quick/touchinteraction/multipointtouch/bearwhack/content/AugmentedTouchPoint.qml 0
 
-    Flick Resize uses a PinchArea to allow Pinch-to-Resize behavior.
+    Flick Resize uses a PinchArea to allow Pinch-to-Resize behavior. This is easily achieved just by listening to the PinchArea signals and responding
+    to user input.
+    \snippet examples/quick/touchinteraction/pincharea/flickresize.qml 0
 
-    Flickable is a simple example demonstrating the Flickable element.
+    Flickable is a simple example demonstrating the Flickable element. The element inside the flickable is very big, but the flickable itself is very small:
+    \snippet examples/quick/touchinteraction/flickable/basic-flickable.qml 0
 
     Corkboards shows a more complex Flickable usecase, with elements on the flickable that respond to mouse and keyboard interaction.
+    This doesn't require special code, the QtQuick elements automatically cooperate with Flickable for accepting the touch events.
 */
 
 Item {