Revision control

- // Copyright (C) 2025 The Qt Company Ltd.
- // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
-
- /*!
- \example widgets/demo
- \meta tags {widgets}
- \examplecategory {Task Tree}
- \title TaskTree Demo
- \ingroup tasktree_examples
- \brief Demonstrates how different execution modes and workflow policies
- affect the complex TaskTree execution.
-
- The \e {TaskTree Demo} shows how to construct a nested TaskTree
- recipe using \l {QtTaskTree::} {timeoutTask}, and demonstrates
- different \l {Execution Mode} {execution modes} and
- \l {Workflow Policy} {workflow policies}.
- Its application provides a graphical overview of progress as the
- TaskTree executes the various work items making up the task.
-
- \image tasktree-demo-example.png
- {Nested task groups with color-coded states showing progress at 78 percent}
-
- The demo application uses a single QWidget to display and manage a TaskTree
- hierarchy. Here's what you'll find in the interface:
-
- \list
- \li \b Tasks appear as leaf nodes on the right side of the tree.
-
- For each task, you can set the execution duration and configure
- success or error completion states.
- \li \b {Group nodes} appear on the left and middle of the tree.
-
- Each group can contain multiple child tasks or nested groups. You
- can configure \l {Execution Mode} {execution modes} and
- \l {Workflow Policy} {workflow policies} for each group.
- \li \b {Color indicators} show the current execution state of each node.
- \endlist
-
- The following sections describe more details of the example's code.
-
- \section1 Helper Glue Classes
-
- The \c GlueItem abstract class connects the user interface (UI) components
- with their corresponding TaskTree recipes. This design pattern enables clean
- separation between the UI and task logic.
-
- \snippet widgets/demo/main.cpp 0
-
- The \c GlueItem class defines three key virtual methods:
- \table
- \header
- \li Method
- \li Purpose
- \row
- \li \c recipe()
- \li Creates and returns a TaskTree recipe that defines the item's behavior
- \row
- \li \c widget()
- \li Provides access to the associated UI component
- \row
- \li \c reset()
- \li Restores the UI component to its initial state
- \endtable
-
- The \c GroupGlueItem class manages \l{QtTaskTree::} {Group} elements in
- your task hierarchy. Each group can hold other \c GlueItem elements as
- children, including nested \c {GroupGlueItem}s or \c {TaskGlueItem}s.
-
- Here's how the \c {recipe()} method creates and configures a group:
-
- \snippet widgets/demo/main.cpp 1
-
- Key components of the implementation:
- \list
- \li Creates a new \l {QtTaskTree::} {Group} with child recipes
- \li Applies \l {Execution Mode} {execution mode}
- and \l {Workflow Policy} {workflow policy} from UI settings
- \li Uses \l {QtTaskTree::onGroupSetup} {onGroupSetup()} to update
- UI when execution begins
- \li Uses \l {QtTaskTree::onGroupDone} {onGroupDone()} to reflect
- execution results in the UI
- \endlist
-
- The \c TaskGlueItem class implements leaf nodes in your task tree using
- \l {QtTaskTree::} {timeoutTask}.
-
- Here's the \c {recipe()} implementation that creates the task:
-
- \snippet widgets/demo/main.cpp 2
-
- The implementation:
- \list
- \li Creates a \l {QtTaskTree::} {Group} that wraps a
- \l {QtTaskTree::} {timeoutTask}
- \li Uses UI settings to configure duration and expected outcome
- \li Updates UI state when task begins via
- \l {QtTaskTree::onGroupSetup} {onGroupSetup()}
- \li Reflects task completion state via
- \l {QtTaskTree::onGroupDone} {onGroupDone()}
- \endlist
-
- \section1 Building the task hierarchy
-
- Two helper methods simplify the creation of task trees:
-
- \snippet widgets/demo/main.cpp 3
-
- \list
- \li \c {group()}: Creates a new \c GroupGlueItem
- \li \c {task()}: Creates a new \c TaskGlueItem
- \endlist
-
- \section1 Defining the tree structure
-
- The following code shows how you can build a complete task hierarchy:
-
- \snippet widgets/demo/main.cpp 4
-
- You can modify the above construct to create different tree structures.
-
- \section1 Connecting the UI with TaskTree
-
- The final step connects the task tree with the application's UI controls:
-
- \snippet widgets/demo/main.cpp 5
-
- This code:
- \list
- \li Creates a QSingleTaskTreeRunner to execute the task tree
- \li Sets up handlers for the Start, Cancel, and Reset buttons
- \li Connects the progress bar to track task execution
- \endlist
-
- \include examples-run.qdocinc
- */