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

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

/*!
    \page creator-scxml.html
    \previouspage creator-reference-search-results-view.html
    \nextpage creator-how-to-create-state-charts.html

    \title Editing SCXML state charts

    State charts are a graphical way of modeling how a system reacts to
    stimuli. They define the \e states that the system can
    be in, and how the system can move from one state to another (\e transitions
    between states). The behavior of event-driven systems (such as Qt
    applications) often depends not only on the last or current
    \e event, but also on earlier events. With state charts, you
    can easily share this information.

    With the \QC file wizard, you can add \l{State Chart XML (SCXML)}
    files with boilerplate code to projects. Edit
    the state charts with the SCXML editor to add states and transitions
    to the files. Then, use the classes in the Qt SCXML module to embed the
    state machines created from the files in Qt applications.

    When you open an .scxml file, it opens in the SCXML editor:

    \image {qtcreator-scxml-editor.webp} {SCXML editor}

    Drag 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}.

    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).

    \section1 Navigating state charts

    Use the toolbar buttons to execute functions such as editing,
    zooming, magnifying, navigating, and panning state charts, as well as
    taking screenshots and viewing statistics.

    \table
    \header
        \li Button
        \li Name
        \li Description
    \row
        \li \imagecamera
        \li \uicontrol {Save Screenshot}
        \li Saves the currently visible part of the state chart as an image.
    \row
        \li \inlineimage {icons/icon-export-canvas.png} {Export Canvas to Image}
        \li \uicontrol {Export Canvas to Image}
        \li Saves the whole state chart as an image.
    \row
        \li \imagezoomin

            \imagezoomout
        \li \uicontrol {Zoom In}

            \uicontrol {Zoom Out}
        \li Zooms into or out of the whole state chart in the state editor.

            You can also select \key Ctrl and use the mouse wheel.
    \row
        \li \inlineimage {icons/pan.png} {Panning}
        \li \uicontrol Panning
        \li Pans the state chart. To increase the pace of panning, select
            \key {Shift}.
    \row
        \li \inlineimage {icons/fittoview.png} {Fit to View}
        \li \uicontrol {Fit to View}
        \li Makes the whole state chart visible in the state editor at a time.
    \row
        \li \inlineimage {icons/zoom.png} {Magnifier Tool}
        \li \uicontrol {Magnifier Tool}
        \li Zooms into a part of the state chart. To move the magnifier tool
            faster, select and hold \key {Alt}.
    \row
        \li \inlineimage {icons/navigator.png} {Navigator}
        \li \uicontrol {Navigator}
        \li Shows a particular part of a large state chart in the state editor.
            Move the navigator frame on the part you want to view.
    \row
        \li \inlineimage {icons/statistics.png} {View Statistics}
        \li \uicontrol {View Statistics}
        \li Shows statistics about the numbers of states and transitions in the
            state chart.
    \endtable

    To search in the state chart, select \uicontrol {Search} and start typing
    in the \uicontrol Filter field. The search checks the whole SCXML tree for
    attributes that match the search criteria.

    \section1 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 you can nest states inside
    other states to create compound states.

    You can create the following types of states:

    \table
    \header
        \li Button
        \li Name
        \li Description
    \row
        \li \inlineimage {icons/recordfill.png} {Initial state}
        \li \uicontrol Initial
        \li The state that the state machine enters when it starts.
    \row
        \li \inlineimage {icons/state.png} {Basic state}
        \li \uicontrol State
        \li The basic state.
    \row
        \li \inlineimage {icons/parallel.png} {Parallel states}
        \li \uicontrol Parallel
        \li Has child states that execute in parallel and are all active
            simultaneously. Each child state processes events independently,
            and the events may trigger different transitions for each child.
    \row
        \li \inlineimage {icons/final.png} {Final state}
        \li \uicontrol Final
        \li Lets a state machine 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.
    \row
        \li \inlineimage {icons/history.png} {History}
        \li \uicontrol History
        \li 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.

    \endtable

    To create transitions between states, select
    \inlineimage {icons/transition.png} {Transition}.

    \section1 Adding states

    You can add new states to the state chart in the following ways:

    \list

        \li Drag 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

    Drag states on top of other states to create compound states. You can also
    drag child states out of their parent state. To move child states
    within their parent, select and hold \key Ctrl while dragging them.

    \section1 Aligning and editing states

    Use the toolbar buttons to align states in the state editor, to adjust
    their size, color, and fonts, and to change the default color scheme.

    \image {qtcreator-scxml-editor-state-toolbar.webp} {Buttons for editing states}

    Overlapping states are marked in red color.

    \section1 Viewing state tree structure

    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 {icons/namespace.png} {Toggle Full Namespace}
    (\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:

    \code [xml]
    <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 either the state
    machine or external entities generate. When events occur, the state
    machine checks for a matching transition 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.

    The editor center-aligns transition labels, but you can drag them to
    other positions.

    Conditions on transitions appear below the transition lines within square
    brackets ([]).

    To add edge points to transitions, select a transition line. You can add
    only two edge points for each line. The editor automatically removes
    unnecessary edge points. To remove the selected edge point, select
    \uicontrol {Remove Point} in the context menu.

    To add new edge points with a mouse click, select
    \inlineimage {icons/transition.png} {Transition}.

    To remove the selected transition, select \uicontrol Remove in the context
    menu.

    \section1 Adding executable content

    Add \e {executable content} to a state chart to enable the state
    machine to change 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 change 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.

    \sa {Create state charts}
*/

/*!
    \page creator-how-to-create-state-charts.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-scxml

    \title Create state charts

    You can use \QC to create applications that embed state machines. A file
    wizard creates \l{State Chart XML (SCXML)}
    files with boilerplate code that you can edit using an SCXML editor. You can
    use the classes in the \l {Qt SCXML} module to embed state machines created
    from the files in Qt applications.

    \image {qtcreator-scxml-editor.webp} {SCXML editor}

    To create a state chart:

    \list 1

        \li Select \uicontrol File > \uicontrol {New File} >
            \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 a state from the \uicontrol {Common States} view (1) to
            the state editor (2).

        \li Drag child states to the initial state to create a
            \e {compound state} or use the tool buttons (3) to create a transition
            from the selected state and its target state.

        \li Select a state in the editor or in the \uicontrol Structure view (5)
            to edit its attributes in the \uicontrol Attributes
            view (6).

        \li Select the transition line (4) 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

    \sa {Editing SCXML state charts}
*/
