// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \example mediaplayer
    \title SCXML Media Player
    \examplecategory {Data Processing & I/O}
    \ingroup examples-qtscxml
    \meta tag {state machine}

    \image mediaplayer.png

    \brief Sends data to and receives it from a C++ data model.

    \e {Media Player} 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/mediaplayer.scxml
    \skipto scxml
    \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/thedatamodel.h
    \skipto qscxmlcppdatamodel.h
    \printuntil Q_SCXML_DATAMODEL

    QScxmlCppDataModel derives from QObject, so we add the \c Q_OBJECT macro in
    the private section of the definition, right after the opening bracket. We
    then place the \c Q_SCXML_DATAMODEL macro after \c Q_OBJECT. 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/mediaplayer.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.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
*/