Deprecate QTimeLine's curveShape in favor of its easingCurve

QEasingCurve has a richer variety of curves and curveShape was already
implemented by changing the easingCurve property.

[ChangeLog][QtCore][QTimeLine] Deprecated QTimeLine's curveShape
property in favor of the easingCurve property.

Pick-to: 5.15
Change-Id: I7261c0f24d7e02bc94624f0b74d699df62de1a52
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
Reviewed-by: hjk <hjk@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

examples/embedded/digiflip/digiflip.cpp

@@ -73,7 +73,7 @@ public:
         connect(&m_animator, SIGNAL(frameChanged(int)), SLOT(update()));
         m_animator.setFrameRange(0, 100);
         m_animator.setDuration(600);
-        m_animator.setCurveShape(QTimeLine::EaseInOutCurve);
+        m_animator.setEasingCurve(QEasingCurve::InOutSine);
     }
 
     void setTransition(int tr) {

src/corelib/tools/qeasingcurve.cpp

@@ -1087,7 +1087,7 @@ static QEasingCurve::EasingFunction curveToFunc(QEasingCurve::Type curve)
         return &easeInOutCirc;
     case QEasingCurve::OutInCirc:
         return &easeOutInCirc;
-    // Internal for, compatibility with QTimeLine only ??
+    // Internal - needed for QTimeLine backward-compatibility:
     case QEasingCurve::InCurve:
         return &easeInCurve;
     case QEasingCurve::OutCurve:

src/corelib/tools/qtimeline.cpp

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtCore module of the Qt Toolkit.
@@ -185,7 +185,7 @@ void QTimeLinePrivate::setCurrentTime(int msecs)
 
     \snippet code/src_corelib_tools_qtimeline.cpp 0
 
-    By default the timeline runs once, from the beginning and towards the end,
+    By default the timeline runs once, from its beginning to its end,
     upon which you must call start() again to restart from the beginning. To
     make the timeline loop, you can call setLoopCount(), passing the number of
     times the timeline should run before finishing. The direction can also be
@@ -193,8 +193,8 @@ void QTimeLinePrivate::setCurrentTime(int msecs)
     setDirection(). You can also pause and unpause the timeline while it's
     running by calling setPaused(). For interactive control, the
     setCurrentTime() function is provided, which sets the time position of the
-    time line directly. Although most useful in NotRunning state, (e.g.,
+    time line directly. Although most useful in NotRunning state (e.g.,
-    connected to a valueChanged() signal in a QSlider,) this function can be
+    connected to a valueChanged() signal in a QSlider), this function can be
     called at any time.
 
     The frame interface is useful for standard widgets, but QTimeLine can be
@@ -205,13 +205,12 @@ void QTimeLinePrivate::setCurrentTime(int msecs)
     step. When running, QTimeLine generates values between 0 and 1 by calling
     valueForTime() and emitting valueChanged(). By default, valueForTime()
     applies an interpolation algorithm to generate these value. You can choose
-    from a set of predefined timeline algorithms by calling
+    from a set of predefined timeline algorithms by calling setEasingCurve().
-    setCurveShape().
 
-    Note that by default, QTimeLine uses the EaseInOut curve shape,
+    Note that, by default, QTimeLine uses QEasingCurve::InOutSine, which
-    which provides a value that grows slowly, then grows steadily, and
+    provides a value that grows slowly, then grows steadily, and finally grows
-    finally grows slowly. For a custom timeline, you can reimplement
+    slowly. For a custom timeline, you can reimplement valueForTime(), in which
-    valueForTime(), in which case QTimeLine's curveShape property is ignored.
+    case QTimeLine's easingCurve property is ignored.
 
     \sa QProgressBar, QProgressDialog
 */
@@ -252,20 +251,20 @@ void QTimeLinePrivate::setCurrentTime(int msecs)
 
 /*!
     \enum QTimeLine::CurveShape
+    \obsolete use QEasingCurve instead
 
-    This enum describes the default shape of QTimeLine's value curve. The
+    This enum describes the shape of QTimeLine's value curve. The default shape
-    default, shape is EaseInOutCurve. The curve defines the relation
+    is EaseInOutCurve. The curve defines the relation between the value and the
-    between the value and the timeline.
+    timeline.
 
-    \value EaseInCurve The value starts growing slowly, then increases in speed.
+    \value EaseInCurve Obsolete equivalent of QEasingCurve::InCurve
-    \value EaseOutCurve The value starts growing steadily, then ends slowly.
+    \value EaseOutCurve Obsolete equivalent of QEasingCurve::OutCurve
-    \value EaseInOutCurve The value starts growing slowly, then runs steadily, then grows slowly again.
+    \value EaseInOutCurve Obsolete equivalent of QEasingCurve::InOutSine
-    \value LinearCurve The value grows linearly (e.g., if the duration is 1000 ms,
+    \value LinearCurve Obsolete equivalent of QEasingCurve::Linear
-           the value at time 500 ms is 0.5).
+    \value SineCurve Obsolete equivalent of QEasingCurve::SineCurve
-    \value SineCurve The value grows sinusoidally.
+    \value CosineCurve Obsolete equivalent of QEasingCurve::CosineCurve
-    \value CosineCurve The value grows cosinusoidally.
 
-    \sa setCurveShape()
+    \sa curveShape, setCurveShape(), easingCurve, QEasingCurve
 */
 
 /*!
@@ -492,6 +491,7 @@ void QTimeLine::setUpdateInterval(int interval)
     d->updateInterval = interval;
 }
 
+#if QT_DEPRECATED_SINCE(5, 15)
 /*!
     \property QTimeLine::curveShape
     \brief the shape of the timeline curve.
@@ -499,11 +499,15 @@ void QTimeLine::setUpdateInterval(int interval)
     The curve shape describes the relation between the time and value for the
     base implementation of valueForTime().
 
-    If you have reimplemented valueForTime(), this value is ignored.
+    This property is an indirect way to update the easingCurve property; if you
+    set both, the one set more recently overrides the other. (If valueForTime()
+    is reimplemented it will override both.)
 
     By default, this property is set to \l EaseInOutCurve.
 
-    \sa valueForTime()
+    \obsolete Access \c easingCurve instead.
+
+    \sa valueForTime(), easingCurve
 */
 QTimeLine::CurveShape QTimeLine::curveShape() const
 {
@@ -545,6 +549,7 @@ void QTimeLine::setCurveShape(CurveShape shape)
 {
     setEasingCurve(convert(shape));
 }
+#endif // 5.15 deprecation
 
 /*!
     \property QTimeLine::easingCurve
@@ -552,9 +557,11 @@ void QTimeLine::setCurveShape(CurveShape shape)
     \since 4.6
 
     Specifies the easing curve that the timeline will use.
-    If both easing curve and curveShape are set, the last set property will
+    If valueForTime() is reimplemented, this value is ignored.
-    override the previous one. (If valueForTime() is reimplemented it will
+    If both easingCurve and curveShape are set, the last property set will
-    override both)
+    override the previous one.
+
+    \sa valueForTime()
 */
 
 QEasingCurve QTimeLine::easingCurve() const

src/corelib/tools/qtimeline.h

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtCore module of the Qt Toolkit.
@@ -59,7 +59,9 @@ class Q_CORE_EXPORT QTimeLine : public QObject
     Q_PROPERTY(int currentTime READ currentTime WRITE setCurrentTime)
     Q_PROPERTY(Direction direction READ direction WRITE setDirection)
     Q_PROPERTY(int loopCount READ loopCount WRITE setLoopCount)
+#if QT_DEPRECATED_SINCE(5, 15)
     Q_PROPERTY(CurveShape curveShape READ curveShape WRITE setCurveShape)
+#endif
     Q_PROPERTY(QEasingCurve easingCurve READ easingCurve WRITE setEasingCurve)
 public:
     enum State {
@@ -71,6 +73,7 @@ public:
         Forward,
         Backward
     };
+#if QT_DEPRECATED_SINCE(5, 15)
     enum CurveShape {
         EaseInCurve,
         EaseOutCurve,
@@ -79,6 +82,7 @@ public:
         SineCurve,
         CosineCurve
     };
+#endif
 
     explicit QTimeLine(int duration = 1000, QObject *parent = nullptr);
     virtual ~QTimeLine();
@@ -103,8 +107,12 @@ public:
     int updateInterval() const;
     void setUpdateInterval(int interval);
 
+#if QT_DEPRECATED_SINCE(5, 15)
+    QT_DEPRECATED_X("Access easingCurve directly")
     CurveShape curveShape() const;
+    QT_DEPRECATED_X("Access easingCurve directly")
     void setCurveShape(CurveShape shape);
+#endif
 
     QEasingCurve easingCurve() const;
     void setEasingCurve(const QEasingCurve &curve);

tests/auto/corelib/tools/qtimeline/tst_qtimeline.cpp

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the test suite of the Qt Toolkit.
@@ -306,13 +306,13 @@ void tst_QTimeLine::loopCount()
 void tst_QTimeLine::interpolation()
 {
     QTimeLine timeLine(400);
-    QCOMPARE(timeLine.curveShape(), QTimeLine::EaseInOutCurve);
+    QCOMPARE(timeLine.easingCurve(), QEasingCurve::InOutSine);
     timeLine.setFrameRange(100, 200);
-    timeLine.setCurveShape(QTimeLine::LinearCurve);
+    timeLine.setEasingCurve(QEasingCurve::Linear);
-    QCOMPARE(timeLine.curveShape(), QTimeLine::LinearCurve);
+    QCOMPARE(timeLine.easingCurve(), QEasingCurve::Linear);
 
     // smooth
-    timeLine.setCurveShape(QTimeLine::EaseInOutCurve);
+    timeLine.setEasingCurve(QEasingCurve::InOutSine);
     timeLine.start();
     QTest::qWait(100);
     QCOMPARE(timeLine.state(), QTimeLine::Running);
@@ -323,7 +323,7 @@ void tst_QTimeLine::interpolation()
     timeLine.setCurrentTime(0);
 
     // linear
-    timeLine.setCurveShape(QTimeLine::LinearCurve);
+    timeLine.setEasingCurve(QEasingCurve::Linear);
     timeLine.start();
     QTest::qWait(100);
     QCOMPARE(timeLine.state(), QTimeLine::Running);
@@ -373,7 +373,7 @@ void tst_QTimeLine::reverse()
     QFETCH(int, wait2);
 
     QTimeLine timeLine(duration);
-    timeLine.setCurveShape(QTimeLine::LinearCurve);
+    timeLine.setEasingCurve(QEasingCurve::Linear);
     timeLine.setFrameRange(start, end);
 
     timeLine.setDirection((QTimeLine::Direction)direction);
@@ -419,7 +419,7 @@ void tst_QTimeLine::toggleDirection()
 void tst_QTimeLine::frameChanged()
 {
     QTimeLine timeLine;
-    timeLine.setCurveShape(QTimeLine::LinearCurve);
+    timeLine.setEasingCurve(QEasingCurve::Linear);
     timeLine.setFrameRange(0,9);
     timeLine.setUpdateInterval(800);
     QSignalSpy spy(&timeLine, &QTimeLine::frameChanged);
@@ -519,7 +519,7 @@ void tst_QTimeLine::multipleTimeLines()
 void tst_QTimeLine::sineCurve()
 {
     QTimeLine timeLine(1000);
-    timeLine.setCurveShape(QTimeLine::SineCurve);
+    timeLine.setEasingCurve(QEasingCurve::SineCurve);
     QCOMPARE(timeLine.valueForTime(0), qreal(0));
     QCOMPARE(timeLine.valueForTime(250), qreal(0.5));
     QCOMPARE(timeLine.valueForTime(500), qreal(1));
@@ -530,7 +530,7 @@ void tst_QTimeLine::sineCurve()
 void tst_QTimeLine::cosineCurve()
 {
     QTimeLine timeLine(1000);
-    timeLine.setCurveShape(QTimeLine::CosineCurve);
+    timeLine.setEasingCurve(QEasingCurve::CosineCurve);
     QCOMPARE(timeLine.valueForTime(0), qreal(0.5));
     QCOMPARE(timeLine.valueForTime(250), qreal(1));
     QCOMPARE(timeLine.valueForTime(500), qreal(0.5));
@@ -544,7 +544,7 @@ void tst_QTimeLine::outOfRange()
     QCOMPARE(timeLine.valueForTime(-100), qreal(0));
     QCOMPARE(timeLine.valueForTime(2000), qreal(1));
 
-    timeLine.setCurveShape(QTimeLine::SineCurve);
+    timeLine.setEasingCurve(QEasingCurve::SineCurve);
     QCOMPARE(timeLine.valueForTime(2000), qreal(0));
 }