En esta página

El marco de animación

El marco de animación ofrece una forma sencilla de animar los elementos de tu interfaz gráfica de usuario. Te permite animar el valor de una propiedad Qt de un widget o de QObject. La mayoría de las funciones que ofrece el marco también están disponibles en Qt Quick, donde es posible definir animaciones de forma declarativa.

Esta descripción general explica la arquitectura del marco, con ejemplos que ilustran las técnicas más habituales utilizadas para animar elementos de la interfaz de usuario ( QObject ) y elementos de la interfaz gráfica de usuario (GUI).

La arquitectura de Animation

El siguiente diagrama muestra las clases más importantes que proporciona el marco:

La jerarquía de clases del Animation Framework.

Incluye la clase ` QAbstractAnimation `, que proporciona la base necesaria para las animaciones. Esta clase define las propiedades genéricas de todas las animaciones compatibles con el marco. Por ejemplo, la capacidad de iniciar, detener y pausar una animación. La clase también recibe las notificaciones de cambios de tiempo.

El marco proporciona además las clases ` QVariantAnimation ` y ` QAnimationGroup `, que se basan en su caso base, ` QAbstractAnimation`. El siguiente en la jerarquía es ` QPropertyAnimation`, que deriva de ` QVariantAnimation` y permite animar una propiedad Qt de un widget o ` QObject`. La clase realiza una interpolación del valor de la propiedad utilizando una curva de aceleración. Con todo esto en su sitio, solo necesitas una clase ` QObject ` con un valor de propiedad Qt que puedas animar.

Nota: Es necesario que el objeto de destino que se va a animar sea un ` QObject ` o una de sus subclases. Esto es necesario, ya que el marco de animación depende del sistema de metaobjetos para obtener toda la información sobre el objeto que está animando.

Se pueden crear animaciones complejas construyendo una estructura de árbol de objetos ` QAbstractAnimation`, donde el árbol es un ` QAnimationGroup ` que contiene otras animaciones. Estos grupos de animación también pueden contener subgrupos que representen diferentes grupos o animaciones, como ` QParallelAnimationGroup ` y ` QSequentialAnimationGroup`.

En segundo plano, todas las animaciones se controlan mediante un temporizador global, que envía updates sobre todas las animaciones que se están ejecutando.

Para obtener información detallada sobre estas clases individuales y sus funciones en el marco, consulta su documentación.

Clases que ofrece el marco

Estas clases proporcionan la infraestructura necesaria para crear animaciones tanto sencillas como complejas.

QAbstractAnimation

La base de todas las animaciones

QAnimationGroup

Clase base abstracta para grupos de animaciones

QEasingCurve

Curvas de aceleración para controlar la animación

QParallelAnimationGroup

Grupo paralelo de animaciones

QPauseAnimation

Pausa para QSequentialAnimationGroup

QPropertyAnimation

Anima las propiedades de Qt

QSequentialAnimationGroup

Grupo secuencial de animaciones

QTimeLine

Línea de tiempo para controlar animaciones

QVariantAnimation

Clase base para animaciones

Animación de propiedades de Qt

Dado que la clase ` QPropertyAnimation ` puede interpolar propiedades de Qt, se utiliza con frecuencia. De hecho, su superclase —`QVariantAnimation`— proporciona una implementación abstracta de ` updateCurrentValue()`, que no modifica ningún valor a menos que se cambie en ` valueChanged signal`.

El marco permite animar las propiedades Qt de las clases existentes en Qt. Por ejemplo, la clase QWidget —que puede integrarse en un QGraphicsView— tiene propiedades para sus límites, colores, etc. El siguiente ejemplo muestra cómo se puede animar un widget QPushButton:

#include <QApplication>
#include <QPushButton>
#include <QPropertyAnimation>

class MyButtonWidget : public QWidget
{
public:
    MyButtonWidget(QWidget *parent = nullptr);
};

MyButtonWidget::MyButtonWidget(QWidget *parent) : QWidget(parent)
{
    QPushButton *button = new QPushButton(tr("Animated Button"), this);
    QPropertyAnimation *anim = new QPropertyAnimation(button, "pos", this);
    anim->setDuration(10000);
    anim->setStartValue(QPoint(0, 0));
    anim->setEndValue(QPoint(100, 250));
    anim->start();
}

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    MyButtonWidget buttonAnimWidget;
    buttonAnimWidget.resize(QSize(800, 600));
    buttonAnimWidget.show();
    return a.exec();
}

El ejemplo anima la propiedad Qt ` pos ` de un ` QPushButton` para desplazarlo desde la esquina superior izquierda de la pantalla hasta la posición final (250, 250) en 10 segundos (10 000 milisegundos).

Utiliza el método de interpolación lineal para controlar la velocidad de la animación entre los valores inicial y final. Intenta añadir otro valor entre el valor inicial y el final para ver cómo se interpolan. Esta vez, utiliza la función ` QPropertyAnimation::setKeyValueAt()` para añadir estos valores:

...
anim->setDuration(10000);
anim->setKeyValueAt(0, QPoint(0, 0));
anim->setKeyValueAt(0.8, QPoint(250, 250));
anim->setKeyValueAt(1, QPoint(0, 0));
...

En este ejemplo, la animación desplaza el botón hasta (250, 250) en 8 segundos y lo devuelve a su posición original en los 2 segundos restantes. El movimiento del botón se interpola de forma lineal entre estos puntos.

También puedes animar el valor de un ` QObject` que no esté declarado como propiedad de Qt, siempre que el valor cuente con un método setter. En tales casos, deriva una nueva clase a partir de la clase que contiene el valor y añade una propiedad de Qt para ese valor con el setter.

Nota: Cada propiedad de Qt requiere también un método de lectura, por lo que debes proporcionar uno si no está definido.

class MyGraphicsRectItem : public QObject, public QGraphicsRectItem
{
    Q_OBJECT
    Q_PROPERTY(QPointF pos READ pos WRITE setPos)
};

En este ejemplo, el ` MyGraphicsRectItem ` deriva de ` QGraphicsRectItem ` y ` QObject`, y define la propiedad ` pos `. Se puede animar el ` pos ` del elemento incluso si ` QGraphicsRectItem ` no proporciona la propiedad ` pos `.

Para obtener una introducción general al sistema de propiedades de Qt, consulta el Sistema de propiedades de Qt.

Las animaciones y el marco de trabajo de la vista gráfica

QPropertyAnimation también se puede utilizar para animar un ` QGraphicsItem`, que no hereda de ` QObject`. En tales casos, se deriva una clase del elemento gráfico que se desea animar. Esta clase derivada también debe heredar de ` QObject ` para permitir el uso de ` QPropertyAnimation ` en un ` QGraphicsItem`. El siguiente ejemplo muestra cómo se hace esto:

class Pixmap : public QObject, public QGraphicsPixmapItem
{
    Q_OBJECT
    Q_PROPERTY(QPointF pos READ pos WRITE setPos)
    ...
}

Nota: Tambiénpuedes derivar de QGraphicsWidget, que ya es un QObject.

Tal y como se describe en la sección anterior, es necesario definir las propiedades que se desean animar. La clase derivada debe heredar primero de QObject, ya que así lo exige el sistema de metaobjetos.

Curvas de aceleración

Un ` QPropertyAnimation ` realiza una interpolación lineal entre los valores iniciales y finales de las propiedades. Además de añadir más valores clave a la animación, también puedes elegir una curva de aceleración para controlar la velocidad de la interpolación entre 0 y 1, sin modificar la trayectoria.

MyButtonWidget::MyButtonWidget(QWidget *parent) : QWidget(parent)
{
    QPushButton *button = new QPushButton(tr("Animated Button"), this);
    QPropertyAnimation *anim = new QPropertyAnimation(button, "pos", this);
    anim->setDuration(10000);
    anim->setStartValue(QPoint(0, 0));
    anim->setEndValue(QPoint(100, 250));
    anim->setEasingCurve(QEasingCurve::OutBounce);
    anim->start();
}

En este ejemplo, la animación sigue una curva que hace que el ` button ` rebote como una pelota. ` QEasingCurve ` ofrece una amplia colección de curvas entre las que elegir en la enumeración ` QEasingCurve::Type `. Si deseas utilizar otra curva que no esté disponible, implementa una tú mismo y regístrala con ` QEasingCurve`.

Agrupación de animaciones

Una aplicación suele contener más de una animación. Por ejemplo, puede querer mover más de un elemento gráfico simultáneamente o moverlos en secuencia, uno tras otro.

Las subclases de ` QAnimationGroup` —`QSequentialAnimationGroup ` y ` QParallelAnimationGroup`— son contenedores de otras animaciones, de modo que estas pueden reproducirse de forma secuencial o en paralelo. El ` QAnimationGroup ` no anima propiedades, pero recibe notificaciones periódicas sobre los cambios de tiempo. Esto le permite reenviar dichos cambios a los grupos de animación, que controlan cuándo se reproducen sus animaciones.

Los dos ejemplos siguientes muestran el uso tanto de QSequentialAnimationGroup como de QParallelAnimationGroup:

MyButtonWidget::MyButtonWidget(QWidget *parent) : QWidget(parent)
{
    QPushButton *bonnie = new QPushButton(tr("Bonnie"), this);
    QPushButton *clyde = new QPushButton(tr("Clyde"), this);

    QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "pos", this);
    anim1->setDuration(3000);
    anim1->setStartValue(QPoint(0, 0));
    anim1->setEndValue(QPoint(100, 250));

    QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "pos", this);
    anim2->setDuration(3000);
    anim2->setStartValue(QPoint(100, 250));
    anim2->setEndValue(QPoint(500, 500));

    QParallelAnimationGroup *parallelAnim = new QParallelAnimationGroup;
    parallelAnim->addAnimation(anim1);
    parallelAnim->addAnimation(anim2);
    parallelAnim->start();
}

Un grupo paralelo reproduce más de una animación al mismo tiempo. Su función start() inicia todas las animaciones que forman parte del grupo.

MyButtonWidget::MyButtonWidget(QWidget *parent) : QWidget(parent)
{
    QPushButton *bonnie = new QPushButton(tr("Bonnie"), this);
    QPushButton *clyde = new QPushButton(tr("Clyde"), this);

    QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "pos", this);
    anim1->setDuration(3000);
    anim1->setStartValue(QPoint(0, 0));
    anim1->setEndValue(QPoint(100, 250));

    QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "pos", this);
    anim2->setDuration(3000);
    anim2->setStartValue(QPoint(0, 0));
    anim2->setEndValue(QPoint(200, 250));

    QSequentialAnimationGroup *sequenceAnim = new QSequentialAnimationGroup;
    sequenceAnim->addAnimation(anim1);
    sequenceAnim->addAnimation(anim2);
    sequenceAnim->start();
}

Como su nombre indica, un grupo « QSequentialAnimationGroup » reproduce sus animaciones de forma secuencial. Inicia la siguiente animación de la lista una vez finalizada la anterior.

Un grupo es en sí mismo una animación, por lo que puedes añadirlo a otro grupo. De esta forma, se crea un árbol de animaciones que define cuándo se reproducen las animaciones unas respecto a otras.

Propiedad de los objetos

Un grupo de animación ( QPropertyAnimation ) siempre debe tener un padre que controle su ciclo de vida. Una aplicación típica puede incluir varias animaciones agrupadas, en cuyo caso el grupo de animación asume la propiedad de dichas animaciones. A una animación independiente ( QPropertyAnimation ) se le debe asignar explícitamente un padre para controlar su ciclo de vida. En el siguiente ejemplo, se puede ver que una animación independiente ( QPropertyAnimation ) tiene como padre la instancia QApplication:

#include <QApplication>
#include <QPushButton>
#include <QPropertyAnimation>

class MyButtonWidget : public QWidget
{
public:
    MyButtonWidget(QWidget *parent = nullptr);
};

MyButtonWidget::MyButtonWidget(QWidget *parent) : QWidget(parent)
{
    QPushButton *button = new QPushButton(tr("Animated Button"), this);
    QPropertyAnimation *anim = new QPropertyAnimation(button, "pos", this);
    anim->setDuration(10000);
    anim->setStartValue(QPoint(0, 0));
    anim->setEndValue(QPoint(100, 250));
    anim->start();
}

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    MyButtonWidget buttonAnimWidget;
    buttonAnimWidget.resize(QSize(800, 600));
    buttonAnimWidget.show();
    return a.exec();
}

Nota: Tambiénse puede controlar la duración de la animación seleccionando un « delete policy » al iniciarla.

© 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.