Fix, test and document animation started/stopped signals.

Rename completed to stopped (as it is not only emitted
on completion). Ensure that the started and stopped signals
are emitted at the right times. Document the signals.

Task-number: QTBUG-14968
Change-Id: Icd3babcef2c9e544476592a26e6b9e58a21ebe95
Reviewed-by: Yunqiao Yin <charles.yin@nokia.com>

2 files changed, 35 insertions, 7 deletions

diff --git a/src/quick/util/qquickanimation.cpp b/src/quick/util/qquickanimation.cpp
index ebdde58c63..5d7e21d42c 100644
--- a/src/quick/util/qquickanimation.cpp
+++ b/src/quick/util/qquickanimation.cpp
@@ -175,7 +175,7 @@ void QQuickAbstractAnimationPrivate::commence()
         animationInstance->start();
         if (animationInstance->isStopped()) {
             running = false;
-            emit q->completed();
+            emit q->stopped();
         }
     }
 }
@@ -193,6 +193,31 @@ QQmlProperty QQuickAbstractAnimationPrivate::createProperty(QObject *obj, const
     return prop;
 }
 
+/*!
+    \qmlsignal QtQuick2::Animation::onStarted()
+
+    This signal handler is called when the animation begins.
+
+    It is only triggered for top-level, standalone animations. It will not be
+    triggered for animations in a Behavior or Transition, or animations
+    that are part of an animation group.
+*/
+
+/*!
+    \qmlsignal QtQuick2::Animation::onStopped()
+
+    This signal handler is called when the animation ends.
+
+    The animation may have been stopped manually, or may have run to completion.
+
+    It is only triggered for top-level, standalone animations. It will not be
+    triggered for animations in a Behavior or Transition, or animations
+    that are part of an animation group.
+
+    If \l alwaysRunToEnd is true, onStopped will not be called until the animation
+    has completed its current iteration.
+*/
+
 void QQuickAbstractAnimation::setRunning(bool r)
 {
     Q_D(QQuickAbstractAnimation);
@@ -231,9 +256,10 @@ void QQuickAbstractAnimation::setRunning(bool r)
                 d->animationInstance->setLoopCount(d->animationInstance->currentLoop() + d->loopCount);
             supressStart = true;    //we want the animation to continue, rather than restart
         }
-        if (!supressStart)
+        if (!supressStart) {
             d->commence();
-        emit started();
+            emit started();
+        }
     } else {
         if (d->paused) {
             d->paused = false; //reset paused state to false when stopped
@@ -246,9 +272,9 @@ void QQuickAbstractAnimation::setRunning(bool r)
                     d->animationInstance->setLoopCount(d->animationInstance->currentLoop()+1);    //finish the current loop
             } else {
                 d->animationInstance->stop();
+                emit stopped();
             }
         }
-        emit completed();
     }
 
     emit runningChanged(d->running);
@@ -608,9 +634,11 @@ void QQuickAbstractAnimationPrivate::animationFinished(QAbstractAnimationJob*)
 {
     Q_Q(QQuickAbstractAnimation);
     q->setRunning(false);
-    if (alwaysRunToEnd && loopCount != 1) {
+    if (alwaysRunToEnd) {
+        emit q->stopped();
         //restore the proper loopCount for the next run
-        animationInstance->setLoopCount(loopCount);
+        if (loopCount != 1)
+            animationInstance->setLoopCount(loopCount);
     }
 }
 
diff --git a/src/quick/util/qquickanimation_p.h b/src/quick/util/qquickanimation_p.h
index 0fd746c4f5..0f8e118a2d 100644
--- a/src/quick/util/qquickanimation_p.h
+++ b/src/quick/util/qquickanimation_p.h
@@ -106,7 +106,7 @@ public:
 
 Q_SIGNALS:
     void started();
-    void completed();
+    void stopped();
     void runningChanged(bool);
     void pausedChanged(bool);
     void alwaysRunToEndChanged(bool);