diff options
Diffstat (limited to 'src/scxml/qscxmlstatemachine.cpp')
| -rw-r--r-- | src/scxml/qscxmlstatemachine.cpp | 242 |
1 files changed, 241 insertions, 1 deletions
diff --git a/src/scxml/qscxmlstatemachine.cpp b/src/scxml/qscxmlstatemachine.cpp index 54bdb9b..e57630f 100644 --- a/src/scxml/qscxmlstatemachine.cpp +++ b/src/scxml/qscxmlstatemachine.cpp @@ -79,6 +79,22 @@ Q_LOGGING_CATEGORY(scxmlLog, "scxml.statemachine") */ /*! + \qmltype ScxmlStateMachine + \instantiates QScxmlStateMachine + \inqmlmodule QtScxml + \since 5.7 + + \brief Provides an interface to the state machines created from SCXML files. + + The ScxmlStateMachine type is an implementation of the + \l{SCXML Specification}{State Chart XML (SCXML)}. + + All states that are defined in the SCXML file are accessible as properties + of this type. These properties are boolean values and indicate whether the + state is active or inactive. +*/ + +/*! \fn QScxmlStateMachine::connectToEvent(const QString &scxmlEventSpec, const QObject *receiver, PointerToMemberFunction method, @@ -415,7 +431,10 @@ QScxmlStateMachinePrivate::QScxmlStateMachinePrivate(const QMetaObject *metaObje , m_eventLoopHook(this) , m_metaObject(metaObject) , m_infoSignalProxy(nullptr) -{} +{ + static int metaType = qRegisterMetaType<QScxmlStateMachine *>(); + Q_UNUSED(metaType); +} QScxmlStateMachinePrivate::~QScxmlStateMachinePrivate() { @@ -1480,6 +1499,12 @@ QScxmlStateMachine::QScxmlStateMachine(QScxmlStateMachinePrivate &dd, QObject *p */ /*! + \qmlproperty bool ScxmlStateMachine::running + + The running state of this state machine. +*/ + +/*! \property QScxmlStateMachine::dataModel \brief The data model to be used for this state machine. @@ -1496,6 +1521,22 @@ QScxmlStateMachine::QScxmlStateMachine(QScxmlStateMachinePrivate &dd, QObject *p */ /*! + \qmlproperty ScxmlDataModel ScxmlStateMachine::dataModel + + The data model to be used for this state machine. + + SCXML data models are described in + \l {SCXML Specification - 5 Data Model and Data Manipulation}. For more + information about supported data models, see \l {SCXML Compliance}. + + Changing the data model when the state machine has been \l initialized is + not specified in the SCXML standard and leads to undefined behavior. + + \sa QScxmlDataModel, QScxmlNullDataModel, QScxmlEcmaScriptDataModel, + QScxmlCppDataModel +*/ + +/*! \property QScxmlStateMachine::initialized \brief Whether the state machine has been initialized. @@ -1506,6 +1547,13 @@ QScxmlStateMachine::QScxmlStateMachine(QScxmlStateMachinePrivate &dd, QObject *p */ /*! + \qmlproperty bool ScxmlStateMachine::initialized + + This read-only property is set to \c true if the state machine has been + initialized, \c false otherwise. +*/ + +/*! \property QScxmlStateMachine::initialValues \brief The initial values to be used for setting up the data model. @@ -1514,6 +1562,12 @@ QScxmlStateMachine::QScxmlStateMachine(QScxmlStateMachinePrivate &dd, QObject *p */ /*! + \qmlproperty var ScxmlStateMachine::initialValues + + The initial values to be used for setting up the data model. +*/ + +/*! \property QScxmlStateMachine::sessionId \brief The session ID of the current state machine. @@ -1528,12 +1582,32 @@ QScxmlStateMachine::QScxmlStateMachine(QScxmlStateMachinePrivate &dd, QObject *p */ /*! + \qmlproperty string ScxmlStateMachine::sessionId + + 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 \c <invoke> element, any event + it sends will have the \c invokeid field set to the session ID. The state + machine will use the origin of an event (which is set by the \e target or + \e targetexpr attribute in a \c <send> element) to dispatch messages to the + correct child state machine. +*/ + +/*! \property QScxmlStateMachine::name \brief The name of the state machine as set by the \e name attribute of the \c <scxml> tag. */ /*! + \qmlproperty string ScxmlStateMachine::name + + The name of the state machine as set by the \e name attribute of the + \c <scxml> tag. +*/ + +/*! \property QScxmlStateMachine::invoked \brief Whether the state machine was invoked from an outer state machine. @@ -1543,18 +1617,41 @@ QScxmlStateMachine::QScxmlStateMachine(QScxmlStateMachinePrivate &dd, QObject *p */ /*! + \qmlproperty bool ScxmlStateMachine::invoked + + Whether the state machine was invoked from an outer state machine. + + This read-only property is set to \c true when the state machine was started + as a service with the \c <invoke> element, \c false otherwise. + */ + +/*! \property QScxmlStateMachine::parseErrors \brief The list of parse errors that occurred while creating a state machine from an SCXML file. */ /*! + \qmlproperty var ScxmlStateMachine::parseErrors + + The list of parse errors that occurred while creating a state machine from + an SCXML file. + */ + +/*! \property QScxmlStateMachine::loader \brief The loader that is currently used to resolve and load URIs for the state machine. */ /*! + \qmlproperty Loader ScxmlStateMachine::loader + + The loader that is currently used to resolve and load URIs for the state + machine. + */ + +/*! \property QScxmlStateMachine::tableData \brief The table data that is used when generating C++ from an SCXML file. @@ -1674,6 +1771,22 @@ void QScxmlStateMachine::setTableData(QScxmlTableData *tableData) } /*! + \qmlmethod ScxmlStateMachine::stateNames(bool compress) + + Retrieves a list of state names of all states. + + When \a compress is \c true (the default), the states that contain child + states is filtered out and only the \e {leaf states} is returned. When it + is \c false, the full list of all states is 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. +*/ + +/*! * Retrieves a list of state names of all states. * * When \a compress is \c true (the default), the states that contain child states @@ -1699,6 +1812,17 @@ QStringList QScxmlStateMachine::stateNames(bool compress) const } /*! + \qmlmethod ScxmlStateMachine::activeStateNames(bool compress) + + Retrieves a list of state names of all active states. + + When a state is active, all its parent states are active by definition. When + \a compress is \c true (the default), the parent states are filtered out and + only the \e {leaf states} are returned. When it is \c false, the full list + of active states is returned. +*/ + +/*! * Retrieves a list of state names of all active states. * * When a state is active, all its parent states are active by definition. When \a compress @@ -1719,6 +1843,13 @@ QStringList QScxmlStateMachine::activeStateNames(bool compress) const } /*! + \qmlmethod ScxmlStateMachine::isActive(string scxmlStateName) + + Returns \c true if the state specified by \a scxmlStateName is active, + \c false otherwise. +*/ + +/*! * Returns \c true if the state specified by \a scxmlStateName is active, \c false otherwise. */ bool QScxmlStateMachine::isActive(const QString &scxmlStateName) const @@ -1810,6 +1941,17 @@ QMetaObject::Connection QScxmlStateMachine::connectToEventImpl(const QString &sc } /*! + \qmlmethod ScxmlStateMachine::init() + + Initializes the state machine by setting the initial values for \c <data> + elements and executing any \c <script> tags of the \c <scxml> tag. The + initial data values are taken from the \l initialValues property. + + Returns \c false if parse errors occur or if any of the initialization steps + fail. Returns \c true otherwise. +*/ + +/*! * Initializes the state machine. * * State machine initialization consists of calling QScxmlDataModel::setup(), setting the initial @@ -1886,10 +2028,24 @@ QString QScxmlStateMachine::name() const } /*! + \qmlmethod ScxmlStateMachine::submitEvent(event) + + Submits the SCXML event \a 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 the event and deletes it + after processing. + + \sa QScxmlEvent + */ + +/*! * Submits the SCXML event \a 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 \a event and deletes it after processing. */ void QScxmlStateMachine::submitEvent(QScxmlEvent *event) { @@ -1924,6 +2080,12 @@ void QScxmlStateMachine::submitEvent(const QString &eventName) e->setEventType(QScxmlEvent::ExternalEvent); submitEvent(e); } +/*! + \qmlmethod ScxmlStateMachine::submitEvent(string eventName, var data) + + A utility method to create and submit an external event with the specified + \a eventName as the name and \a data as the payload data (optional). +*/ /*! * A utility method to create and submit an external event with the specified @@ -1943,6 +2105,12 @@ void QScxmlStateMachine::submitEvent(const QString &eventName, const QVariant &d } /*! + \qmlmethod ScxmlStateMachine::cancelDelayedEvent(string sendId) + + Cancels a delayed event with the specified \a sendId. +*/ + +/*! * Cancels a delayed event with the specified \a sendId. */ void QScxmlStateMachine::cancelDelayedEvent(const QString &sendId) @@ -1963,6 +2131,24 @@ void QScxmlStateMachine::cancelDelayedEvent(const QString &sendId) } /*! + \qmlmethod ScxmlStateMachine::isDispatchableTarget(string target) + + Returns \c true if a message to \a target can be dispatched by this state + machine. + + Valid targets are: + \list + \li \c #_parent for the parent state machine if the current state machine + is started by \c <invoke> + \li \c #_internal for the current state machine + \li \c #_scxml_sessionid, where \c sessionid is the session ID of the + current state machine + \li \c #_servicename, where \c servicename is the ID or name of a service + started with \c <invoke> by this state machine + \endlist + */ + +/*! * Returns \c true if a message to \a target can be dispatched by this state machine. * * Valid targets are: @@ -1997,6 +2183,13 @@ bool QScxmlStateMachine::isDispatchableTarget(const QString &target) const } /*! + \qmlproperty list ScxmlStateMachine::invokedServices + + A list of SCXML services that were invoked from the main state machine + (possibly recursively). +*/ + +/*! \property QScxmlStateMachine::invokedServices \brief A list of SCXML services that were invoked from the main state machine (possibly recursively). @@ -2029,6 +2222,17 @@ QVector<QScxmlInvokableService *> QScxmlStateMachine::invokedServices() const */ /*! + \qmlsignal ScxmlStateMachine::log(string label, string msg) + + This signal is emitted if a \c <log> tag is used in the SCXML. \a label is + the value of the \e label attribute of the \c <log> tag. \a msg is the value + of the evaluated \e expr attribute of the \c <log> tag. If there is no + \e expr attribute, a null string will be returned. + + The corresponding signal handler is \c onLog(). +*/ + +/*! \fn QScxmlStateMachine::reachedStableState() This signal is emitted when the event queue is empty at the end of a macro step or when a final @@ -2036,6 +2240,15 @@ QVector<QScxmlInvokableService *> QScxmlStateMachine::invokedServices() const */ /*! + \qmlsignal ScxmlStateMachine::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. + + The corresponding signal handler is \c onreachedStableState(). +*/ + +/*! \fn QScxmlStateMachine::finished() This signal is emitted when the state machine reaches a top-level final state. @@ -2043,6 +2256,24 @@ QVector<QScxmlInvokableService *> QScxmlStateMachine::invokedServices() const \sa running */ +/*! + \qmlsignal ScxmlStateMachine::finished() + + This signal is emitted when the state machine reaches a top-level final + state. + + The corresponding signal handler is \c onFinished(). +*/ + +/*! + \qmlmethod ScxmlStateMachine::start() + + Starts this state machine. The machine resets its configuration and + transitions to the initial state. When a final top-level state + is entered, the machine emits the finished() signal. + + \sa stop(), finished() +*/ /*! Starts this state machine. The machine will reset its configuration and @@ -2071,6 +2302,15 @@ void QScxmlStateMachine::start() } /*! + \qmlmethod ScxmlStateMachine::stop() + + Stops this state machine. The machine will not execute any further state + transitions. Its \l running property is set to \c false. + + \sa start(), finished() +*/ + +/*! Stops this state machine. The machine will not execute any further state transitions. Its \c running property is set to \c false. |