En esta página

Mover bloques

El ejemplo «Mover bloques» muestra cómo animar elementos en un elemento « QGraphicsScene » utilizando un « QStateMachine » con una transición personalizada.

Cuatro cuadrados azules sobre fondo negro

El ejemplo anima los bloques azules que se pueden ver en la imagen anterior. La animación desplaza los bloques entre cuatro posiciones predefinidas.

El ejemplo consta de las siguientes clases:

  • StateSwitcher hereda de ` QState ` y puede añadir ` StateSwitchTransition` a otros estados. Al entrar en él, se producirá una transición aleatoria a uno de estos estados.
  • StateSwitchTransition es una transición personalizada que se activa en los « StateSwitchEvents».
  • StateSwitchEvent es un « QEvent » que activa « StateSwitchTransitions».
  • QGraphicsRectWidget es un « QGraphicsWidget » que simplemente pinta su fondo con un color sólido de « blue ».

Los bloques son instancias de ` QGraphicsRectWidget ` y se animan en un ` QGraphicsScene`. Para ello, creamos un grafo de estados en el que insertamos las animaciones. A continuación, el grafo se ejecuta en un ` QStateMachine`. Todo esto se lleva a cabo en ` main()`. Veamos primero la función ` main() `.

La función main()

Una vez inicializada QApplication, configuramos QGraphicsScene con sus QGraphicsRectWidgets.

    auto button1 = new QGraphicsRectWidget;
    auto button2 = new QGraphicsRectWidget;
    auto button3 = new QGraphicsRectWidget;
    auto button4 = new QGraphicsRectWidget;
    button2->setZValue(1);
    button3->setZValue(2);
    button4->setZValue(3);
    QGraphicsScene scene(0, 0, 300, 300);
    scene.setBackgroundBrush(Qt::black);
    scene.addItem(button1);
    scene.addItem(button2);
    scene.addItem(button3);
    scene.addItem(button4);

Tras añadir la escena a un ` QGraphicsView`, es el momento de construir el grafo de estados. Veamos primero un diagrama de estados de lo que estamos intentando construir.

StateSwitcher controla las transiciones en «Group State» con «State1», «State2» y «State3»

Ten en cuenta que el group tiene siete subestados, pero solo hemos incluido tres de ellos en el diagrama. El código que construye este gráfico se examinará línea por línea y mostrará cómo funciona el gráfico. En primer lugar, construimos el estado group:

    QStateMachine machine;

    auto group = new QState;
    group->setObjectName("group");
    QTimer timer;
    timer.setInterval(1250);
    timer.setSingleShot(true);
    QObject::connect(group, &QState::entered, &timer, QOverload<>::of(&QTimer::start));

El temporizador se utiliza para añadir un retraso entre cada movimiento de los bloques. El temporizador se pone en marcha al entrar en el estado « group ». Como veremos más adelante, el estado « group » tiene una transición de vuelta al estado « StateSwitcher » cuando el temporizador llega a su fin. « group » es el estado inicial de la máquina, por lo que se programará una animación al iniciar el ejemplo.

    auto state1 = createGeometryState(button1, QRect(100, 0, 50, 50),
                                      button2, QRect(150, 0, 50, 50),
                                      button3, QRect(200, 0, 50, 50),
                                      button4, QRect(250, 0, 50, 50),
                                      group);
    ...
    auto state7 = createGeometryState(button1, QRect(0, 0, 50, 50),
                                      button2, QRect(250, 0, 50, 50),
                                      button3, QRect(0, 250, 50, 50),
                                      button4, QRect(250, 250, 50, 50),
                                      group);
    group->setInitialState(state1);

createGeometryState() Devuelve un ` QState ` que establecerá la geometría de nuestros elementos al entrar en este estado. También asigna ` group ` como padre de este estado.

Un « QPropertyAnimation » insertado en una transición utilizará los valores asignados a un « QState » (con « QState::assignProperty()»), es decir, la animación interpolará entre los valores actuales de las propiedades y los valores del estado de destino. Más adelante añadiremos transiciones animadas al gráfico de estados.

    QParallelAnimationGroup animationGroup;

    auto anim = new QPropertyAnimation(button4, "geometry");
    anim->setDuration(1000);
    anim->setEasingCurve(QEasingCurve::OutElastic);
    animationGroup.addAnimation(anim);

Movemos los elementos en paralelo. Cada elemento se añade a « animationGroup », que es la animación que se inserta en las transiciones.

    auto subGroup = new QSequentialAnimationGroup(&animationGroup);
    subGroup->addPause(100);
    anim = new QPropertyAnimation(button3, "geometry");
    anim->setDuration(1000);
    anim->setEasingCurve(QEasingCurve::OutElastic);
    subGroup->addAnimation(anim);

El grupo de animación secuencial, subGroup, nos ayuda a insertar un retraso entre la animación de cada elemento.

    auto stateSwitcher = new StateSwitcher(&machine);
    stateSwitcher->setObjectName("stateSwitcher");
    group->addTransition(&timer, &QTimer::timeout, stateSwitcher);
    stateSwitcher->addState(state1, &animationGroup);
    stateSwitcher->addState(state2, &animationGroup);
    ...
    stateSwitcher->addState(state7, &animationGroup);

Se añade un `StateSwitchTransition` al selector de estados en ` StateSwitcher::addState()`. También añadimos la animación en esta función. Dado que ` QPropertyAnimation ` utiliza los valores de los estados, podemos insertar la misma instancia de ` QPropertyAnimation ` en todos los ` StateSwitchTransition`.

Como se ha mencionado anteriormente, añadimos una transición al selector de estados que se activa cuando se agota el tiempo del temporizador.

    machine.addState(group);
    machine.setInitialState(group);
    machine.start();

Por último, podemos crear la máquina de estados, añadir nuestro estado inicial e iniciar la ejecución del grafo de estados.

La función « createGeometryState() »

En createGeometryState(), configuramos la geometría de cada elemento gráfico.

static QState *createGeometryState(QObject *w1, const QRect &rect1, QObject *w2, const QRect &rect2,
                                   QObject *w3, const QRect &rect3, QObject *w4, const QRect &rect4,
                                   QState *parent)
{
    auto result = new QState(parent);
    result->assignProperty(w1, "geometry", rect1);
    result->assignProperty(w2, "geometry", rect2);
    result->assignProperty(w3, "geometry", rect3);
    result->assignProperty(w4, "geometry", rect4);

    return result;
}

Como se ha mencionado anteriormente, QAbstractTransition configurará una animación añadida con addAnimation() utilizando los valores de las propiedades establecidos con assignProperty().

La clase StateSwitcher

StateSwitcher cuenta con transiciones de cambio de estado a cada uno de los QStateque hemos creado con createGeometryState(). Su función es realizar una transición aleatoria a uno de estos estados cuando se accede a ella.

Todas las funciones de StateSwitcher están integradas. Repasaremos su definición paso a paso.

class StateSwitcher : public QState
{
    Q_OBJECT
public:
    explicit StateSwitcher(QStateMachine *machine) : QState(machine) { }

StateSwitcher es un estado diseñado para un propósito concreto y siempre será un estado de nivel superior. Utilizamos ` m_stateCount ` para llevar la cuenta de cuántos estados estamos gestionando, y ` m_lastIndex ` para recordar cuál fue el último estado al que realizamos la transición.

    void onEntry(QEvent *) override
    {
        int n;
        while ((n = QRandomGenerator::global()->bounded(m_stateCount) + 1) == m_lastIndex)
        { }
        m_lastIndex = n;
        machine()->postEvent(new StateSwitchEvent(n));
    }
    void onExit(QEvent *) override {}

Seleccionamos el siguiente estado al que vamos a realizar la transición y enviamos un ` StateSwitchEvent`, que sabemos que activará el ` StateSwitchTransition ` hacia el estado seleccionado.

    void addState(QState *state, QAbstractAnimation *animation) {
        auto trans = new StateSwitchTransition(++m_stateCount);
        trans->setTargetState(state);
        addTransition(trans);
        trans->addAnimation(animation);
    }

Aquí es donde ocurre la magia. Asignamos un número a cada estado añadido. Este número se proporciona tanto a StateSwitchTransition como a StateSwitchEvents. Como hemos visto, los eventos de cambio de estado activarán una transición con el mismo número.

La clase StateSwitchTransition

StateSwitchTransition hereda de ` QAbstractTransition ` y se activa en los ` StateSwitchEvent`. Solo contiene funciones en línea, así que echemos un vistazo a su función ` eventTest()`, que es la única que definimos.

    bool eventTest(QEvent *event) override
    {
        return (event->type() == QEvent::Type(StateSwitchEvent::StateSwitchType))
            && (static_cast<StateSwitchEvent *>(event)->rand() == m_rand);
    }

eventTest QStateMachine la invoca cuando comprueba si debe activarse una transición; un valor de retorno «true» significa que se activará. Simplemente comprobamos si el número que nos han asignado es igual al número del evento (en cuyo caso la activamos).

La clase `StateSwitchEvent`

StateSwitchEvent hereda de ` QEvent` y contiene un número que ha sido asignado a un estado y a una transición de cambio de estado mediante ` StateSwitcher`. Ya hemos visto cómo se utiliza para activar eventos ` StateSwitchTransition` en StateSwitcher.

class StateSwitchEvent: public QEvent
{
public:
    explicit StateSwitchEvent(int rand) : QEvent(StateSwitchType), m_rand(rand) { }

    static constexpr QEvent::Type StateSwitchType = QEvent::Type(QEvent::User + 256);

    int rand() const { return m_rand; }

private:
    int m_rand;
};

En esta clase solo hay funciones integradas, por lo que basta con echar un vistazo a su definición.

La clase QGraphicsRectWidget

QGraphicsRectWidget hereda d QGraphicsWidget y simplemente pinta su rect() de azul. Inlineamos paintEvent(), que es la única función que definimos. Aquí está la definición de la clase QGraphicsRectWidget:

class QGraphicsRectWidget : public QGraphicsWidget
{
public:
    void paint(QPainter *painter, const QStyleOptionGraphicsItem *, QWidget *) override
    {
        painter->fillRect(rect(), Qt::blue);
    }
};

Continuemos

La técnica mostrada en este ejemplo funciona igual de bien para todos los ` QPropertyAnimation`. Siempre que el valor que se vaya a animar sea una propiedad de Qt, puedes insertar una animación del mismo en un gráfico de estados.

QState::addAnimation() admite un ` QAbstractAnimation`, por lo que se puede insertar cualquier tipo de animación en el gráfico.

Proyecto de ejemplo en code.qt.io

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