QState Class
QState 类为QStateMachine 提供了通用状态。更多
| 头文件： | #include <QState> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS StateMachine)target_link_libraries(mytarget PRIVATE Qt6::StateMachine) |
| qmake： | QT += statemachine |
| 继承： | QAbstractState |
| 继承于： |
公共类型
| enum | ChildMode { ExclusiveStates, ParallelStates } |
| enum | RestorePolicy { DontRestoreProperties, RestoreProperties } |
属性
- childMode : ChildMode
- errorState : QAbstractState*
- initialState : QAbstractState*
公共功能
| QState(QState *parent = nullptr) | |
| QState(QState::ChildMode childMode, QState *parent = nullptr) | |
| virtual | ~QState() |
| QAbstractTransition * | addTransition(QAbstractState *target) |
| void | addTransition(QAbstractTransition *transition) |
| QSignalTransition * | addTransition(const QObject *sender, const char *signal, QAbstractState *target) |
| QSignalTransition * | addTransition(const QObject *sender, PointerToMemberFunction signal, QAbstractState *target) |
| void | assignProperty(QObject *object, const char *name, const QVariant &value) |
| QBindable<QState::ChildMode> | bindableChildMode() |
| QBindable<QAbstractState *> | bindableErrorState() |
| QBindable<QAbstractState *> | bindableInitialState() |
| QState::ChildMode | childMode() const |
| QAbstractState * | errorState() const |
| QAbstractState * | initialState() const |
| void | removeTransition(QAbstractTransition *transition) |
| void | setChildMode(QState::ChildMode mode) |
| void | setErrorState(QAbstractState *state) |
| void | setInitialState(QAbstractState *state) |
| QList<QAbstractTransition *> | transitions() const |
信号
| void | childModeChanged() |
| void | errorStateChanged() |
| void | finished() |
| void | initialStateChanged() |
| void | propertiesAssigned() |
重新实现的受保护函数
| virtual bool | event(QEvent *e) override |
| virtual void | onEntry(QEvent *event) override |
| virtual void | onExit(QEvent *event) override |
详细说明
QState 对象可以有子状态，并可以过渡到其他状态。QState 是Qt State Machine Framework 的一部分。
addTransition() 函数添加一个过渡。removeTransition() 函数删除一个过渡。transitions() 函数返回状态的传出转换。
assignProperty() 函数用于定义进入状态时应执行的属性分配。
顶层状态必须通过QStateMachine 对象作为父状态，或使用QStateMachine::addState() 添加到状态机中。
带有子状态的状态
childMode 属性决定了如何处理子状态。对于非并行状态组，必须调用setInitialState() 函数来设置初始状态。子状态是互斥状态，当父状态成为转换目标时，状态机需要知道进入哪个子状态。
当进入最终子状态（QFinalState ）时，状态会发出QState::finished() 信号。
setErrorState() 设置状态的错误状态。错误状态是状态机在试图进入状态时检测到错误（如没有设置初始状态）而过渡到的状态。
成员类型文档
enum QState::ChildMode
该枚举指定如何处理状态的子状态。
| 常数 | 值 | 说明 |
|---|---|---|
QState::ExclusiveStates | 0 | 子状态是互斥的，必须通过调用QState::setInitialState() 设置初始状态。 |
QState::ParallelStates | 1 | 子状态是并行的。当进入父状态时，所有子状态都会并行进入。 |
enum QState::RestorePolicy
该枚举用于指定还原策略类型。还原策略在机器进入设置一个或多个属性的状态时生效。如果还原策略设置为 RestoreProperties，状态机将在设置新值前保存属性的原始值。
之后，当状态机进入不设置给定属性值的状态时，该属性将自动恢复为初始值。
任何给定属性都只能保存一个初始值。如果状态机已经保存了某个属性的值，那么在成功恢复该属性之前，该值不会被覆盖。
| 常量 | 值 | 说明 |
|---|---|---|
QState::DontRestoreProperties | 0 | 状态机不应保存属性的初始值并在以后恢复。 |
QState::RestoreProperties | 1 | 状态机应保存属性的初始值并稍后恢复。 |
另请参阅 QStateMachine::globalRestorePolicy 和QState::assignProperty()。
属性文档
[bindable] childMode : ChildMode
注意： 该属性支持QProperty 绑定。
此属性保存此状态的子模式
该属性的默认值为QState::ExclusiveStates 。
[bindable] errorState : QAbstractState*
注意： 该属性支持QProperty 绑定。
此属性保存此状态的错误状态
[bindable] initialState : QAbstractState*
注意： 该属性支持QProperty 绑定。
此属性保存此状态（其子状态之一）的初始状态
成员函数文档
QState::QState(QState *parent = nullptr)
用给定的parent 状态构建一个新状态。
QState::QState(QState::ChildMode childMode, QState *parent = nullptr)
用给定的childMode 和给定的parent 状态构建一个新状态。
[virtual noexcept] QState::~QState()
摧毁这个国家。
QAbstractTransition *QState::addTransition(QAbstractState *target)
添加从本状态到给定target 状态的无条件转换，并返回新的转换对象。
void QState::addTransition(QAbstractTransition *transition)
添加给定的transition 。该状态是过渡的源。该状态拥有过渡的所有权。
QSignalTransition *QState::addTransition(const QObject *sender, const char *signal, QAbstractState *target)
添加与给定sender 对象的给定signal 相关联的过渡，并返回新的QSignalTransition 对象。该过渡将此状态作为源状态，将给定的target 作为目标状态。
template <typename PointerToMemberFunction> QSignalTransition *QState::addTransition(const QObject *sender, PointerToMemberFunction signal, QAbstractState *target)
这是一个重载函数。
添加与给定sender 对象的给定signal 相关联的过渡，并返回新的QSignalTransition 对象。该过渡将此状态作为源状态，将给定的target 作为目标状态。
void QState::assignProperty(QObject *object, const char *name, const QVariant &value)
当进入状态时，指示该状态将给定object 的给定name 的属性设置为给定的value 。
另请参阅 propertiesAssigned().
QState::ChildMode QState::childMode() const
返回此状态的子模式。
注： 属性 childMode 的获取函数。
另请参阅 setChildMode().
[private signal] void QState::childModeChanged()
childMode 属性发生变化时会发出该信号。
注意： 这是一个私有信号。可在信号连接中使用，但用户不能发出。
注： 属性childMode 的通知信号。
另请参阅 QState::childMode 。
QAbstractState *QState::errorState() const
返回此状态的错误状态。
注： 属性 errorState 的获取函数。
另请参阅 setErrorState() 和QStateMachine::error()。
[private signal] void QState::errorStateChanged()
errorState 属性发生变化时会发出该信号。
注意： 这是一个私有信号。可在信号连接中使用，但用户不能发出。
注： 属性errorState 的通知信号。
另请参阅 QState::errorState 。
[override virtual protected] bool QState::event(QEvent *e)
重实现：QAbstractState::event(QEvent *e)。
[private signal] void QState::finished()
当进入该状态的最终子状态时，会发出该信号。
注意： 这是一个私有信号。它可以在信号连接中使用，但不能由用户发出。
另请参见 QFinalState 。
QAbstractState *QState::initialState() const
返回该状态的初始状态，如果该状态没有初始状态，则返回nullptr 。
注： 属性 initialState 的获取函数。
另请参阅 setInitialState().
[private signal] void QState::initialStateChanged()
initialState 属性发生变化时会发出该信号。
注意： 这是一个私有信号。可在信号连接中使用，但用户不能发出。
注： 属性initialState 的通知信号。
另请参阅 QState::initialState 。
[override virtual protected] void QState::onEntry(QEvent *event)
重实现：QAbstractState::onEntry(QEvent *event).
[override virtual protected] void QState::onExit(QEvent *event)
重实现：QAbstractState::onExit(QEvent *event).
[private signal] void QState::propertiesAssigned()
当所有属性的最终值都已分配完毕时，就会发出该信号。如果状态为一个或多个属性赋值，而这些属性又有动画存在（可以在转换时设置，也可以作为状态机的默认动画），那么该信号将在所有这些动画播放完毕后才发出。
如果没有相关动画，或没有为状态定义属性赋值，那么信号将在进入状态前立即发出。
另请参阅 QState::assignProperty() 和QAbstractTransition::addAnimation()
注意： 这是一个私有信号。它可以在信号连接中使用，但不能由用户发出。
void QState::removeTransition(QAbstractTransition *transition)
从该状态移除给定的transition 。该状态会释放过渡的所有权。
另请参阅 addTransition().
void QState::setChildMode(QState::ChildMode mode)
设置此状态的子mode 。
注： 属性childMode 的设置函数。
另请参阅 childMode().
void QState::setErrorState(QAbstractState *state)
将此状态的错误状态设置为给定的state 。如果未设置错误状态，或将其设置为nullptr ，则该状态将递归继承其父级错误状态。如果没有为状态本身或其任何祖先设置错误状态，错误将导致机器停止执行，并将错误信息打印到控制台。
注： 属性errorState 的设置函数。
另请参见 errorState().
void QState::setInitialState(QAbstractState *state)
将此状态的初始状态设置为给定的state 。state 必须是此状态的子状态。
注： 属性initialState 的设置函数。
另请参阅 initialState().
QList<QAbstractTransition *> QState::transitions() const
Returns this state's outgoing transitions (i.e. transitions where this state is thesource state), 或者 Returns an empty list if this state has no outgoing transitions.
另请参见 addTransition().
© 2025 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.
