QStateMachine 类

QStateMachine 类提供了一种分层有限状态机。更多信息...

头文件 #include <QStateMachine>
CMakefind_package(Qt6 REQUIRED COMPONENTS StateMachine)
target_link_libraries(mytarget PRIVATE Qt6::StateMachine)
qmakeQT += statemachine
继承 QState

注意:此类中所有函数都是可重入的

注意:这些函数也是线程安全

公共类型

SignalEvent
WrappedEvent
枚举Error { NoError, NoInitialStateError, NoDefaultStateInHistoryStateError, NoCommonAncestorForTransitionError, StateMachineChildModeSetToParallelError }
枚举EventPriority { NormalPriority, HighPriority }

属性

公共函数

QStateMachine(QObject *parent = nullptr)
虚拟~QStateMachine()
voidaddDefaultAnimation(QAbstractAnimation *animation)
voidaddState(QAbstractState *state)
QBindable<bool>bindableAnimated()
QBindable<QString>bindableErrorString() const
QBindable<QState::RestorePolicy>bindableGlobalRestorePolicy()
boolcancelDelayedEvent(int id)
voidclearError()
QSet<QAbstractState *>configuration() const
QList<QAbstractAnimation *>defaultAnimations() const
QStateMachine::Errorerror() const
QStringerrorString() const
QState::RestorePolicyglobalRestorePolicy() const
boolisAnimated() const
boolisRunning() const
intpostDelayedEvent(QEvent *event, int 延迟)
intpostDelayedEvent(QEvent *event, std::chrono::milliseconds 延迟)
voidpostEvent(QEvent *event, QStateMachine::EventPriority 优先级 = NormalPriority)
voidremoveDefaultAnimation(QAbstractAnimation *动画)
voidremoveState(QAbstractState *状态)
voidsetAnimated(bool 启用)
voidsetGlobalRestorePolicy(QState::RestorePolicy 恢复策略)

重新实现的公共函数

virtual booleventFilter(QObject *watched, QEvent *event) override

公共槽

voidsetRunning(bool running)
voidstart()
voidstop()

信号

voidrunningChanged(bool running)
voidstarted()
voidstopped()

重新实现的保护函数

virtual boolevent(QEvent *e) override
virtual voidonEntry(QEvent *event) override
virtual voidonExit(QEvent *event) override

详细说明

QStateMachine 基于状态图的概念和符号 Statecharts。QStateMachine 是 Qt 状态机框架 的一部分。

状态机管理一组状态(继承自 QAbstractState 的类)和这些状态之间的转换(继承自 QAbstractTransition 的子类);这些状态和转换定义了一个状态图。一旦构建了状态图,状态机就可以执行它。QStateMachine 的执行算法基于 状态图 XML (SCXML) 算法。框架的 概述 提供了几个状态图及其构建代码。

使用 addState() 函数将顶级状态添加到状态机。使用 removeState() 函数移除状态。不建议在机器运行时移除状态。

在机器可以启动之前,必须设置 initial state。初始状态是机器启动时进入的状态。然后可以 start() 状态机。当进入初始状态时将发出 started() 信号。

机器由事件驱动并保持自己的事件循环。事件通过 postEvent() 发送到机器。请注意,这意味着它是异步执行的,并且如果没有运行的事件循环,它将不会进展。通常不需要直接向机器发布事件,因为 Qt 的转换,例如 QEventTransition 及其子类,处理此操作。但是对于由事件触发的自定义转换,postEvent() 很有用。

状态机处理事件并执行转换,直到进入顶级最终状态;然后状态机发出 finished() 信号。还可以显式 stop() 状态机。在这种情况下将发出 stopped() 信号。

以下代码示例展示了一个当点击按钮后将会完成的有限状态机。

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();

此代码示例使用了QState,它继承自QAbstractStateQState类提供了一个状态,你可以使用这个状态在状态进入或离开时设置QObject的属性和调用方法。它还包含添加转换的便捷函数,例如这个例子中使用的QSignalTransition。有关更多详细信息,请参阅QState类的描述。

如果遇到错误,机器将寻找一个错误状态,如果可用,则会进入此状态。可能的错误类型由Error枚举定义。进入错误状态后,可以使用error()获取错误类型。当进入错误状态时,状态图的执行不会停止。如果错误的当前状态没有适用的错误状态,机器将停止执行,并在控制台打印错误消息。

注意:重要:将状态机的ChildMode设置为并行 (ParallelStates)会导致无效的状态机。它只能设置为或保留为ExclusiveStates

另请参阅:QAbstractStateQAbstractTransitionQState,以及Qt状态机概述

成员类型文档

枚举 QStateMachine::Error

该枚举类型定义了在运行时可能发生的错误。当状态机在运行时遇到无法恢复的错误时,它将设置error()返回的错误代码,errorString()返回的错误消息,并根据错误上下文进入错误状态。

常量描述
QStateMachine::NoError0没有发生错误。
QStateMachine::NoInitialStateError1机器已经进入了一个没有设置初始状态的具有子状态的QState。这个错误的上下文是缺少初始状态的状态。
QStateMachine::NoDefaultStateInHistoryStateError2机器已经进入了一个没有设置默认状态的QHistoryState。这个错误的上下文是缺少默认状态的QHistoryState
QStateMachine::NoCommonAncestorForTransitionError3机器选择了一个转换,其源状态和目标状态不属于相同的状态树,因此它们不是同一状态机的一部分。通常,这意味着其中一个状态没有被赋予任何父状态或添加到任何机器中。这个错误的上下文是转换的源状态。
QStateMachine::StateMachineChildModeSetToParallelError4机器的childMode属性被设置为QState::ParallelStates。这是非法的。只有状态可以声明为并行,状态机本身不能。这个枚举值是在Qt 5.14中添加的。

另请参阅:setErrorState().

枚举 QStateMachine::EventPriority

该枚举类型指定了使用postEvent()将事件发布到状态机的事件优先级。

高优先级事件先于正常优先级事件处理。

常量描述
QStateMachine::NormalPriority0该事件具有正常优先级。
QStateMachine::HighPriority1该事件具有高优先级。

属性文档

[bindable] animated : bool

注意:此属性支持QProperty绑定。

此属性表示是否启用动画

此属性的默认值是true

另请参阅 QAbstractTransition::addAnimation()

[bindable read-only] errorString : QString

注意:此属性支持QProperty绑定。

此属性包含该状态机的错误字符串

[bindable] globalRestorePolicy : QState::RestorePolicy

注意:此属性支持QProperty绑定。

此属性包含此状态机的状态的恢复策略。

此属性的默认值是QState::DontRestoreProperties

running : bool

此属性包含该状态机的运行状态

访问函数

boolisRunning() const
voidsetRunning(bool running)

通知信号

voidrunningChanged(bool running)

另请参阅 start(),stop(),started(),stopped() 和runningChanged()。

成员函数文档

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

使用给定的 parent 构造一个新状态机。

[虚拟]

销毁此状态机。

void QStateMachine::addDefaultAnimation(QAbstractAnimation *animation)

添加一个默认的 animation 以供任何转换考虑。

void QStateMachine::addState(QAbstractState *state)

将给定的 state 添加到此状态机。该状态成为顶级状态,状态机接管对该状态的所有权。

如果该状态已经在不同的机器中,它将首先从其以前的机器中删除,然后添加到此机器。

另请参阅 removeState() 和 setInitialState()。

bool QStateMachine::cancelDelayedEvent(int id)

取消由给定的 id 标识的延迟事件。应使用调用 postDelayedEvent 返回的值作为id。如果成功取消了事件,则返回 true,否则返回 false

注意:此函数是 线程安全的

另请参阅 postDelayedEvent

void QStateMachine::clearError()

清除状态机的错误字符串和错误代码。

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

返回当前此状态机所处于的最大一致状态集(包括并行和最终状态)。如果一个状态 s 在配置中,则 s 的父状态也在 c 中。请注意,然而,机器本身并不是配置的显式成员。

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

返回在任意转换中将被考虑的默认动画列表。

QStateMachine::Error QStateMachine::error() const

返回状态机中最后一个发生的错误的错误代码。

QString QStateMachine::errorString() const

返回状态机中最后一个发生的错误的错误字符串。

注意:错误字符串属性的获取函数。

[覆盖虚保护] bool QStateMachine::event(QEvent *e)

重新实现:QState::event(QEvent *e).

[覆盖虚] bool QStateMachine::eventFilter(QObject *watched, QEvent *event)

重新实现:QObject::eventFilter(QObject *watched, QEvent *event).

QState::RestorePolicy QStateMachine::globalRestorePolicy() const

返回状态机的恢复策略。

注意:全局恢复策略属性的获取函数。

另请参阅:setGlobalRestorePolicy()。

bool QStateMachine::isAnimated() const

返回是否为此状态机启用动画。

注意:animated属性的获取函数。

[覆盖虚保护] void QStateMachine::onEntry(QEvent *event)

重新实现:QState::onEntry(QEvent *event).

该函数将调用 start() 以启动状态机。

[覆盖虚保护] void QStateMachine::onExit(QEvent *event)

重新实现:QState::onExit(QEvent *event).

该函数将调用 stop() 以停止状态机,并且随后发出 stopped() 信号。

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

将指定的事件发布给此状态机处理,延迟延迟毫秒。返回与延迟事件关联的标识符,或者如果无法发布事件则返回-1。

此函数立即返回。当延迟时间过期后,事件将添加到状态机的选择队列以进行处理。状态机将拥有该事件,并在处理完成后删除它。

只有在状态机正在运行时才能发布事件。

注意:此函数是 线程安全的

另请参阅cancelDelayedEvent() 和 postEvent().

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

这是重载函数。

将指定的事件发布给此状态机处理,延迟延迟毫秒。返回与延迟事件关联的标识符,或者如果无法发布事件则返回-1。

此函数立即返回。当延迟时间过期后,事件将添加到状态机的选择队列以进行处理。状态机将拥有该事件,并在处理完成后删除它。

只有在状态机正在运行时才能发布事件。

注意:此函数是 线程安全的

另请参阅cancelDelayedEvent() 和 postEvent().

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

将指定的事件以及给定的优先级发布给此状态机以进行处理。

此函数立即返回。事件添加到状态机的选择队列。事件按照发布的顺序进行处理。状态机将拥有该事件,并在处理完成后删除它。

只有在状态机正在运行或开始启动时才能发布事件。

注意:此函数是 线程安全的

另请参阅 postDelayedEvent

void QStateMachine::removeDefaultAnimation(QAbstractAnimation *animation)

从默认动画列表中移除动画

void QStateMachine::removeState(QAbstractState *state)

从状态机中删除指定的状态。状态机释放对状态的拥有权。

另请参阅addState().

[信号] void QStateMachine::runningChanged(bool running)

当运行属性随带running参数而改变时,将发出此信号。

注意:属性 running 的通知信号。

另请参阅QStateMachine::running.

void QStateMachine::setAnimated(bool enabled)

设置是否为此状态机启用动画。

注意:属性 animated 的设置函数。

另请参阅isAnimated().

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

将状态机的恢复策略设置为恢复策略。默认的恢复策略是 QState::DontRestoreProperties

注意:属性 globalRestorePolicy 的设置函数。

另请参阅globalRestorePolicy.

[槽函数] void QStateMachine::start()

启动这个状态机。状态机将重置其配置并转换到初始状态。当进入最终顶级状态(QFinalState)时,状态机将发出finished() 信号。

注意:没有运行的事件循环,如使用 QCoreApplication::exec() 或 QApplication::exec() 启动的默认应用程序事件循环,状态机将无法运行。

另请参阅:started(),finished(),stop(),initialState() 和 setRunning()。

[私有信号] void QStateMachine::started()

当状态机进入其初始状态 (QStateMachine::initialState) 时,发出此信号。

注意:这是一个私有信号。可以在信号连接中使用,但不能由用户发出。

另请参阅:QStateMachine::finished() 和 QStateMachine::start()。

[槽函数] void QStateMachine::stop()

停止此状态机。状态机将停止处理事件,然后发出 stopped() 信号。

另请参阅:stopped(),start() 和 setRunning()。

[私有信号] void QStateMachine::stopped()

当状态机停止时,发出此信号。

注意:这是一个私有信号。可以在信号连接中使用,但不能由用户发出。

另请参阅:QStateMachine::stop() 和 QStateMachine::finished()。

© 2024 The Qt Company Ltd. 本文档的贡献包括各自所有者的版权。本文档提供的内容是根据自由软件基金会出版的 GNU自由文档许可1.3版 许可的。Qt及其 respective 标志是 The Qt Company Ltd. 在芬兰和其他国家/地区的商标。所有其他商标均为各自所有者的财产。