Add documentation to the Animated Tiles example

Pick-to: 6.1
Task-number: QTBUG-89834
Change-Id: I732071c6c526194abc402f28fcb4d13a0a496263
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>

3 files changed, 79 insertions, 0 deletions

diff --git a/examples/statemachine/animation/animatedtiles/main.cpp b/examples/statemachine/animation/animatedtiles/main.cpp
index 29670bb..8f19047 100644
--- a/examples/statemachine/animation/animatedtiles/main.cpp
+++ b/examples/statemachine/animation/animatedtiles/main.cpp
@@ -149,6 +149,7 @@ int main(int argc, char **argv)
     QPixmap kineticPix(":/images/kinetic.png");
     QPixmap bgPix(":/images/Time-For-Lunch-2.jpg");
 
+//! [0]
     QGraphicsScene scene(-350, -350, 700, 700);
 
     QList<Pixmap *> items;
@@ -159,7 +160,9 @@ int main(int argc, char **argv)
         items << item;
         scene.addItem(item);
     }
+//! [0]
 
+//! [1]
     // Buttons
     QGraphicsItem *buttonParent = new QGraphicsRectItem;
     Button *ellipseButton = new Button(QPixmap(":/images/ellipse.png"), buttonParent);
@@ -178,7 +181,9 @@ int main(int argc, char **argv)
     buttonParent->setTransform(QTransform::fromScale(0.75, 0.75), true);
     buttonParent->setPos(200, 200);
     buttonParent->setZValue(65);
+//! [1]
 
+//! [2]
     // States
     QState *rootState = new QState;
     QState *ellipseState = new QState(rootState);
@@ -186,7 +191,9 @@ int main(int argc, char **argv)
     QState *randomState = new QState(rootState);
     QState *tiledState = new QState(rootState);
     QState *centeredState = new QState(rootState);
+//! [2]
 
+//! [3]
     // Values
     for (int i = 0; i < items.count(); ++i) {
         Pixmap *item = items.at(i);
@@ -213,7 +220,9 @@ int main(int argc, char **argv)
         // Centered
         centeredState->assignProperty(item, "pos", QPointF());
     }
+//! [3]
 
+//! [4]
     // Ui
     View *view = new View(&scene);
     view->setWindowTitle(QT_TRANSLATE_NOOP(QGraphicsView, "Animated Tiles"));
@@ -222,12 +231,16 @@ int main(int argc, char **argv)
     view->setCacheMode(QGraphicsView::CacheBackground);
     view->setRenderHints(QPainter::Antialiasing | QPainter::SmoothPixmapTransform);
     view->show();
+//! [4]
 
+//! [5]
     QStateMachine states;
     states.addState(rootState);
     states.setInitialState(rootState);
     rootState->setInitialState(centeredState);
+//! [5]
 
+//! [6]
     QParallelAnimationGroup *group = new QParallelAnimationGroup;
     for (int i = 0; i < items.count(); ++i) {
         QPropertyAnimation *anim = new QPropertyAnimation(items[i], "pos");
@@ -235,6 +248,9 @@ int main(int argc, char **argv)
         anim->setEasingCurve(QEasingCurve::InOutBack);
         group->addAnimation(anim);
     }
+//! [6]
+
+//! [7]
     QAbstractTransition *trans = rootState->addTransition(ellipseButton, &Button::pressed, ellipseState);
     trans->addAnimation(group);
 
@@ -249,7 +265,9 @@ int main(int argc, char **argv)
 
     trans = rootState->addTransition(centeredButton, &Button::pressed, centeredState);
     trans->addAnimation(group);
+//! [7]
 
+//! [8]
     QTimer timer;
     timer.start(125);
     timer.setSingleShot(true);
@@ -257,6 +275,7 @@ int main(int argc, char **argv)
     trans->addAnimation(group);
 
     states.start();
+//! [8]
 
 #ifdef QT_KEYPAD_NAVIGATION
     QApplication::setNavigationMode(Qt::NavigationModeCursorAuto);
diff --git a/examples/statemachine/doc/images/animated-tiles-chart.png b/examples/statemachine/doc/images/animated-tiles-chart.png
new file mode 100644
index 0000000..59ea437
--- /dev/null
+++ b/examples/statemachine/doc/images/animated-tiles-chart.png
diff --git a/examples/statemachine/doc/src/animatedtiles.qdoc b/examples/statemachine/doc/src/animatedtiles.qdoc
index 3d1d5d4..6b16230 100644
--- a/examples/statemachine/doc/src/animatedtiles.qdoc
+++ b/examples/statemachine/doc/src/animatedtiles.qdoc
@@ -32,6 +32,66 @@
 
     \brief The Animated Tiles example animates items in a graphics scene.
 
+    The example demonstrates how QStateMachine states can be used to animate
+    positions of graphical objects. There are five states in the application that
+    can be triggered by five buttons. The buttons initiate state transitions
+    that animate the positions of 64 QGraphicsPixmapItem images.
+
     \image animatedtiles-example.png
+
+    \section1 The \c main() Function
+
+    \snippet animation/animatedtiles/main.cpp 0
+
+    The QGraphicsScene is created, then the 64 images are created and added to the scene
+    with the initial position of the center of the window.
+    The Pixmap class is defined in the example that extends the QGraphicsPixmapItem so that
+    its position can be read and written as Qt properties.
+
+    \snippet animation/animatedtiles/main.cpp 1
+
+    Then the five buttons are created and added to a QGraphicsItem for easier positioning.
+    The Button class is defined in the example. It extends QGraphicsWidget and implements
+    displaying a QPixmap on a circular background with shading based on its pressed state.
+
+    \snippet animation/animatedtiles/main.cpp 2
+
+    The states are created and added to a root state.
+
+    \image animated-tiles-chart.png
+
+    Having the five states as child states of \c rootState allows state transitions from any
+    of the child states to any other child state if the state transitions are set up from
+    \c rootState to the child states.
+
+    \snippet animation/animatedtiles/main.cpp 3
+
+    For each image, the position properties are set to each state based on a function that
+    creates the required shape. The states set these properties to the images when the
+    given state is entered.
+
+    \snippet animation/animatedtiles/main.cpp 4
+
+    The QGraphicsView is created and set up with the required properties.
+
+    \snippet animation/animatedtiles/main.cpp 5
+
+    The state machine is created and the previously created states are added with the \c rootState
+    set as the initial state.
+
+    \snippet animation/animatedtiles/main.cpp 6
+
+    The QParallelAnimationGroup is created with a QPropertyAnimation for each item that animates
+    the item position values.
+
+    \snippet animation/animatedtiles/main.cpp 7
+
+    The state transitions are created with the button presses as their triggers and the animation
+    group assigned to them.
+
+    \snippet animation/animatedtiles/main.cpp 8
+
+    An initial state transition is set up from root to ellipse state that is triggered with a
+    QTimer after application start.
 */