/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \example animation/moveblocks

    \title Move Blocks Example

    The Move Blocks example shows how to animate items in a

    QGraphicsScene using a QStateMachine with a custom transition.

    \image moveblocks-example.png

    The example animates the blue blocks that you can see in the image

    above. The animation moves the blocks between four preset positions.

    The example consists of the following classes:

    \list

        \o \c StateSwitcher inherits QState and can add

              \c {StateSwitchTransition}s to other states.

              When entered, it will randomly transition to one of these

              states. 

        \o \c StateSwitchTransition is a custom transition that

           triggers on \c{StateSwitchEvent}s.

        \o \c StateSwitchEvent is a QEvent that trigger \c{StateSwitchTransition}s.

        \o \c QGraphicsRectWidget is a QGraphicsWidget that simply

           paints its background in a solid \l{Qt::}{blue} color.

    \endlist

    The blocks are instances of \c QGraphicsRectWidget and are

    animated in a QGraphicsScene. We do this by building a state

    graph, which we insert animations into. The graph is then executed

    in a QStateMachine. All this is done in \c main().

    Let's look at the \c main() function first.

    \section1 The \c main() Function

    After QApplication has been initialized, we set up the

    QGraphicsScene with its \c{QGraphicsRectWidget}s.

    \snippet examples/animation/moveblocks/main.cpp 1

    After adding the scene to a QGraphicsView, it is time to build the

    state graph. Let's first look at a statechart of what we are

    trying to build.

    \image move-blocks-chart.png

    Note that the \c group has seven sub states, but we have only

    included three of them in the diagram. The code that builds this

    graph will be examined line-by-line, and will show how the graph

    works. First off, we construct the \c group state:

    \snippet examples/animation/moveblocks/main.cpp 2

    The timer is used to add a delay between each time the blocks are

    moved. The timer is started when \c group is entered. As we will

    see later, \c group has a transition back to the \c StateSwitcher

    when the timer times out. \c group is the initial state in the

    machine, so an animation will be scheduled when the example is

    started.

    \snippet examples/animation/moveblocks/main.cpp 3

    \dots

    \snippet examples/animation/moveblocks/main.cpp 4

    \c createGeometryState() returns a QState that will set the

    geometry of our items upon entry. It also assigns \c group as the

    parent of this state.

    A QPropertyAnimation inserted into a transition will use the

    values assigned to a QState (with QState::assignProperty()), i.e.,

    the animation will interpolate between the current values of the

    properties and the values in the target state. We add animated

    transitions to the state graph later.

    \snippet examples/animation/moveblocks/main.cpp 5

    We move the items in parallel. Each item is added to \c

    animationGroup, which is the animation that is inserted into the

    transitions.

    \snippet examples/animation/moveblocks/main.cpp 6 

    The sequential animation group, \c subGroup, helps us insert a

    delay between the animation of each item.

    \snippet examples/animation/moveblocks/main.cpp 7

    \dots

    \snippet examples/animation/moveblocks/main.cpp 8

    A StateSwitchTransition is added to the state switcher

    in \c StateSwitcher::addState(). We also add the animation in this

    function. Since QPropertyAnimation uses the values from the

    states, we can insert the same QPropertyAnimation instance in all

    \c {StateSwitchTransition}s.

    As mentioned previously, we add a transition to the state switcher

    that triggers when the timer times out.

    \snippet examples/animation/moveblocks/main.cpp 9

    Finally, we can create the state machine, add our initial state,

    and start execution of the state graph.

    \section2 The \c createGemetryState() Function

    In \c createGeometryState(), we set up the geometry for each

    graphics item.

    \snippet examples/animation/moveblocks/main.cpp 13

    As mentioned before, QAbstractTransition will set up an animation

    added with \l{QAbstractTransition::}{addAnimation()} using

    property values set with \l{QState::}{assignProperty()}.

    \section1 The StateSwitcher Class

    \c StateSwitcher has state switch transitions to each \l{QState}s

    we created with \c createGemetryState(). Its job is to transition

    to one of these states at random when it is entered.

    All functions in \c StateSwitcher are inlined. We'll step through

    its definition.

    \snippet examples/animation/moveblocks/main.cpp 10

    \c StateSwitcher is a state designed for a particular purpose and

    will always be a top-level state. We use \c m_stateCount to keep

    track of how many states we are managing, and \c m_lastIndex to

    remember which state was the last state to which we transitioned. 

    \snippet examples/animation/moveblocks/main.cpp 11

    We select the next state we are going to transition to, and post a

    \c StateSwitchEvent, which we know will trigger the \c

    StateSwitchTransition to the selected state.

    \snippet examples/animation/moveblocks/main.cpp 12

    This is where the magic happens. We assign a number to each state

    added. This number is given to both a StateSwitchTransition and to

    StateSwitchEvents. As we have seen, state switch events will

    trigger a transition with the same number.

    \section1 The StateSwitchTransition Class

    \c StateSwitchTransition inherits QAbstractTransition and triggers

    on \c{StateSwitchEvent}s. It contains only inline functions, so

    let's take a look at its \l{QAbstractTransition::}{eventTest()}

    function, which is the only function that we define..

    \snippet examples/animation/moveblocks/main.cpp 14

    \c eventTest is called by QStateMachine when it checks whether a

    transition should be triggered--a return value of true means that

    it will. We simply check if our assigned number is equal to the

    event's number (in which case we fire away).

    \section1 The StateSwitchEvent Class

    \c StateSwitchEvent inherits QEvent, and holds a number that has

    been assigned to a state and state switch transition by

    \c StateSwitcher. We have already seen how it is used to trigger

    \c{StateSwitchTransition}s in \c StateSwitcher.

    \snippet examples/animation/moveblocks/main.cpp 15

    We only have inlined functions in this class, so a look at its

    definition will do.

    \section1 The QGraphicsRectWidget Class

    QGraphicsRectWidget inherits QGraphicsWidget and simply paints its

    \l{QWidget::}{rect()} blue. We inline \l{QWidget::}{paintEvent()},

    which is the only function we define. Here is the

    QGraphicsRectWidget class definition:

    \snippet examples/animation/moveblocks/main.cpp 16

    \section1 Moving On

    The technique shown in this example works equally well for all

    \l{QPropertyAnimation}s. As long as the value to be animated is a

    Qt property, you can insert an animation of it into a state graph.

    QState::addAnimation() takes a QAbstractAnimation, so any type

    of animation can be inserted into the graph.

*/