En esta página

QStateMachine Class

La clase QStateMachine proporciona una máquina de estados finitos jerárquica. Más información...

Encabezado: #include <QStateMachine>
CMake: find_package(Qt6 REQUIRED COMPONENTS StateMachine)
target_link_libraries(mytarget PRIVATE Qt6::StateMachine)
qmake: QT += statemachine
Heredado de: QState

Nota: Todas las funciones de esta clase son reentrantes.

Nota: Estas funciones también son seguras para subprocesos:

Tipos públicos

class SignalEvent
class WrappedEvent
enum Error { NoError, NoInitialStateError, NoDefaultStateInHistoryStateError, NoCommonAncestorForTransitionError, StateMachineChildModeSetToParallelError }
enum EventPriority { NormalPriority, HighPriority }

Propiedades

Funciones públicas

QStateMachine(QObject *parent = nullptr)
virtual ~QStateMachine()
void addDefaultAnimation(QAbstractAnimation *animation)
void addState(QAbstractState *state)
QBindable<bool> bindableAnimated()
QBindable<QString> bindableErrorString() const
QBindable<QState::RestorePolicy> bindableGlobalRestorePolicy()
bool cancelDelayedEvent(int id)
void clearError()
QSet<QAbstractState *> configuration() const
QList<QAbstractAnimation *> defaultAnimations() const
QStateMachine::Error error() const
QString errorString() const
QState::RestorePolicy globalRestorePolicy() const
bool isAnimated() const
bool isRunning() const
int postDelayedEvent(QEvent *event, int delay)
int postDelayedEvent(QEvent *event, std::chrono::milliseconds delay)
void postEvent(QEvent *event, QStateMachine::EventPriority priority = NormalPriority)
void removeDefaultAnimation(QAbstractAnimation *animation)
void removeState(QAbstractState *state)
void setAnimated(bool enabled)
void setGlobalRestorePolicy(QState::RestorePolicy restorePolicy)

Funciones públicas reimplementadas

virtual bool eventFilter(QObject *watched, QEvent *event) override

Ranuras públicas

void setRunning(bool running)
void start()
void stop()

Señales

void runningChanged(bool running)
void started()
void stopped()

Funciones protegidas reimplementadas

virtual bool event(QEvent *e) override
virtual void onEntry(QEvent *event) override
virtual void onExit(QEvent *event) override

Descripción detallada

QStateMachine se basa en los conceptos y la notación de los diagramas de estados (Statecharts). QStateMachine forma parte del marco de trabajo «Qt State Machine ».

Una máquina de estados gestiona un conjunto de estados (clases que heredan de ` QAbstractState`) y transiciones (descendientes de ` QAbstractTransition`) 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 QStateMachine se basa en el algoritmo State Chart XML (SCXML). La descripción general del marco de trabajo ofrece varios grafos de estados y el código para crearlos.

Utiliza la función addState() para añadir un estado de nivel superior a la máquina de estados. Los estados se eliminan con la función removeState(). No se recomienda eliminar estados mientras la máquina está en ejecución.

Antes de poder iniciar la máquina, es necesario establecer el ` initial state `. El estado inicial es aquel al que entra la máquina al iniciarse. A continuación, se puede poner en marcha la máquina de estados con ` start()`. La señal ` started()` se emite cuando se alcanza el estado inicial.

La máquina está controlada por eventos y mantiene su propio bucle de eventos. Los eventos se envían a la máquina mediante postEvent(). Ten en cuenta que esto significa que se ejecuta de forma asíncrona y que no avanzará sin un bucle de eventos en ejecución. Normalmente no tendrás que enviar eventos a la máquina directamente, ya que las transiciones de Qt, por ejemplo, ` QEventTransition ` y sus subclases, se encargan de ello. Sin embargo, para transiciones personalizadas desencadenadas por eventos, ` postEvent()` resulta útil.

La máquina de estados procesa los eventos y realiza transiciones hasta que se alcanza un estado final de nivel superior; entonces, la máquina de estados emite la señal « finished()». También puedes llamar explícitamente a « stop()» en la máquina de estados. En este caso, se emite la señal « stopped()».

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

QPushButton button;

QStateMachine machine;
QState *s1 = new QState();
s1->assignProperty(&button, "text", "Click me");

QFinalState *s2 = new QFinalState();
s1->addTransition(&button, &QPushButton::clicked, s2);

machine.addState(s1);
machine.addState(s2);
machine.setInitialState(s1);
machine.start();

Este ejemplo de código utiliza QState, que hereda de QAbstractState. La clase QState proporciona un estado que se puede utilizar para establecer propiedades e invocar métodos en QObjects al entrar o salir del estado. También contiene funciones prácticas para añadir transiciones, por ejemplo, QSignalTransitions como en este ejemplo. Consulte la descripción de la clase QState para obtener más detalles.

Si se produce un error, la máquina buscará un ` error state` y, si hay uno disponible, entrará en este estado. Los tipos de errores posibles se describen mediante la enumeración Error. 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.

Nota: Importante : establecer el valor de « ChildMode » de una máquina de estados en «parallel» (ParallelStates) da lugar a una máquina de estados no válida. Solo se puede establecer (o mantener) en « ExclusiveStates ».

Véase también « QAbstractState », « QAbstractTransition », « QState » y la Descripción general de «Qt State Machine ».

Documentación sobre los tipos de miembro

enum QStateMachine::Error

Este tipo de enumeración define los errores que pueden producirse en la máquina de estados durante la ejecución. Cuando la máquina de estados detecta un error irrecuperable durante la ejecución, establece el código de error devuelto por error(), el mensaje de error devuelto por errorString() y entra en un estado de error en función del contexto del error.

ConstanteValorDescripción
QStateMachine::NoError0No se ha producido ningún error.
QStateMachine::NoInitialStateError1La máquina ha entrado en un QState con estados secundarios que no tiene definido un estado inicial. El contexto de este error es el estado al que le falta un estado inicial.
QStateMachine::NoDefaultStateInHistoryStateError2La máquina ha entrado en un « QHistoryState » (transición) que no tiene definido un estado por defecto. El contexto de este error es el « QHistoryState » (transición) al que le falta un estado por defecto.
QStateMachine::NoCommonAncestorForTransitionError3La máquina ha seleccionado una transición cuyo origen y destino no forman parte del mismo árbol de estados y, por lo tanto, no pertenecen a la misma máquina de estados. Normalmente, esto podría significar que a uno de los estados no se le ha asignado ningún estado padre ni se ha añadido a ninguna máquina. El contexto de este error es el estado de origen de la transición.
QStateMachine::StateMachineChildModeSetToParallelError4La propiedad « childMode » de la máquina se ha establecido en « QState::ParallelStates ». Esto no es válido. Solo los estados pueden declararse como paralelos, no la propia máquina de estados. Este valor de enumeración se añadió en Qt 5.14.

Véase también setErrorState().

enum QStateMachine::EventPriority

Este tipo de enumeración especifica la prioridad de un evento enviado a la máquina de estados mediante ` postEvent()`.

Los eventos de alta prioridad se procesan antes que los de prioridad normal.

ConstanteValorDescripción
QStateMachine::NormalPriority0El evento tiene prioridad normal.
QStateMachine::HighPriority1El evento tiene prioridad alta.

Documentación de propiedades

[bindable] animated : bool

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

Esta propiedad indica si las animaciones están activadas

El valor predeterminado de esta propiedad es « true ».

Véase también QAbstractTransition::addAnimation()

Funciones de acceso:

bool isAnimated() const
void setAnimated(bool enabled)

[bindable read-only] errorString : QString

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

Esta propiedad contiene la cadena de error de esta máquina de estados

Funciones de acceso:

QString errorString() const

[bindable] globalRestorePolicy : QState::RestorePolicy

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

Esta propiedad contiene la política de restauración para los estados de esta máquina de estados.

El valor por defecto de esta propiedad es QState::DontRestoreProperties.

Funciones de acceso:

QState::RestorePolicy globalRestorePolicy() const
void setGlobalRestorePolicy(QState::RestorePolicy restorePolicy)

running : bool

Esta propiedad contiene el estado actual de esta máquina de estados

Funciones de acceso:

bool isRunning() const
void setRunning(bool running)

Señal de notificación:

void runningChanged(bool running)

Véase también start(), stop(), started(), stopped() y runningChanged().

Documentación de funciones de miembro

[explicit] QStateMachine::QStateMachine(QObject *parent = nullptr)

Crea una nueva máquina de estados con el parent especificado.

[virtual noexcept] QStateMachine::~QStateMachine()

Destruye esta máquina de estados.

void QStateMachine::addDefaultAnimation(QAbstractAnimation *animation)

Añade un valor predeterminado « animation » que se tendrá en cuenta en cualquier transición.

void QStateMachine::addState(QAbstractState *state)

Añade el « state » especificado a esta máquina de estados. El estado pasa a ser un estado de nivel superior y la máquina de estados asume la propiedad del mismo.

Si el estado ya se encuentra en otra máquina, primero se eliminará de su máquina anterior y, a continuación, se añadirá a esta máquina.

Véase también removeState() y setInitialState().

bool QStateMachine::cancelDelayedEvent(int id)

Cancela el evento diferido identificado por el « id » proporcionado. El «id» debe ser un valor devuelto por una llamada a « postDelayedEvent()». Devuelve « true » si el evento se ha cancelado correctamente; en caso contrario, devuelve « false ».

Nota: Esta función es segura para subprocesos.

Véase también postDelayedEvent().

void QStateMachine::clearError()

Borra la cadena de error y el código de error de la máquina de estados.

QSet<QAbstractState *> QStateMachine::configuration() const

Devuelve el conjunto máximo consistente de estados (incluidos los estados paralelos y finales) en el que se encuentra actualmente esta máquina de estados. Si un estado s está en la configuración, siempre se cumple que el estado padre de s también está en c. Sin embargo, hay que tener en cuenta que la propia máquina no es un miembro explícito de la configuración.

QList<QAbstractAnimation *> QStateMachine::defaultAnimations() const

Devuelve la lista de animaciones predeterminadas que se tendrán en cuenta para cualquier transición.

QStateMachine::Error QStateMachine::error() const

Devuelve el código de error del último error que se ha producido en la máquina de estados.

QString QStateMachine::errorString() const

Devuelve la cadena de error del último error que se ha producido en la máquina de estados.

Nota: Funcióngetter para la propiedad errorString.

[override virtual protected] bool QStateMachine::event(QEvent *e)

Reimplementa: QState::event(QEvent *e).

[override virtual] bool QStateMachine::eventFilter(QObject *watched, QEvent *event)

Reimplementa: ` QObject::eventFilter` (`QObject *watched, QEvent *event`).

QState::RestorePolicy QStateMachine::globalRestorePolicy() const

Devuelve la política de restauración de la máquina de estados.

Nota: Funcióngetter para la propiedad globalRestorePolicy.

Véase también setGlobalRestorePolicy().

bool QStateMachine::isAnimated() const

Devuelve si las animaciones están activadas para esta máquina de estados.

Nota: Funcióngetter para la propiedad « animated ».

[override virtual protected] void QStateMachine::onEntry(QEvent *event)

Reimplementa: ` QState::onEntry(QEvent *event)`.

Esta función llamará a start() para iniciar la máquina de estados.

[override virtual protected] void QStateMachine::onExit(QEvent *event)

Reimplementa: ` QState::onExit(QEvent *event)`.

Esta función llamará a stop() para detener la máquina de estados y, a continuación, emitirá la señal stopped().

int QStateMachine::postDelayedEvent(QEvent *event, int delay)

Envía el evento « event » especificado para que lo procese esta máquina de estados, con el retraso « delay » indicado en milisegundos. Devuelve un identificador asociado al evento retrasado, o -1 si no se ha podido enviar el evento.

Esta función devuelve el resultado de forma inmediata. Cuando haya transcurrido el retraso, el evento se añadirá a la cola de eventos de la máquina de estados para su procesamiento. La máquina de estados se hace cargo del evento y lo elimina una vez que ha sido procesado.

Solo se pueden enviar eventos cuando la máquina de estados está en ejecución.

Nota: Esta función es segura para subprocesos.

Véanse también cancelDelayedEvent() y postEvent().

int QStateMachine::postDelayedEvent(QEvent *event, std::chrono::milliseconds delay)

Envía el evento « event » especificado para que lo procese esta máquina de estados, con el retraso « delay » indicado en milisegundos. Devuelve un identificador asociado al evento retrasado, o -1 si no se ha podido enviar el evento.

Esta función devuelve el resultado inmediatamente. Cuando haya transcurrido el retraso, el evento se añadirá a la cola de eventos de la máquina de estados para su procesamiento. La máquina de estados se hace cargo del evento y lo elimina una vez que ha sido procesado.

Solo se pueden enviar eventos cuando la máquina de estados está en ejecución.

Esta es una función sobrecargada.

Nota: Esta función es segura para subprocesos.

Véase también cancelDelayedEvent() y postEvent().

void QStateMachine::postEvent(QEvent *event, QStateMachine::EventPriority priority = NormalPriority)

Envía el « event » especificado del « priority » indicado para que lo procese esta máquina de estados.

Esta función devuelve un resultado inmediatamente. El evento se añade a la cola de eventos de la máquina de estados. Los eventos se procesan en el orden en que se envían. La máquina de estados se hace cargo del evento y lo elimina una vez que ha sido procesado.

Solo se pueden enviar eventos cuando la máquina de estados está en ejecución o durante su puesta en marcha.

Nota: Esta función es segura para subprocesos.

Véase también postDelayedEvent().

void QStateMachine::removeDefaultAnimation(QAbstractAnimation *animation)

Elimina « animation » de la lista de animaciones predeterminadas.

void QStateMachine::removeState(QAbstractState *state)

Elimina el objeto ` state ` indicado de esta máquina de estados. La máquina de estados libera la propiedad del estado.

Véase también addState().

[signal] void QStateMachine::runningChanged(bool running)

Esta señal se emite cuando se modifica la propiedad «running» con « running » como argumento.

Nota: Señalde notificación para la propiedad « running ».

Véase también « QStateMachine::running ».

void QStateMachine::setAnimated(bool enabled)

Establece si las animaciones son « enabled » para esta máquina de estados.

Nota: Funciónde configuración para la propiedad animated.

Véase también ` isAnimated()`.

void QStateMachine::setGlobalRestorePolicy(QState::RestorePolicy restorePolicy)

Establece la política de restauración de la máquina de estados en « restorePolicy ». La política de restauración predeterminada es « QState::DontRestoreProperties ».

Nota: Funciónde asignación para la propiedad globalRestorePolicy.

Véase también globalRestorePolicy().

[slot] void QStateMachine::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 (QFinalState), la máquina emitirá la señal finished().

Nota: Una máquina de estados no se ejecutará 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(), finished(), stop(), initialState() y setRunning().

[private signal] void QStateMachine::started()

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

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 QStateMachine::finished() y QStateMachine::start().

[slot] void QStateMachine::stop()

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

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

[private signal] void QStateMachine::stopped()

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

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 QStateMachine::stop() y QStateMachine::finished().

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