En esta página

QTimeLine Class

La clase QTimeLine proporciona una línea de tiempo para controlar animaciones. Más información...

Encabezado: #include <QTimeLine>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Heredado de: QObject

Tipos públicos

enum Direction { Forward, Backward }
enum State { NotRunning, Paused, Running }

Propiedades

Funciones públicas

QTimeLine(int duration = 1000, QObject *parent = nullptr)
virtual ~QTimeLine()
QBindable<int> bindableCurrentTime()
QBindable<QTimeLine::Direction> bindableDirection()
QBindable<int> bindableDuration()
QBindable<QEasingCurve> bindableEasingCurve()
QBindable<int> bindableLoopCount()
QBindable<int> bindableUpdateInterval()
int currentFrame() const
int currentTime() const
qreal currentValue() const
QTimeLine::Direction direction() const
int duration() const
QEasingCurve easingCurve() const
int endFrame() const
int frameForTime(int msec) const
int loopCount() const
void setDirection(QTimeLine::Direction direction)
void setDuration(int duration)
void setEasingCurve(const QEasingCurve &curve)
void setEndFrame(int frame)
void setFrameRange(int startFrame, int endFrame)
void setLoopCount(int count)
void setStartFrame(int frame)
void setUpdateInterval(int interval)
int startFrame() const
QTimeLine::State state() const
int updateInterval() const
virtual qreal valueForTime(int msec) const

Ranuras públicas

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

Señales

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

Funciones protegidas reimplementadas

virtual void timerEvent(QTimerEvent *event) override

Descripción detallada

Se utiliza principalmente para animar un control de la interfaz gráfica de usuario llamando a una ranura periódicamente. Se puede crear una línea de tiempo pasando su duración en milisegundos al constructor de QTimeLine. La duración de la línea de tiempo indica durante cuánto tiempo se ejecutará la animación. A continuación, se establece un rango de fotogramas adecuado llamando a setFrameRange(). Por último, se conecta la señal frameChanged() a una ranura adecuada del widget que se desea animar (por ejemplo, setValue() en QProgressBar). Al llamar a start(), QTimeLine entrará en el estado «Running» y comenzará a emitir frameChanged() a intervalos regulares, lo que hará que el valor de la propiedad conectada de tu widget aumente desde el extremo inferior hasta el superior de tu rango de fotogramas, a un ritmo constante. Puedes especificar el intervalo de actualización llamando a ` setUpdateInterval()`. Una vez hecho esto, QTimeLine pasa al estado « NotRunning » y emite ` finished()`.

Ejemplo:

//...
auto 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, &QTimeLine::frameChanged, progressBar, &QProgressBar::setValue);

// Clicking the push button will start the progress bar animation
auto pushButton = new QPushButton(tr("Start animation"), this);
connect(pushButton, &QPushButton::clicked, timeLine, &QTimeLine::start);
//...

Por defecto, la línea de tiempo se ejecuta una vez, desde el principio hasta el final, tras lo cual debes volver a llamar a ` start()` para reiniciarla desde el principio. Para que la línea de tiempo se repita en bucle, puedes llamar a ` setLoopCount()`, pasando el número de veces que debe ejecutarse antes de finalizar. La dirección también se puede cambiar, haciendo que la línea de tiempo se ejecute hacia atrás, llamando a ` setDirection()`. También puedes pausar y reanudar la línea temporal mientras se está ejecutando llamando a setPaused(). Para un control interactivo, se proporciona la función setCurrentTime(), que establece directamente la posición temporal de la línea temporal. Aunque resulta más útil en estado NotRunning (por ejemplo, conectada a una señal valueChanged() en un QSlider), esta función se puede llamar en cualquier momento.

La interfaz de fotogramas resulta útil para los widgets estándar, pero QTimeLine puede utilizarse para controlar cualquier tipo de animación. El núcleo de QTimeLine reside en la función valueForTime(), que genera un valor entre 0 y 1 para un tiempo dado. Este valor se utiliza normalmente para describir los pasos de una animación, donde 0 es el primer paso de la animación y 1 es el último. Durante su ejecución, QTimeLine genera valores entre 0 y 1 llamando a ` valueForTime()` y emitiendo ` valueChanged()`. Por defecto, ` valueForTime()` aplica un algoritmo de interpolación para generar estos valores. Puedes elegir entre un conjunto de algoritmos de línea temporal predefinidos llamando a ` setEasingCurve()`.

Ten en cuenta que, por defecto, QTimeLine utiliza QEasingCurve::InOutSine, que proporciona un valor que crece lentamente, luego crece de forma constante y, finalmente, vuelve a crecer lentamente. Para crear una línea temporal personalizada, puedes reimplementar valueForTime(), en cuyo caso se ignora la propiedad easingCurve de QTimeLine.

Véase también QProgressBar y QProgressDialog.

Documentación sobre los tipos de miembros

enum QTimeLine::Direction

Esta enumeración describe la dirección de la línea temporal cuando se encuentra en el estado « Running ».

ConstanteValorDescripción
QTimeLine::Forward0La hora actual de la línea temporal aumenta con el tiempo (es decir, se desplaza desde 0 hacia el final o la duración).
QTimeLine::Backward1La hora actual de la línea de tiempo disminuye con el paso del tiempo (es decir, se desplaza desde el final o la duración hacia 0).

Véase también setDirection().

enum QTimeLine::State

Esta enumeración describe el estado de la línea de tiempo.

ConstanteValorDescripción
QTimeLine::NotRunning0La línea de tiempo no se está ejecutando. Este es el estado inicial de ` QTimeLine`, y el estado ` QTimeLine ` vuelve a activarse una vez finalizada. La hora actual, el fotograma y el valor permanecen sin cambios hasta que se llame a ` setCurrentTime()` o se inicie la línea de tiempo llamando a ` start()`.
QTimeLine::Paused1La línea de tiempo está en pausa (es decir, suspendida temporalmente). Al llamar a ` setPaused(false)`, se reanudará la actividad de la línea de tiempo.
QTimeLine::Running2La línea de tiempo está en ejecución. Mientras el control se encuentra en el bucle de eventos, QTimeLine actualizará su tiempo actual a intervalos regulares, emitiendo valueChanged() y frameChanged() cuando sea apropiado.

Véase también state() y stateChanged().

Documentación de propiedades

[bindable] currentTime : int

Nota: Esta propiedad admite enlaces de tipo « QProperty ».

Esta propiedad contiene el tiempo actual de la línea de tiempo.

Cuando QTimeLine se encuentra en estado «Running», este valor se actualiza continuamente en función de la duración y la dirección de la línea de tiempo. En caso contrario, es el valor que estaba vigente cuando se llamó por última vez a stop(), o el valor establecido mediante setCurrentTime().

Nota: Puedes vincular otras propiedades a currentTime, pero no se recomienda establecer enlaces a ella. A medida que avanza la animación, currentTime se actualiza automáticamente, lo que cancela sus enlaces.

Por defecto, esta propiedad contiene el valor 0.

Funciones de acceso:

int currentTime() const
void setCurrentTime(int msec)

[bindable] direction : Direction

Nota: Esta propiedad admite enlaces de tipo « QProperty ».

Esta propiedad contiene la dirección de la línea de tiempo cuando QTimeLine se encuentra en el estado « Running ».

Esta dirección indica si el tiempo avanza desde 0 hacia la duración de la línea de tiempo, o desde el valor de la duración hacia 0 después de que se haya llamado a start().

Cualquier enlace de «direction» se eliminará no solo mediante «setDirection()», sino también mediante « toggleDirection()».

Por defecto, esta propiedad está establecida en Forward.

Funciones de acceso:

QTimeLine::Direction direction() const
void setDirection(QTimeLine::Direction direction)

[bindable] duration : int

Nota: Esta propiedad admite enlaces de tipo « QProperty ».

Esta propiedad contiene la duración total de la línea de tiempo en milisegundos.

Por defecto, este valor es 1000 (es decir, 1 segundo), pero puedes cambiarlo bien pasando una duración al constructor de ` QTimeLine`, bien llamando a `setDuration()`. La duración debe ser mayor que 0.

Nota: Cambiar la duración no hace que la hora actual se reinicie a cero ni a la nueva duración. También es necesario llamar a ` setCurrentTime()` con el valor deseado.

Funciones de acceso:

int duration() const
void setDuration(int duration)

[bindable] easingCurve : QEasingCurve

Nota: Esta propiedad admite enlaces de tipo « QProperty ».

Especifica la curva de aceleración que utilizará la línea de tiempo. Si se reimplementa ` valueForTime()` (), este valor se ignora.

Funciones de acceso:

QEasingCurve easingCurve() const
void setEasingCurve(const QEasingCurve &curve)

Véase también valueForTime().

[bindable] loopCount : int

Nota: Esta propiedad admite enlaces de tipo « QProperty ».

Esta propiedad indica el número de veces que la línea de tiempo debe reproducirse en bucle antes de que finalice.

Un recuento de bucles de 0 significa que la línea de tiempo se repetirá indefinidamente.

De forma predeterminada, esta propiedad tiene un valor de 1.

Funciones de acceso:

int loopCount() const
void setLoopCount(int count)

[bindable] updateInterval : int

Nota: Esta propiedad es compatible con los enlaces de QProperty.

Esta propiedad contiene el tiempo, en milisegundos, transcurrido entre cada actualización de la hora actual por parte de « QTimeLine ».

Al actualizar la hora actual, QTimeLine emitirá valueChanged() si el valor actual ha cambiado, y frameChanged() si ha cambiado el fotograma.

Por defecto, el intervalo es de 40 ms, lo que corresponde a una frecuencia de 25 actualizaciones por segundo.

Funciones de acceso:

int updateInterval() const
void setUpdateInterval(int interval)

Documentación de funciones de miembro

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

Crea una línea temporal con una duración de duration milisegundos. Se pasa parent al constructor de QObject. La duración por defecto es de 1000 milisegundos.

[virtual noexcept] QTimeLine::~QTimeLine()

Destruye la línea temporal.

int QTimeLine::currentFrame() const

Devuelve el fotograma correspondiente al momento actual.

Véase también currentTime(), frameForTime() y setFrameRange().

qreal QTimeLine::currentValue() const

Devuelve el valor correspondiente a la hora actual.

Véase también valueForTime() y currentFrame().

int QTimeLine::endFrame() const

Devuelve el fotograma final, que es el fotograma correspondiente al final de la línea de tiempo (es decir, el fotograma para el que el valor actual es 1).

Véase también setEndFrame() y setFrameRange().

[private signal] void QTimeLine::finished()

Esta señal se emite cuando finaliza « QTimeLine » (es decir, cuando llega al final de su línea temporal) y no se repite en bucle.

Nota: Se trata de una señal privada. Se puede utilizar en conexiones de señales, pero el usuario no puede emitirla.

[private signal] void QTimeLine::frameChanged(int frame)

QTimeLine Emite esta señal a intervalos regulares cuando se encuentra en estado « Running », pero solo si cambia la trama actual. « frame » es el número de la trama actual.

Nota: Se trata de una señal privada. Se puede utilizar en conexiones de señales, pero el usuario no puede emitirla.

Véase también QTimeLine::setFrameRange() y QTimeLine::updateInterval.

int QTimeLine::frameForTime(int msec) const

Devuelve el fotograma correspondiente al momento msec. Este valor se calcula mediante una interpolación lineal entre el fotograma inicial y el final, basándose en el valor devuelto por valueForTime().

Véanse también valueForTime() y setFrameRange().

[slot] void QTimeLine::resume()

Reanuda la línea temporal a partir del momento actual. ` QTimeLine ` volverá al estado «Running» y, una vez que entre en el bucle de eventos, actualizará su hora, fotograma y valor actuales a intervalos regulares.

A diferencia de start(), esta función no reinicia la línea temporal antes de reanudarla.

Véase también start(), updateInterval(), frameChanged() y valueChanged().

void QTimeLine::setEndFrame(int frame)

Establece el fotograma final —es decir, el fotograma correspondiente al final de la línea de tiempo (o sea, aquel para el que el valor actual es 1)— en frame.

Véase también endFrame(), startFrame() y setFrameRange().

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

Establece el contador de fotogramas de la línea de tiempo para que comience en startFrame y termine en endFrame. Para cada valor de tiempo, QTimeLine buscará el fotograma correspondiente al llamar a currentFrame() o frameForTime(), mediante interpolación y utilizando el valor devuelto por valueForTime().

Cuando se encuentra en estado «Running», QTimeLine también emite la señal « frameChanged()» cada vez que cambia el fotograma.

Véase también startFrame(), endFrame(), start() y currentFrame().

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

Si paused es verdadero, la línea de tiempo se pone en pausa, lo que hace que QTimeLine pase al estado «Pausado». No se notificarán actualizaciones hasta que se llame a start() o a setPaused(false). Si paused es falso, la línea de tiempo se reanuda y continúa desde donde se había quedado.

Véase también state() y start().

void QTimeLine::setStartFrame(int frame)

Establece el fotograma inicial —que es el fotograma correspondiente al inicio de la línea de tiempo (es decir, el fotograma para el que el valor actual es 0)— en frame.

Véase también startFrame(), endFrame() y setFrameRange().

[slot] void QTimeLine::start()

Inicia la línea temporal. « QTimeLine » pasará al estado «Running» y, una vez que entre en el bucle de eventos, actualizará su hora, fotograma y valor actuales a intervalos regulares. El intervalo por defecto es de 40 ms (es decir, 25 veces por segundo). Puedes modificar el intervalo de actualización llamando a « setUpdateInterval()».

La línea de tiempo comenzará desde la posición 0, o desde el final si se reproduce hacia atrás. Si deseas reanudar una línea de tiempo detenida sin reiniciarla, puedes llamar a resume() en su lugar.

Véanse también resume(), updateInterval(), frameChanged() y valueChanged().

int QTimeLine::startFrame() const

Devuelve el fotograma inicial, que es el fotograma correspondiente al inicio de la línea de tiempo (es decir, el fotograma para el que el valor actual es 0).

Véase también setStartFrame() y setFrameRange().

QTimeLine::State QTimeLine::state() const

Devuelve el estado de la línea de tiempo.

Véase también start(), setPaused() y stop().

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

Esta señal se emite cada vez que cambia el estado de « QTimeLine ». El nuevo estado es « newState ».

Nota: Se trata de una señal privada. Se puede utilizar en conexiones de señales, pero el usuario no puede emitirla.

[slot] void QTimeLine::stop()

Detiene la línea temporal, lo que hace que « QTimeLine » pase a un estado « NotRunning ».

Véase también start().

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

Reimplementa: ` QObject::timerEvent(QTimerEvent *event)`.

[slot] void QTimeLine::toggleDirection()

Cambia la dirección de la línea de tiempo. Si la dirección era «Hacia adelante», pasa a ser «Hacia atrás», y viceversa.

Se eliminan las asignaciones existentes de « direction ».

Véase también setDirection().

[private signal] void QTimeLine::valueChanged(qreal value)

QTimeLine Emite esta señal a intervalos regulares cuando se encuentra en estado « Running », pero solo si el valor actual cambia. « value » es el valor actual. « value » es un número comprendido entre 0,0 y 1,0

Nota: Se trata de una señal privada. Se puede utilizar en conexiones de señales, pero el usuario no puede emitirla.

Véase también QTimeLine::setDuration(), QTimeLine::valueForTime() y QTimeLine::updateInterval.

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

Devuelve el valor de la línea de tiempo correspondiente al momento msec. El valor devuelto, que varía en función de la forma de la curva, siempre está comprendido entre 0 y 1. Si msec es 0, la implementación predeterminada siempre devuelve 0.

Reimplementa esta función para proporcionar una forma de curva personalizada para tu línea de tiempo.

Véase también easingCurve y frameForTime().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.