Doc: Started work to tidy up existing QML docs.

Reviewed-by: Trust Me

18 files changed, 409 insertions, 26 deletions

diff --git a/doc/src/declarative/qml-intro.qdoc b/doc/src/declarative/qml-intro.qdoc
index 69dd500..13c8e4f 100644
--- a/doc/src/declarative/qml-intro.qdoc
+++ b/doc/src/declarative/qml-intro.qdoc
@@ -320,7 +320,7 @@ from \l Item. The rotation property is a real number that specifies the
 angle in a clockwise direction for the rotation of the object. Here is the
 code for our animated rotating image.
 
-\quotefile doc/src/snippets/declarative/number-animation1.qml
+\quotefile doc/src/snippets/declarative/qml-intro/number-animation1.qml
 
 The \c {transformOrigin: Item.Center} is redundant since this is the default
 axis of rotation anyway. But if you change \c Center to \c BottomRight you
@@ -333,7 +333,7 @@ combination. For example, if the task had been to animate the rotation
 about the y-axis passing through the center of the image then the following
 code would do it.
 
-\quotefile doc/src/snippets/declarative/number-animation2.qml
+\quotefile doc/src/snippets/declarative/qml-intro/number-animation2.qml
 
 Here there is a rectangle 600 by 400 pixels. Placed within that rectangle
 is an image 100 by 100 pixels. It is rotated about the center of the image
@@ -362,7 +362,7 @@ will be animating the position and the size of the image.
 
 First create two images
 
-\quotefile doc/src/snippets/declarative/sequential-animation1.qml
+\quotefile doc/src/snippets/declarative/qml-intro/sequential-animation1.qml
 
 We will add to 'image1' a SequentialAnimation from x = 20 to the target of
 x = 450. The 'from' values will be used because we will be repeating the
@@ -375,7 +375,7 @@ between the x values and over a given duration. After the NumberAnimation
 there will be a PauseAnimation that will pause the animation for 500
 milliseconds (half a second) simply for the visual effect.
 
-\snippet doc/src/snippets/declarative/sequential-animation2.qml adding a sequential animation
+\snippet doc/src/snippets/declarative/qml-intro/sequential-animation2.qml adding a sequential animation
 
 A similar block of code is written for the animation of the 'y' value of
 the position.
@@ -390,7 +390,7 @@ and image1 to 1 and image2 to 2 then image2 will be in the foreground and
 image1 in the background. When image1 passes image2 it will pass behind it.
 The completed code looks like
 
-\quotefile doc/src/snippets/declarative/sequential-animation3.qml
+\quotefile doc/src/snippets/declarative/qml-intro/sequential-animation3.qml
 
 The \c {easing.type} has many options, expressed as a string. It specifies the
 kind of equation that describes the acceleration of the property value, not
@@ -439,9 +439,6 @@ delivers some of the best examples that illustrate these new elements.
 \endtable
 
 
-
-
-
 \section1 Using States
 
 A state is a defined set of values in the configuration of an object and
@@ -471,7 +468,7 @@ will be the default state. We will just go to 'night' by clicking and
 holding the left mouse button down, releasing the mouse button will reverse
 the process
 
-\quotefile doc/src/snippets/declarative/states1.qml
+\quotefile doc/src/snippets/declarative/qml-intro/states1.qml
 
 Several new things appear in this sample. Firstly, we use a \l MouseArea
 element to detect mouse clicks in the \e mainRectangle. Secondly, we use
@@ -549,15 +546,15 @@ needle_shadow have the same default \e x and \e y values but the rotation origin
 for the needle is slightly different so that a shadow will be evident as the
 needle moves.
 
-\snippet ../../examples/declarative/ui-components/dialcontrol/content/Dial.qml  needle_shadow
+\snippet examples/declarative/ui-components/dialcontrol/content/Dial.qml  needle_shadow
 
 And the needle
 
-\snippet ../../examples/declarative/ui-components/dialcontrol/content/Dial.qml  needle
+\snippet examples/declarative/ui-components/dialcontrol/content/Dial.qml  needle
 
 The final image is the overlay which simply has a position defined.
 
-\snippet ../../examples/declarative/ui-components/dialcontrol/content/Dial.qml  overlay
+\snippet examples/declarative/ui-components/dialcontrol/content/Dial.qml  overlay
 
 \e {dialcontrol.qml} in the \e {examples/declarative/ui-components/dialcontrol} directory is the
 main file of the example. It defines the visual environment that the Dial
@@ -565,17 +562,14 @@ will fit into. Because the \e Dial component and the images live in the \e
 content sub-directory we will have to import this into \e dialcontrol.qml. So the
 start of the file looks like
 
-    \code
-    import Qt 4.7
-    import "content"
-    \endcode
+\snippet examples/declarative/ui-components/dialcontrol/dialcontrol.qml  imports
 
 The visual space is bound by a 300 by 300 pixel \l Rectangle which is given
 a gray color. Inside this rectangle is our component \e Dial and a \l Rectangle.
 Inside the rectangle called 'container' is another rectangle with the
 interesting name 'slider'.
 
-\snippet ../../examples/declarative/ui-components/dialcontrol/dialcontrol.qml  0
+\snippet examples/declarative/ui-components/dialcontrol/dialcontrol.qml  0
 
 The Dial component, named 'dial, is \e anchored to the center of the main
 rectangle. The \c value attribute of 'dial' is set to a value based on the
@@ -584,15 +578,7 @@ rectangle. The \c value attribute of 'dial' is set to a value based on the
 the rotation of the needle image. Notice this piece of code in Dial where
 the change in \c value modifies the position of the needle.
 
-    \code
-    angle: Math.min(Math.max(-130, root.value*2.6 - 130), 133)
-    Behavior on angle {
-        SpringAnimation {
-            spring: 1.4
-            damping: .15
-        }
-    }
-    \endcode
+\snippet examples/declarative/ui-components/dialcontrol/Dial.qml  needle angle
 
 This is part of the \c needleRotation that rotates the needle and causes the
 rotation of its shadow. \l SpringAnimation is an element that modifies the value
diff --git a/doc/src/snippets/declarative/qml-intro/anchors1.qml b/doc/src/snippets/declarative/qml-intro/anchors1.qml
new file mode 100644
index 0000000..320d0e7
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/anchors1.qml
@@ -0,0 +1,14 @@
+import Qt 4.7
+
+Rectangle {
+    id: myWin
+    width: 500
+    height: 400
+
+    Image {
+        id: image1
+        source: "images/qt-logo.png"
+        width: 150; height: 150
+        anchors.bottom: myWin.bottom
+    }
+}
diff --git a/doc/src/snippets/declarative/qml-intro/anchors2.qml b/doc/src/snippets/declarative/qml-intro/anchors2.qml
new file mode 100644
index 0000000..bb9ed75
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/anchors2.qml
@@ -0,0 +1,16 @@
+import Qt 4.7
+
+Rectangle {
+    id: myWin
+    width: 500
+    height: 400
+
+    Image {
+        id: image1
+        source: "images/qt-logo.png"
+        width: 150; height: 150
+        anchors.bottom: myWin.bottom
+        anchors.horizontalCenter: myWin.horizontalCenter
+        anchors.bottomMargin: 10
+    }
+}
diff --git a/doc/src/snippets/declarative/qml-intro/anchors3.qml b/doc/src/snippets/declarative/qml-intro/anchors3.qml
new file mode 100644
index 0000000..99d2ceb
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/anchors3.qml
@@ -0,0 +1,25 @@
+import Qt 4.7
+
+Rectangle {
+    id: myWin
+    width: 500
+    height: 400
+
+    Image {
+        id: image1
+        source: "images/qt-logo.png"
+        width: 150; height: 150
+        anchors.bottom: myWin.bottom
+        anchors.horizontalCenter: myWin.horizontalCenter
+        anchors.bottomMargin: 10
+    }
+
+//! [adding some text]
+    Text {
+        text: "<h2>The Qt Logo</h2>"
+        anchors.bottom: image1.top
+        anchors.horizontalCenter: myWin.horizontalCenter
+        anchors.bottomMargin: 15
+    }
+//! [adding some text]
+}
diff --git a/doc/src/snippets/declarative/qml-intro/basic-syntax.qml b/doc/src/snippets/declarative/qml-intro/basic-syntax.qml
new file mode 100644
index 0000000..b241500
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/basic-syntax.qml
@@ -0,0 +1,8 @@
+// Note: this file is not intended to be run.
+
+//! [basic syntax]
+SomeElement {
+    id: myObject
+    ... some other things here ...
+}
+//! [basic syntax]
diff --git a/doc/src/snippets/declarative/qml-intro/hello-world1.qml b/doc/src/snippets/declarative/qml-intro/hello-world1.qml
new file mode 100644
index 0000000..244175c
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/hello-world1.qml
@@ -0,0 +1,11 @@
+import Qt 4.7
+
+Rectangle {
+    id: myRectangle
+    width: 500
+    height: 400
+
+    Text { text: "Hello World!" }
+
+    color: "lightgray"
+}
diff --git a/doc/src/snippets/declarative/qml-intro/hello-world2.qml b/doc/src/snippets/declarative/qml-intro/hello-world2.qml
new file mode 100644
index 0000000..73b2f8c
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/hello-world2.qml
@@ -0,0 +1,16 @@
+import Qt 4.7
+
+Rectangle {
+    id: myRectangle
+    width: 500
+    height: 400
+
+//! [updated text]
+    Text {
+        text: "<h2>Hello World</h2>"; color: "darkgreen"
+        x: 100; y:100
+    }
+//! [updated text]
+
+    color: "lightgray"
+}
diff --git a/doc/src/snippets/declarative/qml-intro/hello-world3.qml b/doc/src/snippets/declarative/qml-intro/hello-world3.qml
new file mode 100644
index 0000000..112f775
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/hello-world3.qml
@@ -0,0 +1,17 @@
+import Qt 4.7
+
+Rectangle {
+    id: myRectangle
+    width: 500
+    height: 400
+
+//! [updated text]
+    Text {
+        text: "<h1>Hello world again</h1>"
+        color: "#002288"
+        x: 100; y: 100
+    }
+//! [updated text]
+
+    color: "lightgray"
+}
diff --git a/doc/src/snippets/declarative/qml-intro/hello-world4.qml b/doc/src/snippets/declarative/qml-intro/hello-world4.qml
new file mode 100644
index 0000000..c97334e
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/hello-world4.qml
@@ -0,0 +1,21 @@
+import Qt 4.7
+
+Rectangle {
+    id: myRectangle
+    width: 500
+    height: 400
+
+    Text {
+        text: "<h1>Hello world again</h1>"
+        color: "#002288"
+        x: 100; y: 100
+    }
+
+//! [added an image]
+    Image {
+        source: "images/qt-logo.png"
+    }
+//! [added an image]
+
+    color: "lightgray"
+}
diff --git a/doc/src/snippets/declarative/qml-intro/hello-world5.qml b/doc/src/snippets/declarative/qml-intro/hello-world5.qml
new file mode 100644
index 0000000..74a612a
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/hello-world5.qml
@@ -0,0 +1,23 @@
+import Qt 4.7
+
+Rectangle {
+    id: myRectangle
+    width: 500
+    height: 400
+
+    Text {
+        text: "<h1>Hello world again</h1>"
+        color: "#002288"
+        x: 100; y: 100
+    }
+
+//! [positioning the image]
+    Image {
+        source: "images/qt-logo.png"
+        x: 100; y: 150
+        width: 150; height: 150
+    }
+//! [positioning the image]
+
+    color: "lightgray"
+}
diff --git a/doc/src/snippets/declarative/qml-intro/number-animation1.qml b/doc/src/snippets/declarative/qml-intro/number-animation1.qml
new file mode 100644
index 0000000..d80a8dc
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/number-animation1.qml
@@ -0,0 +1,22 @@
+import Qt 4.7
+
+Rectangle {
+    id: mainRec
+    width:  600
+    height: 400
+
+    Image {
+        id: image1
+        source: "images/qt-logo.png"
+        x: 200; y: 100
+        width: 100; height: 100
+
+        // Animate a rotation
+        transformOrigin: Item.Center
+        NumberAnimation on rotation {
+            from: 0; to: 360
+            duration: 2000
+            loops: Animation.Infinite
+        }
+    }
+}
diff --git a/doc/src/snippets/declarative/qml-intro/number-animation2.qml b/doc/src/snippets/declarative/qml-intro/number-animation2.qml
new file mode 100644
index 0000000..beb3114
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/number-animation2.qml
@@ -0,0 +1,24 @@
+import Qt 4.7
+
+Rectangle {
+    id: mainRec
+    width:  600
+    height: 400
+
+    Image {
+        id: image1
+        source: "images/qt-logo.png"
+        x: 200; y: 100
+        width: 100; height: 100
+
+        // Animate a rotation
+        transform: Rotation {
+            origin.x: 50; origin.y: 50; axis {x:0; y:1; z:0} angle:0
+            NumberAnimation on angle  {
+                from: 0; to: 360;
+                duration: 3000;
+                loops: Animation.Infinite
+            }
+        }
+    }
+}
diff --git a/doc/src/snippets/declarative/qml-intro/rectangle.qml b/doc/src/snippets/declarative/qml-intro/rectangle.qml
new file mode 100644
index 0000000..7235e9b
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/rectangle.qml
@@ -0,0 +1,8 @@
+import Qt 4.7
+
+// This is a comment. And below myRectangle is defined.
+Rectangle {
+    id: myRectangle
+    width: 500
+    height: 400
+}
diff --git a/doc/src/snippets/declarative/qml-intro/sequential-animation1.qml b/doc/src/snippets/declarative/qml-intro/sequential-animation1.qml
new file mode 100644
index 0000000..125f99f
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/sequential-animation1.qml
@@ -0,0 +1,23 @@
+import Qt 4.7
+
+Rectangle {
+    id: mainRec
+    width:  600
+    height: 400
+    z: 0
+
+    Image {
+        id: image1
+        source: "images/qt-logo.png"
+        x: 20; y: 20 ; z: 1
+        width: 100; height: 100
+    }
+
+    Image {
+        id: image2
+        source: "images/qt-logo.png"
+        width: 100; height: 100
+        x: (mainRec.width - 100)/2; y: (mainRec.height - 100)/2
+        z: 2
+    }
+}
diff --git a/doc/src/snippets/declarative/qml-intro/sequential-animation2.qml b/doc/src/snippets/declarative/qml-intro/sequential-animation2.qml
new file mode 100644
index 0000000..08c598b
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/sequential-animation2.qml
@@ -0,0 +1,33 @@
+import Qt 4.7
+
+Rectangle {
+    id: mainRec
+    width:  600
+    height: 400
+    z: 0
+
+//! [adding a sequential animation]
+    Image {
+        id: image1
+        source: "images/qt-logo.png"
+        width: 100; height: 100
+
+        SequentialAnimation on x {
+            loops: Animation.Infinite
+            NumberAnimation {
+                from: 20; to: 450; easing.type: "InOutQuad";
+                duration: 2000
+            }
+            PauseAnimation { duration: 500 }
+        }
+    }
+//! [adding a sequential animation]
+
+    Image {
+        id: image2
+        source: "images/qt-logo.png"
+        width: 100; height: 100
+        x: (mainRec.width - 100)/2; y: (mainRec.height - 100)/2
+        z: 2
+    }
+}
diff --git a/doc/src/snippets/declarative/qml-intro/sequential-animation3.qml b/doc/src/snippets/declarative/qml-intro/sequential-animation3.qml
new file mode 100644
index 0000000..5e7b400
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/sequential-animation3.qml
@@ -0,0 +1,46 @@
+Rectangle {
+    id: mainRec
+    width:  600
+    height: 400
+    z: 0
+
+    Image {
+        id: image2
+        source: "images/qt-logo.png"
+        width: 100; height: 100
+        x: (mainRec.width - 100)/2; y: (mainRec.height - 100)/2
+        z: 2
+    }
+
+    Image {
+        id: image1
+        source: "images/qt-logo.png"
+        x: 20; y: 20 ; z: 1
+        width: 100; height: 100
+
+        SequentialAnimation on x {
+            loops: Animation.Infinite
+            NumberAnimation {
+                from: 20; to: 450
+                easing.type: "InOutQuad"; duration: 2000
+            }
+            PauseAnimation { duration: 500 }
+        }
+
+        SequentialAnimation on y {
+            loops: Animation.Infinite
+            NumberAnimation {
+                from: 20; to: 250
+                easing.type: "InOutQuad"; duration: 2000
+            }
+            PauseAnimation { duration: 500 }
+        }
+
+        SequentialAnimation on scale {
+            loops: Animation.Infinite
+            NumberAnimation { from: 1; to: 0.5; duration: 1000 }
+            NumberAnimation { from: 0.5; to: 1; duration: 1000 }
+            PauseAnimation { duration: 500 }
+        }
+    }
+}
diff --git a/doc/src/snippets/declarative/qml-intro/states1.qml b/doc/src/snippets/declarative/qml-intro/states1.qml
new file mode 100644
index 0000000..fcd3f53
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/states1.qml
@@ -0,0 +1,52 @@
+import Qt 4.7
+
+Rectangle {
+    id: mainRectangle
+    width:  600
+    height: 400
+    color: "black"
+
+    Rectangle {
+        id: sky
+        width: 600
+        height: 200
+        y: 0
+        color: "lightblue"
+    }
+
+    Rectangle {
+        id: ground
+        width: 600; height: 200
+        y: 200
+        color: "green"
+    }
+
+    MouseArea {
+        id: mousearea
+        anchors.fill: mainRectangle
+    }
+
+    states: [ State {
+            name: "night"
+            when: mousearea.pressed == true
+            PropertyChanges { target: sky; color: "darkblue" }
+            PropertyChanges { target: ground; color: "black" }
+        },
+        State {
+            name: "daylight"
+            when: mousearea.pressed == false
+            PropertyChanges { target: sky; color: "lightblue" }
+            PropertyChanges { target: ground; color: "green" }
+        }
+    ]
+
+    transitions: [ Transition {
+            from: "daylight"; to: "night"
+            ColorAnimation { duration: 1000 }
+        },
+        Transition {
+            from: "night"; to: "daylight"
+            ColorAnimation { duration: 500 }
+        }
+    ]
+}
diff --git a/doc/src/snippets/declarative/qml-intro/transformations1.qml b/doc/src/snippets/declarative/qml-intro/transformations1.qml
new file mode 100644
index 0000000..1504729
--- /dev/null
+++ b/doc/src/snippets/declarative/qml-intro/transformations1.qml
@@ -0,0 +1,38 @@
+import Qt 4.7
+
+Rectangle {
+    id: myWin
+    width: 500
+    height: 400
+
+    Image {
+        id: image1
+        source: "images/qt-logo.png"
+        width: 150; height: 150
+        anchors.bottom: myWin.bottom
+        anchors.horizontalCenter: myWin.horizontalCenter
+        anchors.bottomMargin: 10
+
+        transform: Rotation {
+            origin.x: 75; origin.y: 75
+            axis{ x: 0; y: 0; z:1 }  angle: -90
+        }
+
+    }
+
+    Text {
+        text: "<h2>The Qt Logo -- taking it easy</h2>"
+        anchors.bottom: image1.top
+        anchors.horizontalCenter: myWin.horizontalCenter
+        anchors.bottomMargin: 15
+
+        transform: [
+            Scale { xScale: 1.5; yScale: 1.2 } ,
+
+            Rotation {
+                origin.x: 75; origin.y: 75
+                axis{ x: 0; y: 0; z:1 }  angle: -45
+            }
+        ]
+    }
+}