QScxmlStateMachine Class
QScxmlStateMachine 类为从 SCXML 文件创建的状态机提供了一个接口。更多
| Header： | #include <QScxmlStateMachine> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Scxml)target_link_libraries(mytarget PRIVATE Qt6::Scxml) |
| qmake： | QT += scxml |
| 在 QML 中： | ScxmlStateMachine |
| 继承： | QObject |
属性
|
|
公共功能
| QStringList | activeStateNames(bool compress = true) const |
| QBindable<QScxmlDataModel *> | bindableDataModel() |
| QBindable<QVariantMap> | bindableInitialValues() |
| QBindable<bool> | bindableInitialized() const |
| QBindable<QList<QScxmlInvokableService *>> | bindableInvokedServices() |
| QBindable<QScxmlCompiler::Loader *> | bindableLoader() |
| QBindable<QScxmlTableData *> | bindableTableData() |
| void | cancelDelayedEvent(const QString &sendId) |
| QMetaObject::Connection | connectToEvent(const QString &scxmlEventSpec, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection) |
| QMetaObject::Connection | connectToEvent(const QString &scxmlEventSpec, const QObject *context, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection) |
| QMetaObject::Connection | connectToEvent(const QString &scxmlEventSpec, const QObject *receiver, const char *method, Qt::ConnectionType type = Qt::AutoConnection) |
| QMetaObject::Connection | connectToState(const QString &scxmlStateName, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection) |
| QMetaObject::Connection | connectToState(const QString &scxmlStateName, const QObject *context, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection) |
| QMetaObject::Connection | connectToState(const QString &scxmlStateName, const QObject *receiver, const char *method, Qt::ConnectionType type = Qt::AutoConnection) |
| QScxmlDataModel * | dataModel() const |
| QVariantMap | initialValues() |
| QList<QScxmlInvokableService *> | invokedServices() const |
| bool | isActive(const QString &scxmlStateName) const |
| bool | isDispatchableTarget(const QString &target) const |
| bool | isInitialized() const |
| bool | isInvoked() const |
| bool | isRunning() const |
| QScxmlCompiler::Loader * | loader() const |
| QString | name() const |
| QList<QScxmlError> | parseErrors() const |
| QString | sessionId() const |
| void | setDataModel(QScxmlDataModel *model) |
| void | setInitialValues(const QVariantMap &initialValues) |
| void | setLoader(QScxmlCompiler::Loader *loader) |
| void | setRunning(bool running) |
| void | setTableData(QScxmlTableData *tableData) |
| QStringList | stateNames(bool compress = true) const |
| void | submitEvent(QScxmlEvent *event) |
| void | submitEvent(const QString &eventName) |
| void | submitEvent(const QString &eventName, const QVariant &data) |
| QScxmlTableData * | tableData() const |
公共插槽
信号
| void | dataModelChanged(QScxmlDataModel *model) |
| void | finished() |
| void | initialValuesChanged(const QVariantMap &initialValues) |
| void | initializedChanged(bool initialized) |
| void | invokedServicesChanged(const QList<QScxmlInvokableService *> &invokedServices) |
| void | loaderChanged(QScxmlCompiler::Loader *loader) |
| void | log(const QString &label, const QString &msg) |
| void | reachedStableState() |
| void | runningChanged(bool running) |
| void | tableDataChanged(QScxmlTableData *tableData) |
静态公共成员
| QScxmlStateMachine * | fromData(QIODevice *data, const QString &fileName = QString()) |
| QScxmlStateMachine * | fromFile(const QString &fileName) |
| std::function<void (bool)> | onEntry(Functor functor) |
| std::function<void (bool)> | onEntry(const QObject *receiver, const char *method) |
| std::function<void (bool)> | onEntry(const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver, PointerToMemberFunction method) |
| std::function<void (bool)> | onExit(Functor functor) |
| std::function<void (bool)> | onExit(const QObject *receiver, const char *method) |
| std::function<void (bool)> | onExit(const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver, PointerToMemberFunction method) |
受保护函数
| bool | isActive(int stateIndex) const |
详细说明
QScxmlStateMachine 是状态图 XML（SCXML）的实现。
SCXML 文件中定义的所有状态都可以作为 QScxmlStateMachine 的属性访问。这些属性都是布尔值，表示状态是激活状态还是非激活状态。
注意： QScxmlStateMachine 需要一个QEventLoop 才能正常工作。事件循环用于为事件实现delay 属性，并在收到嵌套（或父节点）状态机的事件时安排状态机的处理。
属性文档
[bindable] dataModel : QScxmlDataModel*
注意： 该属性支持QProperty 绑定。
该属性包含用于此状态机的数据模型。
SCXML 数据模型在《SCXML 规范 - 5 数据模型和数据处理》（SCXML Specification - 5 Data Model and Data Manipulation）中有描述。有关支持的数据模型的更多信息，请参阅SCXML Compliance。
SCXML 标准中没有规定在状态机initialized 时更改数据模型，这将导致未定义的行为。
另请参阅 QScxmlDataModel,QScxmlNullDataModel, 和QScxmlCppDataModel 。
[bindable] initialValues : QVariantMap
注意： 该属性支持QProperty 绑定。
该属性包含用于设置数据模型的初始值。
另请参阅 QScxmlStateMachine::init() 和QScxmlDataModel 。
[bindable read-only] initialized : bool
注意： 该属性支持QProperty 绑定。
该属性表示状态机是否已被初始化。
如果状态机已初始化，则为true ，否则为false 。
另请参阅 QScxmlStateMachine::init() 和QScxmlDataModel 。
[read-only] invoked : const bool
该属性表示状态机是否从外部状态机调用。
true 时，该状态机是作为 元素的服务启动的，否则为 。<invoke> false
访问功能：
| bool | isInvoked() const |
[bindable read-only] invokedServices : QList<QScxmlInvokableService*>
注意： 该属性支持QProperty 绑定。
该属性包含从主状态机（可能是递归的）调用的 SCXML 服务列表。
[bindable] loader : QScxmlCompiler::Loader*
注意： 该属性支持QProperty 绑定。
该属性包含当前用于解析和加载状态机 URI 的加载器。
[read-only] name : const QString
该属性保存由<scxml> 标签name属性设置的状态机名称。
访问功能：
| QString | name() const |
[read-only] parseErrors : const QList<QScxmlError>
该属性保存从 SCXML 文件创建状态机时发生的解析错误列表。
访问功能：
| QList<QScxmlError> | parseErrors() const |
running : bool
此属性保存此状态机的运行状态
访问功能：
| bool | isRunning() const |
| void | setRunning(bool running) |
Notifier 信号：
| void | runningChanged(bool running) |
另请参见 start().
[read-only] sessionId : const QString
该属性保存当前状态机的会话 ID。
会话 ID 用于父状态机和子状态机之间的消息路由。如果状态机是由<invoke> 元素启动的，那么它发送的任何事件的invokeid 字段都将设置为会话 ID。状态机将使用事件的起源（由<send> 元素中的target或targetexpr属性设置）向正确的子状态机发送信息。
访问功能：
| QString | sessionId() const |
另请参见 QScxmlEvent::invokeId().
[bindable] tableData : QScxmlTableData*
注意： 该属性支持QProperty 绑定。
该属性保存从 SCXML 文件生成 C++ 时使用的表格数据。
实现状态机的类将使用该属性分配生成的表数据。状态机不承担表数据的所有权。
成员函数文档
template <typename Functor> QMetaObject::Connection QScxmlStateMachine::connectToEvent(const QString &scxmlEventSpec, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection)
template <typename Functor> QMetaObject::Connection QScxmlStateMachine::connectToEvent(const QString &scxmlEventSpec, const QObject *context, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection)
从scxmlEventSpec 指定的事件到functor ，创建给定type 的连接，它可以是一个函数或可选context 对象的成员函数。
接收者的functor 必须将QScxmlEvent 作为参数。
与 SCXML 文档中的事件规范不同，这里的scxmlEventSpec 不允许使用空格。为了连接到具有不同前缀的多个事件，必须多次调用connectToEvent() 。
返回连接的句柄，以后可以用它来断开连接。
template <typename Functor> QMetaObject::Connection QScxmlStateMachine::connectToState(const QString &scxmlStateName, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection)
template <typename Functor> QMetaObject::Connection QScxmlStateMachine::connectToState(const QString &scxmlStateName, const QObject *context, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection)
从scxmlStateName 指定的状态创建给定type 的连接到functor ，它可以是一个函数或可选context 对象的成员函数。
接收器的functor 必须包含一个布尔参数，用于指示连接的状态是活动还是非活动。
返回连接的句柄，稍后可使用该句柄断开连接。
[invokable] QStringList QScxmlStateMachine::activeStateNames(bool compress = true) const
读取所有激活状态的状态名称列表。
根据定义，当一个状态处于活动状态时，它的所有父状态都处于活动状态。compress 为true （默认值）时，将过滤掉父级状态，只返回叶级状态。当false 时，将返回活动状态的完整列表。
注： 可通过元对象系统和 QML 调用该函数。请参见Q_INVOKABLE 。
[invokable] void QScxmlStateMachine::cancelDelayedEvent(const QString &sendId)
使用指定的sendId 取消延迟事件。
注： 可通过元对象系统和 QML 调用该函数。请参阅Q_INVOKABLE 。
QMetaObject::Connection QScxmlStateMachine::connectToEvent(const QString &scxmlEventSpec, const QObject *receiver, const char *method, Qt::ConnectionType type = Qt::AutoConnection)
从scxmlEventSpec 指定的事件到receiver 对象中的method ，创建指定type 的连接。接收方的method 可以使用QScxmlEvent 作为参数。例如
void mySlot(const QScxmlEvent &event);
与 SCXML 文档中的事件规范不同，这里的scxmlEventSpec 不允许使用空格。为了连接到多个具有不同前缀的事件，connectToEvent() 必须被多次调用。
connectToEvent() 返回一个连接句柄，以后可以用它来断开连接。
QMetaObject::Connection QScxmlStateMachine::connectToState(const QString &scxmlStateName, const QObject *receiver, const char *method, Qt::ConnectionType type = Qt::AutoConnection)
创建给定type 的连接，从scxmlStateName 标识的状态到receiver 对象中的method 。接收方的method 可以接受一个布尔参数，该参数表示连接的状态是激活状态还是非激活状态。例如
void mySlot(bool active);
返回连接句柄，稍后可使用该句柄断开连接。
QScxmlDataModel *QScxmlStateMachine::dataModel() const
返回状态机使用的数据模型。
注： 属性 dataModel 的获取函数。
另请参阅 setDataModel().
[signal] void QScxmlStateMachine::finished()
当状态机达到顶层最终状态时，会发出该信号。
另请参见 running 。
[static] QScxmlStateMachine *QScxmlStateMachine::fromData(QIODevice *data, const QString &fileName = QString())
通过读取data 指定的QIODevice ，创建状态机。
该方法将始终返回一个状态机。如果在读取 SCXML 文件fileName 时发生错误，则无法启动状态机。可通过调用parseErrors() 方法获取错误信息。
另请参阅 parseErrors() 。
[static] QScxmlStateMachine *QScxmlStateMachine::fromFile(const QString &fileName)
从fileName 指定的 SCXML 文件创建状态机。
该方法将始终返回一个状态机。如果在读取 SCXML 文件时发生错误，则无法启动状态机。可通过调用parseErrors() 方法获取错误信息。
另请参阅 parseErrors() 方法。
[slot] bool QScxmlStateMachine::init()
初始化状态机。
状态机初始化包括调用QScxmlDataModel::setup() 、设置<data> 元素的初始值，以及执行<scxml> 标记的任何<script> 标记。初始数据值取自initialValues 属性。
如果出现解析错误或任何初始化步骤失败，则返回false 。否则返回true 。
[invokable] bool QScxmlStateMachine::isActive(const QString &scxmlStateName) const
如果scxmlStateName 指定的状态处于活动状态，则返回true ，否则返回false 。
注： 可通过元对象系统和 QML 调用此函数。请参见Q_INVOKABLE 。
[protected] bool QScxmlStateMachine::isActive(int stateIndex) const
如果 ID 为stateIndex 的状态处于活动状态，则返回true 。
该方法是 SCXML 状态机编译表示界面的一部分。它只能在内部和由 SCXML 文档编译的状态机中使用。
[invokable] bool QScxmlStateMachine::isDispatchableTarget(const QString &target) const
如果该状态机可以向target 发送信息，则返回true 。
有效目标是
#_parent父状态机，如果当前状态机是由父状态机启动的<invoke>#_internal当前状态机#_scxml_sessionid其中sessionid是当前状态机的会话 ID。#_servicename，其中servicename是该状态机通过<invoke>启动的服务的 ID 或名称。
注： 可通过元对象系统和 QML 调用该函数。请参见Q_INVOKABLE 。
bool QScxmlStateMachine::isRunning() const
如果状态机正在运行，则返回true ，否则返回false 。
注： 属性running 的获取函数。
另请参阅 setRunning() 和runningChanged()。
[signal] void QScxmlStateMachine::log(const QString &label, const QString &msg)
如果 SCXML 中使用了<log> 标签，就会发出该信号。label 是<log> 标签的label属性的值。msg 是<log> 标签的已评估expr属性的值。如果没有expr属性，将返回一个空字符串。
[static] template <typename Functor> std::function<void (bool)> QScxmlStateMachine::onEntry(Functor functor)
返回一个函数，该函数接受一个布尔参数，如果该参数为true ，则调用给定的functor 。给定的functor 必须不接受任何参数。
这对于封装connectToState() 的处理程序非常有用，这些处理程序只应在进入状态时执行。
[static] std::function<void (bool)> QScxmlStateMachine::onEntry(const QObject *receiver, const char *method)
返回一个函数，该函数接受一个布尔参数，如果该参数是true 且receiver 尚未被删除，则使用QMetaObject::invokeMethod() 在receiver 上调用给定的method 。
给定的method 必须不接受任何参数。method 是纯方法名称，不包含在SIGNAL() 或SLOT() 中。
这对于封装connectToState() 的处理程序非常有用，这些处理程序只应在进入状态时执行。
[static] template <typename PointerToMemberFunction> std::function<void (bool)> QScxmlStateMachine::onEntry(const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver, PointerToMemberFunction method)
返回一个函数，该函数接受一个布尔参数，如果该参数是true 且receiver 尚未被删除，则在receiver 上调用给定的method 。给定的method 必须不接受任何参数。
这对于封装connectToState() 的处理程序非常有用，这些处理程序只应在进入状态时执行。
[static] template <typename Functor> std::function<void (bool)> QScxmlStateMachine::onExit(Functor functor)
返回一个函数，该函数接受一个布尔参数，如果该参数为false ，则调用给定的functor 。给定的functor 必须不接受任何参数。
这对于封装connectToState() 的处理程序非常有用，这些处理程序只应在状态离开时执行。
[static] std::function<void (bool)> QScxmlStateMachine::onExit(const QObject *receiver, const char *method)
返回一个函数，该函数接受一个布尔参数，如果该参数是false 且receiver 尚未删除，则使用QMetaObject::invokeMethod() 在receiver 上调用给定的method 。
给定的method 必须不接受任何参数。method 是普通方法名称，不包含在 SIGNAL(...) 或 SLOT(...) 中。
这对于封装connectToState() 的处理程序非常有用，这些处理程序只应在状态离开时执行。
[static] template <typename PointerToMemberFunction> std::function<void (bool)> QScxmlStateMachine::onExit(const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver, PointerToMemberFunction method)
返回一个函数，该函数接受一个布尔参数，如果该参数是false 且receiver 尚未被删除，则在receiver 上调用给定的method 。给定的method 必须不接受任何参数。
这对于封装connectToState() 的处理程序非常有用，这些处理程序只应在状态离开时执行。
[signal] void QScxmlStateMachine::reachedStableState()
当宏步骤结束或达到最终状态时，事件队列为空时，会发出该信号。
[signal] void QScxmlStateMachine::runningChanged(bool running)
当以running 为参数的running 属性发生变化时，将发出该信号。
注： 属性running 的通知信号。
void QScxmlStateMachine::setDataModel(QScxmlDataModel *model)
将此状态机的数据模型设置为model 。状态机和模型之间的关系是 1:1。设置一次模型后，就不能再更改了。任何使用此方法设置模型的尝试都将被忽略。
注： dataModel 属性的设置函数。
另请参阅 dataModel() 。
void QScxmlStateMachine::setRunning(bool running)
如果running 是true ，则启动状态机，否则停止状态机。
注： 属性running 的设置函数。
另请参阅 start(),stop(),isRunning() 和runningChanged().
[slot] void QScxmlStateMachine::start()
启动该状态机。当进入最终顶层状态时，机器将发出finished() 信号。
注意： 如果没有正在运行的事件循环，如使用QCoreApplication::exec() 或QApplication::exec() 启动的主应用程序事件循环，状态机将无法运行。
注意： 在stop() 之后调用 start() 并不会完全重置状态机的配置，因此强烈建议不要这样做。
注意： 启动已完成的机器会产生警告。
另请参阅 runningChanged()、setRunning()、stop() 和finished()。
[invokable] QStringList QScxmlStateMachine::stateNames(bool compress = true) const
检索所有状态的状态名称列表。
compress 为true （默认值）时，将过滤掉包含子状态的状态，只返回叶状态。当false 时，将返回所有状态的完整列表。
返回的列表不包含可能嵌套的状态机的状态。
注： 列表中状态名称的顺序是状态在 SCXML 文档中出现的顺序。
注： 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE 。
[slot] void QScxmlStateMachine::stop()
停止该状态机。机器将不再执行任何状态转换。其running 属性被设置为false 。
另请参阅 runningChanged()、start() 和setRunning()。
[invokable] void QScxmlStateMachine::submitEvent(QScxmlEvent *event)
根据事件的优先级，将 SCXML 事件event 提交到内部或外部事件队列。
如果设置了延时，事件将在超时后排队交付。状态机拥有event 的所有权，并在处理后将其删除。
注： 可通过元对象系统和 QML 调用该函数。请参见Q_INVOKABLE 。
[invokable] void QScxmlStateMachine::submitEvent(const QString &eventName)
用于创建和提交外部事件的实用方法，其名称为指定的eventName 。
注： 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE 。
[invokable] void QScxmlStateMachine::submitEvent(const QString &eventName, const QVariant &data)
一种实用方法，用于创建和提交外部事件，其名称为指定的eventName ，有效载荷数据为data 。
注： 可通过元对象系统和 QML 调用该函数。请参阅Q_INVOKABLE 。
© 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.
