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

/*!
    \example widgets/trafficlight
    \meta tags {TaskTree}
    \examplecategory {Task Tree}
    \title TaskTree Traffic Light
    \ingroup tasktree_examples
    \brief Demonstrates how to implement state machine behavior using TaskTree
           through a traffic light simulation.

    The \e {TaskTree Traffic Light} is an alternative implementation
    for the Traffic Light examples in
    \l {SCXML Traffic Light (Static, Widgets)} {Qt SCXML} and
    \l {Traffic Light} {Qt State Machine}.

    \image tasktree-trafficlight-example.png "Traffic light simulation aplication."

    The application consists of three main components:

    \list
        \li A \c TrafficLight widget that displays the current state.
        \li A \c TaskTree recipe that controls state transitions.
        \li A \c GlueInterface that synchronizes the UI with the state machine.
    \endlist

    The following sections describe more details of the example's code.

    \section1 Helper Glue Class

    The \c GlueInterface class provides a clean separation between the UI and
    operational logic.

    \snippet widgets/trafficlight/glueinterface.h 0

    The \c GlueInterface class provides the following interface methods:
    \table
    \header
        \li Method
        \li Purpose
    \row
        \li \c setLights()
        \li Updates traffic light state from TaskTree recipe
    \row
        \li \c lightsChanged()
        \li Notifies UI when light states change
    \row
        \li \c smash()/ \c repair()
        \li Handles fault simulation and recovery actions
    \endtable

    When users interact with the UI:
    \list
        \li Clicking pause triggers \c smash(), simulating a fault.
        \li Clicking play triggers \c repair(), restoring normal operation.
    \endlist

    \section1 Implementing the state machine

    The state machine logic is implemented through a TaskTree recipe.
    The \c recipe() method creates this logic using a reference to \c GlueInterface:

    \snippet widgets/trafficlight/recipe.cpp 0

    \section2 Root state management

    The top level \l {QtTaskTree::}{Forever} item executes its
    children in an infinite loop. It contains two subgroups representing
    \e working and \e broken states.

    State transition rules:
    \list
        \li States execute in sequence, because the default
            \l {Execution Mode}{execution mode} is
            \l {QtTaskTree::}{sequential}.
        \li When one state completes, the other begins.
        \li Transitions are triggered when a user clicks the pause or play
            button in the UI, emitting the corresponding signal.
    \endlist

    \section2 The "working" operation state

    The \e working \l {QtTaskTree::}{Group} consists of two
    tasks running in \l {QtTaskTree::}{parallel}:

    \list
        \li The \l {QtTaskTree::}{signalAwaiterTask}
            connects to the \c GlueInterface::smashed signal. If the signal is
            triggered, the task immediately finishes with
            \l {QtTaskTree::}{DoneResult::Success}. This
            causes the \e working \l {QtTaskTree::}{Group} to stop
            executing, and the recipe transitions to the \e broken state.
        \li The nested \l {QtTaskTree::}{Forever} task consist of
            four \c switchLightsTask tasks ("red", "redGoingGreen", "green", and
            "greenGoingRed") executed \l {QtTaskTree::sequential}{sequentially}
            in an infinite loop.
    \endlist

    The \l {QtTaskTree::}{stopOnSuccess} item of each group
    instructs it to stop executing when any of its child tasks finishes with
    \l {QtTaskTree::}{DoneResult::Success}.

    The \c switchLightsTask implementation:

    \list 0
        \li Updates light states through \c GlueInterface::setLights().
        \li Creates a timed delay using \l {QtTaskTree::}{timeoutTask}.
        \li Maintains state for the specified duration \c timeout.
    \endlist

    \snippet widgets/trafficlight/recipe.cpp 1

    \section2 The "broken" operation state

    The \e broken \l {QtTaskTree::}{Group} is similar to the
    \e working \l {QtTaskTree::}{Group}. The only difference is that it
    connects to the \c GlueInterface::repaired signal, and the lights cycle only
    between 2 states toggling the \e yellow light on and off.

    \section1 Application setup

    The main application setup creates and connects all components:

    \snippet widgets/trafficlight/main.cpp 0

    The \c main() function instantiates QApplication, \c GlueInterface,
    QTaskTree and \c TrafficLight objects.

    To construct the \c taskTree object, we pass a \c recipe() constructed with
    the \c iface object. The \c widget also uses the passed \c iface object.

    Before executing the application, the \c main() function shows the
    \c TrafficLight widget and starts the task tree.

    \include examples-run.qdocinc
*/
