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:
- postEvent(QEvent *event, QStateMachine::EventPriority priority)
- postDelayedEvent(QEvent *event, int delay)
- cancelDelayedEvent(int id)
- postDelayedEvent(QEvent *event, std::chrono::milliseconds delay)
Tipos públicos
| class | SignalEvent |
| class | WrappedEvent |
| enum | Error { NoError, NoInitialStateError, NoDefaultStateInHistoryStateError, NoCommonAncestorForTransitionError, StateMachineChildModeSetToParallelError } |
| enum | EventPriority { NormalPriority, HighPriority } |
Propiedades
- animated : bool
- errorString : QString
- globalRestorePolicy : QState::RestorePolicy
- running : bool
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.
| Constante | Valor | Descripción |
|---|---|---|
QStateMachine::NoError | 0 | No se ha producido ningún error. |
QStateMachine::NoInitialStateError | 1 | La 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::NoDefaultStateInHistoryStateError | 2 | La 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::NoCommonAncestorForTransitionError | 3 | La 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::StateMachineChildModeSetToParallelError | 4 | La 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.
| Constante | Valor | Descripción |
|---|---|---|
QStateMachine::NormalPriority | 0 | El evento tiene prioridad normal. |
QStateMachine::HighPriority | 1 | El 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.