Animation: add finished() signal

Currently, Animation has a stopped() signal. This is executed even if
the animation is stopped manually. To react to an animation finishing
naturally, you currently have to do the following:

    onRunningChanged: if (!running) doStuff()

This patch adds a dedicated signal:

    onFinished: doStuff()

[ChangeLog][QtQuick][Animation] Added finished() signal to
Animation as a convenient way to react to an animation finishing
naturally.

Change-Id: I8765d3e8e2b7bf7ef66a6acb69feafb43e9619d3
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

1 files changed, 74 insertions, 0 deletions

diff --git a/tests/auto/quick/qquickanimations/tst_qquickanimations.cpp b/tests/auto/quick/qquickanimations/tst_qquickanimations.cpp
index de86bb16db..3cfe03a376 100644
--- a/tests/auto/quick/qquickanimations/tst_qquickanimations.cpp
+++ b/tests/auto/quick/qquickanimations/tst_qquickanimations.cpp
@@ -105,6 +105,7 @@ private slots:
     void pathSvgAnimation();
     void pathLineUnspecifiedXYBug();
     void unsetAnimatorProxyJobWindow();
+    void finished();
 };
 
 #define QTIMED_COMPARE(lhs, rhs) do { \
@@ -1612,6 +1613,79 @@ void tst_qquickanimations::unsetAnimatorProxyJobWindow()
     QCOMPARE(proxy.job().data(), job);
 }
 
+void tst_qquickanimations::finished()
+{
+    QQmlEngine engine;
+    QQmlComponent component(&engine, testFileUrl("finished.qml"));
+    QScopedPointer<QObject> root(component.create());
+    QVERIFY(root);
+
+    // Test that finished() is emitted for a simple top-level animation.
+    // (Each test is in its own block so that we can reuse the nice signal names :))
+    {
+        QQuickAbstractAnimation *simpleTopLevelAnimation
+            = root->property("simpleTopLevelAnimation").value<QQuickAbstractAnimation*>();
+        QVERIFY(simpleTopLevelAnimation);
+
+        QSignalSpy stoppedSpy(simpleTopLevelAnimation, SIGNAL(stopped()));
+        QVERIFY(stoppedSpy.isValid());
+
+        QSignalSpy finishedSpy(simpleTopLevelAnimation, SIGNAL(finished()));
+        QVERIFY(finishedSpy.isValid());
+
+        QVERIFY(simpleTopLevelAnimation->setProperty("running", QVariant(true)));
+        QTRY_COMPARE(stoppedSpy.count(), 1);
+        QCOMPARE(finishedSpy.count(), 1);
+
+        // Test that the signal is properly revisioned and hence accessible from QML.
+        QCOMPARE(root->property("finishedUsableInQml").toBool(), true);
+    }
+
+    // Test that finished() is not emitted for animations within a Transition.
+    {
+        QObject *transition = root->property("transition").value<QObject*>();
+        QVERIFY(transition);
+
+        QSignalSpy runningChangedSpy(transition, SIGNAL(runningChanged()));
+        QVERIFY(runningChangedSpy.isValid());
+
+        QQuickAbstractAnimation *animationWithinTransition
+            = root->property("animationWithinTransition").value<QQuickAbstractAnimation*>();
+        QVERIFY(animationWithinTransition);
+
+        QSignalSpy stoppedSpy(animationWithinTransition, SIGNAL(stopped()));
+        QVERIFY(stoppedSpy.isValid());
+
+        QSignalSpy finishedSpy(animationWithinTransition, SIGNAL(finished()));
+        QVERIFY(finishedSpy.isValid());
+
+        QObject *transitionRect = root->property("transitionRect").value<QObject*>();
+        QVERIFY(transitionRect);
+        QVERIFY(transitionRect->setProperty("state", QVariant(QLatin1String("go"))));
+        QTRY_COMPARE(runningChangedSpy.count(), 1);
+        QCOMPARE(stoppedSpy.count(), 0);
+        QCOMPARE(finishedSpy.count(), 0);
+    }
+
+    // Test that finished() is not emitted for animations within a Behavior.
+    {
+        QQuickAbstractAnimation *animationWithinBehavior
+            = root->property("animationWithinBehavior").value<QQuickAbstractAnimation*>();
+        QVERIFY(animationWithinBehavior);
+
+        QSignalSpy stoppedSpy(animationWithinBehavior, SIGNAL(stopped()));
+        QVERIFY(stoppedSpy.isValid());
+
+        QSignalSpy finishedSpy(animationWithinBehavior, SIGNAL(finished()));
+        QVERIFY(finishedSpy.isValid());
+
+        QVERIFY(root->setProperty("bar", QVariant(1.0)));
+        QTRY_COMPARE(root->property("bar").toReal(), 1.0);
+        QCOMPARE(stoppedSpy.count(), 0);
+        QCOMPARE(finishedSpy.count(), 0);
+    }
+}
+
 QTEST_MAIN(tst_qquickanimations)
 
 #include "tst_qquickanimations.moc"