summaryrefslogtreecommitdiffstats
path: root/doc/src/animation.qdoc
blob: 081660cf66f7110dde801d38361fe4375655c349 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** 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.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at qt-sales@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page animation.html
    \title The Animation Framework
    \ingroup architecture
    \ingroup animation
    \brief An overview of the Animation Framework

    \keyword Animation

    The animation framework is part of the Kinetic project, and aims
    to provide an easy way for creating animated and smooth GUI's.  By
    animating Qt properties, the framework provides great freedom for
    animating widgets and other \l{QObject}s. The framework can also
    be used with the Graphics View framework.

    In this overview, we explain the basics of its architecture. We
    also show examples of the most common techniques that the
    framework allows for animating QObjects and graphics items.

    \tableofcontents

    \section1 The Animation Architecture

    We will in this section take a high-level look at the animation
    framework's architecture and how it is used to animate Qt
    properties.

    The animation framework foundation consists of the base class
    QAbstractAnimation, and its two subclasses QVariantAnimation and
    QAnimationGroup. QAbstractAnimation is the ancestor of all
    animations. It represents basic properties that are common for all
    animations in the framework; notably, the ability to start, stop,
    and pause an animation. It is also receives the time change
    notifications.

    The animation framework further provides the QPropertyAnimation
    class, which inherits QVariantAnimation and performs animation of
    a Qt property, which is part of Qt's \l{Meta-Object
    System}{meta-object system}. The class performs an interpolation
    over the property using an easing curve. So when you want to
    animate a value, you can declare it as a property and make your
    class a QObject. Note that this gives us great freedom in
    animating already existing widgets and other \l{QObject}s.

    Complex animations can be constructed by building a tree structure
    of \l{QAbstractAnimation}s. The tree is built by using
    \l{QAnimationGroup}s, which function as containers for other
    animations. Note also that the groups are subclasses of
    QAbstractAnimation, so groups can themselves contain other groups.

    The animation framework can be used on its own, but is also
    designed to be part of the state machine framework (See the
    \l{The State Machine Framework}{state machine framework} for an
    introduction to the Qt state machine). The state machine provides
    a special state that can play an animation. A QState can also set
    properties when the state is entered or exited, and this special
    animation state will interpolate between these values when given a
    QPropertyAnimation. We will look more closely at this later.

    Behind the scenes, the animations are controlled by a global
    timer, which sends \l{QAbstractAnimation::updateCurrentTime()}{updates} to
    all animations that are playing.

    For detailed descriptions of the classes' function and roles in
    the framework, please look up their class descriptions.

    \section1 Animating Qt Properties

    As mentioned in the previous section, the QPropertyAnimation class
    can interpolate over Qt properties. It is this class that should
    be used for animation of values; in fact, its superclass,
    QVariantAnimation, is an abstract class, and cannot be used
    directly.

    A major reason we chose to animate Qt properties is that it
    presents us with freedom to animate already existing classes in
    the Qt API. Notably, the QWidget class (which we can also embed in
    a QGraphicsView) has properties for its bounds, colors, etc.
    Let's look at a small example:

    \code
        QPushButton button("Animated Button");
        button.show();

        QPropertyAnimation animation(&button, "geometry");
        animation.setDuration(10000);
        animation.setStartValue(QRect(0, 0, 100, 30));
        animation.setEndValue(QRect(250, 250, 100, 30));

        animation.start();
    \endcode

    This code will move \c button from the top left corner of the
    screen to the position (250, 250).

    The example above will do a linear interpolation between the
    start and end value. It is also possible to set values
    situated between the start and end value. The interpolation
    will then go by these points.

    \code
        QPushButton button("Animated Button");
        button.show();

        QPropertyAnimation animation(&button, "geometry");
        animation.setDuration(10000);

        animation.setKeyValueAt(0, QRect(0, 0, 100, 30));
        animation.setKeyValueAt(0.8, QRect(250, 250, 100, 30));
        animation.setKeyValueAt(1, QRect(0, 0, 100, 30));

        animation.start();
    \endcode

    In this example, the animation will take the button to (250, 250)
    in 8 seconds, and then move it back to its original position in
    the remaining 2 seconds. The movement will be linearly
    interpolated between these points.

    You also have the possibility to animate values of a QObject
    that is not declared as a Qt property. The only requirement is
    that this value has a setter. You can then subclass the class
    containing the value and declare a property that uses this setter.
    Note that all Qt properties requires a getter, so you will need to
    provide a getter yourself if this is not defined.

    \code
        class MyGraphicsRectItem : public QObject, public QGraphicsRectItem
        {
            Q_OBJECT
            Q_PROPERTY(QRectF geometry READ geometry WRITE setGeometry)
        };
    \endcode

    In the above code example, we subclass QGraphicsRectItem and
    define a geometry property. We can now animate the widgets
    geometry even if QGraphicsRectItem does not provide the geometry
    property.

    For a general introduction to the Qt property system, see its
    \l{Qt's Property System}{overview}.

    \section1 Animations and the Graphics View Framework

    When you want to animate \l{QGraphicsItem}s, you also use
    QPropertyAnimation. But, unfortunetly, QGraphicsItem does not
    inherit QObject. A good solution is to subclass the graphics item
    you wish to animate. This class will then also inherit QObject.
    This way, QPropertyAnimation can be used for \l{QGraphicsItem}s.
    The example below shows how this is done. Another possibility is
    to inherit QGraphicsWidget, which already is a QObject.

    \code
        class Pixmap : public QObject, public QGraphicsPixmapItem
        {
            Q_OBJECT
            Q_PROPERTY(QPointF pos READ pos WRITE setPos)
            ...
    \endcode

    As described in the previous section, we need to define
    properties that we wish to animate.

    Note that QObject must be the first class inherited as the
    meta-object system demands this.

    \warning The QItemAnimation class, which was initially intended
    for animating \l{QGraphicsItem}s may be deprecated or removed from
    the animation framework.

    \omit (need something about the list of animations). \endomit

    \section1 Easing Curves

    As mentioned, QPropertyAnimation performs an interpolation between
    the start and end property value. In addition to adding more key
    values to the animation, you can also use an easing curve. Easing
    curves describe a function that controls how the speed of the
    interpolation between 0 and 1 should be, and are useful if you
    want to control the speed of an animation without changing the
    path of the interpolation.

    \code
        QPushButton button("Animated Button");
        button.show();

        QPropertyAnimation animation(&button, "geometry");
        animation.setDuration(3000);
        animation.setStartValue(QRect(0, 0, 100, 30));
        animation.setEndValue(QRect(250, 250, 100, 30));

        animation.setEasingCurve(QEasingCurve::OutBounce);

        animation.start();
    \endcode

    Here the animation will follow a curve that makes it bounce like a
    ball as if it was dropped from the start to the end position.
    QEasingCurve has a large collection of curves for you to choose
    from. These are defined by the QEasingCurve::Type enum. If you are
    in need of another curve, you can also implement one yourself, and
    register it with QEasingCurve.

    \omit Drop this for the first Lab release
    (Example of custom easing curve (without the actual impl of
    the function I expect)
    \endomit

    \section1 Putting Animations Together

    An application will often contain more than one animation. For
    instance, you might want to move more than one graphics item
    simultaneously or move them in sequence after each other.

    The subclasses of QAnimationGroup (QSequentialAnimationGroup and
    QParallelAnimationGroup) are containers for other animations so
    that these animations can be animated either in sequence or
    parallel. The QAnimationGroup is an example of an animation that
    does not animate properties, but it gets notified of time changes
    periodically. This enables it to forward those time changes to its
    contained animations, and thereby controlling when its animations
    are played.

    Let's look at code examples that use both
    QSequentialAnimationGroup and QParallelAnimationGroup, starting
    off with the latter.

    \code
        QPushButton *bonnie = new QPushButton("Bonnie");
        bonnie.show();

        QPushButton *clyde = new QPushButton("Clyde");
        clyde.show();

        QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "geometry");
        // Set up anim1

        QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "geometry");
        // Set up anim2

        QParallelAnimationGroup *group = new QParallelAnimationGroup;
        group->addAnimation(anim1);
        group->addAnimation(anim2);

        group->start();
    \endcode

    A parallel group plays more than one animation at the same time.
    Calling its \l{QAbstractAnimation::}{start()} function will start
    all animations it governs.

    \code
        QPushButton button("Animated Button");
        button.show();

        QPropertyAnimation anim1(&button, "geometry");
        anim1.setDuration(3000);
        anim1.setStartValue(QRect(0, 0, 100, 30));
        anim1.setEndValue(QRect(500, 500, 100, 30));

        QPropertyAnimation anim2(&button, "geometry");
        anim2.setDuration(3000);
        anim2.setStartValue(QRect(500, 500, 100, 30));
        anim2.setEndValue(QRect(1000, 500, 100, 30));

        QSequentialAnimationGroup group;

        group.addAnimation(&anim1);
        group.addAnimation(&anim2);

        group.start();
    \endcode

    As you no doubt have guessed, QSequentialAnimationGroup plays
    its animations in sequence. It starts the next animation in
    the list after the previous is finished.

    Since an animation group is an animation itself, you can add
    it to another group. This way, you can build a tree structure
    of animations which specifies when the animations are played
    in relation to each other.

    \section1 Animations and States

    When using a \l{The State Machine Framework}{state machine}, we
    have a special state, QAnimationState, that will play one or more
    animations.
        
    The QState::addAnimatedTransition() convenience function lets you
    associate an animation to a state transition. The function will
    create the QAnimationState for you, and insert it into the state
    machine. We also have the possibility to associate properties with
    the states rather than setting the start and end values ourselves.
    Below is a complete code example that animates the geometry of a
    QPushButton.

    \code
        QPushButton *button = new QPushButton("Animated Button");
        button->show();

        QStateMachine *machine = new QStateMachine;

        QState *state1 = new QState(machine->rootState());
        state1->setPropertyOnEntry(button, "geometry",
                               QRect(0, 0, 100, 30));
        machine->setInitialState(state1);

        QState *state2 = new QState(machine->rootState());
        state2->setPropertyOnEntry(button, "geometry",
                                   QRect(250, 250, 100, 30));

        state1->addAnimatedTransition(button, SIGNAL(clicked()), state2,
            new QPropertyAnimation(button, "geometry"));
        state2->addAnimatedTransition(button, SIGNAL(clicked()), state1,
            new QPropertyAnimation(button, "geometry"));

        machine->start();
    \endcode

    For a more comprehensive example of how to use the state machine
    framework for animations, see the states example (it lives in the
    \c{examples/animation/states} directory).
*/