/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qtscxml-overview.html
    \title Qt SCXML Overview
    \brief Describes the Qt SCXML module.

    The Qt SCXML module provides classes for embedding state machines created
    from State Chart XML (SCXML) files in Qt applications. The SCXML files
    can be created using any suitable tool, such as a text editor or a
    simulator, as long as they comply to the \l {SCXML Specification}, with the
    restrictions and extensions described in \l{SCXML Compliance}.

    Parts of the application logic can be replaced with an encapsulated SCXML
    file. This enables creating a clear division between the application logic
    and the user interface implementation by using Qt Quick or Qt Widgets.

    The Qt SCXML module differs from the \l {The State Machine Framework}
    {State Machine framework} in the Qt Core module in that Qt SCXML provides a
    \e {conforming processor} that can parse and process \e {conforming SCXML
    documents}. In Qt SCXML, state machines are read from separate SCXML files
    and integrated to Qt applications by instantiating the QScxmlStateMachine
    class and loading an SCXML file dynamically or by using the Qt SCXML
    Compiler to generate a subclass of QScxmlStateMachine that is instantiated.
    The communication with the SCXML document is provided by the signals and
    methods of the QScxmlStateMachine class.

    The basic state machine concepts, \e state, \e transition, and \e event are
    based on those in the SCXML Specification. State charts provide a graphical
    way of modeling how a system reacts to stimuli. This is done by defining the
    possible states that the system can be in, and how the system can move from
    one state to another (transitions between states). A key characteristic of
    event-driven systems (such as Qt applications) is that behavior often
    depends not only on the last or current event, but also the events that
    preceded it. With state charts, this information is easy to express.

    Qt SCXML integrates tightly with Qt's meta-object system; for example,
    transitions between states can be triggered by signals, and states can be
    configured to set properties and invoke methods on \l{QObject}{QObjects}.
    Qt's event system is used to drive the state machines.

    The state graph in Qt SCXML is hierarchical. States can be nested inside
    other states, and the current configuration of the state machine consists of
    the set of states that are currently active.

    \section1 Data Models

    Qt SCXML supports the null data model, which must be supported by conforming
    SCXML processors, and the ECMAScript data model. In addition, Qt SCXML
    provices its own C++ data model that is implemented by the
    QScxmlCppDataModel class. The class 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
    will generate the dispatch methods.

    \section1 Qt SCXML Compiler

    The Qt SCXML Compiler, \c qscxmlc, reads an .scxml file and produces C++
    source and header files that contain a class that implements a state
    machine as defined in SCXML. For more information about using the compiler,
    see \l{Using the Qt SCXML Compiler (qscxmlc)}.

    Both the dynamically created and the compiled state machines behave in the
    same way, have the same properties, states, data model, and so on. They only
    differ in the way they are instantiated. For more information, see
    \l{Instantiating State Machines} and \l{Qt SCXML Examples}.

    \section1 Qt Mode

    State machines that are compatible with Qt can be compiled or loaded in the
    \e {Qt mode} to fully benefit from Qt. The Qt mode is unconditionally
    enabled by adding the following line to the beginning of the SCXML file:
    \c {<!-- enable-qt-mode: yes -->}. It is unconditionally disabled by the
    value \c no.

    The Qt mode should be disabled for random SCXML files that do not comply to
    the Qt rules. For example, for an SCXML file to be compatible with the Qt
    mode, all IDs and names must be valid Qt identifiers.

    In the Qt mode, external signals defined inside an SCXML file that are of
    the \c qt:signal type, are accessible as signals of QScxmlStateMachine. As
    an argument, they take QVariant. It is of QMap<QString, QVariant> type and
    contains the content of all the \c <param> elements specified as children of
    a \c <send> element. The name of each QScxmlStateMachine signal corresponds
    to the value defined in the \e event attribute of one \c <send> tag in the
    SCXML file.

    \section1 Logging Categories

    The Qt SCXML module exports the following logging categories:
    \table
    \header
        \li Logging Category
        \li Description
    \row
        \li qscxmlLog
        \li Enables Qt SCXML module log
    \row
        \li scxmlLog
        \li Enables log of SCXML documents
    \endtable
*/
