Doc: Add docs for SCXML Editor

Change-Id: I563a2a06b101e3954c3365baba4a596ef29517ab
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>

7 files changed, 312 insertions, 2 deletions

diff --git a/doc/config/qtcreator-project.qdocconf b/doc/config/qtcreator-project.qdocconf
index 9eb4f83521..947a500950 100644
--- a/doc/config/qtcreator-project.qdocconf
+++ b/doc/config/qtcreator-project.qdocconf
@@ -18,6 +18,7 @@ imagedirs = $SRCDIR/images \
             $SRCDIR/../src/plugins/projectexplorer/images \
             $SRCDIR/../src/plugins/qmldesigner/components/formeditor \
             $SRCDIR/../src/plugins/qmldesigner/components/navigator \
+            $SRCDIR/../src/plugins/scxmleditor/common/images \
             $SRCDIR/../src/plugins/texteditor/images
 
 outputdir = $OUTDIR
diff --git a/doc/images/qtcreator-scxml-editor.png b/doc/images/qtcreator-scxml-editor.png
new file mode 100644
index 0000000000..2598cfead8
--- /dev/null
+++ b/doc/images/qtcreator-scxml-editor.png
diff --git a/doc/src/editors/creator-coding.qdoc b/doc/src/editors/creator-coding.qdoc
index 4d518aa78e..73ca7751ce 100644
--- a/doc/src/editors/creator-coding.qdoc
+++ b/doc/src/editors/creator-coding.qdoc
@@ -92,6 +92,15 @@
             Modeling Language (UML) style models with structured diagrams and
             store them in XML format.
 
+       \li \l{Editing State Charts}
+
+            You can use \QC to create applications that embed state machines. A
+            project wizard creates \l{https://www.w3.org/TR/scxml/}
+            {State Chart XML (SCXML)} files with boilerplate code that you can
+            edit using an experimental SCXML editor. You can use the classes in
+            the Qt SCXML module to embed state machines created from the files
+            in Qt applications.
+
     \endlist
 
 */
diff --git a/doc/src/editors/creator-modeling.qdoc b/doc/src/editors/creator-modeling.qdoc
index 6ae6696afa..fedb7d703a 100644
--- a/doc/src/editors/creator-modeling.qdoc
+++ b/doc/src/editors/creator-modeling.qdoc
@@ -33,7 +33,7 @@
     \contentspage {Qt Creator Manual}
     \previouspage creator-mime-types.html
     \page creator-modeling.html
-    \nextpage creator-building-running.html
+    \nextpage creator-scxml.html
 
     \title Modeling
 
diff --git a/doc/src/editors/creator-scxml.qdoc b/doc/src/editors/creator-scxml.qdoc
new file mode 100644
index 0000000000..384f8c0aba
--- /dev/null
+++ b/doc/src/editors/creator-scxml.qdoc
@@ -0,0 +1,297 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Creator documentation.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or (at your option) the GNU General
+** Public license version 3 or any later version approved by the KDE Free
+** Qt Foundation. The licenses are as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-2.0.html and
+** https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+// **********************************************************************
+// NOTE: the sections are not ordered by their logical order to avoid
+// reshuffling the file each time the index order changes (i.e., often).
+// Run the fixnavi.pl script to adjust the links to the index order.
+// **********************************************************************
+
+/*!
+    \contentspage {Qt Creator Manual}
+    \previouspage creator-modeling.html
+    \page creator-scxml.html
+    \nextpage creator-building-running.html
+
+    \title Editing State Charts
+
+    State charts provide a graphical way of modeling how a system reacts to
+    stimuli. This is done by defining the possible \e states that the system can
+    be in, and how the system can move from one state to another (\e 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
+    \e event, but also the events that preceded it. With state charts, this
+    information is easy to express.
+
+    \QC provides a project wizard for adding \l{https://www.w3.org/TR/scxml/}
+    {State Chart XML (SCXML)} files with boilerplate code to projects and an
+    experimental SCXML editor for editing the state charts. You can use the
+    SCXML editor to add \e states and \e transitions to the files. You can then
+    use the classes in the Qt SCXML module to embed the state machines created
+    from the files in Qt applications.
+
+    \image qtcreator-scxml-editor.png SXCML Editor
+
+    You can drag and drop states from the \uicontrol {Common States} view (1) to
+    the state editor (2). Select a state in the state editor and use the tool
+    buttons (3) to create a transition (4) and its \e {target state}.
+
+    You can view the state chart structure in the \uicontrol Structure view (5)
+    and specify attributes for the selected state or transition in the
+    \uicontrol Attributes view (6).
+
+    You can use the toolbar buttons (7) to execute functions such as editing,
+    zooming, magnifying, navigating, and panning state charts, as well as
+    taking screenshots and viewing statistics.
+
+    To zoom into and out of the whole state chart in the state editor, select
+    \inlineimage icon-zoom-in.png
+    (\uicontrol {Zoom In}) or \inlineimage icon-zoom-out.png
+    (\uicontrol {Zoom Out}) or press \key Ctrl and use the mouse wheel. To make
+    the whole state chart visible in the state editor at a time, select
+    \inlineimage icon-fit-screen.png
+    (\uicontrol {Fit to View}).
+
+    To view a particular part of a large state chart in the state editor, select
+    \inlineimage navigator.png
+    (\uicontrol {Navigator}) and move the navigator frame on the part you want
+    to view.
+
+    To use the magnifier to zoom into a part of the state chart, select
+    \inlineimage zoom.png
+    (\uicontrol Magnifier). To move the magnifier faster, press down the
+    \key Alt key.
+
+    To pan the state chart, select \inlineimage icon-pan.png
+    (\uicontrol Panning). To increase the pace of panning, press down the
+    \key Shift key.
+
+    To view statistics about the numbers of states and transitions in the state
+    chart, select \inlineimage statistics.png
+    (\uicontrol {View Statistics}).
+
+    To search from the state chart, use the \uicontrol Search pane. The search
+    checks the whole SCXML tree for attributes that match the search criteria.
+
+    To save the currently visible part of the state chart as an image, select
+    \inlineimage screenshot.png
+    (\uicontrol {Save Screenshot}). To save the whole state chart as an image,
+    select \inlineimage icon-export-canvas.png
+    (\uicontrol {Export Canvas to Image}).
+
+    \section1 Creating State Charts
+
+    To create a state chart:
+
+    \list 1
+
+        \li Select \uicontrol Help > \uicontrol {About Plugins} >
+            \uicontrol Modeling > \uicontrol ScxmlEditor and restart \QC to
+            enable the plugin.
+
+        \li Select \uicontrol File > \uicontrol {New File or Project} >
+            \uicontrol {Files and Classes} > \uicontrol Modeling >
+            \uicontrol {State Chart} > \uicontrol Choose to create an empty
+            state chart and to open it in the SCXML editor.
+
+        \li Drag and drop a state from the \uicontrol {Common States} view to
+            the state editor.
+
+        \li Drag and drop child states to the initial state to create a
+            \e {compound state} or use the tool buttons to create a transition
+            from the selected state and its target state.
+
+        \li Select a state to edit its attributes in the \uicontrol Attributes
+            view.
+
+        \li Select the transition line to add edge points to it.
+
+        \li To raise or send events, for example, use the context menu commands
+            to add executable content to the \c <onentry> and \c <onexit>
+            elements of states or to transitions.
+
+    \endlist
+
+    The following sections describe how to manage states, transitions, and
+    executable content.
+
+    \section1 Managing States
+
+    When the state machine enters a state in response to an event, the state
+    that it entered becomes the \e {active state}.
+
+    State charts are hierarchical, and therefore states can be nested inside
+    other states, to create compound states.
+
+    In addition to basic states, you can create the following types of states:
+
+    \list
+
+        \li \e Initial state is the state the state machine enters when it
+            starts.
+
+        \li \e {Parallel state} contains child states that execute in parallel
+            and are all active simultaneously. Events are processed
+            independently by each child state and may trigger different
+            transitions for each child.
+
+        \li \e {Final state} enables a state machine to finish. When the state
+            machine enters a top-level final state, it emits the finished signal
+            and halts. You can create final states in compound states to hide
+            the internal details of a compound state. The outside world can only
+            enter the state and get a notification when the state has finished.
+            A parallel state finishes when all its child states reach final
+            states.
+
+        \li \e {History state} is a pseudo-state that represents the child state
+            the parent state was in the last time the parent state was exited.
+
+            Create a history state as a child of the state for which you want to
+            record the current child state. When the state machine detects the
+            presence of such a state at runtime, it automatically records the
+            current (real) child state when the parent state is exited. A
+            transition to the history state is in fact a transition to the child
+            state that the state machine previously saved. The state machine
+            automatically forwards the transition to the real child state.
+
+    \endlist
+
+    You can add new states to the state chart in the following ways:
+
+    \list
+
+        \li Drag and drop states from the \uicontrol {Common States} view to the
+            state editor.
+
+        \li Select a state in the state editor, and then select the
+            \uicontrol State tool button to create a transition and its target
+            state.
+
+        \li Copy and paste states within the SCXML editor or between the SCXML
+            editor and the \uicontrol Edit mode.
+
+    \endlist
+
+    You can drag states on top of other states to create compound states, or
+    you can drag child states out of their parent state. To move child states
+    within their parent, press down the \key Ctrl key while moving them.
+
+    You can use toolbar buttons to align states in the state editor, to adjust
+    their size, and to change the default color scheme. Overlapping states are
+    marked in red color.
+
+    To expand or collapse the state tree structure in the \uicontrol Structure
+    view, double-click a state.
+
+    To view a child state of a nested state in more detail in the state editor,
+    select \uicontrol {Zoom to State}.
+
+    To ensure that the state ids are unique within a compound state machine,
+    select \inlineimage fullnamespace.png
+    (\uicontrol {Toggle Full Namespace}). The name of the parent state is
+    added to the names of the child states, separated by two colons (::).
+    For example:
+
+    \badcode
+    <state id="broken">
+    ...
+        <state id="broken::blinking">
+        ...
+        </state>
+        <state id="broken::unblinking">
+        ...
+        </state>
+    </state>
+    \endcode
+
+    \section1 Managing Transitions
+
+    Transitions define how a state reacts to \e events that are generated either
+    by the state machine or external entities. When events occur, the state
+    machine checks for a matching transition defined in the active state and
+    moves to its target state.
+
+    To create a transition from the selected state to a new state, drag and
+    release the mouse at the location where you want to add the target state.
+    When you draw a transition to the center of another state, it points to the
+    center of the state, but you can also draw a transition to the edge of the
+    state.
+
+    To add edge points to transitions, select a transition line. Only two edge
+    points are permitted for each line, and unnecessary edge points are removed
+    automatically. To remove the selected edge point, select
+    \uicontrol {Remove Point} in the context menu.
+
+    To add new edge points with a mouse click, select the \uicontrol Transition
+    tool button.
+
+    A transition label is automatically center-aligned, but you can drag it to
+    another position.
+
+    To remove the selected transition, select \uicontrol Remove in the context
+    menu.
+
+    \section1 Adding Executable Content
+
+    You can add \e {executable content} to a state chart to enable the state
+    machine to modify its data model and to interact with external entities.
+
+    Use the context menu commands to add executable content to the \c <onentry>
+    and \c <onexit> elements or to transitions:
+
+    \list
+        \li \c <raise> to raise events
+        \li \c <send> to communicate with external entities
+        \li \c <script> to run scripts
+        \li \c <assign> to modify the data model
+        \li \c <cancel> to cancel action execution
+        \li \c <log> to record information in a log
+        \li \c <if> to execute actions conditionally
+        \li \c <foreach> to iterate over the items in a collection and execute
+            an action for each of them
+    \endlist
+
+    During a transition, the state machine executes the content that you specify
+    for the \c <onexit> element in the state it is leaving, then the content in
+    the transition, and then the content for the \c <onentry> element in the
+    state it is entering.
+
+    You can add attributes for the selected executable content in the
+    \uicontrol Attributes view.
+*/
diff --git a/doc/src/projects/creator-projects-building-running.qdoc b/doc/src/projects/creator-projects-building-running.qdoc
index a8abe97ef9..955d6d96f9 100644
--- a/doc/src/projects/creator-projects-building-running.qdoc
+++ b/doc/src/projects/creator-projects-building-running.qdoc
@@ -31,7 +31,7 @@
 
 /*!
     \contentspage {Qt Creator Manual}
-    \previouspage creator-modeling.html
+    \previouspage creator-scxml.html
     \page creator-building-running.html
     \nextpage creator-building-targets.html
 
diff --git a/doc/src/qtcreator.qdoc b/doc/src/qtcreator.qdoc
index 5cd8d5175a..1f22d1d0dd 100644
--- a/doc/src/qtcreator.qdoc
+++ b/doc/src/qtcreator.qdoc
@@ -84,6 +84,7 @@
                     \li \l{Refactoring}
                     \li \l{Configuring the Editor}
                     \li \l{Modeling}
+                    \li \l{Editing State Charts}
                 \endlist
         \row
             \li \inlineimage creator_buildingrunning.png
@@ -227,6 +228,8 @@
             \endlist
             \li \l{Editing MIME Types}
             \li \l{Modeling}
+            \li \l{Editing State Charts}
+
         \endlist
         \li \l{Building and Running}
         \list