QStateMachine 类
QStateMachine 类提供了一种分层有限状态机。更多信息...
头文件 | #include <QStateMachine> |
CMake | find_package(Qt6 REQUIRED COMPONENTS StateMachine) target_link_libraries(mytarget PRIVATE Qt6::StateMachine) |
qmake | QT += statemachine |
继承 | QState |
注意:此类中所有函数都是可重入的。
注意:这些函数也是线程安全的
- postEvent(QEvent *event, QStateMachine::EventPriority priority)
- postDelayedEvent(QEvent *event, int delay)
- cancelDelayedEvent(int id)
- postDelayedEvent(QEvent *event, std::chrono::milliseconds delay)
公共类型
类 | SignalEvent |
类 | WrappedEvent |
枚举 | Error { NoError, NoInitialStateError, NoDefaultStateInHistoryStateError, NoCommonAncestorForTransitionError, StateMachineChildModeSetToParallelError } |
枚举 | EventPriority { NormalPriority, HighPriority } |
属性
- animated : bool
- errorString : QString
- globalRestorePolicy : QState::RestorePolicy
- running : bool
公共函数
QStateMachine(QObject *parent = nullptr) | |
虚拟 | ~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 延迟) |
int | postDelayedEvent(QEvent *event, std::chrono::milliseconds 延迟) |
void | postEvent(QEvent *event, QStateMachine::EventPriority 优先级 = NormalPriority) |
void | removeDefaultAnimation(QAbstractAnimation *动画) |
void | removeState(QAbstractState *状态) |
void | setAnimated(bool 启用) |
void | setGlobalRestorePolicy(QState::RestorePolicy 恢复策略) |
重新实现的公共函数
virtual bool | eventFilter(QObject *watched, QEvent *event) override |
公共槽
void | setRunning(bool running) |
void | start() |
void | stop() |
信号
void | runningChanged(bool running) |
void | started() |
void | stopped() |
重新实现的保护函数
virtual bool | event(QEvent *e) override |
virtual void | onEntry(QEvent *event) override |
virtual void | onExit(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,它继承自QAbstractState。QState类提供了一个状态,你可以使用这个状态在状态进入或离开时设置QObject的属性和调用方法。它还包含添加转换的便捷函数,例如这个例子中使用的QSignalTransition。有关更多详细信息,请参阅QState类的描述。
如果遇到错误,机器将寻找一个错误状态,如果可用,则会进入此状态。可能的错误类型由Error枚举定义。进入错误状态后,可以使用error()获取错误类型。当进入错误状态时,状态图的执行不会停止。如果错误的当前状态没有适用的错误状态,机器将停止执行,并在控制台打印错误消息。
注意:重要:将状态机的ChildMode设置为并行 (ParallelStates)会导致无效的状态机。它只能设置为或保留为ExclusiveStates。
另请参阅:QAbstractState,QAbstractTransition,QState,以及Qt状态机概述。
成员类型文档
枚举 QStateMachine::Error
该枚举类型定义了在运行时可能发生的错误。当状态机在运行时遇到无法恢复的错误时,它将设置error()返回的错误代码,errorString()返回的错误消息,并根据错误上下文进入错误状态。
常量 | 值 | 描述 |
---|---|---|
QStateMachine::NoError | 0 | 没有发生错误。 |
QStateMachine::NoInitialStateError | 1 | 机器已经进入了一个没有设置初始状态的具有子状态的QState。这个错误的上下文是缺少初始状态的状态。 |
QStateMachine::NoDefaultStateInHistoryStateError | 2 | 机器已经进入了一个没有设置默认状态的QHistoryState。这个错误的上下文是缺少默认状态的QHistoryState。 |
QStateMachine::NoCommonAncestorForTransitionError | 3 | 机器选择了一个转换,其源状态和目标状态不属于相同的状态树,因此它们不是同一状态机的一部分。通常,这意味着其中一个状态没有被赋予任何父状态或添加到任何机器中。这个错误的上下文是转换的源状态。 |
QStateMachine::StateMachineChildModeSetToParallelError | 4 | 机器的childMode属性被设置为QState::ParallelStates。这是非法的。只有状态可以声明为并行,状态机本身不能。这个枚举值是在Qt 5.14中添加的。 |
另请参阅:setErrorState().
枚举 QStateMachine::EventPriority
该枚举类型指定了使用postEvent()将事件发布到状态机的事件优先级。
高优先级事件先于正常优先级事件处理。
常量 | 值 | 描述 |
---|---|---|
QStateMachine::NormalPriority | 0 | 该事件具有正常优先级。 |
QStateMachine::HighPriority | 1 | 该事件具有高优先级。 |
属性文档
[bindable]
animated : bool
注意:此属性支持QProperty绑定。
此属性表示是否启用动画
此属性的默认值是true
。
另请参阅 QAbstractTransition::addAnimation()
[bindable read-only]
errorString : QString
注意:此属性支持QProperty绑定。
此属性包含该状态机的错误字符串
[bindable]
globalRestorePolicy : QState::RestorePolicy
注意:此属性支持QProperty绑定。
此属性包含此状态机的状态的恢复策略。
此属性的默认值是QState::DontRestoreProperties。
running : bool
此属性包含该状态机的运行状态
访问函数
bool | isRunning() const |
void | setRunning(bool running) |
通知信号
void | runningChanged(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 的通知信号。
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. 在芬兰和其他国家/地区的商标。所有其他商标均为各自所有者的财产。