Add Flipable example.

Task-number: QT-2824

4 files changed, 50 insertions, 38 deletions

diff --git a/examples/declarative/flipable/back.png b/examples/declarative/flipable/back.png
new file mode 100644
index 0000000..0b4cafc
--- /dev/null
+++ b/examples/declarative/flipable/back.png
diff --git a/examples/declarative/flipable/flipable.qml b/examples/declarative/flipable/flipable.qml
new file mode 100644
index 0000000..c837ebc
--- /dev/null
+++ b/examples/declarative/flipable/flipable.qml
@@ -0,0 +1,37 @@
+//! [0]
+import Qt 4.6
+
+Flipable {
+    id: flipable
+    width: 240
+    height: 240
+
+    property int angle: 0
+    property bool flipped: false
+
+    front: Image { source: "front.png" }
+    back: Image { source: "back.png" }
+
+    transform: Rotation {
+        origin.x: flipable.width/2; origin.y: flipable.height/2
+        axis.x: 0; axis.y: 1; axis.z: 0     // rotate around y-axis
+        angle: flipable.angle
+    }
+
+    states: State {
+        name: "back"
+        PropertyChanges { target: flipable; angle: 180 }
+        when: flipable.flipped
+    }
+
+    transitions: Transition {
+        NumberAnimation { properties: "angle"; duration: 1000 }
+    }
+
+    MouseArea {
+        anchors.fill: parent
+        onClicked: flipable.flipped = !flipable.flipped
+    }
+}
+//! [0]
+
diff --git a/examples/declarative/flipable/front.png b/examples/declarative/flipable/front.png
new file mode 100644
index 0000000..796b605
--- /dev/null
+++ b/examples/declarative/flipable/front.png
diff --git a/src/declarative/graphicsitems/qdeclarativeflipable.cpp b/src/declarative/graphicsitems/qdeclarativeflipable.cpp
index b36127f..1ebbaee 100644
--- a/src/declarative/graphicsitems/qdeclarativeflipable.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeflipable.cpp
@@ -68,56 +68,31 @@ public:
     \brief The Flipable item provides a surface that can be flipped.
     \inherits Item
 
-    Flipable allows you to specify a front and a back and then flip between those sides.
+    Flipable is an item that can be visibly "flipped" between its front and
+    back sides. It is used together with Rotation and State/Transition to
+    produce a flipping effect.
 
-    Here's an example that flips between the front and back sides when clicked:
+    Here is a Flipable that flips whenever it is clicked:
 
-    \qml
-
-    Flipable {
-        id: flipable
-        width: 250; height: 250
-        property int angle: 0
-
-        transform: Rotation {
-            id: rotation
-            origin.x: flipable.width/2; origin.y: flipable.height/2
-            axis.x: 0; axis.y: 1; axis.z: 0     // rotate around y-axis
-            angle: flipable.angle
-        }
-
-        front: Image { source: "front.png" }
-        back: Image { source: "back.png" }
-
-        states: State {
-            name: "back"
-            PropertyChanges { target: flipable; angle: 180 }
-        }
-
-        transitions: Transition {
-            NumberAnimation { properties: "angle"; duration: 2000 }
-        }
-
-        MouseArea {
-            // change between default and 'back' states
-            onClicked: flipable.state = (flipable.state == 'back' ? '' : 'back')
-            anchors.fill: parent
-        }
-    }
-    \endqml
+    \snippet examples/declarative/flipable/flipable.qml 0
 
     \image flipable.gif
+
+    The Rotation element is used to specify the angle and axis of the flip,
+    and the State defines the changes in angle which produce the flipping
+    effect. Finally, the Transition creates the animation that changes the
+    angle over one second.
 */
 
 /*!
     \internal
     \class QDeclarativeFlipable
-    \brief The QDeclarativeFlipable class provides a flipable surface.
+    \brief The Flipable item provides a surface that can be flipped.
 
     \ingroup group_widgets
 
-    QDeclarativeFlipable allows you to specify a front and a back, as well as an
-    axis for the flip.
+    Flipable is an item that can be visibly "flipped" between its front and
+    back sides.
 */
 
 QDeclarativeFlipable::QDeclarativeFlipable(QDeclarativeItem *parent)