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

Conflicts:
	src/gui/graphicsview/qgraphicsitem.cpp

14 files changed, 448 insertions, 253 deletions

diff --git a/src/corelib/animation/qabstractanimation.cpp b/src/corelib/animation/qabstractanimation.cpp
index 2b9e77d..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 iteration 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 setIterationCount(); a
-    iteration 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}
 */
 
 /*!
@@ -119,12 +126,12 @@
 */
 
 /*!
-    \fn QAbstractAnimation::currentIterationChanged(int currentIteration)
+    \fn QAbstractAnimation::currentLoopChanged(int currentLoop)
 
-    QAbstractAnimation emits this signal whenever the current iteration
-    changes. \a currentIteration is the current iteration.
+    QAbstractAnimation emits this signal whenever the current loop
+    changes. \a currentLoop is the current loop.
 
-    \sa currentIteration(), iterationCount()
+    \sa currentLoop(), loopCount()
 */
 
 /*!
@@ -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();
         }
@@ -245,7 +278,7 @@ void QAbstractAnimationPrivate::setState(QAbstractAnimation::State newState)
 
     QAbstractAnimation::State oldState = state;
     int oldCurrentTime = currentTime;
-    int oldCurrentIteration = currentIteration;
+    int oldCurrentLoop = currentLoop;
     QAbstractAnimation::Direction oldDirection = direction;
 
     state = newState;
@@ -274,7 +307,7 @@ void QAbstractAnimationPrivate::setState(QAbstractAnimation::State newState)
                     if (direction == QAbstractAnimation::Forward)
                         q->setCurrentTime(0);
                     else
-                        q->setCurrentTime(iterationCount == -1 ? q->duration() : q->totalDuration());
+                        q->setCurrentTime(loopCount == -1 ? q->duration() : q->totalDuration());
                 }
 
                 // Check if the setCurrentTime() function called stop().
@@ -302,8 +335,8 @@ void QAbstractAnimationPrivate::setState(QAbstractAnimation::State newState)
 
         QUnifiedTimer::instance()->unregisterAnimation(q);
 
-        if (dura == -1 || iterationCount < 0
-            || (oldDirection == QAbstractAnimation::Forward && (oldCurrentTime * (oldCurrentIteration + 1)) == (dura * iterationCount))
+        if (dura == -1 || loopCount < 0
+            || (oldDirection == QAbstractAnimation::Forward && (oldCurrentTime * (oldCurrentLoop + 1)) == (dura * loopCount))
             || (oldDirection == QAbstractAnimation::Backward && oldCurrentTime == 0)) {
                 if (guard)
                     emit q->finished();
@@ -459,10 +492,10 @@ void QAbstractAnimation::setDirection(Direction direction)
     if (state() == Stopped) {
         if (direction == Backward) {
             d->currentTime = duration();
-            d->currentIteration = d->iterationCount - 1;
+            d->currentLoop = d->loopCount - 1;
         } else {
             d->currentTime = 0;
-            d->currentIteration = 0;
+            d->currentLoop = 0;
         }
     }
     updateDirection(direction);
@@ -474,14 +507,14 @@ void QAbstractAnimation::setDirection(Direction direction)
     \brief the duration of the animation.
 
     If the duration is -1, it means that the duration is undefined.
-    In this case, iterationCount is ignored.
+    In this case, loopCount is ignored.
 */
 
 /*!
-    \property QAbstractAnimation::iterationCount
-    \brief the iteration count of the animation
+    \property QAbstractAnimation::loopCount
+    \brief the loop count of the animation
 
-    This property describes the iteration count of the animation as an integer.
+    This property describes the loop count of the animation as an integer.
     By default this value is 1, indicating that the animation
     should run once only, and then stop. By changing it you can let the
     animation loop several times. With a value of 0, the animation will not
@@ -490,34 +523,34 @@ void QAbstractAnimation::setDirection(Direction direction)
     It is not supported to have loop on an animation that has an undefined
     duration. It will only run once.
 */
-int QAbstractAnimation::iterationCount() const
+int QAbstractAnimation::loopCount() const
 {
     Q_D(const QAbstractAnimation);
-    return d->iterationCount;
+    return d->loopCount;
 }
-void QAbstractAnimation::setIterationCount(int iterationCount)
+void QAbstractAnimation::setLoopCount(int loopCount)
 {
     Q_D(QAbstractAnimation);
-    d->iterationCount = iterationCount;
+    d->loopCount = loopCount;
 }
 
 /*!
-    \property QAbstractAnimation::currentIteration
-    \brief the current iteration of the animation
+    \property QAbstractAnimation::currentLoop
+    \brief the current loop of the animation
 
-    This property describes the current iteration of the animation. By default,
-    the animation's iteration count is 1, and so the current iteration will
-    always be 0. If the iteration count is 2 and the animation runs past its
+    This property describes the current loop of the animation. By default,
+    the animation's loop count is 1, and so the current loop will
+    always be 0. If the loop count is 2 and the animation runs past its
     duration, it will automatically rewind and restart at current time 0, and
-    current iteration 1, and so on.
+    current loop 1, and so on.
 
-    When the current iteration changes, QAbstractAnimation emits the
-    currentIterationChanged() signal.
+    When the current loop changes, QAbstractAnimation emits the
+    currentLoopChanged() signal.
 */
-int QAbstractAnimation::currentIteration() const
+int QAbstractAnimation::currentLoop() const
 {
     Q_D(const QAbstractAnimation);
-    return d->currentIteration;
+    return d->currentLoop;
 }
 
 /*!
@@ -525,7 +558,7 @@ int QAbstractAnimation::currentIteration() const
 
     This pure virtual function returns the duration of the animation, and
     defines for how long QAbstractAnimation should update the current
-    time. This duration is local, and does not include the iteration count.
+    time. This duration is local, and does not include the loop count.
 
     A return value of -1 indicates that the animation has no defined duration;
     the animation should run forever until stopped. This is useful for
@@ -535,24 +568,24 @@ int QAbstractAnimation::currentIteration() const
     If the animation is a parallel QAnimationGroup, the duration will be the longest
     duration of all its animations. If the animation is a sequential QAnimationGroup,
     the duration will be the sum of the duration of all its animations.
-    \sa iterationCount
+    \sa loopCount
 */
 
 /*!
     Returns the total and effective duration of the animation, including the
-    iteration count.
+    loop count.
 
     \sa duration(), currentTime
 */
 int QAbstractAnimation::totalDuration() const
 {
     Q_D(const QAbstractAnimation);
-    if (d->iterationCount < 0)
+    if (d->loopCount < 0)
         return -1;
     int dura = duration();
     if (dura == -1)
         return -1;
-    return dura * d->iterationCount;
+    return dura * d->loopCount;
 }
 
 /*!
@@ -565,11 +598,11 @@ int QAbstractAnimation::totalDuration() const
     progresses.
 
     The animation's current time starts at 0, and ends at duration(). If the
-    animation's iterationCount is larger than 1, the current time will rewind and
+    animation's loopCount is larger than 1, the current time will rewind and
     start at 0 again for the consecutive loops. If the animation has a pause.
     currentTime will also include the duration of the pause.
 
-    \sa iterationCount
+    \sa loopCount
  */
 int QAbstractAnimation::currentTime() const
 {
@@ -583,31 +616,31 @@ void QAbstractAnimation::setCurrentTime(int msecs)
 
     // Calculate new time and loop.
     int dura = duration();
-    int totalDura = (d->iterationCount < 0 || dura == -1) ? -1 : dura * d->iterationCount;
+    int totalDura = (d->loopCount < 0 || dura == -1) ? -1 : dura * d->loopCount;
     if (totalDura != -1)
         msecs = qMin(totalDura, msecs);
     d->totalCurrentTime = msecs;
 
     // Update new values.
-    int oldLoop = d->currentIteration;
-    d->currentIteration = ((dura <= 0) ? 0 : (msecs / dura));
-    if (d->currentIteration == d->iterationCount) {
+    int oldLoop = d->currentLoop;
+    d->currentLoop = ((dura <= 0) ? 0 : (msecs / dura));
+    if (d->currentLoop == d->loopCount) {
         //we're at the end
         d->currentTime = qMax(0, dura);
-        d->currentIteration = qMax(0, d->iterationCount - 1);
+        d->currentLoop = qMax(0, d->loopCount - 1);
     } else {
         if (d->direction == Forward) {
             d->currentTime = (dura <= 0) ? msecs : (msecs % dura);
         } else {
             d->currentTime = (dura <= 0) ? msecs : ((msecs - 1) % dura) + 1;
             if (d->currentTime == dura)
-                --d->currentIteration;
+                --d->currentLoop;
         }
     }
 
     updateCurrentTime(msecs);
-    if (d->currentIteration != oldLoop)
-        emit currentIterationChanged(d->currentIteration);
+    if (d->currentLoop != oldLoop)
+        emit currentLoopChanged(d->currentLoop);
 
     // All animations are responsible for stopping the animation when their
     // own end state is reached; in this case the animation is time driven,
@@ -648,7 +681,7 @@ void QAbstractAnimation::start(DeletionPolicy policy)
     signal, and state() returns Stopped. The current time is not changed.
 
     If the animation stops by itself after reaching the end (i.e.,
-    currentTime() == duration() and currentIteration() > iterationCount() - 1), the
+    currentTime() == duration() and currentLoop() > loopCount() - 1), the
     finished() signal is emitted.
 
     \sa start(), state()
diff --git a/src/corelib/animation/qabstractanimation.h b/src/corelib/animation/qabstractanimation.h
index d6260cd..a7f0082 100644
--- a/src/corelib/animation/qabstractanimation.h
+++ b/src/corelib/animation/qabstractanimation.h
@@ -60,9 +60,9 @@ class Q_CORE_EXPORT QAbstractAnimation : public QObject
 {
     Q_OBJECT
     Q_PROPERTY(State state READ state NOTIFY stateChanged)
-    Q_PROPERTY(int iterationCount READ iterationCount WRITE setIterationCount)
+    Q_PROPERTY(int loopCount READ loopCount WRITE setLoopCount)
     Q_PROPERTY(int currentTime READ currentTime WRITE setCurrentTime)
-    Q_PROPERTY(int currentIteration READ currentIteration NOTIFY currentIterationChanged)
+    Q_PROPERTY(int currentLoop READ currentLoop NOTIFY currentLoopChanged)
     Q_PROPERTY(Direction direction READ direction WRITE setDirection NOTIFY directionChanged)
     Q_PROPERTY(int duration READ duration)
 
@@ -93,9 +93,9 @@ public:
     Direction direction() const;
     void setDirection(Direction direction);
 
-    int iterationCount() const;
-    void setIterationCount(int iterationCount);
-    int currentIteration() const;
+    int loopCount() const;
+    void setLoopCount(int loopCount);
+    int currentLoop() const;
 
     virtual int duration() const = 0;
     int totalDuration() const;
@@ -105,7 +105,7 @@ public:
 Q_SIGNALS:
     void finished();
     void stateChanged(QAbstractAnimation::State oldState, QAbstractAnimation::State newState);
-    void currentIterationChanged(int currentIteration);
+    void currentLoopChanged(int currentLoop);
     void directionChanged(QAbstractAnimation::Direction);
 
 public Q_SLOTS:
diff --git a/src/corelib/animation/qabstractanimation_p.h b/src/corelib/animation/qabstractanimation_p.h
index 28d7d71..41983a5 100644
--- a/src/corelib/animation/qabstractanimation_p.h
+++ b/src/corelib/animation/qabstractanimation_p.h
@@ -77,8 +77,8 @@ public:
           deleteWhenStopped(false),
           totalCurrentTime(0),
           currentTime(0),
-          iterationCount(1),
-          currentIteration(0),
+          loopCount(1),
+          currentLoop(0),
           group(0)
     {
     }
@@ -97,8 +97,8 @@ public:
 
     int totalCurrentTime;
     int currentTime;
-    int iterationCount;
-    int currentIteration;
+    int loopCount;
+    int currentLoop;
 
     QAnimationGroup *group;
 #ifdef QT_EXPERIMENTAL_SOLUTION
@@ -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 f39738b..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}
 */
@@ -164,9 +192,10 @@ void QAnimationGroup::insertAnimationAt(int index, QAbstractAnimation *animation
         return;
     }
 
-    d->animations.insert(index, animation);
     if (QAnimationGroup *oldGroup = animation->group())
         oldGroup->removeAnimation(animation);
+
+    d->animations.insert(index, animation);
     QAbstractAnimationPrivate::get(animation)->group = this;
     // this will make sure that ChildAdded event is sent to 'this'
     animation->setParent(this);
diff --git a/src/corelib/animation/qparallelanimationgroup.cpp b/src/corelib/animation/qparallelanimationgroup.cpp
index 993c577..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
@@ -111,7 +130,7 @@ void QParallelAnimationGroup::updateCurrentTime(int)
     if (d->animations.isEmpty())
         return;
 
-    if (d->currentIteration > d->lastIteration) {
+    if (d->currentLoop > d->lastLoop) {
         // simulate completion of the loop
         int dura = duration();
         if (dura > 0) {
@@ -119,7 +138,7 @@ void QParallelAnimationGroup::updateCurrentTime(int)
                 animation->setCurrentTime(dura);   // will stop
             }
         }
-    } else if (d->currentIteration < d->lastIteration) {
+    } else if (d->currentLoop < d->lastLoop) {
         // simulate completion of the loop seeking backwards
         foreach (QAbstractAnimation *animation, d->animations) {
             animation->setCurrentTime(0);
@@ -127,11 +146,11 @@ void QParallelAnimationGroup::updateCurrentTime(int)
         }
     }
 
-    bool timeFwd = ((d->currentIteration == d->lastIteration && d->currentTime >= d->lastCurrentTime)
-                   || d->currentIteration > d->lastIteration);
+    bool timeFwd = ((d->currentLoop == d->lastLoop && d->currentTime >= d->lastCurrentTime)
+                   || d->currentLoop > d->lastLoop);
 #ifdef QANIMATION_DEBUG
     qDebug("QParallellAnimationGroup %5d: setCurrentTime(%d), loop:%d, last:%d, timeFwd:%d, lastcurrent:%d, %d",
-        __LINE__, d->currentTime, d->currentIteration, d->lastIteration, timeFwd, d->lastCurrentTime, state());
+        __LINE__, d->currentTime, d->currentLoop, d->lastLoop, timeFwd, d->lastCurrentTime, state());
 #endif
     // finally move into the actual time of the current loop
     foreach (QAbstractAnimation *animation, d->animations) {
@@ -139,7 +158,7 @@ void QParallelAnimationGroup::updateCurrentTime(int)
         if (dura == -1 && d->isUncontrolledAnimationFinished(animation))
             continue;
         if (dura == -1 || (d->currentTime <= dura && dura != 0)
-            || (dura == 0 && d->currentIteration != d->lastIteration)) {
+            || (dura == 0 && d->currentLoop != d->lastLoop)) {
             switch (state()) {
             case Running:
                 animation->start();
@@ -165,7 +184,7 @@ void QParallelAnimationGroup::updateCurrentTime(int)
         if (d->currentTime > dura)
             animation->stop();
     }
-    d->lastIteration = d->currentIteration;
+    d->lastLoop = d->currentLoop;
     d->lastCurrentTime = d->currentTime;
 }
 
@@ -207,7 +226,7 @@ void QParallelAnimationGroupPrivate::_q_uncontrolledAnimationFinished()
     Q_ASSERT(animation);
 
     int uncontrolledRunningCount = 0;
-    if (animation->duration() == -1 || animation->iterationCount() < 0) {
+    if (animation->duration() == -1 || animation->loopCount() < 0) {
         QHash<QAbstractAnimation *, int>::iterator it = uncontrolledFinishTime.begin();
         while (it != uncontrolledFinishTime.end()) {
             if (it.key() == animation) {
@@ -248,7 +267,7 @@ void QParallelAnimationGroupPrivate::connectUncontrolledAnimations()
     Q_Q(QParallelAnimationGroup);
 
     foreach (QAbstractAnimation *animation, animations) {
-        if (animation->duration() == -1 || animation->iterationCount() < 0) {
+        if (animation->duration() == -1 || animation->loopCount() < 0) {
             uncontrolledFinishTime[animation] = -1;
             QObject::connect(animation, SIGNAL(finished()), q, SLOT(_q_uncontrolledAnimationFinished()));
         }
@@ -273,11 +292,11 @@ void QParallelAnimationGroup::updateDirection(QAbstractAnimation::Direction dire
         }
     } else {
         if (direction == Forward) {
-            d->lastIteration = 0;
+            d->lastLoop = 0;
             d->lastCurrentTime = 0;
         } else {
-            // Looping backwards with iterationCount == -1 does not really work well...
-            d->lastIteration = (d->iterationCount == -1 ? 0 : d->iterationCount - 1);
+            // Looping backwards with loopCount == -1 does not really work well...
+            d->lastLoop = (d->loopCount == -1 ? 0 : d->loopCount - 1);
             d->lastCurrentTime = duration();
         }
     }
diff --git a/src/corelib/animation/qparallelanimationgroup_p.h b/src/corelib/animation/qparallelanimationgroup_p.h
index 8a4dc1b..f36d972 100644
--- a/src/corelib/animation/qparallelanimationgroup_p.h
+++ b/src/corelib/animation/qparallelanimationgroup_p.h
@@ -64,12 +64,12 @@ class QParallelAnimationGroupPrivate : public QAnimationGroupPrivate
     Q_DECLARE_PUBLIC(QParallelAnimationGroup)
 public:
     QParallelAnimationGroupPrivate()
-        : lastIteration(0), lastCurrentTime(0)
+        : lastLoop(0), lastCurrentTime(0)
     {
     }
 
     QHash<QAbstractAnimation*, int> uncontrolledFinishTime;
-    int lastIteration;
+    int lastLoop;
     int lastCurrentTime;
 
     bool isUncontrolledAnimationFinished(QAbstractAnimation *anim) const;
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 adf3527..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;
         }
     }
@@ -220,11 +243,20 @@ void QPropertyAnimation::updateCurrentValue(const QVariant &value)
 
 /*!
     \reimp
+
+    If the startValue is not defined when the state of the animation changes from Stopped to Running,
+    the current property value is used as the initial value for the animation.
 */
 void QPropertyAnimation::updateState(QAbstractAnimation::State oldState,
                                      QAbstractAnimation::State newState)
 {
     Q_D(QPropertyAnimation);
+
+    if (!d->target) {
+        qWarning("QPropertyAnimation::updateState: Changing state of an animation without target");
+        return;
+    }
+
     QVariantAnimation::updateState(oldState, newState);
     QMutexLocker locker(guardHashLock());
     QPropertyAnimationHash * hash = _q_runningAnimations();
@@ -233,20 +265,21 @@ void QPropertyAnimation::updateState(QAbstractAnimation::State oldState,
         d->updateMetaProperty();
         QPropertyAnimation *oldAnim = hash->value(key, 0);
         if (oldAnim) {
-            //we try to stop the top level group
+            // try to stop the top level group
             QAbstractAnimation *current = oldAnim;
-            while(current->group() && current->state() != Stopped) current = current->group();
+            while (current->group() && current->state() != Stopped)
+                current = current->group();
             current->stop();
         }
         hash->insert(key, this);
-        // Initialize start value
-        if (d->target && !d->defaultStartValue.isValid() && (d->atBeginning() || d->atEnd())) {
+
+        // update the default start value
+        if (oldState == Stopped) {
             d->setDefaultStartValue(d->target->property(d->propertyName.constData()));
         }
     } else if (hash->value(key) == this) {
         hash->remove(key);
     }
-
 }
 
 #include "moc_qpropertyanimation.cpp"
diff --git a/src/corelib/animation/qpropertyanimation.h b/src/corelib/animation/qpropertyanimation.h
index e5d5305..b619256 100644
--- a/src/corelib/animation/qpropertyanimation.h
+++ b/src/corelib/animation/qpropertyanimation.h
@@ -47,7 +47,6 @@
 #else
 # include <QtCore/qvariantanimation.h>
 #endif
-#include <QtCore/qvariant.h>
 
 QT_BEGIN_HEADER
 
diff --git a/src/corelib/animation/qsequentialanimationgroup.cpp b/src/corelib/animation/qsequentialanimationgroup.cpp
index 879532c..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
@@ -77,7 +100,7 @@ bool QSequentialAnimationGroupPrivate::atEnd() const
     // 3. the current animation is the last one
     // 4. the current animation has reached its end
     const int animTotalCurrentTime = QAbstractAnimationPrivate::get(currentAnimation)->totalCurrentTime;
-    return (currentIteration == iterationCount - 1
+    return (currentLoop == loopCount - 1
         && direction == QAbstractAnimation::Forward
         && currentAnimation == animations.last()
         && animTotalCurrentTime == animationActualTotalDuration(currentAnimationIndex));
@@ -101,7 +124,7 @@ QSequentialAnimationGroupPrivate::AnimationIndex QSequentialAnimationGroupPrivat
     int duration = 0;
 
     // in case duration is -1, currentLoop will always be 0
-    ret.timeOffset = currentIteration * q->duration();
+    ret.timeOffset = currentLoop * q->duration();
 
     for (int i = 0; i < animations.size(); ++i) {
         duration = animationActualTotalDuration(i);
@@ -133,13 +156,13 @@ void QSequentialAnimationGroupPrivate::restart()
 {
     // restarting the group by making the first/last animation the current one
     if (direction == QAbstractAnimation::Forward) {
-        lastIteration = 0;
+        lastLoop = 0;
         if (currentAnimationIndex == 0)
             activateCurrentAnimation();
         else
             setCurrentAnimation(0);
     } else { // direction == QAbstractAnimation::Backward
-        lastIteration = iterationCount - 1;
+        lastLoop = loopCount - 1;
         int index = animations.size() - 1;
         if (currentAnimationIndex == index)
             activateCurrentAnimation();
@@ -156,7 +179,7 @@ void QSequentialAnimationGroupPrivate::restart()
 */
 void QSequentialAnimationGroupPrivate::advanceForwards(const AnimationIndex &newAnimationIndex)
 {
-    if (lastIteration < currentIteration) {
+    if (lastLoop < currentLoop) {
         // we need to fast forward to the end
         for (int i = currentAnimationIndex; i < animations.size(); ++i) {
             QAbstractAnimation *anim = animations.at(i);
@@ -188,7 +211,7 @@ void QSequentialAnimationGroupPrivate::advanceForwards(const AnimationIndex &new
 */
 void QSequentialAnimationGroupPrivate::rewindForwards(const AnimationIndex &newAnimationIndex)
 {
-    if (lastIteration > currentIteration) {
+    if (lastLoop > currentLoop) {
         // we need to fast rewind to the beginning
         for (int i = currentAnimationIndex; i >= 0 ; --i) {
             QAbstractAnimation *anim = animations.at(i);
@@ -329,12 +352,12 @@ void QSequentialAnimationGroup::updateCurrentTime(int msecs)
         d->actualDuration.removeLast();
 
     // newAnimationIndex.index is the new current animation
-    if (d->lastIteration < d->currentIteration
-        || (d->lastIteration == d->currentIteration && d->currentAnimationIndex < newAnimationIndex.index)) {
+    if (d->lastLoop < d->currentLoop
+        || (d->lastLoop == d->currentLoop && d->currentAnimationIndex < newAnimationIndex.index)) {
             // advancing with forward direction is the same as rewinding with backwards direction
             d->advanceForwards(newAnimationIndex);
-    } else if (d->lastIteration > d->currentIteration
-        || (d->lastIteration == d->currentIteration && d->currentAnimationIndex > newAnimationIndex.index)) {
+    } else if (d->lastLoop > d->currentLoop
+        || (d->lastLoop == d->currentLoop && d->currentAnimationIndex > newAnimationIndex.index)) {
             // rewinding with forward direction is the same as advancing with backwards direction
             d->rewindForwards(newAnimationIndex);
     }
@@ -358,7 +381,7 @@ void QSequentialAnimationGroup::updateCurrentTime(int msecs)
         stop();
     }
 
-    d->lastIteration = d->currentIteration;
+    d->lastLoop = d->currentLoop;
 }
 
 /*!
@@ -505,7 +528,7 @@ void QSequentialAnimationGroupPrivate::animationInsertedAt(int index)
         setCurrentAnimation(0); // initialize the current animation
 
     if (currentAnimationIndex == index
-        && currentAnimation->currentTime() == 0 && currentAnimation->currentIteration() == 0) {
+        && currentAnimation->currentTime() == 0 && currentAnimation->currentLoop() == 0) {
             //in this case we simply insert an animation before the current one has actually started
             setCurrentAnimation(index);
     }
@@ -513,7 +536,7 @@ void QSequentialAnimationGroupPrivate::animationInsertedAt(int index)
     //we update currentAnimationIndex in case it has changed (the animation pointer is still valid)
     currentAnimationIndex = animations.indexOf(currentAnimation);
 
-    if (index < currentAnimationIndex || currentIteration != 0) {
+    if (index < currentAnimationIndex || currentLoop != 0) {
         qWarning("QSequentialGroup::insertAnimationAt only supports to add animations after the current one.");
         return; //we're not affected because it is added after the current one
     }
@@ -562,7 +585,7 @@ void QSequentialAnimationGroupPrivate::animationRemovedAt(int index)
     }
 
     //let's also update the total current time
-    totalCurrentTime = currentTime + iterationCount * q->duration();
+    totalCurrentTime = currentTime + loopCount * q->duration();
 }
 
 QT_END_NAMESPACE
diff --git a/src/corelib/animation/qsequentialanimationgroup_p.h b/src/corelib/animation/qsequentialanimationgroup_p.h
index 05d2a40..3ac90f8 100644
--- a/src/corelib/animation/qsequentialanimationgroup_p.h
+++ b/src/corelib/animation/qsequentialanimationgroup_p.h
@@ -64,7 +64,7 @@ class QSequentialAnimationGroupPrivate : public QAnimationGroupPrivate
     Q_DECLARE_PUBLIC(QSequentialAnimationGroup)
 public:
     QSequentialAnimationGroupPrivate()
-        : currentAnimation(0), currentAnimationIndex(-1), lastIteration(0)
+        : currentAnimation(0), currentAnimationIndex(-1), lastLoop(0)
     { }
 
 
@@ -96,7 +96,7 @@ public:
     QList<int> actualDuration;
 
     void restart();
-    int lastIteration;
+    int lastLoop;
 
     // handle time changes
     void rewindForwards(const AnimationIndex &newAnimationIndex);
diff --git a/src/corelib/animation/qvariantanimation.cpp b/src/corelib/animation/qvariantanimation.cpp
index 6b162ae..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}
 */
 
 /*!
@@ -175,26 +217,16 @@ void QVariantAnimationPrivate::updateCurrentValue()
                 endProgress = currentInterval.end.first;
     const qreal localProgress = (progress - startProgress) / (endProgress - startProgress);
 
-    bool changed = false;
-    {
-      //we do that here in a limited scope so that ret is dereferenced and frees memory
-      //and the call to updateCurrentValue can recreate QVariant of the same type (for ex. in
-      //QGraphicsItem::setPos
-      QVariant ret = q->interpolated(currentInterval.start.second,
-                                    currentInterval.end.second,
-                                    localProgress);
-      if (currentValue != ret) {
-          changed = true;
-          qSwap(currentValue, ret);
-      }
-    }
-
-    if (changed) {
-        //the value has changed
-        q->updateCurrentValue(currentValue);
+    QVariant ret = q->interpolated(currentInterval.start.second,
+                                   currentInterval.end.second,
+                                   localProgress);
+    qSwap(currentValue, ret);
+    q->updateCurrentValue(currentValue);
 #ifndef QT_EXPERIMENTAL_SOLUTION
         if (connectedSignals & changedSignalMask)
 #endif
+    if (currentValue != ret) {
+        //the value has changed
             emit q->valueChanged(currentValue);
     }
 }
@@ -271,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 iterationCount, 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
 {
@@ -340,7 +372,7 @@ template<typename T> static inline QVariantAnimation::Interpolator castToInterpo
      return reinterpret_cast<QVariantAnimation::Interpolator>(func);
 }
 
-static QVariantAnimation::Interpolator getInterpolator(int interpolationType)
+QVariantAnimation::Interpolator QVariantAnimationPrivate::getInterpolator(int interpolationType)
 {
     QReadLocker locker(registeredInterpolatorsLock());
     QVariantAnimation::Interpolator ret = 0;
@@ -382,8 +414,8 @@ static QVariantAnimation::Interpolator getInterpolator(int interpolationType)
     \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()
  */
@@ -519,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);
@@ -559,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
  */
@@ -574,7 +620,7 @@ QVariant QVariantAnimation::interpolated(const QVariant &from, const QVariant &t
     Q_D(const QVariantAnimation);
     if (d->interpolator == 0) {
         if (from.userType() == to.userType())
-            d->interpolator = getInterpolator(from.userType());
+            d->interpolator = QVariantAnimationPrivate::getInterpolator(from.userType());
         if (d->interpolator == 0) //no interpolator found
             return QVariant();
     }
diff --git a/src/corelib/animation/qvariantanimation.h b/src/corelib/animation/qvariantanimation.h
index 7ce597f..69dbbf3 100644
--- a/src/corelib/animation/qvariantanimation.h
+++ b/src/corelib/animation/qvariantanimation.h
@@ -49,8 +49,7 @@
 # include <QtCore/qeasingcurve.h>
 # include <QtCore/qabstractanimation.h>
 #endif
-#include <QtCore/qlist.h>
-#include <QtCore/qpoint.h>
+#include <QtCore/qvector.h>
 #include <QtCore/qvariant.h>
 #include <QtCore/qpair.h>
 
diff --git a/src/corelib/animation/qvariantanimation_p.h b/src/corelib/animation/qvariantanimation_p.h
index e468ac9..14a3ef6 100644
--- a/src/corelib/animation/qvariantanimation_p.h
+++ b/src/corelib/animation/qvariantanimation_p.h
@@ -88,18 +88,6 @@ public:
         return q->d_func();
     }
 
-    
-    //some helper functions
-    bool atBeginning() const
-    {
-        return currentTime == 0;
-    }
-
-    bool atEnd() const
-    {
-        return currentTime == duration && currentIteration == (iterationCount - 1);
-    }
-
     void setDefaultStartValue(const QVariant &value);
 
     int duration;
@@ -109,7 +97,7 @@ public:
     QVariant currentValue;
     QVariant defaultStartValue;
     bool hasStartValue;
-   
+
     //this is used to keep track of the KeyValue interval in which we currently are
     struct
     {
@@ -124,6 +112,8 @@ public:
     void setValueAt(qreal, const QVariant &);
     QVariant valueAt(qreal step) const;
     void convertValues(int t);
+
+    static QVariantAnimation::Interpolator getInterpolator(int interpolationType);
 };
 
 //this should make the interpolation faster