Doc: Add information to the Overview

Change-Id: Icd445aa69747603a38397f6399208859df765aee
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>

1 files changed, 78 insertions, 2 deletions

diff --git a/src/scxml/doc/qtscxml-overview.qdoc b/src/scxml/doc/qtscxml-overview.qdoc
index 9b30775..8b38e39 100644
--- a/src/scxml/doc/qtscxml-overview.qdoc
+++ b/src/scxml/doc/qtscxml-overview.qdoc
@@ -28,11 +28,87 @@
 /*!
     \page qtscxml-overview.html
     \title Qt SCXML Overview
-    \brief Describes the Qt SCXML module architecture.
+    \brief Describes the Qt SCXML module.
 
-    \section1 Qt SCXML Architecture
+    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