1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qscxmlcppdatamodel_p.h"
5#include "qscxmlstatemachine.h"
6
7QT_BEGIN_NAMESPACE
8
9using namespace QScxmlExecutableContent;
10
11/*!
12 \class QScxmlCppDataModel
13 \brief The QScxmlCppDataModel class is a C++ data model for a Qt SCXML state machine.
14 \since 5.7
15 \inmodule QtScxml
16
17 \sa QScxmlStateMachine QScxmlDataModel
18
19 The C++ data model for SCXML lets you write C++ code for \e expr attributes and \c <script>
20 elements. The \e {data part} of the data model is backed by a subclass of QScxmlCppDataModel, for
21 which the Qt SCXML compiler (\c qscxmlc) will generate the dispatch methods. It cannot be used
22 when loading an SCXML file at runtime.
23
24 Usage is through the \e datamodel attribute of the \c <scxml> element:
25 \code
26 <scxml datamodel="cplusplus:TheDataModel:thedatamodel.h" ....>
27 \endcode
28 The format of the \e datamodel attribute is: \c{cplusplus:<class-name>:<classdef-header>}.
29 So, for the example above, there should be a file \e thedatamodel.h containing a subclass of
30 QScxmlCppDataModel, containing at least the following:
31 \badcode
32#include "qscxmlcppdatamodel.h"
33
34class TheDataModel: public QScxmlCppDataModel
35{
36 \Q_OBJECT
37 Q_SCXML_DATAMODEL
38};
39 \endcode
40 The Q_SCXML_DATAMODEL has to appear in the private section of the class definition, for example
41 right after the opening bracket, or after a Q_OBJECT macro.
42 This macro expands to the declaration of some virtual
43 methods whose implementation is generated by the Qt SCXML compiler.
44
45 The Qt SCXML compiler will generate the various \c evaluateTo methods, and convert expressions and
46 scripts into lambdas inside those methods. For example:
47 \code
48<scxml datamodel="cplusplus:TheDataModel:thedatamodel.h" xmlns="http://www.w3.org/2005/07/scxml" version="1.0" name="MediaPlayerStateMachine">
49 <state id="stopped">
50 <transition event="tap" cond="isValidMedia()" target="playing"/>
51 </state>
52
53 <state id="playing">
54 <onentry>
55 <script>
56 media = eventData().value(QStringLiteral(&quot;media&quot;)).toString();
57 </script>
58 <send event="playbackStarted">
59 <param name="media" expr="media"/>
60 </send>
61 </onentry>
62 </state>
63</scxml>
64 \endcode
65 This will result in:
66 \code
67bool TheDataModel::evaluateToBool(QScxmlExecutableContent::EvaluatorId id, bool *ok) {
68 // ....
69 return [this]()->bool{ return isValidMedia(); }();
70 // ....
71}
72
73QVariant TheDataModel::evaluateToVariant(QScxmlExecutableContent::EvaluatorId id, bool *ok) {
74 // ....
75 return [this]()->QVariant{ return media; }();
76 // ....
77}
78
79void TheDataModel::evaluateToVoid(QScxmlExecutableContent::EvaluatorId id, bool *ok) {
80 // ....
81 [this]()->void{ media = eventData().value(QStringLiteral("media")).toString(); }();
82 // ....
83}
84 \endcode
85
86 So, you are not limited to call functions. In a \c <script> element you can put zero or more C++
87 statements, and in \e cond or \e expr attributes you can use any C++ expression that can be
88 converted to the respective bool or QVariant. And, as the \c this pointer is also captured, you
89 can call or access the data model (the \e media attribute in the example above). For the full
90 example, see \l {SCXML Media Player}.
91 */
92
93/*!
94 * Creates a new C++ data model with the parent object \a parent.
95 */
96QScxmlCppDataModel::QScxmlCppDataModel(QObject *parent)
97 : QScxmlDataModel(*(new QScxmlCppDataModelPrivate), parent)
98{}
99
100/*!
101 * Called during state machine initialization to set up a state machine using the initial values
102 * for data model variables specified by their keys, \a initialDataValues. These
103 * are the values specified by \c <param> tags in an \c <invoke> element.
104 *
105 * Returns \c true on success.
106 *
107 * \sa QScxmlStateMachine::init
108 */
109bool QScxmlCppDataModel::setup(const QVariantMap &initialDataValues)
110{
111 Q_UNUSED(initialDataValues);
112
113 return true;
114}
115
116/*!
117 \reimp
118
119 This method does not perform any action, ignores \a id, and sets \a ok to
120 \c false. Override it in your specific data model in order to implement
121 \c <assign>.
122 */
123void QScxmlCppDataModel::evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, bool *ok)
124{
125 Q_UNUSED(id);
126 *ok = false;
127}
128
129/*!
130 \reimp
131
132 This method does not perform any action, ignores \a id, and sets \a ok to
133 \c false. Override it in your specific data model in order to implement
134 \c <data>.
135 */
136void QScxmlCppDataModel::evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, bool *ok)
137{
138 Q_UNUSED(id);
139 *ok = false;
140}
141
142/*!
143 \reimp
144
145 This method does not perform any action, ignores \a id and \a body, and sets
146 \a ok to \c false. Override it in your specific data model in order to
147 implement \c <foreach>.
148 */
149void QScxmlCppDataModel::evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok,
150 ForeachLoopBody *body)
151{
152 Q_UNUSED(id);
153 Q_UNUSED(body);
154 *ok = false;
155}
156
157/*!
158 \reimp
159
160 Sets the \a event that will be processed next.
161
162 \sa QScxmlCppDataModel::scxmlEvent
163 */
164void QScxmlCppDataModel::setScxmlEvent(const QScxmlEvent &event)
165{
166 Q_D(QScxmlCppDataModel);
167 if (event.name().isEmpty())
168 return;
169
170 d->event = event;
171}
172
173/*!
174 * Holds the current event that is being processed by the
175 * state machine.
176 *
177 * See also \l {SCXML Specification - 5.10 System Variables} for the description
178 * of the \c _event variable.
179 *
180 * Returns the event currently being processed.
181 */
182const QScxmlEvent &QScxmlCppDataModel::scxmlEvent() const
183{
184 Q_D(const QScxmlCppDataModel);
185 return d->event;
186}
187
188/*!
189 \reimp
190
191 This method always returns an empty QVariant and ignores \a name.
192 Override it to implement the lookup of data model properties via the
193 \c location attribute of various elements.
194 */
195QVariant QScxmlCppDataModel::scxmlProperty(const QString &name) const
196{
197 Q_UNUSED(name);
198 return QVariant();
199}
200
201/*!
202 \reimp
203
204 This method always returns \c false and ignores \a name.
205 Override it to implement the lookup of data model properties via the
206 \c location attribute of various elements.
207 */
208bool QScxmlCppDataModel::hasScxmlProperty(const QString &name) const
209{
210 Q_UNUSED(name);
211 return false;
212}
213
214/*!
215 \reimp
216
217 This method always returns \c false and ignores \a name, \a value, and
218 \a context.
219 Override it to implement the lookup of data model properties via the
220 \c location attribute of various elements.
221 */
222bool QScxmlCppDataModel::setScxmlProperty(const QString &name, const QVariant &value,
223 const QString &context)
224{
225 Q_UNUSED(name);
226 Q_UNUSED(value);
227 Q_UNUSED(context);
228 return false;
229}
230
231/*!
232 Returns \c true if the state machine is in the state specified by
233 \a stateName, \c false otherwise.
234 */
235bool QScxmlCppDataModel::inState(const QString &stateName) const
236{
237 return stateMachine()->isActive(scxmlStateName: stateName);
238}
239
240QT_END_NAMESPACE
241

source code of qtscxml/src/scxml/qscxmlcppdatamodel.cpp