Move some example code into snippets/ and add other doc fixes

7 files changed, 277 insertions, 167 deletions

diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc
index 6e98949..c320898 100644
--- a/doc/src/declarative/animation.qdoc
+++ b/doc/src/declarative/animation.qdoc
@@ -46,14 +46,14 @@
 Animation in QML is done by animating properties of objects. Properties of type
 real, int, color, rect, point, size, and vector3d can all be animated.
 
-QML supports three main forms of animation - basic property animation,
+QML supports three main forms of animation: basic property animation,
 transitions, and property behaviors.
 
 \tableofcontents
 
 \section1 Basic Property Animation
 
-The simplest form of animation is directly using \l PropertyAnimation, which can animate all of the property
+The simplest form of animation is a \l PropertyAnimation, which can animate all of the property
 types listed above. If the property you are animating is a number or color, you can alternatively use
 NumberAnimation or ColorAnimation. These elements don't add any additional functionality,
 but will help enforce type correctness and are slightly more efficient.
@@ -62,61 +62,23 @@ A property animation can be specified as a value source using the \e Animation \
 for repeating animations.
 
 The following example creates a bouncing effect:
-\qml
-Rectangle {
-    id: rect
-    width: 120; height: 200;
-    Image {
-        id: img
-        source: "qt-logo.png"
-        x: 60-img.width/2
-        y: 0
-        SequentialAnimation on y {
-            loops: Animation.Infinite
-            NumberAnimation { to: 200-img.height; easing.type: Easing.OutBounce; duration: 2000 }
-            PauseAnimation { duration: 1000 }
-            NumberAnimation { to: 0; easing.type: Easing.OutQuad; duration: 1000 }
-        }
-    }
-}
-\endqml
+\snippet doc/src/snippets/declarative/animation.qml property-anim-1
 
 \image propanim.gif
 
 When you assign an animation as a value source, you do not need to specify \c property
-or \c target; they are automatically selected for you. You do, however, need to specify \c to.
+or \c target values; they are automatically selected for you. You do, however, need to specify a \c to value.
 An animation specified as a value source will be \c running by default.
 
-\qml
-Rectangle {
-    id: rect
-    width: 200; height: 200;
-    Rectangle {
-        color: "red"
-        width: 50; height: 50
-        NumberAnimation on x { to: 50 }
-    }
-}
-\endqml
+For example, here is a rectangle that uses a \l NumberAnimation value source to animate the movement
+from its current position to an \c x value of 50. The animation starts immediately, and only the \c to 
+property is required:
+
+\snippet doc/src/snippets/declarative/animation.qml property-anim-2
 
 A property animation can also be specified as a resource that is manipulated from script.
 
-\qml
-PropertyAnimation {
-    id: animation
-    target: image
-    property: "scale"
-    from: 1; to: .5
-}
-Image {
-    id: image
-    source: "image.png"
-    MouseArea {
-        anchors.fill: parent
-        onPressed: animation.start()
-    }
-}
-\endqml
+\snippet doc/src/snippets/declarative/animation.qml property-anim-3
 
 As can be seen, when an animation is used like this (as opposed to as a value source) you will need
 to explicitly set the \c target and \c property to animate.
@@ -131,50 +93,20 @@ can only be triggered by a state change.
 
 For example, a transition could describe how an item moves from its initial position to its new position:
 
-\code
-transitions: [
-    Transition {
-        NumberAnimation {
-            properties: "x,y"
-            easing.type: Easing.OutBounce
-            duration: 200
-        }
-    }
-]
-\endcode
+\snippet doc/src/snippets/declarative/animation.qml transitions-1
 
 As can be seen, transitions make use of the same basic animation classes introduced above.
 In the above example we have specified that we want to animate the \c x and \c y properties, but have not
-specified the objects to animate or the \c to values. By default these values are supplied by the framework --
+specified the objects to animate or the \c to values. By default these values are supplied by the framework;
 the animation will animate any \c targets whose \c x and \c y have changed, and the \c to values will be those
 defined in the end state. You can always supply explicit values to override these implicit values when needed.
 
-\code
-Transition {
-    from: "*"
-    to: "MyState"
-    reversible: true
-    SequentialAnimation {
-        NumberAnimation {
-            duration: 1000
-            easing.type: Easing.OutBounce
-            // animate myItem's x and y if they have changed in the state
-            target: myItem
-            properties: "x,y"
-        }
-        NumberAnimation {
-            duration: 1000
-            // animate myItem2's y to 200, regardless of what happens in the state
-            target: myItem2
-            property: "y"
-            to: 200
-        }
-    }
-}
-\endcode
+\snippet doc/src/snippets/declarative/animation.qml transitions-2
 
 QML transitions have selectors to determine which state changes a transition should apply to.
 The following transition will only be triggered when we enter into the \c "details" state.
+(The "*" value is a wildcard value that specifies the transition should be applied when changing
+from \e any state to the "details" state.)
 
 \code
 Transition {
@@ -188,30 +120,7 @@ Transitions can happen in parallel, in sequence, or in any combination of the tw
 animations in a transition will happen in parallel. The following example shows a rather complex transition
 making use of both sequential and parallel animations:
 
-\code
-Transition {
-    from: "*"
-    to: "MyState"
-    reversible: true
-    SequentialAnimation {
-        ColorAnimation { duration: 1000 }
-        PauseAnimation { duration: 1000 }
-        ParallelAnimation {
-            NumberAnimation {
-                duration: 1000
-                easing.type: Easing.OutBounce
-                targets: box1
-                properties: "x,y"
-            }
-            NumberAnimation {
-                duration: 1000
-                targets: box2
-                properties: "x,y"
-            }
-        }
-    }
-}
-\endcode
+\snippet doc/src/snippets/declarative/animation.qml transitions-3
 
 \section1 Property Behaviors
 
@@ -219,24 +128,15 @@ A \l{Behavior}{property behavior} specifies a default animation to run whenever
 of what caused the change. The \c enabled property can be used to force a \l Behavior
 to only apply under certain circumstances.
 
-In the following snippet, we specify that we want the x position of redRect to be animated
-whenever it changes. The animation will last 300 milliseconds and use an InOutQuad easing curve.
+In the following snippet, we specify that we want the \c x position of \c redRect to be animated
+whenever it changes. The animation will last 300 milliseconds and use an \l{PropertyAnimation::easing.type}{Easing.InOutQuad} easing curve.
 
-\qml
-Rectangle {
-    id: redRect
-    color: "red"
-    width: 100; height: 100
-    Behavior on x { NumberAnimation { duration: 300; easing.type: Easing.InOutQuad } }
-}
-\endqml
+\snippet doc/src/snippets/declarative/animation.qml behavior
 
 Like using an animation as a value source, when used in a Behavior and animation does not need to specify
 a \c target or \c property.
 
-To trigger this behavior, we could:
-\list
-\o Enter a state that changes x
+To trigger this behavior, we could enter a state that changes \c x:
 
 \qml
 State {
@@ -249,7 +149,7 @@ State {
 }
 \endqml
 
-\o Update x from a script
+Or, update \c x from a script:
 
 \qml
 MouseArea {
@@ -257,11 +157,10 @@ MouseArea {
     onClicked: redRect.x = 24;
 }
 \endqml
-\endlist
 
-If x were bound to another property, triggering the binding would also trigger the behavior.
+If \c x were bound to another property, triggering the binding would also trigger the behavior.
 
-If a state change has a transition animation matching a property with a Behavior, the transition animation
-will override the Behavior for that state change.
+If a state change has a transition animation matching a property with a \l Behavior, the transition animation
+will override the \l Behavior for that state change.
 
 */
diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc
index fd0c677..43b5c31 100644
--- a/doc/src/declarative/qdeclarativestates.qdoc
+++ b/doc/src/declarative/qdeclarativestates.qdoc
@@ -70,58 +70,30 @@ In QML:
 \o A state can affect the properties of other objects, not just the object owning the state (and not just that object's children).
 \endlist
 
+To define a state for an item, add a \l State element to the \l{Item::states}{states} property. To
+change the current state of an \l Item, set the \l{Item::state}{state} property to the name
+of the required state.
+
 Here is an example of using states. In the default state \c myRect is positioned at 0,0. In the 'moved' state it is positioned at 50,50. Clicking within the mouse area changes the state from the default state to the 'moved' state, thus moving the rectangle.
 
-\qml
-Item {
-    id: myItem
-
-    Rectangle {
-        id: myRect
-        width: 100
-        height: 100
-        color: "red"
-    }
-
-    states: [
-        State {
-            name: "moved"
-            PropertyChanges {
-                target: myRect
-                x: 50
-                y: 50
-            }
-        }
-    ]
-
-    MouseArea {
-        anchors.fill: parent
-        onClicked: myItem.state = 'moved'
-    }
-}
-\endqml
+\snippet doc/src/snippets/declarative/states.qml 0
+\snippet doc/src/snippets/declarative/states.qml 1
 
 State changes can be animated using \l{state-transitions}{Transitions}.
 
-For example, adding this code to the above \c {Item {}} element animates the transition to the "moved" state:
+For example, adding this code to the above \c Item element animates the transition to the "moved" state:
 
-\qml
-    transitions: [
-        Transition {
-            NumberAnimation { properties: "x,y"; duration: 500 }
-        }
-    ]
-\endqml
+\snippet doc/src/snippets/declarative/states.qml transitions
 
 See \l{state-transitions}{Transitions} for more information.
 
 
 Other things you can do in a state change:
 \list
-\o override signal handlers with PropertyChanges
-\o change an item's visual parent with ParentChange
-\o change an item's anchors with AnchorChanges
-\o run some script with StateChangeScript
+\o Override signal handlers with PropertyChanges
+\o Change an item's visual parent with ParentChange
+\o Change an item's anchors with AnchorChanges
+\o Run some script with StateChangeScript
 \endlist
 
 */
diff --git a/doc/src/snippets/declarative/anchorchanges.qml b/doc/src/snippets/declarative/anchorchanges.qml
new file mode 100644
index 0000000..6c0a0ad
--- /dev/null
+++ b/doc/src/snippets/declarative/anchorchanges.qml
@@ -0,0 +1,28 @@
+//![0]
+import Qt 4.7
+
+Item {
+    id: window
+    width: 200; height: 200
+
+    Rectangle { id: myRect; width: 100; height: 100; color: "red" }
+
+    states: State {
+        name: "reanchored"
+
+        AnchorChanges {
+            target: myRect
+            anchors.top: window.top
+            anchors.bottom: window.bottom
+        }
+        PropertyChanges {
+            target: myRect
+            anchors.topMargin: 3
+            anchors.bottomMargin: 3
+        }
+    }
+
+    MouseArea { anchors.fill: parent; onClicked: window.state = "reanchored" }
+}
+//![0]
+
diff --git a/doc/src/snippets/declarative/animation.qml b/doc/src/snippets/declarative/animation.qml
new file mode 100644
index 0000000..f5c6bf6
--- /dev/null
+++ b/doc/src/snippets/declarative/animation.qml
@@ -0,0 +1,141 @@
+import Qt 4.7
+
+Row {
+
+//![property-anim-1]
+Rectangle {
+    id: rect
+    width: 120; height: 200
+
+    Image {
+        id: img
+        source: "pics/qt.png"
+        x: 60 - img.width/2
+        y: 0
+
+        SequentialAnimation on y {
+            loops: Animation.Infinite
+            NumberAnimation { to: 200 - img.height; easing.type: Easing.OutBounce; duration: 2000 }
+            PauseAnimation { duration: 1000 }
+            NumberAnimation { to: 0; easing.type: Easing.OutQuad; duration: 1000 }
+        }
+    }
+}
+//![property-anim-1]
+
+//![property-anim-2]
+Rectangle {
+    width: 200; height: 200
+
+    Rectangle {
+        color: "red"
+        width: 50; height: 50
+        NumberAnimation on x { to: 50 }
+    }
+}
+//![property-anim-2]
+
+
+Item {
+//![property-anim-3]
+PropertyAnimation {
+    id: animation
+    target: image
+    property: "scale"
+    from: 1; to: 0.5
+}
+
+Image {
+    id: image
+    source: "pics/qt.png"
+    MouseArea {
+        anchors.fill: parent
+        onPressed: animation.start()
+    }
+}
+//![property-anim-3]
+}
+
+
+//![transitions-1]
+transitions: [
+    Transition {
+        NumberAnimation {
+            properties: "x,y"
+            easing.type: Easing.OutBounce
+            duration: 200
+        }
+    }
+]
+//![transitions-1]
+
+
+//![transitions-2]
+Transition {
+    from: "*"
+    to: "MyState"
+    reversible: true
+
+    SequentialAnimation {
+        NumberAnimation {
+            duration: 1000
+            easing.type: Easing.OutBounce
+
+            // animate myItem's x and y if they have changed in the state
+            target: myItem
+            properties: "x,y"
+        }
+
+        NumberAnimation {
+            duration: 1000
+
+            // animate myItem2's y to 200, regardless of what happens in the state
+            target: myItem2
+            property: "y"
+            to: 200
+        }
+    }
+}
+//![transitions-2]
+
+
+//![transitions-3]
+Transition {
+    from: "*"
+    to: "MyState"
+    reversible: true
+
+    SequentialAnimation {
+        ColorAnimation { duration: 1000 }
+        PauseAnimation { duration: 1000 }
+
+        ParallelAnimation {
+            NumberAnimation {
+                duration: 1000
+                easing.type: Easing.OutBounce
+                targets: box1
+                properties: "x,y"
+            }
+            NumberAnimation {
+                duration: 1000
+                targets: box2
+                properties: "x,y"
+            }
+        }
+    }
+}
+//![transitions-3]
+
+//![behavior]
+Rectangle {
+    id: redRect
+    color: "red"
+    width: 100; height: 100
+
+    Behavior on x { 
+        NumberAnimation { duration: 300; easing.type: Easing.InOutQuad }
+    }
+}
+//![behavior]
+
+}
diff --git a/doc/src/snippets/declarative/createQmlObject.qml b/doc/src/snippets/declarative/createQmlObject.qml
index f2ac6e6..f274e40 100644
--- a/doc/src/snippets/declarative/createQmlObject.qml
+++ b/doc/src/snippets/declarative/createQmlObject.qml
@@ -42,7 +42,7 @@
 import Qt 4.7
 
 Rectangle {
-    id: targetItem
+    id: parentItem
     property QtObject newObject
 
     width: 100
@@ -51,7 +51,7 @@ Rectangle {
     function createIt() {
 //![0]
 newObject = Qt.createQmlObject('import Qt 4.7; Rectangle {color: "red"; width: 20; height: 20}',
-    targetItem, "dynamicSnippet1");
+    parentItem, "dynamicSnippet1");
 //![0]
     }
 
diff --git a/doc/src/snippets/declarative/state.qml b/doc/src/snippets/declarative/state.qml
new file mode 100644
index 0000000..0954298
--- /dev/null
+++ b/doc/src/snippets/declarative/state.qml
@@ -0,0 +1,29 @@
+//![0]
+import Qt 4.7
+
+Rectangle {
+    id: myRect
+    width: 100; height: 100
+    color: "black"
+
+    states: [
+        State {
+            name: "clicked"
+            PropertyChanges {
+                target: myRect
+                color: "red"
+            }
+        }
+    ]
+
+    MouseArea {
+        anchors.fill: parent
+        onClicked: {
+            if (myRect.state == "")     // i.e. the default state
+                myRect.state = "clicked";
+            else
+                myRect.state = "";
+        }
+    }
+}
+//![0]
diff --git a/doc/src/snippets/declarative/states.qml b/doc/src/snippets/declarative/states.qml
new file mode 100644
index 0000000..7bfb5bd
--- /dev/null
+++ b/doc/src/snippets/declarative/states.qml
@@ -0,0 +1,41 @@
+//![0]
+import Qt 4.7
+
+Item {
+    id: myItem
+    width: 200; height: 200
+
+    Rectangle {
+        id: myRect
+        width: 100; height: 100
+        color: "red"
+    }
+
+    states: [
+        State {
+            name: "moved"
+            PropertyChanges {
+                target: myRect
+                x: 50
+                y: 50
+            }
+        }
+    ]
+
+    MouseArea {
+        anchors.fill: parent
+        onClicked: myItem.state = 'moved'
+    }
+//![0]
+
+//![transitions]
+transitions: [
+    Transition {
+        NumberAnimation { properties: "x,y"; duration: 500 }
+    }
+]
+//![transitions]
+
+//![1]
+}
+//![1]