QScxmlStateMachine Class | Qt SCXML 5.9

Qt 5.9 | Qt SCXML | C++ Classes | QScxmlStateMachine

Qt 5.9.4 Reference Documentation

# QScxmlStateMachine Class

The QScxmlStateMachine class provides an interface to the state machines created from SCXML files. More...

Header: | #include <QScxmlStateMachine>
qmake: | QT += scxml
Since: | Qt 5.7
Instantiated By: | ScxmlStateMachine
Inherits: | QObject

- List of all members, including inherited members

## Properties

dataModel : QScxmlDataModel * initialValues : QVariantMap initialized : const bool invoked : const bool invokedServices : QVector<QScxmlInvokableService *> const loader : QScxmlCompiler::Loader * | name : const QString parseErrors : const QVector<QScxmlError> running : bool sessionId : const QString tableData : QScxmlTableData *

- 1 property inherited from QObject

## Public Functions

QStringList | activeStateNames(bool compress = true) const
void | cancelDelayedEvent(const QString &sendId)
QMetaObject::Connection | connectToEvent(const QString &scxmlEventSpec, const QObject *receiver, const char *method, Qt::ConnectionType type = Qt::AutoConnection)
QMetaObject::Connection | connectToEvent(const QString &scxmlEventSpec, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type = Qt::AutoConnection)
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 | connectToState(const QString &scxmlStateName, const QObject *receiver, const char *method, Qt::ConnectionType type = Qt::AutoConnection)
QMetaObject::Connection | connectToState(const QString &scxmlStateName, const QObject *receiver, PointerToMemberFunction 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)
QScxmlDataModel * | dataModel() const
QVariantMap | initialValues()
QVector<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
QVector<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

- 32 public functions inherited from QObject

## Public Slots

bool | init()
void | start()
void | stop()

- 1 public slot inherited from QObject

## Signals

void | dataModelChanged(QScxmlDataModel *model)
void | finished()
void | initialValuesChanged(const QVariantMap &initialValues)
void | initializedChanged(bool initialized)
void | invokedServicesChanged(const QVector<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)

- 2 signals inherited from QObject

## Static Public Members

QScxmlStateMachine * | fromData(QIODevice *data, const QString &fileName = QString())
QScxmlStateMachine * | fromFile(const QString &fileName)
std::function<void( bool ) > | onEntry(const QObject *receiver, const char *method)
std::function<void( bool ) > | onEntry(Functor functor)
std::function<void( bool ) > | onEntry(const QObject *receiver, PointerToMemberFunction method)
std::function<void( bool ) > | onExit(const QObject *receiver, const char *method)
std::function<void( bool ) > | onExit(Functor functor)
std::function<void( bool ) > | onExit(const QObject *receiver, PointerToMemberFunction method)

- 10 static public members inherited from QObject

## Protected Functions

| QScxmlStateMachine(const QMetaObject *metaObject, QObject *parent = nullptr)
| QScxmlStateMachine(QScxmlStateMachinePrivate &dd, QObject *parent = nullptr)
bool | isActive(int stateIndex) const

- 9 protected functions inherited from QObject

### Additional Inherited Members

- 1 public variable inherited from QObject
- 2 protected variables inherited from QObject

## Detailed Description

The QScxmlStateMachine class provides an interface to the state machines created from SCXML files.

QScxmlStateMachine is an implementation of the State Chart XML (SCXML).

All states that are defined in the SCXML file are accessible as properties of QScxmlStateMachine. These properties are boolean values and indicate whether the state is active or inactive.

Note: The QScxmlStateMachine needs a QEventLoop to work correctly. The event loop is used to implement the `delay` attribute for events and to schedule the processing of a state machine when events are received from nested (or parent) state machines.

## Property Documentation

### dataModel : QScxmlDataModel *

This property holds the data model to be used for this state machine.

SCXML data models are described in SCXML Specification - 5 Data Model and Data Manipulation. For more information about supported data models, see SCXML Compliance.

Changing the data model when the state machine has been `initialized` is not specified in the SCXML standard and leads to undefined behavior.

Access functions:

QScxmlDataModel * | dataModel() const
void | setDataModel(QScxmlDataModel *model)

Notifier signal:

void | dataModelChanged(QScxmlDataModel *model)

See also QScxmlDataModel, QScxmlNullDataModel, QScxmlEcmaScriptDataModel, and QScxmlCppDataModel.

### initialValues : QVariantMap

This property holds the initial values to be used for setting up the data model.

Access functions:

QVariantMap | initialValues()
void | setInitialValues(const QVariantMap &initialValues)

Notifier signal:

void | initialValuesChanged(const QVariantMap &initialValues)

See also QScxmlStateMachine::init() and QScxmlDataModel.

### initialized : const bool

This property holds whether the state machine has been initialized.

It is `true` if the state machine has been initialized, `false` otherwise.

Access functions:

bool | isInitialized() const

Notifier signal:

void | initializedChanged(bool initialized)

See also QScxmlStateMachine::init() and QScxmlDataModel.

### invoked : const bool

This property holds whether the state machine was invoked from an outer state machine.

`true` when the state machine was started as a service with the `<invoke>` element, `false` otherwise.

Access functions:

bool | isInvoked() const

### invokedServices : QVector<QScxmlInvokableService *> const

This property holds a list of SCXML services that were invoked from the main state machine (possibly recursively).

Access functions:

QVector<QScxmlInvokableService *> | invokedServices() const

Notifier signal:

void | invokedServicesChanged(const QVector<QScxmlInvokableService *> &invokedServices)

### loader : QScxmlCompiler::Loader *

This property holds the loader that is currently used to resolve and load URIs for the state machine.

Access functions:

QScxmlCompiler::Loader * | loader() const
void | setLoader(QScxmlCompiler::Loader *loader)

Notifier signal:

void | loaderChanged(QScxmlCompiler::Loader *loader)

### name : const QString

This property holds the name of the state machine as set by the name attribute of the `<scxml>` tag.

Access functions:

QString | name() const

### parseErrors : const QVector<QScxmlError>

This property holds the list of parse errors that occurred while creating a state machine from an SCXML file.

Access functions:

QVector<QScxmlError> | parseErrors() const

### running : bool

This property holds the running state of this state machine

Access functions:

bool | isRunning() const
void | setRunning(bool running)

Notifier signal:

void | runningChanged(bool running)

See also start().

### sessionId : const QString

This property holds the session ID of the current state machine.

The session ID is used for message routing between parent and child state machines. If a state machine is started by an `<invoke>` element, any event it sends will have the `invokeid` field set to the session ID. The state machine will use the origin of an event (which is set by the target or targetexpr attribute in a `<send>` element) to dispatch messages to the correct child state machine.

Access functions:

QString | sessionId() const

See also QScxmlEvent::invokeId().

### tableData : QScxmlTableData *

This property holds the table data that is used when generating C++ from an SCXML file.

The class implementing the state machine will use this property to assign the generated table data. The state machine does not assume ownership of the table data.

Access functions:

QScxmlTableData * | tableData() const
void | setTableData(QScxmlTableData *tableData)

Notifier signal:

void | tableDataChanged(QScxmlTableData *tableData)

## Member Function Documentation

### `[protected]` QScxmlStateMachine::QScxmlStateMachine(const QMetaObject *metaObject, QObject *parent = nullptr)

Default constructs an instance of QScxmlStateMachine.

### `[protected]` QScxmlStateMachine::QScxmlStateMachine(QScxmlStateMachinePrivate &dd, QObject *parent = nullptr)

Copy constructor.

### QStringList QScxmlStateMachine::activeStateNames(bool compress = true) const

Retrieves a list of state names of all active states.

When a state is active, all its parent states are active by definition. When compress is `true` (the default), the parent states will be filtered out and only the leaf states will be returned. When it is `false`, the full list of active states will be returned.

### void QScxmlStateMachine::cancelDelayedEvent(const QString &sendId)

Cancels a delayed event with the specified sendId.

### QMetaObject::Connection QScxmlStateMachine::connectToEvent(const QString &scxmlEventSpec, const QObject *receiver, const char *method, Qt::ConnectionType type = Qt::AutoConnection)

Creates a connection of the specified type from the event specified by scxmlEventSpec to the method in the receiver object. The receiver's method may take a QScxmlEvent as a parameter. For example:

      void mySlot(const QScxmlEvent &event);

In contrast to event specifications in SCXML documents, spaces are not allowed in the scxmlEventSpec here. In order to connect to multiple events with different prefixes, connectToEvent() has to be called multiple times.

Returns a handle to the connection, which can be used later to disconnect.

### QMetaObject::Connection QScxmlStateMachine::connectToEvent(const QString &scxmlEventSpec, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type = Qt::AutoConnection)

Creates a connection of the given type from the event specified by scxmlEventSpec to method in the receiver object.

The receiver's method must take a QScxmlEvent as a parameter.

In contrast to event specifications in SCXML documents, spaces are not allowed in the scxmlEventSpec here. In order to connect to multiple events with different prefixes, connectToEvent() has to be called multiple times.

Returns a handle to the connection, which can be used later to disconnect.

### QMetaObject::Connection QScxmlStateMachine::connectToEvent(const QString &scxmlEventSpec, Functor functor, Qt::ConnectionType type = Qt::AutoConnection)

Creates a connection of the given type from the event specified by scxmlEventSpec to functor.

The functor must take a QScxmlEvent as a parameter.

In contrast to event specifications in SCXML documents, spaces are not allowed in the scxmlEventSpec here. In order to connect to multiple events with different prefixes, connectToEvent() has to be called multiple times.

Returns a handle to the connection, which can be used later to disconnect.

### QMetaObject::Connection QScxmlStateMachine::connectToEvent(const QString &scxmlEventSpec, const QObject *context, Functor functor, Qt::ConnectionType type = Qt::AutoConnection)

Creates a connection of the given type from the event specified by scxmlEventSpec to functor using context as context.

The functor must take a QScxmlEvent as a parameter.

In contrast to event specifications in SCXML documents, spaces are not allowed in the scxmlEventSpec here. In order to connect to multiple events with different prefixes, connectToEvent() has to be called multiple times.

Returns a handle to the connection, which can be used later to disconnect.

### QMetaObject::Connection QScxmlStateMachine::connectToState(const QString &scxmlStateName, const QObject *receiver, const char *method, Qt::ConnectionType type = Qt::AutoConnection)

Creates a connection of the given type from the state identified by scxmlStateName to the method in the receiver object. The receiver's method may take a boolean argument that indicates whether the state connected became active or inactive. For example:

      void mySlot(bool active);

Returns a handle to the connection, which can be used later to disconnect.

### QMetaObject::Connection QScxmlStateMachine::connectToState(const QString &scxmlStateName, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type = Qt::AutoConnection)

Creates a connection of the given type from the state specified by scxmlStateName to method in the receiver object.

The receiver's method must take a boolean argument that indicates whether the state connected became active or inactive.

Returns a handle to the connection, which can be used later to disconnect.

### QMetaObject::Connection QScxmlStateMachine::connectToState(const QString &scxmlStateName, Functor functor, Qt::ConnectionType type = Qt::AutoConnection)

Creates a connection of the given type from the state specified by scxmlStateName to functor.

The functor must take a boolean argument that indicates whether the state connected became active or inactive.

Returns a handle to the connection, which can be used later to disconnect.

### QMetaObject::Connection QScxmlStateMachine::connectToState(const QString &scxmlStateName, const QObject *context, Functor functor, Qt::ConnectionType type = Qt::AutoConnection)

Creates a connection of the given type from the state specified by scxmlStateName to functor using context as context.

The functor must take a boolean argument that indicates whether the state connected became active or inactive.

Returns a handle to the connection, which can be used later to disconnect.

### QScxmlDataModel *QScxmlStateMachine::dataModel() const

Returns the data model used by the state machine.

Note: Getter function for property dataModel.

See also setDataModel().

### `[signal]` void QScxmlStateMachine::finished()

This signal is emitted when the state machine reaches a top-level final state.

See also running.

### `[static]` QScxmlStateMachine *QScxmlStateMachine::fromData(QIODevice *data, const QString &fileName = QString())

Creates a state machine by reading from the QIODevice specified by data.

This method will always return a state machine. If errors occur while reading the SCXML file, fileName, the state machine cannot be started. The errors can be retrieved by calling the parseErrors() method.

See also parseErrors().

### `[static]` QScxmlStateMachine *QScxmlStateMachine::fromFile(const QString &fileName)

Creates a state machine from the SCXML file specified by fileName.

This method will always return a state machine. If errors occur while reading the SCXML file, the state machine cannot be started. The errors can be retrieved by calling the parseErrors() method.

See also parseErrors().

### `[slot]` bool QScxmlStateMachine::init()

Initializes the state machine.

State machine initialization consists of calling QScxmlDataModel::setup(), setting the initial values for `<data>` elements, and executing any `<script>` tags of the `<scxml>` tag. The initial data values are taken from the `initialValues` property.

Returns `false` if parse errors occur or if any of the initialization steps fail. Returns `true` otherwise.

### bool QScxmlStateMachine::isActive(const QString &scxmlStateName) const

Returns `true` if the state specified by scxmlStateName is active, `false` otherwise.

### `[protected]` bool QScxmlStateMachine::isActive(int stateIndex) const

Returns `true` if the state with the ID stateIndex is active.

This method is part of the interface to the compiled representation of SCXML state machines. It should only be used internally and by state machines compiled from SCXML documents.

### bool QScxmlStateMachine::isDispatchableTarget(const QString &target) const

Returns `true` if a message to target can be dispatched by this state machine.

Valid targets are:

- `#_parent` for the parent state machine if the current state machine is started by `<invoke>`
- `#_internal` for the current state machine
- `#_scxml_sessionid`, where `sessionid` is the session ID of the current state machine
- `#_servicename`, where `servicename` is the ID or name of a service started with `<invoke>` by this state machine

### bool QScxmlStateMachine::isRunning() const

Returns `true` if the state machine is running, `false` otherwise.

Note: Getter function for property running.

See also setRunning() and runningChanged().

### `[signal]` void QScxmlStateMachine::log(const QString &label, const QString &msg)

This signal is emitted if a `<log>` tag is used in the SCXML. label is the value of the label attribute of the `<log>` tag. msg is the value of the evaluated expr attribute of the `<log>` tag. If there is no expr attribute, a null string will be returned.

### `[static]` std::function<void( bool ) > QScxmlStateMachine::onEntry(const QObject *receiver, const char *method)

Returns a functor that accepts a boolean argument and calls the given method on receiver using QMetaObject::invokeMethod() if that argument is `true` and receiver has not been deleted, yet.

The given method must not accept any arguments. method is the plain method name, not enclosed in `SIGNAL()` or `SLOT()`.

This is useful to wrap handlers for connectToState() that should only be executed when the state is entered.

### `[static]` std::function<void( bool ) > QScxmlStateMachine::onEntry(Functor functor)

Returns a functor that accepts a boolean argument and calls the given functor if that argument is `true`. The given functor must not accept any arguments.

This is useful to wrap handlers for connectToState() that should only be executed when the state is entered.

### `[static]` std::function<void( bool ) > QScxmlStateMachine::onEntry(const QObject *receiver, PointerToMemberFunction method)

Returns a functor that accepts a boolean argument and calls the given method on receiver if that argument is `true` and the receiver has not been deleted, yet. The given method must not accept any arguments.

This is useful to wrap handlers for connectToState() that should only be executed when the state is entered.

### `[static]` std::function<void( bool ) > QScxmlStateMachine::onExit(const QObject *receiver, const char *method)

Returns a functor that accepts a boolean argument and calls the given method on receiver using QMetaObject::invokeMethod() if that argument is `false` and receiver has not been deleted, yet.

The given method must not accept any arguments. method is the plain method name, not enclosed in SIGNAL(...) or SLOT(...).

This is useful to wrap handlers for connectToState() that should only be executed when the state is left.

### `[static]` std::function<void( bool ) > QScxmlStateMachine::onExit(Functor functor)

Returns a functor that accepts a boolean argument and calls the given functor if that argument is `false`. The given functor must not accept any arguments.

This is useful to wrap handlers for connectToState() that should only be executed when the state is left.

### `[static]` std::function<void( bool ) > QScxmlStateMachine::onExit(const QObject *receiver, PointerToMemberFunction method)

Returns a functor that accepts a boolean argument and calls the given method on receiver if that argument is `false` and the receiver has not been deleted, yet. The given method must not accept any arguments.

This is useful to wrap handlers for connectToState() that should only be executed when the state is left.

### `[signal]` void QScxmlStateMachine::reachedStableState()

This signal is emitted when the event queue is empty at the end of a macro step or when a final state is reached.

### `[signal]` void QScxmlStateMachine::runningChanged(bool running)

This signal is emitted when the `running` property is changed with running as argument.

Note: Notifier signal for property running.

### void QScxmlStateMachine::setDataModel(QScxmlDataModel *model)

Sets the data model for this state machine to model. There is a 1:1 relation between state machines and models. After setting the model once you cannot change it anymore. Any further attempts to set the model using this method will be ignored.

Note: Setter function for property dataModel.

See also dataModel().

### void QScxmlStateMachine::setRunning(bool running)

Starts the state machine if running is `true`, or stops it otherwise.

Note: Setter function for property running.

See also start(), stop(), isRunning(), and runningChanged().

### `[slot]` void QScxmlStateMachine::start()

Starts this state machine. The machine will reset its configuration and transition to the initial state. When a final top-level state is entered, the machine will emit the finished() signal.

Note: A state machine will not run without a running event loop, such as the main application event loop started with QCoreApplication::exec() or QApplication::exec().

See also runningChanged(), setRunning(), stop(), and finished().

### QStringList QScxmlStateMachine::stateNames(bool compress = true) const

Retrieves a list of state names of all states.

When compress is `true` (the default), the states that contain child states will be filtered out and only the leaf states will be returned. When it is `false`, the full list of all states will be returned.

The returned list does not contain the states of possible nested state machines.

Note: The order of the state names in the list is the order in which the states occurred in the SCXML document.

### `[slot]` void QScxmlStateMachine::stop()

Stops this state machine. The machine will not execute any further state transitions. Its `running` property is set to `false`.

See also runningChanged(), start(), and setRunning().

### void QScxmlStateMachine::submitEvent(QScxmlEvent *event)

Submits the SCXML event event to the internal or external event queue depending on the priority of the event.

When a delay is set, the event will be queued for delivery after the timeout has passed. The state machine takes ownership of event and deletes it after processing.

### void QScxmlStateMachine::submitEvent(const QString &eventName)

A utility method to create and submit an external event with the specified eventName as the name.

### void QScxmlStateMachine::submitEvent(const QString &eventName, const QVariant &data)

A utility method to create and submit an external event with the specified eventName as the name and data as the payload data.