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 框架的一部分。
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 。
访问函数：
| QState::ChildMode | childMode() const |
| void | setChildMode(QState::ChildMode mode) |
通知信号：
| void | childModeChanged() | [see note below] |
注意：这是一个 私有信号。它可以在信号连接中使用，但用户无法发出该信号。
[bindable] errorState : QAbstractState*
注意：此 属性支持QProperty 绑定。
该属性保存此状态的错误状态
访问函数：
| QAbstractState * | errorState() const |
| void | setErrorState(QAbstractState *state) |
通知信号：
| void | errorStateChanged() | [see note below] |
注意：这是一个 私有信号。它可在信号连接中使用，但用户无法触发该信号。
[bindable] initialState : QAbstractState*
注意：此 属性支持QProperty 绑定。
该属性保存此状态（及其子状态之一）的初始状态
访问函数：
| QAbstractState * | initialState() const |
| void | setInitialState(QAbstractState *state) |
通知信号：
| void | initialStateChanged() | [see note below] |
注意：这是一个 私有信号。它可在信号连接中使用，但用户无法触发该信号。
成员函数文档
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
返回该状态的出向转换（即该状态作为source state 的转换），如果该状态没有出向转换，则返回一个空列表。
另请参阅 addTransition()。
© 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.
