1 files changed, 21 insertions, 8 deletions
diff --git a/doc/src/declarative/qmlstates.qdoc b/doc/src/declarative/qmlstates.qdoc
index ddb0fc8..245a57f 100644
--- a/doc/src/declarative/qmlstates.qdoc
+++ b/doc/src/declarative/qmlstates.qdoc
@@ -3,6 +3,8 @@
 \target qmlstates
 \title QML States
 
+\section1 Overview
+
 QML states typically describe user interface configurations, including:
 \list
 \o What UI elements are present
@@ -14,10 +16,12 @@ A state can also be thought of as a set of batched changes from a default config
 
 Examples of states in modern UI:
 \list
-\o A Contacts application has a 'View Contact' state and an 'Edit Contact' State. In the first state the information presented is static (using labels), and in the second it is editable (using editors).
-\o A button has a pressed and unpressed state. When pressed the text moves down and to the right, and the button has a slightly darker appearance.
+\o An Address Book application with a 'View Contact' state and an 'Edit Contact' State. In the first state the contact information presented is read-only (using labels), and in the second it is editable (using editors).
+\o A button with a pressed and unpressed state. When pressed the text moves slightly down and to the right, and the button has a slightly darker appearance.
 \endlist
 
+\section1 States in QML
+
 In QML:
 \list
 \o Any object can use states.
@@ -25,29 +29,38 @@ 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
 
-The following example shows a simple use of states. In the default state \c myrect is positioned at 0,0. In the 'moved' state it is positioned at 50,50.
+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 region changes the state from the default state to the 'moved' state.
 
-\code
+\qml
 Item {
+    id: myItem
+
     Rectangle {
-        id: myrect
+        id: myRect
         width: 100
         height: 100
+        color: "red"
     }
+
     states: [
         State {
             name: "moved"
             PropertyChanges {
-                target: myrect
+                target: myRect
                 x: 50
                 y: 50
             }
         }
     ]
+
+    MouseRegion {
+        anchors.fill: parent
+        onClicked: myItem.state = 'moved'
+    }
 }
-\endcode
+\endqml
 
-To animate state changes, you can use \l{state-transitions}{transitions}.
+State changes can be animated using \l{state-transitions}{transitions}.
 
 Other things you can do in a state change:
 \list