summaryrefslogtreecommitdiffstats
path: root/doc/src/animation.qdoc
diff options
context:
space:
mode:
authorMichael Brasser <michael.brasser@nokia.com>2009-04-22 04:47:24 (GMT)
committerMichael Brasser <michael.brasser@nokia.com>2009-04-22 04:47:24 (GMT)
commit2366667fc97eb6a56203b2dd7dac776ff4164abd (patch)
treeb2acb6cc6bfe475d7e619e4788973b61fff775e0 /doc/src/animation.qdoc
parent2c762f3b8b284a7c6dc0c499b7052013bad5b707 (diff)
downloadQt-2366667fc97eb6a56203b2dd7dac776ff4164abd.zip
Qt-2366667fc97eb6a56203b2dd7dac776ff4164abd.tar.gz
Qt-2366667fc97eb6a56203b2dd7dac776ff4164abd.tar.bz2
Initial import of kinetic-dui branch from the old kinetic
Diffstat (limited to 'doc/src/animation.qdoc')
-rw-r--r--doc/src/animation.qdoc365
1 files changed, 365 insertions, 0 deletions
diff --git a/doc/src/animation.qdoc b/doc/src/animation.qdoc
new file mode 100644
index 0000000..081660c
--- /dev/null
+++ b/doc/src/animation.qdoc
@@ -0,0 +1,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).
+*/
+