QTimeLine Class Reference

#include <qtimeline.h>

Inheritance diagram for QTimeLine:

Inheritance graph
[legend]
Collaboration diagram for QTimeLine:

Collaboration graph
[legend]
List of all members.

Detailed Description

The QTimeLine class provides a timeline for controlling animations.

Since:
4.2
It's most commonly used to animate a GUI control by calling a slot periodically. You can construct a timeline by passing its duration in milliseconds to QTimeLine's constructor. The timeline's duration describes for how long the animation will run. Then you set a suitable frame range by calling setFrameRange(). Finally connect the frameChanged() signal to a suitable slot in the widget you wish to animate (e.g., setValue() in QProgressBar). When you proceed to calling start(), QTimeLine will enter Running state, and start emitting frameChanged() at regular intervals, causing your widget's connected property's value to grow from the lower end to the upper and of your frame range, at a steady rate. You can specify the update interval by calling setUpdateInterval(). When done, QTimeLine enters NotRunning state, and emits finished().

Example:

        ...
        progressBar = new QProgressBar(this);
        progressBar->setRange(0, 100);

        // Construct a 1-second timeline with a frame range of 0 - 100
        QTimeLine *timeLine = new QTimeLine(1000, this);
        timeLine->setFrameRange(0, 100);
        connect(timeLine, SIGNAL(frameChanged(int)), progressBar, SLOT(setValue(int)));

        // Clicking the pushbutton will start the progress bar animation
        pushButton = new QPushButton(tr("Start animation"), this);
        connect(pushButton, SIGNAL(clicked()), timeLine, SLOT(start()));
        ...

You can also use QTimeLine with the {Graphics View}{Graphics View framework} for animations. The QGraphicsItemAnimation class implements animation of {QGraphicsItem}{QGraphicsItems} with a timeline.

By default the timeline runs once, from the beginning and towards the 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 changed, causing the timeline to run backward, by calling 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., 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 used to control any type of animation. The heart of QTimeLine lies in the valueForTime() function, which generates a value between 0 and 1 for a given time. This value is typically used to describe the steps of an animation, where 0 is the first step of an animation, and 1 is the last 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 setCurveShape(). By default, QTimeLine uses the EaseInOut curve shape, which provides a value that grows slowly, then grows steadily, and finally grows slowly. For a custom timeline, you can reimplement valueForTime(), in which case QTimeLine's curveShape property is ignored.

See also:
QProgressBar, QProgressDialog, QGraphicsItemAnimation

Definition at line 34 of file qtimeline.h.

Public Types

enum  State
enum  Direction
enum  CurveShape

Public Slots

void start ()
void stop ()
void setPaused (bool paused)
void setCurrentTime (int msec)
void toggleDirection ()

Signals

void valueChanged (qreal x)
void frameChanged (int)
void stateChanged (QTimeLine::State newState)
void finished ()

Public Member Functions

 QTimeLine (int duration=1000, QObject *parent=0)
virtual ~QTimeLine ()
State state () const
int loopCount () const
void setLoopCount (int count)
Direction direction () const
void setDirection (Direction direction)
int duration () const
void setDuration (int duration)
int startFrame () const
void setStartFrame (int frame)
int endFrame () const
void setEndFrame (int frame)
void setFrameRange (int startFrame, int endFrame)
int updateInterval () const
void setUpdateInterval (int interval)
CurveShape curveShape () const
void setCurveShape (CurveShape shape)
int currentTime () const
int currentFrame () const
qreal currentValue () const
int frameForTime (int msec) const
virtual qreal valueForTime (int msec) const

Protected Member Functions

void timerEvent (QTimerEvent *event)

Member Enumeration Documentation

enum QTimeLine::State

This enum describes the state of the timeline.

NotRunning The timeline is not running. This is the initial state of QTimeLine, and the state QTimeLine reenters when finished. The current time, frame and value remain unchanged until either setCurrentTime() is called, or the timeline is started by calling start().

Paused The timeline is paused (i.e., temporarily suspended). Calling setPaused(false) will resume timeline activity.

Running The timeline is running. While control is in the event loop, QTimeLine will update its current time at regular intervals, emitting valueChanged() and frameChanged() when appropriate.

See also:
state(), stateChanged()

Definition at line 44 of file qtimeline.h.

00044                {
00045         NotRunning,
00046         Paused,
00047         Running
00048     };

enum QTimeLine::Direction

This enum describes the direction of the timeline when in Running state.

Forward The current time of the timeline increases with time (i.e., moves from 0 and towards the end / duration).

Backward The current time of the timeline decreases with time (i.e., moves from the end / duration and towards 0).

See also:
setDirection()

Definition at line 49 of file qtimeline.h.

00049                    {
00050         Forward,
00051         Backward
00052     };

enum QTimeLine::CurveShape

This enum describes the default shape of QTimeLine's value curve. The default, shape is EaseInOutCurve. The curve defines the relation between the value and the timeline.

EaseInCurve The value starts growing slowly, then increases in speed. EaseOutCurve The value starts growing steadily, then ends slowly. EaseInOutCurve The value starts growing slowly, the runs steadily, then grows slowly again. LinearCurve The value grows linearly (e.g., if the duration is 1000 ms, the value at time 500 ms is 0.5). SineCurve The value grows sinusoidally.

See also:
setCurveShape()

Definition at line 53 of file qtimeline.h.

00053                     {
00054         EaseInCurve,
00055         EaseOutCurve,
00056         EaseInOutCurve,
00057         LinearCurve,
00058         SineCurve
00059     };

Constructor & Destructor Documentation

QTimeLine::QTimeLine ( int  duration = 1000,
QObject *  parent = 0 
) [explicit]

Constructs a timeline with a duration of duration milliseconds. parent is passed to QObject's constructor. The default duration is 1000 milliseconds.

Definition at line 278 of file qtimeline.cpp.

References setDuration().

00279     : QObject(*new QTimeLinePrivate, parent)
00280 {
00281     setDuration(duration);
00282 }

Here is the call graph for this function:

QTimeLine::~QTimeLine (  )  [virtual]

Destroys the timeline.

Definition at line 287 of file qtimeline.cpp.

00288 {
00289 }

Member Function Documentation

QTimeLine::State QTimeLine::state (  )  const

Returns the state of the timeline.

See also:
start(), setPaused(), stop()

Definition at line 296 of file qtimeline.cpp.

References d.

00297 {
00298     Q_D(const QTimeLine);
00299     return d->state;
00300 }

int QTimeLine::loopCount (  )  const

Definition at line 308 of file qtimeline.cpp.

References d.

00309 {
00310     Q_D(const QTimeLine);
00311     return d->totalLoopCount;
00312 }

void QTimeLine::setLoopCount ( int  count  ) 

Definition at line 313 of file qtimeline.cpp.

References d.

Referenced by Robot::Robot().

00314 {
00315     Q_D(QTimeLine);
00316     d->totalLoopCount = count;
00317 }

QTimeLine::Direction QTimeLine::direction (  )  const

Definition at line 328 of file qtimeline.cpp.

References d.

Referenced by GLWidget::animFinished().

00329 {
00330     Q_D(const QTimeLine);
00331     return d->direction;
00332 }

void QTimeLine::setDirection ( Direction  direction  ) 

Definition at line 333 of file qtimeline.cpp.

References d.

Referenced by GLWidget::animFinished(), and toggleDirection().

00334 {
00335     Q_D(QTimeLine);
00336     d->direction = direction;
00337     d->startTime = d->currentTime;
00338     d->timer.start();
00339 }

int QTimeLine::duration (  )  const

Definition at line 349 of file qtimeline.cpp.

References d.

00350 {
00351     Q_D(const QTimeLine);
00352     return d->duration;
00353 }

void QTimeLine::setDuration ( int  duration  ) 

Definition at line 354 of file qtimeline.cpp.

References d.

Referenced by QTreeViewPrivate::beginAnimatedOperation(), QTimeLine(), and Robot::Robot().

00355 {
00356     Q_D(QTimeLine);
00357     d->duration = duration;
00358 }

int QTimeLine::startFrame (  )  const

Returns the start frame, which is the frame corresponding to the start of the timeline (i.e., the frame for which the current value is 0).

See also:
setStartFrame(), setFrameRange()

Definition at line 366 of file qtimeline.cpp.

References d.

Referenced by QTreeViewPrivate::drawAnimatedOperation().

00367 {
00368     Q_D(const QTimeLine);
00369     return d->startFrame;
00370 }

void QTimeLine::setStartFrame ( int  frame  ) 

Sets the start frame, which is the frame corresponding to the start of the timeline (i.e., the frame for which the current value is 0), to frame.

See also:
startFrame(), endFrame(), setFrameRange()

Definition at line 378 of file qtimeline.cpp.

References d.

00379 {
00380     Q_D(QTimeLine);
00381     d->startFrame = frame;
00382 }

int QTimeLine::endFrame (  )  const

Returns the end frame, which is the frame corresponding to the end of the timeline (i.e., the frame for which the current value is 1).

See also:
setEndFrame(), setFrameRange()

Definition at line 390 of file qtimeline.cpp.

References d.

Referenced by QTreeViewPrivate::drawAnimatedOperation().

00391 {
00392     Q_D(const QTimeLine);
00393     return d->endFrame;
00394 }

void QTimeLine::setEndFrame ( int  frame  ) 

Sets the end frame, which is the frame corresponding to the end of the timeline (i.e., the frame for which the current value is 1), to frame.

See also:
endFrame(), startFrame(), setFrameRange()

Definition at line 402 of file qtimeline.cpp.

References d.

00403 {
00404     Q_D(QTimeLine);
00405     d->endFrame = frame;
00406 }

void QTimeLine::setFrameRange ( int  startFrame,
int  endFrame 
)

Sets the timeline's frame counter to start at startFrame, and end and endFrame. For each time value, QTimeLine will find the corresponding frame when you call currentFrame() or frameForTime() by interpolating, using the return value of valueForTime().

When in Running state, QTimeLine also emits the frameChanged() signal when the frame changes.

See also:
startFrame(), endFrame(), start(), currentFrame()

Definition at line 419 of file qtimeline.cpp.

References d.

Referenced by QTreeViewPrivate::beginAnimatedOperation().

00420 {
00421     Q_D(QTimeLine);
00422     d->startFrame = startFrame;
00423     d->endFrame = endFrame;
00424 }

int QTimeLine::updateInterval (  )  const

Definition at line 437 of file qtimeline.cpp.

References d.

00438 {
00439     Q_D(const QTimeLine);
00440     return d->updateInterval;
00441 }

void QTimeLine::setUpdateInterval ( int  interval  ) 

Definition at line 442 of file qtimeline.cpp.

References d.

Referenced by GLWidget::GLWidget(), and Robot::Robot().

00443 {
00444     Q_D(QTimeLine);
00445     d->updateInterval = interval;
00446 }

QTimeLine::CurveShape QTimeLine::curveShape (  )  const

Definition at line 459 of file qtimeline.cpp.

References d.

00460 {
00461     Q_D(const QTimeLine);
00462     return d->curveShape;
00463 }

void QTimeLine::setCurveShape ( CurveShape  shape  ) 

Definition at line 464 of file qtimeline.cpp.

References d.

Referenced by Robot::Robot().

00465 {
00466     Q_D(QTimeLine);
00467     d->curveShape = shape;
00468 }

int QTimeLine::currentTime (  )  const

Definition at line 479 of file qtimeline.cpp.

References d.

00480 {
00481     Q_D(const QTimeLine);
00482     return d->currentTime;
00483 }

int QTimeLine::currentFrame (  )  const

Returns the frame corresponding to the current time.

See also:
currentTime(), frameForTime(), setFrameRange()

Definition at line 497 of file qtimeline.cpp.

References d, and frameForTime().

Referenced by QTreeViewPrivate::drawAnimatedOperation().

00498 {
00499     Q_D(const QTimeLine);
00500     return frameForTime(d->currentTime);
00501 }

Here is the call graph for this function:

qreal QTimeLine::currentValue (  )  const

Returns the value corresponding to the current time.

See also:
valueForTime(), currentFrame()

Definition at line 508 of file qtimeline.cpp.

References d, and valueForTime().

00509 {
00510     Q_D(const QTimeLine);
00511     return valueForTime(d->currentTime);
00512 }

Here is the call graph for this function:

int QTimeLine::frameForTime ( int  msec  )  const

Returns the frame corresponding to the time msec. This value is calculated using a linear interpolation of the start and end frame, based on the value returned by valueForTime().

See also:
valueForTime(), setFrameRange()

Definition at line 521 of file qtimeline.cpp.

References d, int, and valueForTime().

Referenced by currentFrame().

00522 {
00523     Q_D(const QTimeLine);
00524     return d->startFrame + int((d->endFrame - d->startFrame) * valueForTime(msec));
00525 }

Here is the call graph for this function:

qreal QTimeLine::valueForTime ( int  msec  )  const [virtual]

Returns the timeline value for the time msec. The returned value, which varies depending on the curve shape, is always between 0 and 1. If msec is 0, the default implementation always returns 0.

Reimplement this function to provide a custom curve shape for your timeline.

See also:
CurveShape, frameForTime()

Definition at line 537 of file qtimeline.cpp.

References d, EaseInCurve, EaseInOutCurve, EaseOutCurve, pi, qMax(), qMin(), qt_sinProgress(), qt_smoothBeginEndMixFactor(), SineCurve, and value.

Referenced by currentValue(), and frameForTime().

00538 {
00539     Q_D(const QTimeLine);
00540     msec = qMin(qMax(msec, 0), d->duration);
00541 
00542     // Simple linear interpolation
00543     qreal value = msec / qreal(d->duration);
00544 
00545     switch (d->curveShape) {
00546     case EaseInOutCurve:
00547         value = qt_sinProgress(value);
00548         break;
00549         // SmoothBegin blends Smooth and Linear Interpolation.
00550         // Progress 0 - 0.3      : Smooth only
00551         // Progress 0.3 - ~ 0.5  : Mix of Smooth and Linear
00552         // Progress ~ 0.5  - 1   : Linear only
00553     case EaseInCurve: {
00554         const qreal sinProgress = qt_sinProgress(value);
00555         const qreal linearProgress = value;
00556         const qreal mix = qt_smoothBeginEndMixFactor(value);
00557         value = sinProgress * mix + linearProgress * (1.0 - mix);
00558         break;
00559     }
00560     case EaseOutCurve: {
00561         const qreal sinProgress = qt_sinProgress(value);
00562         const qreal linearProgress = value;
00563         const qreal mix = qt_smoothBeginEndMixFactor(1.0 - value);
00564         value = sinProgress * mix + linearProgress * (1.0 - mix);
00565         break;
00566     }
00567     case SineCurve:
00568         value = (::sin(((msec * pi * 2) / d->duration) - pi/2.0) + 1.0) / 2.0;
00569         break;
00570     default:
00571         break;
00572     }
00573 
00574     return value;
00575 }

Here is the call graph for this function:

void QTimeLine::start (  )  [slot]

Starts the timeline. QTimeLine will enter Running state, and once it enters the event loop, it will update its current time, frame and value at regular intervals. The default interval is 40 ms (i.e., 25 times per second). You can change the update interval by calling setUpdateInterval().

See also:
updateInterval(), frameChanged(), valueChanged()

Definition at line 585 of file qtimeline.cpp.

References Backward, d, Forward, qWarning(), Running, and QObject::startTimer().

Referenced by QTreeViewPrivate::beginAnimatedOperation(), GLWidget::mouseDoubleClickEvent(), and Robot::Robot().

00586 {
00587     Q_D(QTimeLine);
00588     if (d->timerId) {
00589         qWarning("QTimeLine::start: already running");
00590         return;
00591     }
00592     if (d->currentTime == d->duration && d->direction == Forward)
00593         d->currentTime = 0;
00594     else if (d->currentTime == 0 && d->direction == Backward)
00595         d->currentTime = d->duration;
00596     d->timerId = startTimer(d->updateInterval);
00597     d->startTime = d->currentTime;
00598     d->timer.start();
00599     d->setState(Running);
00600 }

void QTimeLine::stop (  )  [slot]

Stops the timeline, causing QTimeLine to enter NotRunning state.

See also:
start()

Definition at line 607 of file qtimeline.cpp.

References d, QObject::killTimer(), and NotRunning.

Referenced by QTreeViewPrivate::beginAnimatedOperation().

00608 {
00609     Q_D(QTimeLine);
00610     if (d->timerId)
00611         killTimer(d->timerId);
00612     d->setState(NotRunning);
00613     d->timerId = 0;
00614 }

void QTimeLine::setPaused ( bool  paused  )  [slot]

If paused is true, the timeline is paused, causing QTimeLine to enter Paused state. No updates will be signaled until either start() or setPaused(false) is called. If paused is false, the timeline is resumed and continues where it left.

See also:
state(), start()

Definition at line 624 of file qtimeline.cpp.

References d, QObject::killTimer(), NotRunning, Paused, qWarning(), Running, and QObject::startTimer().

00625 {
00626     Q_D(QTimeLine);
00627     if (d->state == NotRunning) {
00628         qWarning("QTimeLine::setPaused: Not running");
00629         return;
00630     }
00631     if (paused && d->state != Paused) {
00632         d->startTime = d->currentTime;
00633         killTimer(d->timerId);
00634         d->timerId = 0;
00635         d->setState(Paused);
00636     } else if (!paused && d->state == Paused) {
00637         d->timerId = startTimer(d->updateInterval);
00638         d->setState(Running);
00639     }
00640 }

void QTimeLine::setCurrentTime ( int  msec  )  [slot]

Definition at line 484 of file qtimeline.cpp.

References d.

00485 {
00486     Q_D(QTimeLine);
00487     d->startTime = 0;
00488     d->timer.restart();
00489     d->setCurrentTime(msec);
00490 }

void QTimeLine::toggleDirection (  )  [slot]

Toggles the direction of the timeline. If the direction was Forward, it becomes Backward, and vice verca.

See also:
setDirection()

Definition at line 648 of file qtimeline.cpp.

References Backward, d, Forward, and setDirection().

00649 {
00650     Q_D(QTimeLine);
00651     setDirection(d->direction == Forward ? Backward : Forward);
00652 }

QTimeLine::valueChanged ( qreal  value  )  [signal]

QTimeLine emits this signal at regular intervals when in Running state, but only if the current value changes. value is the current value. value is a number between 0.0 and 1.0

See also:
QTimeLine::setDuration(), QTimeLine::valueForTime(), QTimeLine::updateInterval

QTimeLine::frameChanged ( int  frame  )  [signal]

QTimeLine emits this signal at regular intervals when in Running state, but only if the current frame changes. frame is the current frame number.

See also:
QTimeLine::setFrameRange(), QTimeLine::updateInterval

QTimeLine::stateChanged ( QTimeLine::State  newState  )  [signal]

This signal is emitted whenever QTimeLine's state changes. The new state is newState.

QTimeLine::finished (  )  [signal]

This signal is emitted when QTimeLine finishes (i.e., reaches the end of its time line), and does not loop.

void QTimeLine::timerEvent ( QTimerEvent *  event  )  [protected, virtual]

Reimplemented from QObject.

Definition at line 657 of file qtimeline.cpp.

References d, QObject::event(), and Forward.

00658 {
00659     Q_D(QTimeLine);
00660     if (event->timerId() != d->timerId) {
00661         event->ignore();
00662         return;
00663     }
00664     event->accept();
00665 
00666     if (d->direction == Forward) {
00667         d->setCurrentTime(d->startTime + d->timer.elapsed());
00668     } else {
00669         d->setCurrentTime(d->startTime - d->timer.elapsed());
00670     }
00671 }

Here is the call graph for this function:

The documentation for this class was generated from the following files:
Generated on Thu Mar 15 19:33:53 2007 for Qt 4.2 User's Guide by  doxygen 1.5.1