Doc: Add docs for Mediaplayer example versions

- Add screenshot
- Use include files for info common to several app versions
- Add examples directory to sourcedirs in the .qdocconf file to
  be able to put the include files to the mediaplayer-common
  folder

Change-Id: I411d74d51d17b9ed5d906e23ede3b64e3b6b2dac
Reviewed-by: Ulf Hermann <ulf.hermann@theqtcompany.com>

9 files changed, 200 insertions, 10 deletions

diff --git a/examples/scxml/mediaplayer-common/doc/images/mediaplayer.png b/examples/scxml/mediaplayer-common/doc/images/mediaplayer.png
new file mode 100644
index 0000000..9c32b78
--- /dev/null
+++ b/examples/scxml/mediaplayer-common/doc/images/mediaplayer.png
diff --git a/examples/scxml/mediaplayer-common/doc/src/mediaplayer-compiling.qdocinc b/examples/scxml/mediaplayer-common/doc/src/mediaplayer-compiling.qdocinc
new file mode 100644
index 0000000..d4eb6ee
--- /dev/null
+++ b/examples/scxml/mediaplayer-common/doc/src/mediaplayer-compiling.qdocinc
@@ -0,0 +1,20 @@
+    \section1 Compiling the State Machine
+
+    We link against the Qt SCXML module by adding the following line to the
+    \e .pro file:
+
+    \quotefromfile mediaplayer-widgets-static/mediaplayer-widgets-static.pro
+    \skipto QT
+    \printline scxml
+
+    We then specify the state machine to compile:
+
+    \skipto STATECHARTS
+    \printline scxml
+
+    We also tell qmake to run \c qscxmlc, which generates \e mediaplayer.h and
+    \e mediaplayer.cpp, and adds them to the \c HEADERS and \c SOURCES
+    variables for compilation:
+
+    \skipto load
+    \printline qscxmlc
diff --git a/examples/scxml/mediaplayer-common/doc/src/mediaplayer-dynamic.qdocinc b/examples/scxml/mediaplayer-common/doc/src/mediaplayer-dynamic.qdocinc
new file mode 100644
index 0000000..e9ae43b
--- /dev/null
+++ b/examples/scxml/mediaplayer-common/doc/src/mediaplayer-dynamic.qdocinc
@@ -0,0 +1,15 @@
+    \section1 Dynamically Loading the State Machine
+
+    We link against the Qt SCXML module by adding the following line to the
+    example \e .pro file:
+
+    \quotefromfile mediaplayer-qml-dynamic/mediaplayer-qml-dynamic.pro
+    \skipto QT
+    \printline scxml
+
+    We dynamically create the state machine in
+    \e mediaplayer-common\Mediaplayer.qml:
+
+    \quotefromfile mediaplayer-common/Mediaplayer.qml
+    \skipto import Scxml
+    \printuntil scxmlLoader.filename
diff --git a/examples/scxml/mediaplayer-common/doc/src/mediaplayer-ecmascript-data-model.qdocinc b/examples/scxml/mediaplayer-common/doc/src/mediaplayer-ecmascript-data-model.qdocinc
new file mode 100644
index 0000000..31218ef
--- /dev/null
+++ b/examples/scxml/mediaplayer-common/doc/src/mediaplayer-ecmascript-data-model.qdocinc
@@ -0,0 +1,9 @@
+    \section1 Using the ECMAScript Data Model
+
+    We specify the data model as a value of the \e datamodel attribute of the
+    \c <scxml> element in \e mediaplayer-common/mediaplayer.scxml:
+
+    \quotefromfile mediaplayer-common/mediaplayer.scxml
+    \skipto enable-qt-mode
+    \printuntil </datamodel>
+
diff --git a/examples/scxml/mediaplayer-qml-cppdatamodel/doc/src/mediaplayer-qml-cppdatamodel.qdoc b/examples/scxml/mediaplayer-qml-cppdatamodel/doc/src/mediaplayer-qml-cppdatamodel.qdoc
index d1b2eaa..9cf1603 100644
--- a/examples/scxml/mediaplayer-qml-cppdatamodel/doc/src/mediaplayer-qml-cppdatamodel.qdoc
+++ b/examples/scxml/mediaplayer-qml-cppdatamodel/doc/src/mediaplayer-qml-cppdatamodel.qdoc
@@ -27,8 +27,74 @@
 
 /*!
     \example mediaplayer-qml-cppdatamodel
-    \title Qt SCXML: Media Player QML Example (C++ Data Model)
+    \title Qt SCXML Media Player QML Example (C++ Data Model)
     \ingroup examples-qtscxml
 
-    \brief Demonstrates how to send/receive data to/from a C++ data-model.
+    \image mediaplayer.png
+
+    \brief Sends data to and receives it from a C++ data model.
+
+    \e {Media Player QML Example (C++ Data Model)} demonstrates how to access
+    data from a C++ data model. The data model enables writing 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) generates the dispatch methods.
+
+    The UI is created using Qt Quick.
+
+    \include examples-run.qdocinc
+
+    \section1 Using the C++ Data Model
+
+    We specify the data model as a value of the \e datamodel attribute of the
+    \c <scxml> element in the SCXML file:
+
+    \quotefromfile mediaplayer-qml-cppdatamodel/mediaplayer-cppdatamodel.scxml
+    \skipto enable-qt-mode
+    \printuntil datamodel
+
+    The format of the \e datamodel attribute is:
+    \c {cplusplus:<class-name>:<classdef-header>}. Therefore, we need a file
+    called \e thedatamodel.h that contains a subclass of QScxmlCppDataModel:
+
+    \quotefromfile mediaplayer-qml-cppdatamodel/thedatamodel.h
+    \skipto qscxmlcppdatamodel.h
+    \printuntil Q_SCXML_DATAMODEL
+
+    We place the \c Q_SCXML_DATAMODEL macro in the private section of the
+    definition, right after the opening bracket. The macro expands to the
+    declaration of virtual methods, the implementation of which is generated by
+    the Qt SCXML compiler.
+
+    In the SCXML file, we specify C++ statements in the \c <script> element and
+    use the \e expr attribute to access the data model:
+
+    \quotefromfile mediaplayer-qml-cppdatamodel/mediaplayer-cppdatamodel.scxml
+    \skipto state
+    \printuntil </state>
+    \printuntil </state>
+
+    The Qt SCXML compiler generates the various \c evaluateTo methods and
+    converts the expressions and scripts into lambdas inside those methods in
+    \e mediaplayer-cppdatamodel.cpp:
+
+    \code
+    bool TheDataModel::evaluateToBool(QScxmlExecutableContent::EvaluatorId id, bool *ok) {
+    ....
+        return [this]()->bool{ return isValidMedia(); }();
+    ....
+    }
+
+    QVariant TheDataModel::evaluateToVariant(QScxmlExecutableContent::EvaluatorId id, bool *ok) {
+    ....
+            return [this]()->QVariant{ return media; }();
+    ....
+    }
+
+    void TheDataModel::evaluateToVoid(QScxmlExecutableContent::EvaluatorId id, bool *ok) {
+    ....
+            [this]()->void{ media = eventData().value(QStringLiteral("media")).toString(); }();
+    ....
+    }
+    \endcode
 */
diff --git a/examples/scxml/mediaplayer-qml-dynamic/doc/src/mediaplayer-qml-dynamic.qdoc b/examples/scxml/mediaplayer-qml-dynamic/doc/src/mediaplayer-qml-dynamic.qdoc
index 7bdc6e3..525974a 100644
--- a/examples/scxml/mediaplayer-qml-dynamic/doc/src/mediaplayer-qml-dynamic.qdoc
+++ b/examples/scxml/mediaplayer-qml-dynamic/doc/src/mediaplayer-qml-dynamic.qdoc
@@ -27,8 +27,22 @@
 
 /*!
     \example mediaplayer-qml-dynamic
-    \title Qt SCXML: Media Player QML Example (Dynamic)
+    \title Qt SCXML Media Player QML Example (Dynamic)
     \ingroup examples-qtscxml
 
-    \brief Demonstrates how to send/receive data to/from EcmaScript data-model.
+    \brief A Qt Quick application that sends data to and receives it from a
+    dynamically loaded ECMAScript data model.
+
+    \image mediaplayer.png
+
+    \e {Media Player QML Example (Dynamic)} demonstrates how to access data from
+    a dynamically loaded ECMAScript data model.
+
+    The UI is created using Qt Quick.
+
+    \include examples-run.qdocinc
+
+    \include mediaplayer-ecmascript-data-model.qdocinc
+
+    \include mediaplayer-dynamic.qdocinc
 */
diff --git a/examples/scxml/mediaplayer-qml-static/doc/src/mediaplayer-qml-static.qdoc b/examples/scxml/mediaplayer-qml-static/doc/src/mediaplayer-qml-static.qdoc
index 427a100..4232ff1 100644
--- a/examples/scxml/mediaplayer-qml-static/doc/src/mediaplayer-qml-static.qdoc
+++ b/examples/scxml/mediaplayer-qml-static/doc/src/mediaplayer-qml-static.qdoc
@@ -27,8 +27,31 @@
 
 /*!
     \example mediaplayer-qml-static
-    \title Qt SCXML: Media Player QML Example (Static)
+    \title Qt SCXML Media Player QML Example (Static)
     \ingroup examples-qtscxml
 
-    \brief Demonstrates how to send/receive data to/from EcmaScript data-model.
+    \brief A Qt Quick application that sends data to and receives it from a
+    compiled ECMAScript data model.
+
+    \image mediaplayer.png
+
+    \e {Media Player QML Example (Static)} demonstrates how to access data from
+    an ECMAScript data model that is compiled into a C++ class.
+
+    The UI is created using Qt Quick.
+
+    \include examples-run.qdocinc
+
+    \include mediaplayer-ecmascript-data-model.qdocinc
+
+    \include mediaplayer-compiling.qdocinc
+
+    \section1 Instantiating the State Machine
+
+    We instantiate the generated \c MediaPlayerStateMachine class in
+    \e mediaplayer-qml-static.cpp:
+
+    \quotefromfile mediaplayer-qml-static/mediaplayer-qml-static.cpp
+    \skipto mediaplayer.h
+    \printuntil }
 */
diff --git a/examples/scxml/mediaplayer-widgets-dynamic/doc/src/mediaplayer-widgets-dynamic.qdoc b/examples/scxml/mediaplayer-widgets-dynamic/doc/src/mediaplayer-widgets-dynamic.qdoc
index 6ef43ea..6cc41df 100644
--- a/examples/scxml/mediaplayer-widgets-dynamic/doc/src/mediaplayer-widgets-dynamic.qdoc
+++ b/examples/scxml/mediaplayer-widgets-dynamic/doc/src/mediaplayer-widgets-dynamic.qdoc
@@ -27,8 +27,22 @@
 
 /*!
     \example mediaplayer-widgets-dynamic
-    \title Qt SCXML: Media Player Example (Dynamic)
+    \title Qt SCXML Media Player Example (Dynamic)
     \ingroup examples-qtscxml
 
-    \brief Demonstrates how to send/receive data to/from EcmaScript data-model.
+    \brief A widget-based application that sends data to and receives it from a
+    dynamically loaded ECMAScript data model.
+
+    \image mediaplayer.png
+
+    \e {Media Player Example (Dynamic)} demonstrates how to access data from a
+    dynamically loaded ECMAScript data model.
+
+    The UI is created using Qt Widgets.
+
+    \include examples-run.qdocinc
+
+    \include mediaplayer-ecmascript-data-model.qdocinc
+
+    \include mediaplayer-dynamic.qdocinc
 */
diff --git a/examples/scxml/mediaplayer-widgets-static/doc/src/mediaplayer-widgets-static.qdoc b/examples/scxml/mediaplayer-widgets-static/doc/src/mediaplayer-widgets-static.qdoc
index f06db24..562a7af 100644
--- a/examples/scxml/mediaplayer-widgets-static/doc/src/mediaplayer-widgets-static.qdoc
+++ b/examples/scxml/mediaplayer-widgets-static/doc/src/mediaplayer-widgets-static.qdoc
@@ -27,8 +27,37 @@
 
 /*!
     \example mediaplayer-widgets-static
-    \title Qt SCXML: Media Player Example (Static)
+    \title Qt SCXML Media Player Example (Static)
     \ingroup examples-qtscxml
 
-    \brief Demonstrates how to send/receive data to/from EcmaScript data-model.
+    \brief A widget-based application that sends data to and receives it from a
+    compiled ECMAScript data model.
+
+    \image mediaplayer.png
+
+    \e {Media Player Example (Static)} demonstrates how to access data from an
+     ECMAScript data model that is compiled into a C++ class.
+
+    The UI is created using Qt Widgets.
+
+    \include examples-run.qdocinc
+
+    \include mediaplayer-ecmascript-data-model.qdocinc
+
+    \include mediaplayer-compiling.qdocinc
+
+    \section1 Instantiating the State Machine
+
+    We instantiate the generated \c MediaPlayerStateMachine class in
+    \e {mediaplayer-widgets-static.cpp}:
+
+    \quotefromfile mediaplayer-widgets-static/mediaplayer-widgets-static.cpp
+    \skipto mediaplayer.h
+    \printuntil machine.init
+
+    To be notified when a state machine sends out an event, we connect to the
+    corresponding signals. The media player state machine will send out events
+    when users tap a control and when playback starts or stops:
+
+    \printuntil MainWindow::stopped
 */