Merge branch 'kinetic-animations' of git@scm.dev.nokia.troll.no:qt/kinetic into kinetic-animations

8 files changed, 334 insertions, 128 deletions

diff --git a/src/corelib/animation/qabstractanimation.cpp b/src/corelib/animation/qabstractanimation.cpp
index 71ef45c..f5b9323 100644
--- a/src/corelib/animation/qabstractanimation.cpp
+++ b/src/corelib/animation/qabstractanimation.cpp
@@ -42,51 +42,58 @@
 /*!
     \class QAbstractAnimation
     \ingroup animation
-    \brief The QAbstractAnimation class provides an abstract base class for animations.
+    \brief The QAbstractAnimation class is the base of all animations.
     \since 4.5
     \preliminary
 
-    This class is part of \l{The Animation Framework}. It serves as a base class
-    for standard animations and groups, with functions for shared
-    functionality, and it also makes it easy for you to define custom
+    The class defines the functions for the functionality shared by
+    all animations. By inheriting this class, you can create custom
     animations that plug into the rest of the animation framework.
 
-    If you want to create an animation, you should look at the two subclasses,
-    QVariantAnimation and QAnimationGroup, instead.
-
-    QAbstractAnimation provides an interface for the current time and
-    duration, the loop count, and the state of an animation. These properties
-    define the base functionality common to all animations in Qt. The virtual
-    duration() function returns the local duration of the animation; i.e., for
-    how long the animation should update the current time before
-    looping. Subclasses can implement this function differently; for example,
-    QVariantAnimation returns the duration of a simple animated property, whereas
-    QAnimationGroup returns the duration of a set or sequence of
-    animations. You can also set a loop count by calling setLoopCount(); a
-    loop count of 2 will let the animation run twice (the default value is
-    1).
-
-    Like QTimeLine, QAbstractAnimation also provides an interface for starting
-    and stopping an animation, and for tracking its progress. You can call the
-    start() slot to start the animation. When the animation starts, the
-    stateChanged() signal is emitted, and state() returns Running. If you call the
-    stop() slot, the stateChanged() signal is emitted, and state() returns
-    Stopped. If you call the pause() slot, the stateChanged() signal is emitted
-    and state() returns Paused. If the animation reaches the end, the finished()
-    signal is emitted. You can check the current state by calling state().
-
-    QAbstractAnimation provides two functions that are pure virtual, and must
-    be reimplemented in a subclass: duration(), and updateCurrentTime(). The
-    duration() function lets you report a duration for the animation (a return
-    value of -1 signals that the animation runs forever until explicitly
-    stopped). The current time is delivered by the framework through calls to
-    updateCurrentTime(). By reimplementing this function, you can track the
-    animation progress and update your target objects accordingly. By
-    reimplementing updateState(), you can track the animation's state
-    changes, which is particularily useful for animations that are not driven
-    by time.
-
-    \sa QVariantAnimation, QAnimationGroup, {The Animation Framework}
+    The progress of an animation is given by its current time
+    (currentTime()), which is measured in milliseconds from the start
+    of the animation (0) to its end (duration()). The value is updated
+    automatically while the animation is running. It can also be set
+    directly with setCurrentTime().
+
+    At any point an animation is in one of three states:
+    \l{QAbstractAnimation::}{Running},
+    \l{QAbstractAnimation::}{Stopped}, or
+    \l{QAbstractAnimation::}{Paused}--as defined by the
+    \l{QAbstractAnimation::}{State} enum. The current state can be
+    changed by calling start(), stop(), pause(), or resume(). An
+    animation will always reset its \l{currentTime()}{current time}
+    when it is started. If paused, it will continue with the same
+    current time when resumed. When an animation is stopped, it cannot
+    be resumed, but will keep its current time (until started again).
+    QAbstractAnimation will emit stateChanged() whenever its state
+    changes.
+
+    An animation can loop any number of times by setting the loopCount
+    property. When an animation's current time reaches its duration(),
+    it will reset the current time and keep running. A loop count of 1
+    (the default value) means that the animation will run one time.
+    Note that a duration of -1 means that the animation will run until
+    stopped; the current time will increase indefinitely. When the
+    current time equals duration() and the animation is in its
+    final loop, the \l{QAbstractAnimation::}{Stopped} state is
+    entered, and the finished() signal is emitted.
+
+    QAbstractAnimation provides pure virtual functions used by
+    subclasses to track the progress of the animation: duration() and
+    updateCurrentTime(). The duration() function lets you report a
+    duration for the animation (as discussed above). The current time
+    is delivered by the animation framework through calls to
+    updateCurrentTime(). By reimplementing this function, you can
+    track the animation progress. Note that neither the interval
+    between calls nor the number of calls to this function are
+    defined; though, it will normally be 60 updates per second.
+
+    By reimplementing updateState(), you can track the animation's
+    state changes, which is particularly useful for animations that
+    are not driven by time.
+
+    \sa QVariantAnimation, QPropertyAnimation, QAnimationGroup, {The Animation Framework}
 */
 
 /*!
@@ -149,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)
+QUnifiedTimer::QUnifiedTimer() : QObject(), lastTick(0), timingInterval(DEFAULT_TIMER_INTERVAL), consistentTiming(false)
 {
 }
 
@@ -182,12 +189,38 @@ void QUnifiedTimer::updateRecentlyStartedAnimations()
     animationsToStart.clear();
 }
 
+/*
+  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.
+*/
+void QUnifiedTimer::setConsistentTiming(bool b)
+{
+    consistentTiming = b;
+}
+
+int QUnifiedTimer::elapsedTime() const
+{
+    return lastTick;
+}
+
 void QUnifiedTimer::timerEvent(QTimerEvent *event)
 {
     //this is simply the time we last received a tick
-    int oldLastTick = lastTick;
+    const int oldLastTick = lastTick;
     if (time.isValid())
-        lastTick = time.elapsed();
+        lastTick = consistentTiming ? oldLastTick + timingInterval : time.elapsed();
 
     //we transfer the waiting animations into the "really running" state
     updateRecentlyStartedAnimations();
@@ -198,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 666e6a7..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,11 +118,17 @@ private:
 public:
     static QUnifiedTimer *instance();
 
-    void timerEvent(QTimerEvent *);
-    void updateTimer();
     void registerAnimation(QAbstractAnimation *animation);
     void unregisterAnimation(QAbstractAnimation *animation);
 
+    void setTimingInterval(int interval);
+    void setConsistentTiming(bool consistent);
+
+    int elapsedTime() const;
+
+protected:
+    void timerEvent(QTimerEvent *);
+    void updateTimer();
 
 private:
     void updateRecentlyStartedAnimations();
@@ -130,6 +136,8 @@ private:
     QBasicTimer animationTimer, startStopAnimationTimer;
     QTime time;
     int lastTick;
+    int timingInterval;
+    bool consistentTiming;
     QList<QAbstractAnimation*> animations, animationsToStart;
 };
 
diff --git a/src/corelib/animation/qanimationgroup.cpp b/src/corelib/animation/qanimationgroup.cpp
index 0d87527..e0be3f7 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/qparallelanimationgroup.cpp b/src/corelib/animation/qparallelanimationgroup.cpp
index 407ffde..e4bce6a 100644
--- a/src/corelib/animation/qparallelanimationgroup.cpp
+++ b/src/corelib/animation/qparallelanimationgroup.cpp
@@ -46,8 +46,27 @@
     \ingroup animation
     \preliminary
 
-    The animations are all started at the same time, and run in parallel. The animation group
-    finishes when the longest lasting animation has finished.
+    QParallelAnimationGroup--a \l{QAnimationGroup}{container for
+    animations}--starts all its animations when it is
+    \l{QAbstractAnimation::start()}{started} itself, i.e., runs all
+    animations in parallel. The animation group finishes when the
+    longest lasting animation has finished.
+
+    You can treat QParallelAnimation as any other QAbstractAnimation,
+    e.g., pause, resume, or add it to other animation groups.
+
+    \code
+        QParallelAnimationGroup *group = new QParallelAnimationGroup;
+        group->addAnimation(anim1);
+        group->addAnimation(anim2);
+
+        group->start();
+    \endcode
+    
+    In this example, \c anim1 and \c anim2 are two
+    \l{QPropertyAnimation}s that have already been set up.
+
+    \sa QAnimationGroup, QPropertyAnimation, {The Animation Framework}
 */
 
 #ifndef QT_NO_ANIMATION
diff --git a/src/corelib/animation/qpauseanimation.cpp b/src/corelib/animation/qpauseanimation.cpp
index 30ea92c..685fa98 100644
--- a/src/corelib/animation/qpauseanimation.cpp
+++ b/src/corelib/animation/qpauseanimation.cpp
@@ -45,6 +45,22 @@
     \since 4.5
     \ingroup animation
     \preliminary
+
+    If you wish to introduce a delay between animations in a
+    QSequentialAnimationGroup, you can insert a QPauseAnimation. This
+    class does not animate anything, but does not
+    \l{QAbstractAnimation::finished()}{finish} before a specified
+    number of milliseconds have elapsed from when it was started. You
+    specify the duration of the pause in the constructor. It can also
+    be set directly with setDuration().    
+
+    It is not necessary to construct a QPauseAnimation yourself.
+    QSequentialAnimationGroup provides the convenience functions
+    \l{QSequentialAnimationGroup::}{addPause()} and
+    \l{QSequentialAnimationGroup::}{insertPauseAt()}. These functions
+    simply take the number of milliseconds the pause should last.
+
+    \sa QSequentialAnimationGroup
 */
 
 #ifndef QT_NO_ANIMATION
diff --git a/src/corelib/animation/qpropertyanimation.cpp b/src/corelib/animation/qpropertyanimation.cpp
index 9a0c5bc..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}
 */
@@ -97,6 +118,8 @@ void QPropertyAnimationPrivate::updateMetaProperty()
             property = mo->property(propertyIndex);
             propertyType = property.userType();
         } else {
+            if (!target->dynamicPropertyNames().contains(propertyName))
+                qWarning("QPropertyAnimation: you're trying to animate a non-existing property %s of your QObject", propertyName.constData());
             hasMetaProperty = 2;
         }
     }
diff --git a/src/corelib/animation/qsequentialanimationgroup.cpp b/src/corelib/animation/qsequentialanimationgroup.cpp
index 61ff98d..38f4818 100644
--- a/src/corelib/animation/qsequentialanimationgroup.cpp
+++ b/src/corelib/animation/qsequentialanimationgroup.cpp
@@ -46,13 +46,36 @@
     \ingroup animation
     \preliminary
 
-    The first animation in the group is started first, and when it finishes, the next animation
-    is started, and so on. The animation group finishes when the last animation has finished.
+    QSequentialAnimationGroup is a QAnimationGroup that runs its
+    animations in sequence, i.e., it starts one animation after
+    another has finished playing. The animations are played in the
+    order they are added to the group (using
+    \l{QAnimationGroup::}{addAnimation()} or
+    \l{QAnimationGroup::}{insertAnimationAt()}). The animation group
+    finishes when its last animation has finished.
 
-    At each moment there is at most one animation that is active in the group, called currentAnimation.
-    An empty group has no current animation.
+    At each moment there is at most one animation that is active in
+    the group; it is returned by currentAnimation(). An empty group
+    has no current animation.
 
-    You can call addPause() or insertPause() to add a pause to a sequential animation group.
+    A sequential animation group can be treated as any other
+    animation, i.e., it can be started, stopped, and added to other
+    groups. You can also call addPause() or insertPauseAt() to add a
+    pause to a sequential animation group.
+
+    \code
+        QSequentialAnimationGroup group;
+
+        group.addAnimation(anim1);
+        group.addAnimation(anim2);
+
+        group.start();
+    \endcode
+
+    In this example, \c anim1 and \c anim2 are two already set up
+    \l{QPropertyAnimation}s.
+
+    \sa QAnimationGroup, QAbstractAnimation, {The Animation Framework}
 */
 
 #ifndef QT_NO_ANIMATION
diff --git a/src/corelib/animation/qvariantanimation.cpp b/src/corelib/animation/qvariantanimation.cpp
index bb6cf1c..73ed0df 100644
--- a/src/corelib/animation/qvariantanimation.cpp
+++ b/src/corelib/animation/qvariantanimation.cpp
@@ -59,26 +59,68 @@ QT_BEGIN_NAMESPACE
     \since 4.5
     \preliminary
 
-    This class is part of {The Animation Framework}. It serves as a base class
-    for property and item animations, with functions for shared functionality.
-
-    If you want to create an animation, you should look at QPropertyAnimation instead.
-
+    This class is part of \l{The Animation Framework}. It serves as a
+    base class for property and item animations, with functions for
+    shared functionality.
+
+    QVariantAnimation cannot be used directly as it is an abstract
+    class; it does not implement
+    \l{QAbstractAnimation::}{updateCurrentValue()} from
+    QAbstractAnimation. The class performs interpolation over
+    \l{QVariant}s, but leaves using the interpolated values to its
+    subclasses. Currently, Qt provides QPropertyAnimation, which
+    animates Qt \l{Qt's Property System}{properties}. See the
+    QPropertyAnimation class description if you wish to animate such
+    properties.
+    
     You can then set start and end values for the property by calling
     setStartValue() and setEndValue(), and finally call start() to
-    start the animation. When control goes back to the event loop, QVariantAnimation
-    will interpolate the property of the target object and emit the valueChanged
-    signal. To react to a change in the current value you have to reimplement the
-    updateCurrentValue virtual method.
-
-    There are two ways to affect how QVariantAnimation interpolates the values.
-    You can set an easing curve by calling setEasingCurve(), and configure the
-    duration by calling setDuration(). You can change how the QVariants are
-    interpolated by creating a subclass of QVariantAnimation, and reimplementing the
-    virtual interpolated() function.
-
-
-    \sa QPropertyAnimation, {The Animation Framework}
+    start the animation. QVariantAnimation will interpolate the
+    property of the target object and emit valueChanged(). To react to
+    a change in the current value you have to reimplement the
+    updateCurrentValue() virtual function.
+
+    It is also possible to set values at specified steps situated
+    between the start and end value. The interpolation will then
+    touch these points at the specified steps. Note that the start and
+    end values are defined as the key values at 0.0 and 1.0.
+
+    There are two ways to affect how QVariantAnimation interpolates
+    the values. You can set an easing curve by calling
+    setEasingCurve(), and configure the duration by calling
+    setDuration(). You can change how the QVariants are interpolated
+    by creating a subclass of QVariantAnimation, and reimplementing
+    the virtual interpolated() function.
+
+    Subclassing QVariantAnimation can be an alternative if you have
+    \l{QVariant}s that you do not wish to declare as Qt properties.
+    Note, however, that you in most cases will be better off declaring
+    your QVariant as a property.
+
+    Not all QVariant types are supported. Below is a list of currently
+    supported QVariant types:
+
+    \list
+        \o \l{QMetaType::}{Int}
+        \o \l{QMetaType::}{Double}
+        \o \l{QMetaType::}{Float}
+        \o \l{QMetaType::}{QLine}
+        \o \l{QMetaType::}{QLineF}
+        \o \l{QMetaType::}{QPoint}
+        \o \l{QMetaType::}{QSize}
+        \o \l{QMetaType::}{QSizeF}
+        \o \l{QMetaType::}{QRect}
+        \o \l{QMetaType::}{QRectF}
+    \endlist 
+
+    If you need to interpolate other variant types, including custom
+    types, you have to implement interpolation for these yourself.
+    You do this by reimplementing interpolated(), which returns
+    interpolation values for the value being interpolated. 
+
+    \omit We need some snippets around here. \endomit
+
+    \sa QPropertyAnimation, QAbstractAnimation, {The Animation Framework}
 */
 
 /*!
@@ -261,16 +303,16 @@ QVariantAnimation::~QVariantAnimation()
     \property QVariantAnimation::easingCurve
     \brief the easing curve of the animation
 
-    This property defines the easing curve of the animation. By default, a
-    linear easing curve is used, resulting in linear interpolation of the
-    end property. For many animations, it's useful to try different easing
-    curves, including QEasingCurve::InCirc, which provides a circular entry curve,
-    and QEasingCurve::InOutElastic, which provides an elastic effect on the values
-    of the interpolated property.
+    This property defines the easing curve of the animation. By
+    default, a linear easing curve is used, resulting in linear
+    interpolation. Other curves are provided, for instance,
+    QEasingCurve::InCirc, which provides a circular entry curve.
+    Another example is QEasingCurve::InOutElastic, which provides an
+    elastic effect on the values of the interpolated variant.
 
-    The easing curve is used with the interpolator, the interpolated() virtual
-    function, the animation's duration, and loopCount, to control how the
-    current value changes as the animation progresses.
+    The easing curve is used with the interpolator, the interpolated()
+    virtual function, the animation's duration, and iterationCount, to
+    control how the current value changes as the animation progresses.
 */
 QEasingCurve QVariantAnimation::easingCurve() const
 {
@@ -372,8 +414,8 @@ QVariantAnimation::Interpolator QVariantAnimationPrivate::getInterpolator(int in
     \property QVariantAnimation::duration
     \brief the duration of the animation
 
-    This property describes the duration of the animation. The default
-    duration is 250 milliseconds.
+    This property describes the duration in milliseconds of the
+    animation. The default duration is 250 milliseconds.
 
     \sa QAbstractAnimation::duration()
  */
@@ -509,17 +551,22 @@ void QVariantAnimation::setKeyValues(const KeyValues &keyValues)
 
 /*!
     \property QVariantAnimation::currentValue
-    \brief the current value of the animation
+    \brief the current value of the animation.
 
-    This property describes the current value; an interpolation between the
-    start value and the end value, using the current time for progress.
+    This property describes the current value; an interpolated value
+    between the \l{startValue}{start value} and the \l{endValue}{end
+    value}, using the current time for progress. The value itself is
+    obtained from interpolated(), which is called repeatedly as the
+    animation is running.
 
-    QVariantAnimation calls the virtual updateCurrentValue() function when the
-    current value changes. This is particularily useful for subclasses that
-    need to track updates.
+    QVariantAnimation calls the virtual updateCurrentValue() function
+    when the current value changes. This is particularly useful for
+    subclasses that need to track updates. For example,
+    QPropertyAnimation uses this function to animate Qt \l{Qt's
+    Property System}{properties}.
 
     \sa startValue, endValue
- */
+*/
 QVariant QVariantAnimation::currentValue() const
 {
     Q_D(const QVariantAnimation);
@@ -549,13 +596,22 @@ void QVariantAnimation::updateState(QAbstractAnimation::State oldState,
 }
 
 /*!
-    This virtual function returns the linear interpolation between variants \a
-    from and \a to, at \a progress, usually a value between 0 and 1. You can reimplement
-    this function in a subclass of QVariantAnimation to provide your own interpolation
-    algorithm. Note that in order for the interpolation to work with a QEasingCurve
-    that return a value smaller than 0 or larger than 1 (such as QEasingCurve::InBack)
-    you should make sure that it can extrapolate. If the semantic of the datatype
-    does not allow extrapolation this function should handle that gracefully.
+
+    This virtual function returns the linear interpolation between
+    variants \a from and \a to, at \a progress, usually a value
+    between 0 and 1. You can reimplement this function in a subclass
+    of QVariantAnimation to provide your own interpolation algorithm.
+
+    Note that in order for the interpolation to work with a
+    QEasingCurve that return a value smaller than 0 or larger than 1
+    (such as QEasingCurve::InBack) you should make sure that it can
+    extrapolate. If the semantic of the datatype does not allow
+    extrapolation this function should handle that gracefully.
+
+    You should call the QVariantAnimation implementation of this
+    function if you want your class to handle the types already
+    supported by Qt (see class QVariantAnimation description for a
+    list of supported types).
 
     \sa QEasingCurve
  */