| /**************************************************************************** |
| ** |
| ** 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 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 |
| */ |