Merge branch 'kinetic-animations' into kinetic-statemachine

4 files changed, 114 insertions, 44 deletions

diff --git a/src/corelib/animation/qabstractanimation.cpp b/src/corelib/animation/qabstractanimation.cpp
index 93ecc73..f5b9323 100644
--- a/src/corelib/animation/qabstractanimation.cpp
+++ b/src/corelib/animation/qabstractanimation.cpp
@@ -156,13 +156,13 @@
 #include <QtCore/qcoreevent.h>
 #include <QtCore/qpointer.h>
 
-#define TIMER_INTERVAL 16
+#define DEFAULT_TIMER_INTERVAL 16
 
 QT_BEGIN_NAMESPACE
 
 Q_GLOBAL_STATIC(QThreadStorage<QUnifiedTimer *>, unifiedTimer);
 
-QUnifiedTimer::QUnifiedTimer() : QObject(), lastTick(0), consistentTimingInterval(0)
+QUnifiedTimer::QUnifiedTimer() : QObject(), lastTick(0), timingInterval(DEFAULT_TIMER_INTERVAL), consistentTiming(false)
 {
 }
 
@@ -190,13 +190,29 @@ void QUnifiedTimer::updateRecentlyStartedAnimations()
 }
 
 /*
-   this allows to haeve a consistent timer interval at each tick from the timer
+  defines the timing interval. Default is DEFAULT_TIMER_INTERVAL
+*/
+void QUnifiedTimer::setTimingInterval(int interval)
+{
+    timingInterval = interval;
+    if (animationTimer.isActive()) {
+        //we changed the timing interval
+        animationTimer.start(timingInterval, this);
+    }
+}
+
+/*
+   this allows to have a consistent timer interval at each tick from the timer
    not taking the real time that passed into account.
-   Just set this to 0 if you want to get back to a time-driven behaviour.
- */
-void QUnifiedTimer::setConsitentTiming(int interval)
+*/
+void QUnifiedTimer::setConsistentTiming(bool b)
+{
+    consistentTiming = b;
+}
+
+int QUnifiedTimer::elapsedTime() const
 {
-    consistentTimingInterval = interval;
+    return lastTick;
 }
 
 void QUnifiedTimer::timerEvent(QTimerEvent *event)
@@ -204,7 +220,7 @@ void QUnifiedTimer::timerEvent(QTimerEvent *event)
     //this is simply the time we last received a tick
     const int oldLastTick = lastTick;
     if (time.isValid())
-        lastTick = consistentTimingInterval > 0 ? oldLastTick + consistentTimingInterval : time.elapsed();
+        lastTick = consistentTiming ? oldLastTick + timingInterval : time.elapsed();
 
     //we transfer the waiting animations into the "really running" state
     updateRecentlyStartedAnimations();
@@ -215,7 +231,7 @@ void QUnifiedTimer::timerEvent(QTimerEvent *event)
             animationTimer.stop();
             time = QTime();
         } else {
-            animationTimer.start(TIMER_INTERVAL, this);
+            animationTimer.start(timingInterval, this);
             lastTick = 0;
             time.start();
         }
diff --git a/src/corelib/animation/qabstractanimation_p.h b/src/corelib/animation/qabstractanimation_p.h
index 0e10b9a..41983a5 100644
--- a/src/corelib/animation/qabstractanimation_p.h
+++ b/src/corelib/animation/qabstractanimation_p.h
@@ -110,7 +110,7 @@ private:
 };
 
 
-class QUnifiedTimer : public QObject
+class Q_CORE_EXPORT QUnifiedTimer : public QObject
 {
 private:
     QUnifiedTimer();
@@ -118,13 +118,17 @@ private:
 public:
     static QUnifiedTimer *instance();
 
-    void timerEvent(QTimerEvent *);
-    void updateTimer();
     void registerAnimation(QAbstractAnimation *animation);
     void unregisterAnimation(QAbstractAnimation *animation);
 
-    void setConsitentTiming(int interval);
+    void setTimingInterval(int interval);
+    void setConsistentTiming(bool consistent);
+
+    int elapsedTime() const;
 
+protected:
+    void timerEvent(QTimerEvent *);
+    void updateTimer();
 
 private:
     void updateRecentlyStartedAnimations();
@@ -132,7 +136,8 @@ private:
     QBasicTimer animationTimer, startStopAnimationTimer;
     QTime time;
     int lastTick;
-    int consistentTimingInterval;
+    int timingInterval;
+    bool consistentTiming;
     QList<QAbstractAnimation*> animations, animationsToStart;
 };
 
diff --git a/src/corelib/animation/qanimationgroup.cpp b/src/corelib/animation/qanimationgroup.cpp
index 03573bb..2f8cc28 100644
--- a/src/corelib/animation/qanimationgroup.cpp
+++ b/src/corelib/animation/qanimationgroup.cpp
@@ -46,18 +46,46 @@
     \ingroup animation
     \preliminary
 
-    QAnimationGroup represents a group of animations, such as parallel or sequential,
-    and lets you combine different animations into one. The group manages any animation
-    that inherits QAbstractAnimation. By combining groups, you can easily construct
-    complex animation graphs.
-
-    The QAnimationGroup base class provides methods for adding and retrieving animations.
-    Besides that, you can remove animations by calling remove(), and clear the animation
-    group by calling clearAnimations(). You may keep track of changes in the group's animations by
-    listening to QEvent::ChildAdded and QEvent::ChildRemoved events.
-
-    QAnimationGroup takes ownership of the animations it manages, and ensures that they are
-    deleted when the animation group is deleted.
+    An animation group is a container for animations (subclasses of
+    QAbstractAnimation). A group is usually responsible for managing
+    the \l{QAbstractAnimation::State}{state} of its animations, i.e.,
+    it decides when to start, stop, resume, and pause them. Currently,
+    Qt provides two such groups: QParallelAnimationGroup and
+    QSequentialAnimationGroup. Look up their class descriptions for
+    details.
+
+    Since QAnimationGroup inherits from QAbstractAnimation, you can
+    combine groups, and easily construct complex animation graphs.
+    You can query QAbstractAnimation for the group it belongs to
+    (using the \l{QAbstractAnimation::}{group()} function).
+
+    To start a top-level animation group, you simply use the
+    \l{QAbstractAnimation::}{start()} function from
+    QAbstractAnimation. By a top-level animation group, we think of a
+    group that itself is not contained within another group. Starting
+    sub groups directly is not supported, and may lead to unexpected
+    behavior.
+
+    \omit OK, we'll put in a snippet on this here \endomit
+
+    QAnimationGroup provides methods for adding and retrieving
+    animations. Besides that, you can remove animations by calling
+    remove(), and clear the animation group by calling
+    clearAnimations(). You may keep track of changes in the group's
+    animations by listening to QEvent::ChildAdded and
+    QEvent::ChildRemoved events.
+
+    \omit OK, let's find a snippet here as well. \endomit
+
+    QAnimationGroup takes ownership of the animations it manages, and
+    ensures that they are deleted when the animation group is deleted.
+
+    You can also use a \l{The State Machine Framework}{state machine}
+    to create complex animations. The framework provides a special
+    state, QAnimationState, that plays an animation upon entry and
+    transitions to a new state when the animation has finished
+    playing. This technique can also be combined with using animation
+    groups.
 
     \sa QAbstractAnimation, QVariantAnimation, {The Animation Framework}
 */
diff --git a/src/corelib/animation/qpropertyanimation.cpp b/src/corelib/animation/qpropertyanimation.cpp
index 65e2f57..96cfa6b 100644
--- a/src/corelib/animation/qpropertyanimation.cpp
+++ b/src/corelib/animation/qpropertyanimation.cpp
@@ -41,27 +41,48 @@
 
 /*!
     \class QPropertyAnimation
-    \brief The QPropertyAnimation class animates properties for QObject(and QWidget)
+    \brief The QPropertyAnimation class animates Qt properties
     \ingroup animation
     \preliminary
 
-    This class is part of {The Animation Framework}.  You can use QPropertyAnimation
-    by itself as a simple animation class, or as part of more complex
-    animations through QAnimationGroup.
-
-    The most common way to use QPropertyAnimation is to construct an instance
-    of it by passing a pointer to a QObject or a QWidget, and the name of the
-    property you would like to animate to QPropertyAnimation's constructor.
-
-    The start value of the animation is optional. If you do not set any start
-    value, the animation will operate on the target's current property value
-    at the point when the animation was started. You can call setStartValue()
-    to set the start value, and setEndValue() to set the target value for
-    the animated property.
-
-    Animations can operate on QObjects and QWidgets. You can choose to assign a
-    target object by either calling setTargetObject() or by passing a QObject
-    pointer to QPropertyAnimation's constructor.
+    QPropertyAnimation interpolates over \l{Qt's Property System}{Qt
+    properties}. As property values are stored in \l{QVariant}s, the
+    class inherits QVariantAnimation, and supports animation of the
+    same \l{QVariant::Type}{variant types} as its super class. 
+
+    A class declaring properties must be a QObject. To make it
+    possible to animate a property, it must provide a setter (so that
+    QPropertyAnimation can set the property's value). Note that this
+    makes it possible to animate many of Qt's widgets. Let's look at
+    an example:
+    
+    \code
+        QPropertyAnimation animation(myWidget, "geometry");
+        animation.setDuration(10000);
+        animation.setStartValue(QRect(0, 0, 100, 30));
+        animation.setEndValue(QRect(250, 250, 100, 30));
+
+        animation.start();
+    \endcode
+
+    The property name and the QObject instance of which property
+    should be animated are passed to the constructor. You can then
+    specify the start and end value of the property. The procedure is
+    equal for properties in classes you have implemented
+    yourself--just check with QVariantAnimation that your QVariant
+    type is supported.
+
+    The QVariantAnimation class description explains how to set up the
+    animation in detail. Note, however, that if a start value is not
+    set, the property will start at the value it had when the
+    QPropertyAnimation instance was created.
+
+    QPropertyAnimation works like a charm on its own. For complex
+    animations that, for instance, contain several objects,
+    QAnimationGroup is provided. An animation group is an animation
+    that can contain other animations, and that can manage when its
+    animations are played. Look at QParallelAnimationGroup for an
+    example.
 
     \sa QVariantAnimation, QAnimationGroup, {The Animation Framework}
 */