QQuickTimeLine Class

The QQuickTimeLine class provides a timeline for controlling animations. More...

Header: #include <QQuickTimeLine>
Inherits: QObject and

Public Types

enum SyncMode { LocalSync, GlobalSync }

Public Functions

QQuickTimeLine(QObject *parent = nullptr)
virtual ~QQuickTimeLine()
int accel(QQuickTimeLineValue &timeLineValue, qreal velocity, qreal acceleration)
int accel(QQuickTimeLineValue &timeLineValue, qreal velocity, qreal acceleration, qreal maxDistance)
int accelDistance(QQuickTimeLineValue &timeLineValue, qreal velocity, qreal distance)
void callback(const QQuickTimeLineCallback &callback)
void clear()
void complete()
bool isActive() const
void move(QQuickTimeLineValue &timeLineValue, qreal destination, int time = 500)
void move(QQuickTimeLineValue &timeLineValue, qreal destination, const QEasingCurve &easing, int time = 500)
void moveBy(QQuickTimeLineValue &timeLineValue, qreal change, int time = 500)
void moveBy(QQuickTimeLineValue &timeLineValue, qreal change, const QEasingCurve &easing, int time = 500)
void pause(QQuickTimeLineObject &obj, int time)
void reset(QQuickTimeLineValue &timeLineValue)
void set(QQuickTimeLineValue &timeLineValue, qreal value)
void setSyncMode(SyncMode syncMode)
void setSyncPoint(int sp)
void sync(QQuickTimeLineValue &timeLineValue)
void sync(QQuickTimeLineValue &timeLineValue, QQuickTimeLineValue &syncTo)
SyncMode syncMode() const
int syncPoint() const

Reimplemented Protected Functions

virtual void debugAnimation(QDebug d) const override

Detailed Description

\internal

QQuickTimeLine is similar to QTimeLine except:

  • It updates QQuickTimeLineValue instances directly, rather than maintaining a single current value.

    For example, the following animates a simple value over 200 milliseconds:

     QQuickTimeLineValue v(<starting value>);
     QQuickTimeLine tl;
     tl.move(v, 100., 200);
     tl.start()
    

    If your program needs to know when values are changed, it can either connect to the QQuickTimeLine's updated() signal, or inherit from QQuickTimeLineValue and reimplement the QQuickTimeLineValue::setValue() method.

  • Supports multiple QQuickTimeLineValue, arbitrary start and end values and allows animations to be strung together for more complex effects.

    For example, the following animation moves the x and y coordinates of an object from wherever they are to the position (100, 100) in 50 milliseconds and then further animates them to (100, 200) in 50 milliseconds:

     QQuickTimeLineValue x(<starting value>);
     QQuickTimeLineValue y(<starting value>);
    
     QQuickTimeLine tl;
     tl.start();
    
     tl.move(x, 100., 50);
     tl.move(y, 100., 50);
     tl.move(y, 200., 50);
    
  • All QQuickTimeLine instances share a single, synchronized clock.

    Actions scheduled within the same event loop tick are scheduled synchronously against each other, regardless of the wall time between the scheduling. Synchronized scheduling applies both to within the same QQuickTimeLine and across separate QQuickTimeLine's within the same process.

Currently easing functions are not supported.

Member Type Documentation

enum QQuickTimeLine::SyncMode

Member Function Documentation

QQuickTimeLine::QQuickTimeLine(QObject *parent = nullptr)

Construct a new QQuickTimeLine with the specified parent.

[virtual noexcept] QQuickTimeLine::~QQuickTimeLine()

Destroys the time line. Any inprogress animations are canceled, but not completed.

int QQuickTimeLine::accel(QQuickTimeLineValue &timeLineValue, qreal velocity, qreal acceleration)

Decelerate timeLineValue from the starting velocity to zero at the given acceleration rate. Although the acceleration is technically a deceleration, it should always be positive. The QQuickTimeLine will ensure that the deceleration is in the opposite direction to the initial velocity.

int QQuickTimeLine::accel(QQuickTimeLineValue &timeLineValue, qreal velocity, qreal acceleration, qreal maxDistance)

This is an overloaded function.

Decelerate timeLineValue from the starting velocity to zero at the given acceleration rate over a maximum distance of maxDistance.

If necessary, QQuickTimeLine will reduce the acceleration to ensure that the entire operation does not require a move of more than maxDistance. maxDistance should always be positive.

int QQuickTimeLine::accelDistance(QQuickTimeLineValue &timeLineValue, qreal velocity, qreal distance)

Decelerate timeLineValue from the starting velocity to zero over the given distance. This is like accel(), but the QQuickTimeLine calculates the exact deceleration to use.

distance should be positive.

void QQuickTimeLine::callback(const QQuickTimeLineCallback &callback)

Execute the event.

void QQuickTimeLine::clear()

Resets the timeline. All queued actions are discarded and QQuickTimeLineValue's retain their current value. For example,

 QQuickTimeLineValue v(0.);
 QQuickTimeLine tl;
 tl.move(v, 100., 1000.);
 // 500 ms passes
 // v.value() == 50.
 tl.clear();
 // v.value() == 50.

void QQuickTimeLine::complete()

Completes the timeline. All queued actions are played to completion, and then discarded. For example,

 QQuickTimeLineValue v(0.);
 QQuickTimeLine tl;
 tl.move(v, 100., 1000.);
 // 500 ms passes
 // v.value() == 50.
 tl.complete();
 // v.value() == 100.

[override virtual protected] void QQuickTimeLine::debugAnimation(QDebug d) const

GfxClock::isActive()

bool QQuickTimeLine::isActive() const

Returns true if the timeline is active. An active timeline is one where QQuickTimeLineValue actions are still pending.

void QQuickTimeLine::move(QQuickTimeLineValue &timeLineValue, qreal destination, int time = 500)

Linearly change the timeLineValue from its current value to the given destination value over time milliseconds.

void QQuickTimeLine::move(QQuickTimeLineValue &timeLineValue, qreal destination, const QEasingCurve &easing, int time = 500)

Change the timeLineValue from its current value to the given destination value over time milliseconds using the easing curve.

void QQuickTimeLine::moveBy(QQuickTimeLineValue &timeLineValue, qreal change, int time = 500)

Linearly change the timeLineValue from its current value by the change amount over time milliseconds.

void QQuickTimeLine::moveBy(QQuickTimeLineValue &timeLineValue, qreal change, const QEasingCurve &easing, int time = 500)

Change the timeLineValue from its current value by the change amount over time milliseconds using the easing curve.

void QQuickTimeLine::pause(QQuickTimeLineObject &obj, int time)

Pause obj for time milliseconds.

void QQuickTimeLine::reset(QQuickTimeLineValue &timeLineValue)

Cancel (but don't complete) all scheduled actions for timeLineValue.

void QQuickTimeLine::set(QQuickTimeLineValue &timeLineValue, qreal value)

Set the value of timeLineValue.

void QQuickTimeLine::setSyncMode(SyncMode syncMode)

Set the timeline's synchronization mode to syncMode.

See also syncMode().

void QQuickTimeLine::setSyncPoint(int sp)

\internal

Temporary hack.

See also syncPoint().

void QQuickTimeLine::sync(QQuickTimeLineValue &timeLineValue)

Synchronize the end point of timeLineValue to the endpoint of the longest action cursrently scheduled in the timeline.

In pseudo-code, this is equivalent to:

 QQuickTimeLine::pause(timeLineValue, length_of(timeline) - length_of(timeLineValue))

void QQuickTimeLine::sync(QQuickTimeLineValue &timeLineValue, QQuickTimeLineValue &syncTo)

Synchronize the end point of timeLineValue to the endpoint of syncTo within this timeline.

Following operations on timeLineValue in this timeline will be scheduled after all the currently scheduled actions on syncTo are complete. In pseudo-code this is equivalent to:

 QQuickTimeLine::pause(timeLineValue, min(0, length_of(syncTo) - length_of(timeLineValue)))

SyncMode QQuickTimeLine::syncMode() const

Return the timeline's synchronization mode.

See also setSyncMode().

int QQuickTimeLine::syncPoint() const

\internal

Temporary hack.

See also setSyncPoint().