diff options
author | Ulf Hermann <ulf.hermann@qt.io> | 2016-09-21 18:36:11 +0200 |
---|---|---|
committer | Jani Heikkinen <jani.heikkinen@qt.io> | 2016-11-30 08:32:44 +0000 |
commit | 15942fe84483ff6aabf1008f3edc153b9ff31b4d (patch) | |
tree | 0c91fa4cf641155a22d5151ad459c0142cf321ae | |
parent | 7cb37856848f4ead8030d3aa660c1c244ccecdaa (diff) |
Add missing documentation
Most of the methods marked as \internal or excluded via
"#ifndef Q_QDOC" so far are not actually internal as they are called
from compiled state machines. We have to document them.
Change-Id: Ib80268ae00f536e9ac2d337b565dcafbbdc31dea
Reviewed-by: Erik Verbruggen <erik.verbruggen@qt.io>
-rw-r--r-- | src/scxml/qscxmlcppdatamodel.cpp | 67 | ||||
-rw-r--r-- | src/scxml/qscxmlcppdatamodel.h | 3 | ||||
-rw-r--r-- | src/scxml/qscxmldatamodel.cpp | 75 | ||||
-rw-r--r-- | src/scxml/qscxmldatamodel.h | 2 | ||||
-rw-r--r-- | src/scxml/qscxmlecmascriptdatamodel.cpp | 42 | ||||
-rw-r--r-- | src/scxml/qscxmlecmascriptdatamodel.h | 2 | ||||
-rw-r--r-- | src/scxml/qscxmlexecutablecontent.cpp | 169 | ||||
-rw-r--r-- | src/scxml/qscxmlexecutablecontent_p.h | 2 | ||||
-rw-r--r-- | src/scxml/qscxmlinvokableservice.cpp | 133 | ||||
-rw-r--r-- | src/scxml/qscxmlnulldatamodel.cpp | 53 | ||||
-rw-r--r-- | src/scxml/qscxmlnulldatamodel.h | 2 | ||||
-rw-r--r-- | src/scxml/qscxmlstatemachine.cpp | 25 | ||||
-rw-r--r-- | src/scxml/qscxmlstatemachine.h | 4 | ||||
-rw-r--r-- | src/scxml/qscxmltabledata.cpp | 73 |
14 files changed, 602 insertions, 50 deletions
diff --git a/src/scxml/qscxmlcppdatamodel.cpp b/src/scxml/qscxmlcppdatamodel.cpp index 060c220..23a7392 100644 --- a/src/scxml/qscxmlcppdatamodel.cpp +++ b/src/scxml/qscxmlcppdatamodel.cpp @@ -52,7 +52,7 @@ using namespace QScxmlExecutableContent; \sa QScxmlStateMachine QScxmlDataModel - The C++ data model for SCXML that lets you write C++ code for \e expr attributes and \c <script> + The C++ data model for SCXML lets you write C++ code for \e expr attributes and \c <script> elements. The \e {data part} of the data model is backed by a subclass of QScxmlCppDataModel, for which the Qt SCXML compiler (\c qscxmlc) will generate the dispatch methods. It cannot be used when loading an SCXML file at runtime. @@ -69,6 +69,7 @@ using namespace QScxmlExecutableContent; class TheDataModel: public QScxmlCppDataModel { + Q_OBJECT Q_SCXML_DATAMODEL }; \endcode @@ -77,8 +78,6 @@ class TheDataModel: public QScxmlCppDataModel This macro expands to the declaration of some virtual methods whose implementation is generated by the Qt SCXML compiler. - \note You can of course inherit from both QScxmlCppDataModel and QObject. - The Qt SCXML compiler will generate the various \c evaluateTo methods, and convert expressions and scripts into lambdas inside those methods. For example: \code @@ -148,19 +147,41 @@ bool QScxmlCppDataModel::setup(const QVariantMap &initialDataValues) return true; } -void QScxmlCppDataModel::evaluateAssignment(EvaluatorId id, bool *ok) +/*! + \reimp + + This method doesn't perform any action, ignores \a id, and sets \a ok to + \c false. Override it in your specific data model in order to implement + \c <assign>. + */ +void QScxmlCppDataModel::evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, bool *ok) { Q_UNUSED(id); *ok = false; } -void QScxmlCppDataModel::evaluateInitialization(EvaluatorId id, bool *ok) +/*! + \reimp + + This method doesn't perform any action, ignores \a id, and sets \a ok to + \c false. Override it in your specific data model in order to implement + \c <data>. + */ +void QScxmlCppDataModel::evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, bool *ok) { Q_UNUSED(id); *ok = false; } -void QScxmlCppDataModel::evaluateForeach(EvaluatorId id, bool *ok, ForeachLoopBody *body) +/*! + \reimp + + This method doesn't perform any action, ignores \a id and \a body, and sets + \a ok to \c false. Override it in your specific data model in order to + implement \c <foreach>. + */ +void QScxmlCppDataModel::evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok, + ForeachLoopBody *body) { Q_UNUSED(id); Q_UNUSED(body); @@ -168,9 +189,11 @@ void QScxmlCppDataModel::evaluateForeach(EvaluatorId id, bool *ok, ForeachLoopBo } /*! - * Sets the \a event that will be processed next. - * - * \sa QScxmlCppDataModel::scxmlEvent + \reimp + + Sets the \a event that will be processed next. + + \sa QScxmlCppDataModel::scxmlEvent */ void QScxmlCppDataModel::setScxmlEvent(const QScxmlEvent &event) { @@ -197,7 +220,11 @@ const QScxmlEvent &QScxmlCppDataModel::scxmlEvent() const } /*! - * \reimp + \reimp + + This method always returns an empty QVariant and ignores \a name. + Override it to implement lookup of data model properties via the + \c location attribute of various elements. */ QVariant QScxmlCppDataModel::scxmlProperty(const QString &name) const { @@ -206,7 +233,11 @@ QVariant QScxmlCppDataModel::scxmlProperty(const QString &name) const } /*! - * \reimp + \reimp + + This method always returns false and ignores \a name. + Override it to implement lookup of data model properties via the + \c location attribute of various elements. */ bool QScxmlCppDataModel::hasScxmlProperty(const QString &name) const { @@ -215,9 +246,15 @@ bool QScxmlCppDataModel::hasScxmlProperty(const QString &name) const } /*! - * \reimp + \reimp + + This method always returns false and ignores \a name, \a value, and + \a context. + Override it to implement lookup of data model properties via the + \c location attribute of various elements. */ -bool QScxmlCppDataModel::setScxmlProperty(const QString &name, const QVariant &value, const QString &context) +bool QScxmlCppDataModel::setScxmlProperty(const QString &name, const QVariant &value, + const QString &context) { Q_UNUSED(name); Q_UNUSED(value); @@ -226,8 +263,8 @@ bool QScxmlCppDataModel::setScxmlProperty(const QString &name, const QVariant &v } /*! - * Returns \c true if the state machine is in the state specified by \a stateName, \c false - * otherwise. + Returns \c true if the state machine is in the state specified by + \a stateName, \c false otherwise. */ bool QScxmlCppDataModel::inState(const QString &stateName) const { diff --git a/src/scxml/qscxmlcppdatamodel.h b/src/scxml/qscxmlcppdatamodel.h index a491326..244259f 100644 --- a/src/scxml/qscxmlcppdatamodel.h +++ b/src/scxml/qscxmlcppdatamodel.h @@ -62,11 +62,10 @@ public: Q_INVOKABLE bool setup(const QVariantMap &initialDataValues) Q_DECL_OVERRIDE; -#ifndef Q_QDOC void evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE; void evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE; void evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok, ForeachLoopBody *body) Q_DECL_OVERRIDE; -#endif // Q_QDOC + void setScxmlEvent(const QScxmlEvent &scxmlEvent) Q_DECL_OVERRIDE Q_DECL_FINAL; const QScxmlEvent &scxmlEvent() const; diff --git a/src/scxml/qscxmldatamodel.cpp b/src/scxml/qscxmldatamodel.cpp index 570289d..bf84ef8 100644 --- a/src/scxml/qscxmldatamodel.cpp +++ b/src/scxml/qscxmldatamodel.cpp @@ -45,14 +45,27 @@ QT_BEGIN_NAMESPACE /*! - * \class QScxmlDataModel::ForeachLoopBody - * \internal + \class QScxmlDataModel::ForeachLoopBody + \brief The ForeachLoopBody class represents a function to be executed on + each iteration of an SCXML foreach loop. + \since 5.8 + \inmodule QtScxml */ +/*! + Destroys a ForeachLoopBody + */ QScxmlDataModel::ForeachLoopBody::~ForeachLoopBody() {} /*! + \fn QScxmlDataModel::ForeachLoopBody::run(bool *ok) + + Function to be executed on each iteration. If the execution fails \a ok is + set to \c false, otherwise it is set to \c true. + */ + +/*! * \class QScxmlDataModel * \brief The QScxmlDataModel class is the data model base class for a Qt SCXML * state machine. @@ -89,7 +102,8 @@ QScxmlDataModel::QScxmlDataModel(QObject *parent) } /*! - * \internal + Creates a new QScxmlDataModel from a private object \a dd with parent + object \a parent. */ QScxmlDataModel::QScxmlDataModel(QScxmlDataModelPrivate &dd, QObject *parent) : QObject(dd, parent) @@ -184,4 +198,59 @@ QScxmlDataModel *QScxmlDataModelPrivate::instantiateDataModel(DocumentModel::Scx * Returns \c true if successful or \c false if an error occurred. */ +/*! + * \fn QScxmlDataModel::evaluateToString( + * QScxmlExecutableContent::EvaluatorId id, bool *ok) + * Evaluates the executable content pointed to by \a id, and sets \a ok to + * \c false if there was an error, or to \c true if there wasn't. + * Returns the result of the evaluation as a QString. + */ + +/*! + * \fn QScxmlDataModel::evaluateToBool(QScxmlExecutableContent::EvaluatorId id, + * bool *ok) + * Evaluates the executable content pointed to by \a id, and sets \a ok to + * \c false if there was an error, or to \c true if there wasn't. + * Returns the result of the evaluation as a bool. + */ + +/*! + * \fn QScxmlDataModel::evaluateToVariant( + * QScxmlExecutableContent::EvaluatorId id, bool *ok) + * Evaluates the executable content pointed to by \a id, and sets \a ok to + * \c false if there was an error, or to \c true if there wasn't. + * Returns the result of the evaluation as a QVariant. + */ + +/*! + * \fn QScxmlDataModel::evaluateToVoid(QScxmlExecutableContent::EvaluatorId id, + * bool *ok) + * Evaluates the executable content pointed to by \a id, and sets \a ok to + * \c false if there was an error, or to \c true if there wasn't. + * The execution is expected to return no result. + */ + +/*! + * \fn QScxmlDataModel::evaluateAssignment( + * QScxmlExecutableContent::EvaluatorId id, bool *ok) + * Evaluates the assignement pointed to by \a id, and sets \a ok to + * \c false if there was an error, or to \c true if there wasn't. + */ + +/*! + * \fn QScxmlDataModel::evaluateInitialization( + * QScxmlExecutableContent::EvaluatorId id, bool *ok) + * Evaluates the initialization pointed to by \a id, and sets \a ok to + * \c false if there was an error, or to \c true if there wasn't. + */ + +/*! + * \fn QScxmlDataModel::evaluateForeach( + * QScxmlExecutableContent::EvaluatorId id, bool *ok, + * ForeachLoopBody *body) + * Evaluates the foreach loop pointed to by \a id, and sets \a ok to + * \c false if there was an error, or to \c true if there wasn't. The + * \a body is executed on each iteration. + */ + QT_END_NAMESPACE diff --git a/src/scxml/qscxmldatamodel.h b/src/scxml/qscxmldatamodel.h index e16f2f7..d34a84a 100644 --- a/src/scxml/qscxmldatamodel.h +++ b/src/scxml/qscxmldatamodel.h @@ -75,7 +75,6 @@ public: Q_INVOKABLE virtual bool setup(const QVariantMap &initialDataValues) = 0; -#ifndef Q_QDOC virtual QString evaluateToString(QScxmlExecutableContent::EvaluatorId id, bool *ok) = 0; virtual bool evaluateToBool(QScxmlExecutableContent::EvaluatorId id, bool *ok) = 0; virtual QVariant evaluateToVariant(QScxmlExecutableContent::EvaluatorId id, bool *ok) = 0; @@ -83,7 +82,6 @@ public: virtual void evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, bool *ok) = 0; virtual void evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, bool *ok) = 0; virtual void evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok, ForeachLoopBody *body) = 0; -#endif // Q_QDOC virtual void setScxmlEvent(const QScxmlEvent &event) = 0; diff --git a/src/scxml/qscxmlecmascriptdatamodel.cpp b/src/scxml/qscxmlecmascriptdatamodel.cpp index 869afec..e517989 100644 --- a/src/scxml/qscxmlecmascriptdatamodel.cpp +++ b/src/scxml/qscxmlecmascriptdatamodel.cpp @@ -393,7 +393,11 @@ bool QScxmlEcmaScriptDataModel::setup(const QVariantMap &initialDataValues) return ok; } -QString QScxmlEcmaScriptDataModel::evaluateToString(EvaluatorId id, bool *ok) +/*! + \reimp + */ +QString QScxmlEcmaScriptDataModel::evaluateToString(QScxmlExecutableContent::EvaluatorId id, + bool *ok) { Q_D(QScxmlEcmaScriptDataModel); const EvaluatorInfo &info = d->m_stateMachine->tableData()->evaluatorInfo(id); @@ -401,7 +405,11 @@ QString QScxmlEcmaScriptDataModel::evaluateToString(EvaluatorId id, bool *ok) return d->evalStr(d->string(info.expr), d->string(info.context), ok); } -bool QScxmlEcmaScriptDataModel::evaluateToBool(EvaluatorId id, bool *ok) +/*! + \reimp + */ +bool QScxmlEcmaScriptDataModel::evaluateToBool(QScxmlExecutableContent::EvaluatorId id, + bool *ok) { Q_D(QScxmlEcmaScriptDataModel); const EvaluatorInfo &info = d->m_stateMachine->tableData()->evaluatorInfo(id); @@ -409,7 +417,11 @@ bool QScxmlEcmaScriptDataModel::evaluateToBool(EvaluatorId id, bool *ok) return d->evalBool(d->string(info.expr), d->string(info.context), ok); } -QVariant QScxmlEcmaScriptDataModel::evaluateToVariant(EvaluatorId id, bool *ok) +/*! + \reimp + */ +QVariant QScxmlEcmaScriptDataModel::evaluateToVariant(QScxmlExecutableContent::EvaluatorId id, + bool *ok) { Q_D(QScxmlEcmaScriptDataModel); const EvaluatorInfo &info = d->m_stateMachine->tableData()->evaluatorInfo(id); @@ -417,7 +429,11 @@ QVariant QScxmlEcmaScriptDataModel::evaluateToVariant(EvaluatorId id, bool *ok) return d->evalJSValue(d->string(info.expr), d->string(info.context), ok).toVariant(); } -void QScxmlEcmaScriptDataModel::evaluateToVoid(EvaluatorId id, bool *ok) +/*! + \reimp + */ +void QScxmlEcmaScriptDataModel::evaluateToVoid(QScxmlExecutableContent::EvaluatorId id, + bool *ok) { Q_D(QScxmlEcmaScriptDataModel); const EvaluatorInfo &info = d->m_stateMachine->tableData()->evaluatorInfo(id); @@ -425,7 +441,11 @@ void QScxmlEcmaScriptDataModel::evaluateToVoid(EvaluatorId id, bool *ok) d->eval(d->string(info.expr), d->string(info.context), ok); } -void QScxmlEcmaScriptDataModel::evaluateAssignment(EvaluatorId id, bool *ok) +/*! + \reimp + */ +void QScxmlEcmaScriptDataModel::evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, + bool *ok) { Q_D(QScxmlEcmaScriptDataModel); Q_ASSERT(ok); @@ -445,7 +465,11 @@ void QScxmlEcmaScriptDataModel::evaluateAssignment(EvaluatorId id, bool *ok) } } -void QScxmlEcmaScriptDataModel::evaluateInitialization(EvaluatorId id, bool *ok) +/*! + \reimp + */ +void QScxmlEcmaScriptDataModel::evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, + bool *ok) { Q_D(QScxmlEcmaScriptDataModel); const AssignmentInfo &info = d->m_stateMachine->tableData()->assignmentInfo(id); @@ -458,7 +482,11 @@ void QScxmlEcmaScriptDataModel::evaluateInitialization(EvaluatorId id, bool *ok) evaluateAssignment(id, ok); } -void QScxmlEcmaScriptDataModel::evaluateForeach(EvaluatorId id, bool *ok, ForeachLoopBody *body) +/*! + \reimp + */ +void QScxmlEcmaScriptDataModel::evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok, + ForeachLoopBody *body) { Q_D(QScxmlEcmaScriptDataModel); Q_ASSERT(ok); diff --git a/src/scxml/qscxmlecmascriptdatamodel.h b/src/scxml/qscxmlecmascriptdatamodel.h index 81041c7..7c22044 100644 --- a/src/scxml/qscxmlecmascriptdatamodel.h +++ b/src/scxml/qscxmlecmascriptdatamodel.h @@ -55,7 +55,6 @@ public: Q_INVOKABLE bool setup(const QVariantMap &initialDataValues) Q_DECL_OVERRIDE; -#ifndef Q_QDOC QString evaluateToString(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL; bool evaluateToBool(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL; QVariant evaluateToVariant(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL; @@ -63,7 +62,6 @@ public: void evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL; void evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL; void evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok, ForeachLoopBody *body) Q_DECL_OVERRIDE Q_DECL_FINAL; -#endif // Q_QDOC void setScxmlEvent(const QScxmlEvent &event) Q_DECL_OVERRIDE; diff --git a/src/scxml/qscxmlexecutablecontent.cpp b/src/scxml/qscxmlexecutablecontent.cpp index 9fbcd15..bbe304d 100644 --- a/src/scxml/qscxmlexecutablecontent.cpp +++ b/src/scxml/qscxmlexecutablecontent.cpp @@ -46,6 +46,175 @@ QT_BEGIN_NAMESPACE using namespace QScxmlExecutableContent; +/*! + \namespace QScxmlExecutableContent + \inmodule QtScxml + \since 5.8 + \brief The QScxmlExecutableContent namespace contains various types used + to interpret executable content in state machines. + */ + +/*! + \typedef QScxmlExecutableContent::ContainerId + \inmodule QtScxml + \since 5.8 + \brief ID for a container holding executable content + */ + +/*! + \typedef QScxmlExecutableContent::EvaluatorId + \inmodule QtScxml + \since 5.8 + \brief ID for a unit of executable content + */ + +/*! + \typedef QScxmlExecutableContent::InstructionId + \inmodule QtScxml + \since 5.8 + \brief ID for an instruction of executable content + */ + +/*! + \typedef QScxmlExecutableContent::StringId + \inmodule QtScxml + \since 5.8 + \brief ID for a string contained in executable content + */ + +/*! + \class QScxmlExecutableContent::EvaluatorInfo + \brief Representation of a unit of executable content + \since 5.8 + \inmodule QtScxml + */ + +/*! + \variable QScxmlExecutableContent::EvaluatorInfo::expr + \brief Expression to be evaluated + */ + +/*! + \variable QScxmlExecutableContent::EvaluatorInfo::context + \brief Context for evaluating the expression + */ + +/*! + \class QScxmlExecutableContent::AssignmentInfo + \brief Representation of a data assignment + \since 5.8 + \inmodule QtScxml + */ + +/*! + \variable QScxmlExecutableContent::AssignmentInfo::expr + \brief Expression to be evaluated + */ + +/*! + \variable QScxmlExecutableContent::AssignmentInfo::context + \brief Context for evaluating the expression + */ + +/*! + \variable QScxmlExecutableContent::AssignmentInfo::dest + \brief Name of the data item to assign to + */ + +/*! + \class QScxmlExecutableContent::ForeachInfo + \brief Representation of a foreach construct + \since 5.8 + \inmodule QtScxml + */ + +/*! + \variable QScxmlExecutableContent::ForeachInfo::array + \brief Name of the array we are iterating over + */ + +/*! + \variable QScxmlExecutableContent::ForeachInfo::item + \brief Name of the iteration variable + */ + +/*! + \variable QScxmlExecutableContent::ForeachInfo::index + \brief Name of the index variable + */ + +/*! + \variable QScxmlExecutableContent::ForeachInfo::context + \brief Context for evaluating the expression + */ + +/*! + \class QScxmlExecutableContent::ParameterInfo + \brief Representation of a parameter to a service invocation + \since 5.8 + \inmodule QtScxml + */ + +/*! + \variable QScxmlExecutableContent::ParameterInfo::name + \brief Name of the parameter + */ + +/*! + \variable QScxmlExecutableContent::ParameterInfo::expr + \brief Expression to be evaluated + */ + +/*! + \variable QScxmlExecutableContent::ParameterInfo::location + \brief Data model name of the item to be passed as parameter + */ + +/*! + \class QScxmlExecutableContent::InvokeInfo + \brief Representation of a service invocation + \since 5.8 + \inmodule QtScxml + */ + +/*! + \variable QScxmlExecutableContent::InvokeInfo::id + \brief the ID specified by the id attribute in the invoke element + */ + +/*! + \variable QScxmlExecutableContent::InvokeInfo::prefix + \brief Unique prefix for this invocation in the context of the state from + which it is called + */ + +/*! + \variable QScxmlExecutableContent::InvokeInfo::location + \brief Data model location to write the invocation ID to + */ + +/*! + \variable QScxmlExecutableContent::InvokeInfo::context + \brief The context to interpret the location in + */ + +/*! + \variable QScxmlExecutableContent::InvokeInfo::expr + \brief The expression representing the srcexpr of the invoke element + */ + +/*! + \variable QScxmlExecutableContent::InvokeInfo::finalize + \brief An ID of a container of executable content to be run on finalizing the invocation + */ + +/*! + \variable QScxmlExecutableContent::InvokeInfo::autoforward + \brief Whether events should automatically be forwarded to the invoked + service + */ + + #ifndef BUILD_QSCXMLC static int parseTime(const QString &t, bool *ok = 0) { diff --git a/src/scxml/qscxmlexecutablecontent_p.h b/src/scxml/qscxmlexecutablecontent_p.h index 98461fe..cfaec55 100644 --- a/src/scxml/qscxmlexecutablecontent_p.h +++ b/src/scxml/qscxmlexecutablecontent_p.h @@ -61,6 +61,7 @@ #include <QtScxml/qscxmlstatemachine.h> #endif // BUILD_QSCXMLC +#ifndef Q_QDOC QT_BEGIN_NAMESPACE namespace QScxmlExecutableContent { @@ -509,5 +510,6 @@ private: }; QT_END_NAMESPACE +#endif // Q_QDOC #endif // QSCXMLEXECUTABLECONTENT_P_H diff --git a/src/scxml/qscxmlinvokableservice.cpp b/src/scxml/qscxmlinvokableservice.cpp index 9dfda21..35cd924 100644 --- a/src/scxml/qscxmlinvokableservice.cpp +++ b/src/scxml/qscxmlinvokableservice.cpp @@ -43,6 +43,111 @@ QT_BEGIN_NAMESPACE +/*! + * \class QScxmlInvokableService + * \brief Service invoked from \l{SCXML Specification}{SCXML} + * \since 5.8 + * \inmodule QtScxml + * + * QScxmlInvokableService is the base class for services called from state + * machines via the mechanism described in + * \l {SCXML Specification - 6.4 <invoke>}. This represents an actual instance + * of an invoked service. + */ + +/*! + * \class QScxmlInvokableServiceFactory + * \brief Factory for creating instances of QScxmlInvokableService + * \since 5.8 + * \inmodule QtScxml + * + * A factory for creating instances of QScxmlInvokableService. This reperesents + * an \c <invoke> element in the SCXML document. Each time the service is + * actually invoked a new instance of QScxmlInvokableService is created. + */ + +/*! + \property QScxmlInvokableServiceFactory::invokeInfo + + The QScxmlExecutableContent::InvokeInfo passed to the constructor. + */ + +/*! + \property QScxmlInvokableServiceFactory::names + + The QVector<QScxmlExecutableContent::StringId> of names passed to the + constructor. + */ + +/*! + \property QScxmlInvokableServiceFactory::parameters + + The QVector<QScxmlExecutableContent::ParameterInfo> passed to the + constructor. + */ + +/*! + * \class QScxmlStaticScxmlServiceFactory + * \brief Factory for creating QScxmlScxmlService instances from precompiled + * documents + * \since 5.8 + * \inmodule QtScxml + * + * A factory for instantiating QScxmlStateMachines from files known at compile + * time, that is files specified via the \c src attribute in \c <invoke> + */ + +/*! + * \class QScxmlDynamicScxmlServiceFactory + * \brief Factory for QScxmlScxmlService instances created from documents + * loaded at run time + * \since 5.8 + * \inmodule QtScxml + * + * A QScxmlScxmlServiceFactory for creating dynamically resolved services. This + * is used when loading \l{SCXML Specification}{SCXML} content from files a + * parent state machine requests at runtime, via the \c srcexpr attribute in + * \c <invoke>. + */ + +/*! + * \property QScxmlInvokableService::parentStateMachine + * + * The QScxmlStateMachine that invoked the service. + */ + +/*! + * \property QScxmlInvokableService::id + * + * The id specified in the \c id attribute of the \c <invoke> element. + */ + +/*! + * \property QScxmlInvokableService::name + * + * The name of the service being invoked. + */ + +/*! + * \fn QScxmlInvokableService::postEvent(QScxmlEvent *event) + * + * Sends an \a event to the service. + */ + +/*! + * \fn QScxmlInvokableService::start() + * + * Starts the invokable service. Returns \c true on success, or \c false if the + * invocation fails. + */ + +/*! + * \fn QScxmlInvokableServiceFactory::invoke(QScxmlStateMachine *parentStateMachine) + * + * Invoke the service with the parameters given in the contructor, passing + * \a parentStateMachine as parent. Returns the new QScxmlInvokableService. + */ + QScxmlInvokableServicePrivate::QScxmlInvokableServicePrivate(QScxmlStateMachine *parentStateMachine) : parentStateMachine(parentStateMachine) { @@ -216,6 +321,10 @@ QScxmlScxmlService::~QScxmlScxmlService() delete stateMachine; } +/*! + Create a QScxmlScxmlService wrapping \a stateMachine, invoked from + \a parentStateMachine, as child of \a parent. + */ QScxmlScxmlService::QScxmlScxmlService(QScxmlStateMachine *stateMachine, QScxmlStateMachine *parentStateMachine, QScxmlInvokableServiceFactory *factory) @@ -224,6 +333,9 @@ QScxmlScxmlService::QScxmlScxmlService(QScxmlStateMachine *stateMachine, QScxmlStateMachinePrivate::get(stateMachine)->m_parentStateMachine = parentStateMachine; } +/*! + * \reimp + */ bool QScxmlScxmlService::start() { Q_D(QScxmlInvokableService); @@ -254,21 +366,36 @@ bool QScxmlScxmlService::start() return false; } +/*! + \reimp + */ QString QScxmlScxmlService::id() const { return stateMachine->sessionId(); } +/*! + \reimp + */ QString QScxmlScxmlService::name() const { return stateMachine->name(); } +/*! + \reimp + */ void QScxmlScxmlService::postEvent(QScxmlEvent *event) { QScxmlStateMachinePrivate::get(stateMachine)->postEvent(event); } +/*! + Create a QScxmlDynamicScxmlServiceFactory, passing the attributes of the + \c <invoke> element as \a invokeInfo, any \c <param> child elements as + \a parameters, the content of the \c names attribute as \a names, and the + QObject parent \a parent. + */ QScxmlDynamicScxmlServiceFactory::QScxmlDynamicScxmlServiceFactory( const QScxmlExecutableContent::InvokeInfo &invokeInfo, const QVector<QScxmlExecutableContent::StringId> &names, @@ -277,6 +404,9 @@ QScxmlDynamicScxmlServiceFactory::QScxmlDynamicScxmlServiceFactory( : QScxmlInvokableServiceFactory(invokeInfo, names, parameters, parent) {} +/*! + \reimp + */ QScxmlInvokableService *QScxmlDynamicScxmlServiceFactory::invoke( QScxmlStateMachine *parentStateMachine) { @@ -299,6 +429,9 @@ QScxmlStaticScxmlServiceFactory::QScxmlStaticScxmlServiceFactory( { } +/*! + \reimp + */ QScxmlInvokableService *QScxmlStaticScxmlServiceFactory::invoke( QScxmlStateMachine *parentStateMachine) { diff --git a/src/scxml/qscxmlnulldatamodel.cpp b/src/scxml/qscxmlnulldatamodel.cpp index d7b64d0..d3e9942 100644 --- a/src/scxml/qscxmlnulldatamodel.cpp +++ b/src/scxml/qscxmlnulldatamodel.cpp @@ -122,19 +122,22 @@ private: * This class implements the null data model as described in the * \l {SCXML Specification - B.1 The Null Data Model}. Using the value \c "null" * for the \e datamodel attribute of the \c <scxml> element means that there is - * no underlying data model. + * no underlying data model, but some executable content, like \c In(...) or + * \c <log> can still be used. * * \sa QScxmlStateMachine QScxmlDataModel */ /*! - * Creates a new Qt SCXML data model, with the parent object \a parent. + * Creates a new Qt SCXML null data model, with the parent object \a parent. */ QScxmlNullDataModel::QScxmlNullDataModel(QObject *parent) : QScxmlDataModel(*(new QScxmlNullDataModelPrivate), parent) {} -/*! \internal */ +/*! + Destroys the data model. + */ QScxmlNullDataModel::~QScxmlNullDataModel() { } @@ -149,6 +152,13 @@ bool QScxmlNullDataModel::setup(const QVariantMap &initialDataValues) return true; } +/*! + \reimp + Evaluates the executable content pointed to by \a id, and records in \a ok + if there was an error. returns the result of the evaluation as a string. The + null data model can evaluate "<log>", so this might result in an actual + value, rather than an error + */ QString QScxmlNullDataModel::evaluateToString(QScxmlExecutableContent::EvaluatorId id, bool *ok) { Q_D(QScxmlNullDataModel); @@ -160,12 +170,25 @@ QString QScxmlNullDataModel::evaluateToString(QScxmlExecutableContent::Evaluator return td->string(info.expr); } +/*! + \reimp + Evaluates the executable content pointed to by \a id, and records in \a ok + if there was an error. returns the result of the evaluation as a bool. The + null data model can evaluate the instruction "In(...)", so this might result + in an actual value, rather than an error. + */ bool QScxmlNullDataModel::evaluateToBool(QScxmlExecutableContent::EvaluatorId id, bool *ok) { Q_D(QScxmlNullDataModel); return d->evalBool(id, ok); } +/*! + \reimp + Evaluates the executable content pointed to by \a id, and records in \a ok + if there was an error. As this is the null data model, any evaluation will in + fact result in an error, with \a ok set to \c false. Returns an empty QVariant. + */ QVariant QScxmlNullDataModel::evaluateToVariant(QScxmlExecutableContent::EvaluatorId id, bool *ok) { Q_UNUSED(id); @@ -176,6 +199,12 @@ QVariant QScxmlNullDataModel::evaluateToVariant(QScxmlExecutableContent::Evaluat return QVariant(); } +/*! + \reimp + Evaluates the executable content pointed to by \a id, and records in \a ok + if there was an error. As this is the null data model, any evaluation will in + fact result in an error, with \a ok set to \c false. + */ void QScxmlNullDataModel::evaluateToVoid(QScxmlExecutableContent::EvaluatorId id, bool *ok) { Q_UNUSED(id); @@ -185,6 +214,11 @@ void QScxmlNullDataModel::evaluateToVoid(QScxmlExecutableContent::EvaluatorId id QStringLiteral("Cannot evaluate expressions on a null data model")); } +/*! + \reimp + Throws an error and sets \a ok to \c false because the null data model cannot evaluate + assignments. + */ void QScxmlNullDataModel::evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, bool *ok) { Q_UNUSED(id); @@ -194,6 +228,10 @@ void QScxmlNullDataModel::evaluateAssignment(QScxmlExecutableContent::EvaluatorI QStringLiteral("Cannot assign values on a null data model")); } +/*! + \reimp + Throws an error and sets \a ok to \c false because the null data model cannot initialize data. + */ void QScxmlNullDataModel::evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, bool *ok) { Q_UNUSED(id); @@ -203,7 +241,13 @@ void QScxmlNullDataModel::evaluateInitialization(QScxmlExecutableContent::Evalua QStringLiteral("Cannot initialize values on a null data model")); } -void QScxmlNullDataModel::evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok, ForeachLoopBody *body) +/*! + \reimp + Throws an error and sets \a ok to \c false because the null data model cannot evaluate <foreach> + blocks. + */ +void QScxmlNullDataModel::evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok, + ForeachLoopBody *body) { Q_UNUSED(id); Q_UNUSED(body); @@ -215,6 +259,7 @@ void QScxmlNullDataModel::evaluateForeach(QScxmlExecutableContent::EvaluatorId i /*! * \reimp + * Does not actually set the \a event, because the null data model does not handle events. */ void QScxmlNullDataModel::setScxmlEvent(const QScxmlEvent &event) { diff --git a/src/scxml/qscxmlnulldatamodel.h b/src/scxml/qscxmlnulldatamodel.h index 098adcf..830162f 100644 --- a/src/scxml/qscxmlnulldatamodel.h +++ b/src/scxml/qscxmlnulldatamodel.h @@ -55,7 +55,6 @@ public: Q_INVOKABLE bool setup(const QVariantMap &initialDataValues) Q_DECL_OVERRIDE; -#ifndef Q_QDOC QString evaluateToString(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL; bool evaluateToBool(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL; QVariant evaluateToVariant(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL; @@ -63,7 +62,6 @@ public: void evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL; void evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL; void evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok, ForeachLoopBody *body) Q_DECL_OVERRIDE Q_DECL_FINAL; -#endif // Q_QDOC void setScxmlEvent(const QScxmlEvent &event) Q_DECL_OVERRIDE; diff --git a/src/scxml/qscxmlstatemachine.cpp b/src/scxml/qscxmlstatemachine.cpp index d71755b..41d47ba 100644 --- a/src/scxml/qscxmlstatemachine.cpp +++ b/src/scxml/qscxmlstatemachine.cpp @@ -589,21 +589,21 @@ void QScxmlStateMachinePrivate::submitDelayedEvent(QScxmlEvent *event) } /*! - * \internal - * \brief Submits an error event to the external event queue of this state machine. + * Submits an error event to the external event queue of this state machine. * - * \param type The error message type, e.g. "error.execution". The type has to start with "error.". - * \param msg A string describing the nature of the error. This is passed to the event as the - * errorMessage - * \param sendid The sendid of the message causing the error, if it has one. + * The error is of \a type, e.g. "error.execution". The type has to start with "error.". An + * \a message is specified, describing the nature of the error. This is passed to the event as the + * \c errorMessage property. The \a sendId of the message causing the error is specified, if it has + * one. */ -void QScxmlStateMachinePrivate::submitError(const QString &type, const QString &msg, const QString &sendid) +void QScxmlStateMachinePrivate::submitError(const QString &type, const QString &message, + const QString &sendId) { Q_Q(QScxmlStateMachine); - qCDebug(qscxmlLog) << q << "had error" << type << ":" << msg; + qCDebug(qscxmlLog) << q << "had error" << type << ":" << message; if (!type.startsWith(QStringLiteral("error."))) qCWarning(qscxmlLog) << q << "Message type of error message does not start with 'error.'!"; - q->submitEvent(QScxmlEventBuilder::errorEvent(q, type, msg, sendid)); + q->submitEvent(QScxmlEventBuilder::errorEvent(q, type, message, sendId)); } void QScxmlStateMachinePrivate::start() @@ -2067,6 +2067,13 @@ void QScxmlStateMachine::stop() d->pause(); } +/*! + Returns \c true if the state with ID \a 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::isActive(int stateIndex) const { Q_D(const QScxmlStateMachine); diff --git a/src/scxml/qscxmlstatemachine.h b/src/scxml/qscxmlstatemachine.h index da8de50..d4435f7 100644 --- a/src/scxml/qscxmlstatemachine.h +++ b/src/scxml/qscxmlstatemachine.h @@ -78,10 +78,8 @@ class Q_SCXML_EXPORT QScxmlStateMachine: public QObject Q_PROPERTY(QScxmlTableData *tableData READ tableData WRITE setTableData NOTIFY tableDataChanged) protected: -#ifndef Q_QDOC explicit QScxmlStateMachine(const QMetaObject *metaObject, QObject *parent = nullptr); QScxmlStateMachine(QScxmlStateMachinePrivate &dd, QObject *parent = nullptr); -#endif // Q_QDOC public: static QScxmlStateMachine *fromFile(const QString &fileName); @@ -341,10 +339,8 @@ protected: // methods for friends: friend class QScxmlInvokableServicePrivate; friend class QScxmlExecutionEngine; -#ifndef Q_QDOC // The methods below are used by the compiled state machines. bool isActive(int stateIndex) const; -#endif // Q_QDOC private: QMetaObject::Connection connectToStateImpl(const QString &scxmlStateName, diff --git a/src/scxml/qscxmltabledata.cpp b/src/scxml/qscxmltabledata.cpp index 2457840..fc2bbb7 100644 --- a/src/scxml/qscxmltabledata.cpp +++ b/src/scxml/qscxmltabledata.cpp @@ -43,6 +43,75 @@ QT_USE_NAMESPACE +/*! + \class QScxmlTableData + \since 5.8 + \inmodule QtScxml + \brief The QScxmlTableData class is used by compiled state machines. + + QScxmlTableData is the interface to the compiled representation of SCXML + state machines. It should only be used internally and by state machines + compiled from SCXML documents. + */ + +/*! + \fn QScxmlTableData::string(QScxmlExecutableContent::StringId id) const + Returns a QString for the given \a id. + */ + +/*! + \fn QScxmlTableData::instructions() const + Returns a pointer to the instructions of executable content contained in + the state machine. + */ + +/*! + \fn QScxmlTableData::evaluatorInfo(QScxmlExecutableContent::EvaluatorId evaluatorId) const + Returns the QScxmlExecutableContent::EvaluatorInfo object for the given \a evaluatorId. + */ + +/*! + \fn QScxmlTableData::assignmentInfo(QScxmlExecutableContent::EvaluatorId assignmentId) const + Returns the QScxmlExecutableContent::AssignmentInfo object for the given \a assignmentId. + */ + +/*! + \fn QScxmlTableData::foreachInfo(QScxmlExecutableContent::EvaluatorId foreachId) const + Returns the QScxmlExecutableContent::ForeachInfo object for the given \a foreachId. + */ + +/*! + \fn QScxmlTableData::dataNames(int *count) const + Retrieves the string IDs for names of data items in the data model. The + number of strings is saved into \a count and a pointer to an array of + string IDs is returned. + + Returns a pointer to an array of string IDs. + */ + +/*! + \fn QScxmlTableData::initialSetup() const + Initializes the table data. Returns the ID of the container with + instructions to be executed when initializing the state machine. + */ + +/*! + \fn QScxmlTableData::name() const + Returns the name of the state machine. + */ + +/*! + \fn QScxmlTableData::stateMachineTable() const + Returns a pointer to the complete state table, expressed as an opaque + sequence of integers. + */ + +/*! + \fn QScxmlTableData::serviceFactory(int id) const + Returns the service factory that creates invokable services for the state + with the ID \a id. + */ + using namespace QScxmlInternal; namespace { @@ -898,6 +967,10 @@ private: } // anonymous namespace +/*! + \fn QScxmlTableData::~QScxmlTableData() + Destroys a QScxmlTableData. + */ QScxmlTableData::~QScxmlTableData() {} |