← Back to branch summary

~ubuntu-branches/ubuntu/wily/qtbase-opensource-src/wily

« back to all changes in this revision

Viewing changes to src/corelib/doc/src/animation.qdoc

  • Committer: Package Import Robot
  • Author(s): Timo Jyrinki
  • Date: 2013-02-05 12:46:17 UTC
  • Revision ID: package-import@ubuntu.com-20130205124617-c8jouts182j002fx
Tags: upstream-5.0.1+dfsg
Import upstream version 5.0.1+dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/corelib/doc/src/animation.qdoc
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
 
4
** Contact: http://www.qt-project.org/legal
 
5
**
 
6
** This file is part of the documentation of the Qt Toolkit.
 
7
**
 
8
** $QT_BEGIN_LICENSE:FDL$
 
9
** Commercial License Usage
 
10
** Licensees holding valid commercial Qt licenses may use this file in
 
11
** accordance with the commercial license agreement provided with the
 
12
** Software or, alternatively, in accordance with the terms contained in
 
13
** a written agreement between you and Digia.  For licensing terms and
 
14
** conditions see http://qt.digia.com/licensing.  For further information
 
15
** use the contact form at http://qt.digia.com/contact-us.
 
16
**
 
17
** GNU Free Documentation License Usage
 
18
** Alternatively, this file may be used under the terms of the GNU Free
 
19
** Documentation License version 1.3 as published by the Free Software
 
20
** Foundation and appearing in the file included in the packaging of
 
21
** this file.  Please review the following information to ensure
 
22
** the GNU Free Documentation License version 1.3 requirements
 
23
** will be met: http://www.gnu.org/copyleft/fdl.html.
 
24
** $QT_END_LICENSE$
 
25
**
 
26
****************************************************************************/
 
27
 
 
28
/*!
 
29
    \group animation
 
30
    \title Animation Framework
 
31
 
 
32
    This page lists classes belonging to \l{Qt Core}'s
 
33
    \l{The Animation Framework}{animation framework}.
 
34
 
 
35
*/
 
36
 
 
37
/*!
 
38
    \page animation-overview.html
 
39
    \title The Animation Framework
 
40
    \ingroup qt-gui-concepts
 
41
 
 
42
    \brief An overview of the Animation Framework
 
43
 
 
44
    \ingroup frameworks-technologies
 
45
 
 
46
    \keyword Animation
 
47
 
 
48
    The animation framework aims to provide an easy way for creating animated
 
49
    and smooth GUI's. By animating Qt properties, the framework provides great
 
50
    freedom for animating widgets and other \l{QObject}s. The framework can
 
51
    also be used with the Graphics View framework. Many of the concepts
 
52
    available in the animation framework are also available in \l{Qt Quick},
 
53
    where it offers a declarative way of defining animations. Much of the
 
54
    knowledge acquired about the animation framework can be applied to
 
55
    \l{Qt Quick}.
 
56
 
 
57
    In this overview, we explain the basics of its architecture. We
 
58
    also show examples of the most common techniques that the
 
59
    framework allows for animating QObjects and graphics items.
 
60
 
 
61
    \tableofcontents
 
62
 
 
63
    \section1 The Animation Architecture
 
64
 
 
65
    We will in this section take a high-level look at the animation
 
66
    framework's architecture and how it is used to animate Qt
 
67
    properties. The following diagram shows the most important classes
 
68
    in the animation framework.
 
69
 
 
70
    \image animations-architecture.png
 
71
 
 
72
    The animation framework foundation consists of the base class
 
73
    QAbstractAnimation, and its two subclasses QVariantAnimation and
 
74
    QAnimationGroup. QAbstractAnimation is the ancestor of all
 
75
    animations. It represents basic properties that are common for all
 
76
    animations in the framework; notably, the ability to start, stop,
 
77
    and pause an animation. It is also receives the time change
 
78
    notifications.
 
79
 
 
80
    The animation framework further provides the QPropertyAnimation
 
81
    class, which inherits QVariantAnimation and performs animation of
 
82
    a Qt property, which is part of Qt's \l{Meta-Object
 
83
    System}{meta-object system}. The class performs an interpolation
 
84
    over the property using an easing curve. So when you want to
 
85
    animate a value, you can declare it as a property and make your
 
86
    class a QObject. Note that this gives us great freedom in
 
87
    animating already existing widgets and other \l{QObject}s.
 
88
 
 
89
    Complex animations can be constructed by building a tree structure
 
90
    of \l{QAbstractAnimation}s. The tree is built by using
 
91
    \l{QAnimationGroup}s, which function as containers for other
 
92
    animations. Note also that the groups are subclasses of
 
93
    QAbstractAnimation, so groups can themselves contain other groups.
 
94
 
 
95
    The animation framework can be used on its own, but is also
 
96
    designed to be part of the state machine framework (See the
 
97
    \l{The State Machine Framework}{state machine framework} for an
 
98
    introduction to the Qt state machine). The state machine provides
 
99
    a special state that can play an animation. A QState can also set
 
100
    properties when the state is entered or exited, and this special
 
101
    animation state will interpolate between these values when given a
 
102
    QPropertyAnimation. We will look more closely at this later.
 
103
 
 
104
    Behind the scenes, the animations are controlled by a global
 
105
    timer, which sends \l{QAbstractAnimation::updateCurrentTime()}{updates} to
 
106
    all animations that are playing.
 
107
 
 
108
    For detailed descriptions of the classes' function and roles in
 
109
    the framework, please look up their class descriptions.
 
110
 
 
111
    \section1 Classes in the Animation Framework
 
112
 
 
113
    These classes provide a framework for creating both simple and complex
 
114
    animations.
 
115
 
 
116
    \annotatedlist animation
 
117
 
 
118
    \section1 Animating Qt Properties
 
119
 
 
120
    As mentioned in the previous section, the QPropertyAnimation class
 
121
    can interpolate over Qt properties. It is this class that should
 
122
    be used for animation of values; in fact, its superclass,
 
123
    QVariantAnimation, is an abstract class, and cannot be used
 
124
    directly.
 
125
 
 
126
    A major reason we chose to animate Qt properties is that it
 
127
    presents us with freedom to animate already existing classes in
 
128
    the Qt API. Notably, the QWidget class (which we can also embed in
 
129
    a QGraphicsView) has properties for its bounds, colors, etc.
 
130
    Let's look at a small example:
 
131
 
 
132
    \code
 
133
        QPushButton button("Animated Button");
 
134
        button.show();
 
135
 
 
136
        QPropertyAnimation animation(&button, "geometry");
 
137
        animation.setDuration(10000);
 
138
        animation.setStartValue(QRect(0, 0, 100, 30));
 
139
        animation.setEndValue(QRect(250, 250, 100, 30));
 
140
 
 
141
        animation.start();
 
142
    \endcode
 
143
 
 
144
    This code will move \c button from the top left corner of the
 
145
    screen to the position (250, 250) in 10 seconds (10000 milliseconds).
 
146
 
 
147
    The example above will do a linear interpolation between the
 
148
    start and end value. It is also possible to set values
 
149
    situated between the start and end value. The interpolation
 
150
    will then go by these points.
 
151
 
 
152
    \code
 
153
        QPushButton button("Animated Button");
 
154
        button.show();
 
155
 
 
156
        QPropertyAnimation animation(&button, "geometry");
 
157
        animation.setDuration(10000);
 
158
 
 
159
        animation.setKeyValueAt(0, QRect(0, 0, 100, 30));
 
160
        animation.setKeyValueAt(0.8, QRect(250, 250, 100, 30));
 
161
        animation.setKeyValueAt(1, QRect(0, 0, 100, 30));
 
162
 
 
163
        animation.start();
 
164
    \endcode
 
165
 
 
166
    In this example, the animation will take the button to (250, 250)
 
167
    in 8 seconds, and then move it back to its original position in
 
168
    the remaining 2 seconds. The movement will be linearly
 
169
    interpolated between these points.
 
170
 
 
171
    You also have the possibility to animate values of a QObject
 
172
    that is not declared as a Qt property. The only requirement is
 
173
    that this value has a setter. You can then subclass the class
 
174
    containing the value and declare a property that uses this setter.
 
175
    Note that each Qt property requires a getter, so you will need to
 
176
    provide a getter yourself if this is not defined.
 
177
 
 
178
    \code
 
179
        class MyGraphicsRectItem : public QObject, public QGraphicsRectItem
 
180
        {
 
181
            Q_OBJECT
 
182
            Q_PROPERTY(QRectF geometry READ geometry WRITE setGeometry)
 
183
        };
 
184
    \endcode
 
185
 
 
186
    In the above code example, we subclass QGraphicsRectItem and
 
187
    define a geometry property. We can now animate the widgets
 
188
    geometry even if QGraphicsRectItem does not provide the geometry
 
189
    property.
 
190
 
 
191
    For a general introduction to the Qt property system, see its
 
192
    \l{Qt's Property System}{overview}.
 
193
 
 
194
    \section1 Animations and the Graphics View Framework
 
195
 
 
196
    When you want to animate \l{QGraphicsItem}s, you also use
 
197
    QPropertyAnimation. However, QGraphicsItem does not inherit QObject.
 
198
    A good solution is to subclass the graphics item you wish to animate.
 
199
    This class will then also inherit QObject.
 
200
    This way, QPropertyAnimation can be used for \l{QGraphicsItem}s.
 
201
    The example below shows how this is done. Another possibility is
 
202
    to inherit QGraphicsWidget, which already is a QObject.
 
203
 
 
204
    \code
 
205
        class Pixmap : public QObject, public QGraphicsPixmapItem
 
206
        {
 
207
            Q_OBJECT
 
208
            Q_PROPERTY(QPointF pos READ pos WRITE setPos)
 
209
            ...
 
210
    \endcode
 
211
 
 
212
    As described in the previous section, we need to define
 
213
    properties that we wish to animate.
 
214
 
 
215
    Note that QObject must be the first class inherited as the
 
216
    meta-object system demands this.
 
217
 
 
218
    \section1 Easing Curves
 
219
 
 
220
    As mentioned, QPropertyAnimation performs an interpolation between
 
221
    the start and end property value. In addition to adding more key
 
222
    values to the animation, you can also use an easing curve. Easing
 
223
    curves describe a function that controls how the speed of the
 
224
    interpolation between 0 and 1 should be, and are useful if you
 
225
    want to control the speed of an animation without changing the
 
226
    path of the interpolation.
 
227
 
 
228
    \code
 
229
        QPushButton button("Animated Button");
 
230
        button.show();
 
231
 
 
232
        QPropertyAnimation animation(&button, "geometry");
 
233
        animation.setDuration(3000);
 
234
        animation.setStartValue(QRect(0, 0, 100, 30));
 
235
        animation.setEndValue(QRect(250, 250, 100, 30));
 
236
 
 
237
        animation.setEasingCurve(QEasingCurve::OutBounce);
 
238
 
 
239
        animation.start();
 
240
    \endcode
 
241
 
 
242
    Here the animation will follow a curve that makes it bounce like a
 
243
    ball as if it was dropped from the start to the end position.
 
244
    QEasingCurve has a large collection of curves for you to choose
 
245
    from. These are defined by the QEasingCurve::Type enum. If you are
 
246
    in need of another curve, you can also implement one yourself, and
 
247
    register it with QEasingCurve.
 
248
 
 
249
    \omit Drop this for the first Lab release
 
250
    (Example of custom easing curve (without the actual impl of
 
251
    the function I expect)
 
252
    \endomit
 
253
 
 
254
    \section1 Putting Animations Together
 
255
 
 
256
    An application will often contain more than one animation. For
 
257
    instance, you might want to move more than one graphics item
 
258
    simultaneously or move them in sequence after each other.
 
259
 
 
260
    The subclasses of QAnimationGroup (QSequentialAnimationGroup and
 
261
    QParallelAnimationGroup) are containers for other animations so
 
262
    that these animations can be animated either in sequence or
 
263
    parallel. The QAnimationGroup is an example of an animation that
 
264
    does not animate properties, but it gets notified of time changes
 
265
    periodically. This enables it to forward those time changes to its
 
266
    contained animations, and thereby controlling when its animations
 
267
    are played.
 
268
 
 
269
    Let's look at code examples that use both
 
270
    QSequentialAnimationGroup and QParallelAnimationGroup, starting
 
271
    off with the latter.
 
272
 
 
273
    \code
 
274
        QPushButton *bonnie = new QPushButton("Bonnie");
 
275
        bonnie->show();
 
276
 
 
277
        QPushButton *clyde = new QPushButton("Clyde");
 
278
        clyde->show();
 
279
 
 
280
        QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "geometry");
 
281
        // Set up anim1
 
282
 
 
283
        QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "geometry");
 
284
        // Set up anim2
 
285
 
 
286
        QParallelAnimationGroup *group = new QParallelAnimationGroup;
 
287
        group->addAnimation(anim1);
 
288
        group->addAnimation(anim2);
 
289
 
 
290
        group->start();
 
291
    \endcode
 
292
 
 
293
    A parallel group plays more than one animation at the same time.
 
294
    Calling its \l{QAbstractAnimation::}{start()} function will start
 
295
    all animations it governs.
 
296
 
 
297
    \code
 
298
        QPushButton button("Animated Button");
 
299
        button.show();
 
300
 
 
301
        QPropertyAnimation anim1(&button, "geometry");
 
302
        anim1.setDuration(3000);
 
303
        anim1.setStartValue(QRect(0, 0, 100, 30));
 
304
        anim1.setEndValue(QRect(500, 500, 100, 30));
 
305
 
 
306
        QPropertyAnimation anim2(&button, "geometry");
 
307
        anim2.setDuration(3000);
 
308
        anim2.setStartValue(QRect(500, 500, 100, 30));
 
309
        anim2.setEndValue(QRect(1000, 500, 100, 30));
 
310
 
 
311
        QSequentialAnimationGroup group;
 
312
 
 
313
        group.addAnimation(&anim1);
 
314
        group.addAnimation(&anim2);
 
315
 
 
316
        group.start();
 
317
    \endcode
 
318
 
 
319
    As you no doubt have guessed, QSequentialAnimationGroup plays
 
320
    its animations in sequence. It starts the next animation in
 
321
    the list after the previous is finished.
 
322
 
 
323
    Since an animation group is an animation itself, you can add
 
324
    it to another group. This way, you can build a tree structure
 
325
    of animations which specifies when the animations are played
 
326
    in relation to each other.
 
327
 
 
328
    \section1 Animations and States
 
329
 
 
330
    When using a \l{The State Machine Framework}{state machine}, we
 
331
    can associate one or more animations to a transition between states
 
332
    using a QSignalTransition or QEventTransition class. These classes
 
333
    are both derived from QAbstractTransition, which defines the
 
334
    convenience function \l{QAbstractTransition::}{addAnimation()} that
 
335
    enables the appending of one or more animations triggered when the
 
336
    transition occurs.
 
337
 
 
338
    We also have the possibility to associate properties with the
 
339
    states rather than setting the start and end values ourselves.
 
340
    Below is a complete code example that animates the geometry of a
 
341
    QPushButton.
 
342
 
 
343
    \code
 
344
        QPushButton *button = new QPushButton("Animated Button");
 
345
        button->show();
 
346
 
 
347
        QStateMachine *machine = new QStateMachine;
 
348
 
 
349
        QState *state1 = new QState(machine);
 
350
        state1->assignProperty(button, "geometry", QRect(0, 0, 100, 30));
 
351
        machine->setInitialState(state1);
 
352
 
 
353
        QState *state2 = new QState(machine);
 
354
        state2->assignProperty(button, "geometry", QRect(250, 250, 100, 30));
 
355
 
 
356
        QSignalTransition *transition1 = state1->addTransition(button,
 
357
            SIGNAL(clicked()), state2);
 
358
        transition1->addAnimation(new QPropertyAnimation(button, "geometry"));
 
359
 
 
360
        QSignalTransition *transition2 = state2->addTransition(button,
 
361
            SIGNAL(clicked()), state1);
 
362
        transition2->addAnimation(new QPropertyAnimation(button, "geometry"));
 
363
 
 
364
        machine->start();
 
365
    \endcode
 
366
 
 
367
    For a more comprehensive example of how to use the state machine
 
368
    framework for animations, see the states example (it lives in the
 
369
    \c{examples/animation/states} directory).
 
370
*/