En esta página

StateMachine QML Type

Ofrece una máquina de estados finitos jerárquica. Más información...

Import Statement: import QtQml.StateMachine 6.12
Inherits:

State

Propiedades

Señales

Métodos

Descripción detallada

StateMachine se basa en los conceptos y la notación de los diagramas de estados (Statecharts). StateMachine forma parte de la API QML deQt State Machine

Una máquina de estados gestiona un conjunto de estados y transiciones entre dichos estados; estos estados y transiciones definen un grafo de estados. Una vez construido el grafo de estados, la máquina de estados puede ejecutarlo. El algoritmo de ejecución de StateMachine se basa en el algoritmo State Chart XML (SCXML). La descripción general del marco ofrece varios grafos de estados y el código para construirlos.

Antes de poder iniciar la máquina, se debe establecer el estado « initialState ». El estado inicial es aquel en el que entra la máquina al iniciarse. A continuación, puedes establecer la propiedad «running» en «true» o llamar a « start()» para poner en marcha la máquina de estados. La señal «started» se emite al entrar en el estado inicial.

La máquina de estados procesa los eventos y realiza transiciones hasta que se alcanza un estado final de nivel superior; en ese momento, la máquina de estados emite la señal «finished()». También se puede detener la máquina de estados explícitamente mediante « stop()» (o bien estableciendo la propiedad «running» en «false»). En este caso, se emite la señal «stopped».

Ejemplo de uso

El siguiente fragmento de código muestra una máquina de estados que finalizará al hacer clic en un botón:

import QtQuick
import QtQml.StateMachine as DSM

Rectangle {
    Button {
        anchors.fill: parent
        id: button
        text: "Finish state"
        DSM.StateMachine {
            id: stateMachine
            initialState: state
            running: true
            DSM.State {
                id: state
                DSM.SignalTransition {
                    targetState: finalState
                    signal: button.clicked
                }
            }
            DSM.FinalState {
                id: finalState
            }
            onFinished: Qt.quit()
        }
    }
}

Si se produce un error, la máquina buscará un « errorState » y, si hay uno disponible, entrará en ese estado. Una vez entrado en el estado de error, se puede obtener el tipo de error mediante error(). La ejecución del grafo de estados no se detendrá al entrar en el estado de error. Si no hay ningún estado de error que se aplique a la situación errónea, la máquina dejará de ejecutarse y se mostrará un mensaje de error en la consola.

Advertencia: Establecer el parámetro `childMode` de una `StateMachine` en cualquier valor distinto de ` QState::ExclusiveStates ` dará lugar a una máquina de estados no válida y puede provocar un comportamiento incorrecto.


Véase también QAbstractState, State, SignalTransition, TimeoutTransition, HistoryState y Qt State Machine en la Guía de QML.

Documentación de propiedades

errorString : string [read-only]

La cadena de error de esta máquina de estados.

globalRestorePolicy : enumeration

La política de restauración de los estados de esta máquina de estados.

El valor predeterminado de esta propiedad es QState.DontRestoreProperties.

Esta enumeración especifica el tipo de política de restauración. La política de restauración entra en vigor cuando la máquina entra en un estado que establece una o más propiedades. Si la política de restauración se establece en QState.RestoreProperties, la máquina de estados guardará el valor original de la propiedad antes de que se establezca el nuevo valor.

Posteriormente, cuando la máquina entre en un estado en el que no se establezca un valor para la propiedad en cuestión, esta se restaurará automáticamente a su valor inicial.

Solo se guardará un valor inicial para cada propiedad. Si la máquina de estados ya ha guardado un valor para una propiedad, este no se sobrescribirá hasta que la propiedad se haya restaurado correctamente.

  • QState.DontRestoreProperties La máquina de estados no debe guardar los valores iniciales de las propiedades ni restaurarlos posteriormente.
  • QState.RestoreProperties La máquina de estados debe guardar los valores iniciales de las propiedades y restaurarlos más tarde.

running : bool

El estado actual de esta máquina de estados.

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

Documentación de Signal

started()

Esta señal se emite cuando la máquina de estados ha entrado en su estado inicial (State::initialState).

Nota: El controlador correspondiente es onStarted.

Véase también running, start() y State::finished.

stopped()

Esta señal se emite cuando la máquina de estados se ha detenido.

Nota: El controlador correspondiente es onStopped.

Véanse también running, stop() y State::finished.

Documentación de métodos

void start()

Inicia esta máquina de estados. La máquina restablecerá su configuración y pasará al estado inicial. Cuando se alcance un estado final de nivel superior (FinalState), la máquina emitirá la señal finished().

Nota: Una máquina de estados no funcionará sin un bucle de eventos en ejecución, como el bucle de eventos principal de la aplicación iniciado con QCoreApplication::exec() o QApplication::exec().

Véase también started, State::finished, stop(), State::initialState y running.

void stop()

Detiene esta máquina de estados. La máquina de estados dejará de procesar eventos y, a continuación, emitirá la señal de detención.

Véase también stopped, start() y running.

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