En esta página

Qt State Machine Guía de QML

Qt State Machine Las API de QML proporcionan tipos para crear y ejecutar gráficos de estados en QML. Es similar al marco de trabajo de máquinas de estados de C++ basado en «Statecharts: A visual formalism for complex systems» de Harel, que también constituye la base de los diagramas de estados de UML. Al igual que su « C++ counterpart », el marco proporciona una API y un modelo de ejecución basados en State Chart XML (SCXML) para integrar los elementos y la semántica de los diagramas de estados en aplicaciones QML.

Para interfaces de usuario con múltiples estados visuales, independientes del estado lógico de la aplicación, se recomienda utilizar «QML States and Transitions».

Para ver la lista completa de tipos de QML que ofrece el marco de trabajo para crear máquinas de estados controladas por eventos, consulta: Qt State Machine QML Types

Uso de las importaciones tanto de QtQuick como de QtQml.StateMachine

Advertencia: Si intentas importar tanto QtQuick como QtQml.StateMachine en un único archivo QML, asegúrate de importar QtQml.StateMachine en último lugar. De esta forma, el tipo «State» lo proporciona el marco de trabajo de máquinas de estados declarativas y no QtQuick:

import QtQuick
import QtQml.StateMachine

StateMachine {
    State {
        // okay, is of type QtQml.StateMachine.State
    }
}

Como alternativa, puedes importar QtQml.StateMachine en un espacio de nombres independiente para evitar cualquier ambigüedad con el elemento «State» de QtQuick:

import QtQuick
import QtQml.StateMachine as DSM

DSM.StateMachine {
    DSM.State {
        // ...
    }
}

Una máquina de estados sencilla

Para demostrar la funcionalidad básica de la API de la máquina de estados, veamos un ejemplo: una máquina de estados con tres estados, s1, s2 y s3. La máquina de estados se controla mediante un único botón; al hacer clic en el botón, la máquina pasa a otro estado. Inicialmente, la máquina de estados se encuentra en el estado s1. A continuación se muestra un diagrama de estados que ilustra los diferentes estados de nuestro ejemplo.

Tres estados s1, s2 y s3 que cambian al pulsar el botón. Transiciones al hacer clic en el botón.

El siguiente fragmento de código muestra el código necesario para crear dicha máquina de estados.

    Button {
        anchors.fill: parent
        id: button

        // change the button label to the active state id
        text: s1.active ? "s1" : s2.active ? "s2" : "s3"
    }

    StateMachine {
        id: stateMachine
        // set the initial state
        initialState: s1

        // start the state machine
        running: true

        State {
            id: s1
            // create a transition from s1 to s2 when the button is clicked
            SignalTransition {
                targetState: s2
                signal: button.clicked
            }
            // do something when the state enters/exits
            onEntered: console.log("s1 entered")
            onExited: console.log("s1 exited")
        }

        State {
            id: s2
            // create a transition from s2 to s3 when the button is clicked
            SignalTransition {
                targetState: s3
                signal: button.clicked
            }
            // do something when the state enters/exits
            onEntered: console.log("s2 entered")
            onExited: console.log("s2 exited")
        }
        State {
            id: s3
            // create a transition from s3 to s1 when the button is clicked
            SignalTransition {
                targetState: s1
                signal: button.clicked
            }
            // do something when the state enters/exits
            onEntered: console.log("s3 entered")
            onExited: console.log("s3 exited")
        }
    }

La máquina de estados se ejecuta de forma asíncrona para formar parte del bucle de eventos de tu aplicación.

Máquinas de estados que finalizan

La máquina de estados definida en la sección anterior nunca finaliza. Para que una máquina de estados pueda finalizar, debe tener un estado final de nivel superior (objeto `FinalState `). Cuando la máquina de estados entra en el estado final de nivel superior, emite la señal ` finished ` y se detiene.

Lo único que hay que hacer para introducir un estado final en el gráfico es crear un objeto ` FinalState ` y utilizarlo como destino de una o más transiciones.

Compartir transiciones

Supongamos que queremos que el usuario pueda salir de la aplicación en cualquier momento haciendo clic en un botón «Salir». Para ello, debemos crear un estado final y convertirlo en el destino de una transición asociada a la señal clicked() del botón «Salir». Podríamos añadir una transición para cada estado; sin embargo, esto parece redundante y además habría que acordarse de añadir dicha transición desde cada nuevo estado que se añada en el futuro.

Podemos conseguir el mismo comportamiento (es decir, que al hacer clic en el botón «Salir» se salga de la máquina de estados, independientemente del estado en el que se encuentre) agrupando los estados s1, s2 y s3. Para ello, se crea un nuevo estado de nivel superior y se convierten los tres estados originales en hijos del nuevo estado. El siguiente diagrama muestra la nueva máquina de estados.

Estado s1 que contiene tres subestados s11, s12 y s13 que se alternan en las transiciones al pulsar el botón.

Los tres estados originales han pasado a denominarse s11, s12 y s13 para reflejar que ahora son hijos del nuevo estado de nivel superior, s1. Los estados hijos heredan implícitamente las transiciones de su estado padre. Esto significa que ahora basta con añadir una única transición desde s1 al estado final, s2. Los nuevos estados añadidos a s1 heredarán automáticamente esta transición.

Lo único que hay que hacer para agrupar estados es especificar el estado padre adecuado al crear el estado. También hay que especificar cuál de los estados hijos es el inicial (el estado hijo al que debe entrar la máquina de estados cuando el estado padre sea el destino de una transición).

    Row {
        anchors.fill: parent
        spacing: 2
        Button {
            id: button
            // change the button label to the active state id
            text: s11.active ? "s11" : s12.active ? "s12" : "s13"
        }
        Button {
            id: quitButton
            text: "quit"
        }
    }

    StateMachine {
        id: stateMachine
        // set the initial state
        initialState: s1

        // start the state machine
        running: true

        State {
            id: s1
            // set the initial state
            initialState: s11

            // create a transition from s1 to s2 when the button is clicked
            SignalTransition {
                targetState: s2
                signal: quitButton.clicked
            }
            // do something when the state enters/exits
            onEntered: console.log("s1 entered")
            onExited: console.log("s1 exited")
            State {
                id: s11
                // create a transition from s11 to s12 when the button is clicked
                SignalTransition {
                    targetState: s12
                    signal: button.clicked
                }
                // do something when the state enters/exits
                onEntered: console.log("s11 entered")
                onExited: console.log("s11 exited")
            }

            State {
                id: s12
                // create a transition from s12 to s13 when the button is clicked
                SignalTransition {
                    targetState: s13
                    signal: button.clicked
                }
                // do something when the state enters/exits
                onEntered: console.log("s12 entered")
                onExited: console.log("s12 exited")
            }
            State {
                id: s13
                // create a transition from s13 to s11 when the button is clicked
                SignalTransition {
                    targetState: s11
                    signal: button.clicked
                }
                // do something when the state enters/exits
                onEntered: console.log("s13 entered")
                onExited: console.log("s13 exited")
            }
        }
        FinalState {
            id: s2
            onEntered: console.log("s2 entered")
            onExited: console.log("s2 exited")
        }
        onFinished: Qt.quit()
    }

En este caso, queremos que la aplicación se cierre cuando la máquina de estados haya finalizado, por lo que la señal finished() de la máquina se conecta a la ranura quit() de la aplicación.

Un estado hijo puede anular una transición heredada. Por ejemplo, el siguiente código añade una transición que, en la práctica, hace que se ignore el botón «Salir» cuando la máquina de estados se encuentra en el estado « s12 ».

            State {
                id: s12
                // create a transition from s12 to s13 when the button is clicked
                SignalTransition {
                    targetState: s13
                    signal: button.clicked
                }

                // ignore Quit button when we are in state 12
                SignalTransition {
                    targetState: s12
                    signal: quitButton.clicked
                }

                // do something when the state enters/exits
                onEntered: console.log("s12 entered")
                onExited: console.log("s12 exited")
            }

Una transición puede tener cualquier estado como destino, independientemente de dónde se encuentre dicho estado en la jerarquía de estados.

Uso de los estados de historial

Imaginemos que queremos añadir un mecanismo de «interrupción» al ejemplo comentado en la sección anterior; el usuario debería poder hacer clic en un botón para que la máquina de estados realice alguna tarea no relacionada, tras lo cual la máquina de estados debería reanudar lo que estuviera haciendo antes (es decir, volver al estado anterior, que en este caso es uno de los tres estados).

Este comportamiento se puede modelar fácilmente utilizando estados de historial. Un estado de historial (objeto `HistoryState `) es un pseudoestado que representa el estado hijo en el que se encontraba el estado padre antes de salir de él por última vez.

Un estado de historial se crea como hijo del estado para el que deseamos registrar el estado hijo actual; cuando la máquina de estados detecta la presencia de dicho estado en tiempo de ejecución, registra automáticamente el estado hijo actual (real) al salir del estado padre. Una transición al estado de historial es, de hecho, una transición al estado hijo que la máquina de estados había guardado previamente; la máquina de estados «reenvía» automáticamente la transición al estado hijo real.

El siguiente diagrama muestra la máquina de estados tras añadir el mecanismo de interrupción.

Estado s1 con subestados y estado histórico; al pulsar el botón de interrupción, se pasa a s3, que vuelve al estado histórico s1 una vez finalizado.

El código siguiente muestra cómo se puede implementar; en este ejemplo, simplemente mostramos un cuadro de mensaje cuando se accede a « s3 » y, a continuación, volvemos inmediatamente al estado hijo anterior, « s1 », a través del estado de historial.

    Row {
        anchors.fill: parent
        spacing: 2
        Button {
            id: button
            // change the button label to the active state id
            text: s11.active ? "s11" : s12.active ? "s12" :  s13.active ? "s13" : "s3"
        }
        Button {
            id: interruptButton
            text: s1.active ? "Interrupt" : "Resume"
        }
        Button {
            id: quitButton
            text: "quit"
        }
    }

    StateMachine {
        id: stateMachine
        // set the initial state
        initialState: s1

        // start the state machine
        running: true

        State {
            id: s1
            // set the initial state
            initialState: s11

            // create a transition from s1 to s2 when the button is clicked
            SignalTransition {
                targetState: s2
                signal: quitButton.clicked
            }
            // do something when the state enters/exits
            onEntered: console.log("s1 entered")
            onExited: console.log("s1 exited")
            State {
                id: s11
                // create a transition from s1 to s2 when the button is clicked
                SignalTransition {
                    targetState: s12
                    signal: button.clicked
                }
                // do something when the state enters/exits
                onEntered: console.log("s11 entered")
                onExited: console.log("s11 exited")
            }

            State {
                id: s12
                // create a transition from s2 to s3 when the button is clicked
                SignalTransition {
                    targetState: s13
                    signal: button.clicked
                }
                // do something when the state enters/exits
                onEntered: console.log("s12 entered")
                onExited: console.log("s12 exited")
            }
            State {
                id: s13
                // create a transition from s3 to s1 when the button is clicked
                SignalTransition {
                    targetState: s1
                    signal: button.clicked
                }
                // do something when the state enters/exits
                onEntered: console.log("s13 entered")
                onExited: console.log("s13 exited")
            }

            // create a transition from s1 to s3 when the button is clicked
            SignalTransition {
                targetState: s3
                signal: interruptButton.clicked
            }
            HistoryState {
                id: s1h
            }
        }
        FinalState {
            id: s2
            onEntered: console.log("s2 entered")
            onExited: console.log("s2 exited")
        }
        State {
            id: s3
            SignalTransition {
                targetState: s1h
                signal: interruptButton.clicked
            }
            // do something when the state enters/exits
            onEntered: console.log("s3 entered")
            onExited: console.log("s3 exited")
        }
        onFinished: Qt.quit()
    }

Uso de estados paralelos

Supongamos que se desea modelar un conjunto de propiedades mutuamente excluyentes de un coche en una única máquina de estados. Digamos que las propiedades que nos interesan son «Limpio» frente a «Sucio» y «En movimiento» frente a «Sin movimiento». Se necesitarían cuatro estados mutuamente excluyentes y ocho transiciones para representar los estados y moverse libremente entre todas las combinaciones posibles, tal y como se muestra en el siguiente diagrama de estados.

Cuatro estados: limpio/sin movimiento, limpio/en movimiento, sucio/sin movimiento, sucio/en movimiento, con transiciones de «iniciado», «detenido», «limpiado» y «ensuciado»

Si añadiéramos una tercera propiedad (por ejemplo, «rojo» frente a «azul»), el número total de estados se duplicaría, hasta ocho; y si añadiéramos una cuarta propiedad (por ejemplo, «cierre» frente a «descapotable»), el número total de estados se duplicaría de nuevo, hasta 16.

Este aumento exponencial puede reducirse utilizando estados paralelos, lo que permite un crecimiento lineal del número de estados y transiciones a medida que añadimos más propiedades. Además, se pueden añadir o eliminar estados del grupo de estados paralelos sin que ello afecte a ninguno de sus estados hermanos. El siguiente diagrama de estados muestra los diferentes estados paralelos para el ejemplo del coche.

Estado paralelo s1 con regiones s11 (limpio/sucio) y s12 (en movimiento/sin movimiento)

Para crear un grupo de estados paralelos, establece `childMode` en ` QState.ParallelStates`.

State {
    id: s1
    childMode: QState.ParallelStates
    State {
        id: s11
    }
    State {
        id: s12
    }
}

Cuando se entra en un grupo de estados paralelos, se entra simultáneamente en todos sus estados hijos. Las transiciones dentro de cada uno de los estados hijos funcionan con normalidad. Sin embargo, cualquiera de los estados hijos puede realizar una transición que salga del estado padre. Cuando esto ocurre, se sale del estado padre y de todos sus estados hijos.

El paralelismo en el marco de la máquina de estados sigue una semántica intercalada. Todas las operaciones paralelas se ejecutarán en un único paso atómico del procesamiento de eventos, por lo que ningún evento puede interrumpir las operaciones paralelas. Sin embargo, los eventos seguirán procesándose de forma secuencial, ya que la propia máquina es de un solo subproceso. Por ejemplo, consideremos la situación en la que hay dos transiciones que salen del mismo grupo de estados paralelos y sus condiciones se cumplen simultáneamente. En este caso, el evento que se procese en último lugar de los dos no tendrá ningún efecto.

Salida de un estado compuesto

Un estado hijo puede ser final (un objeto ` FinalState `); cuando se entra en un estado hijo final, el estado padre emite la señal ` State::finished `. El siguiente diagrama muestra un estado compuesto ` s1 ` que realiza algún procesamiento antes de entrar en un estado final:

Estado s1 con un subestado de procesamiento que da paso al estado final, lo que provoca el paso a s2

Al entrar en el estado final de ` s1 `, ` s1 ` emitirá automáticamente ` finished`. Utilizamos una transición de señal para que este evento desencadene un cambio de estado:

State {
    id: s1
    SignalTransition {
        targetState: s2
        signal: s1.finished
    }
}

El uso de estados finales en estados compuestos resulta útil cuando se desea ocultar los detalles internos de un estado compuesto. El mundo exterior debería poder entrar en el estado y recibir una notificación cuando este haya completado su trabajo, sin necesidad de conocer los detalles internos. Se trata de un mecanismo de abstracción y encapsulación muy potente a la hora de construir máquinas de estados complejas (profundamente anidadas). (En el ejemplo anterior, por supuesto, se podría crear una transición directamente desde el estado « done » de « s1 », en lugar de depender de la señal «finished()» de « s1 », pero con la consecuencia de que los detalles de implementación de « s1 » quedarían expuestos y se dependería de ellos).

En el caso de los grupos de estados paralelos, la señal ` State::finished ` se emite cuando todos los estados hijos han entrado en estados finales.

Transiciones sin destino

Una transición no tiene por qué tener un estado de destino. Una transición sin destino puede activarse de la misma forma que cualquier otra transición; la diferencia es que no provoca ningún cambio de estado. Esto te permite reaccionar ante una señal o un evento cuando tu máquina se encuentra en un estado determinado, sin tener que salir de ese estado. Por ejemplo:

Button {
    id: button
    text: "button"
    StateMachine {
        id: stateMachine
        initialState: s1
        running: true
        State {
            id: s1
            SignalTransition {
                signal: button.clicked
                onTriggered: console.log("button pressed")
            }
        }
    }
}

El mensaje «botón pulsado» se mostrará cada vez que se haga clic en el botón, pero la máquina de estados permanecerá en su estado actual (s1). Si el estado de destino se estableciera explícitamente como s1, se saldría de s1 y se volvería a entrar en él cada vez (se emitirían las señales « QAbstractState::entered » y « QAbstractState::exited »).

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