/**************************************************************************** ** ** Copyright (C) 2010 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:FDL$ ** Commercial Usage ** Licensees holding valid Qt Commercial licenses may use this file in ** accordance with the Qt Commercial License Agreement provided with the ** Software or, alternatively, in accordance with the terms contained in a ** written agreement between you and Nokia. ** ** GNU Free Documentation License ** Alternatively, this file may be used under the terms of the GNU Free ** Documentation License version 1.3 as published by the Free Software ** Foundation and appearing in the file included in the packaging of this ** file. ** ** 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 triggers \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 createGeometryState() 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 createGeometryState(). 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. */