- Qt 6.12
- Qt TaskTree
- C++ Classes
- GroupItem
- Qt 6.12.0 Reference Documentation

# QtTaskTree::GroupItem Class

class QtTaskTree::GroupItem

GroupItem represents the basic element that may be a part of any Group. More...

Header: | `#include <qtasktree.h>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS TaskTree)` `target_link_libraries(mytarget PRIVATE Qt6::TaskTree)`
qmake: | `QT += tasktree`
Since: | Qt 6.11
Inherited By: | QtTaskTree::ExecutableItem and QtTaskTree::ExecutionMode
Status: | Technology preview

This class is in technology preview and is subject to change.

- List of all members, including inherited members

Note: All functions in this class are reentrant.

## Public Types

| GroupDoneHandler
| GroupSetupHandler

## Public Functions

| GroupItem(const QtTaskTree::GroupItems &children)
| GroupItem(const QtTaskTree::Storage<StorageStruct> &storage)
| GroupItem(std::initializer_list<QtTaskTree::GroupItem> children)
| GroupItem(QtTaskTree::GroupItem &&other)

## Detailed Description

GroupItem is a basic element that may be a part of any Group. It encapsulates the functionality provided by any GroupItem's subclass. It is a value type and it is safe to copy the GroupItem instance, even when it is originally created via the subclass' constructor.

There are four main kinds of GroupItem:

GroupItem Kind | Brief Description
--- | ---
QCustomTask | Defines asynchronous task type and task's start, done, and error handlers. Aliased with a unique task name, such as, QThreadFunctionTask<ResultType> or QNetworkReplyWrapperTask. Asynchronous tasks are the main reason for using a task tree.
Group | A container for other group items. Since the group is of the GroupItem type, it's possible to nest it inside another group. The group is seen by its parent as a single asynchronous task.
GroupItem containing Storage | Enables the child tasks of a group to exchange data. When GroupItem containing Storage is placed inside a group, the task tree instantiates the storage's data object just before the group is entered, and destroys it just after the group is left.
Other group control items | The ExecutionMode or items returned by workflowPolicy() influence the group's behavior. The items returned by onGroupSetup() or onGroupDone() define custom handlers called when the group starts or ends execution.

## Member Type Documentation

### `[alias]` GroupItem::GroupDoneHandler

Type alias for `std::function<DoneResult(DoneWith)>` or DoneResult.

The GroupDoneHandler is an argument of the onGroupDone() element. Any function with the above signature, when passed as a group done handler, will be called by the running task tree when the group execution ends.

The DoneWith argument is optional and your done handler may omit it. When provided, it holds the info about the final result of a group that will be reported to its parent.

The returned DoneResult value is optional and your handler may return `void` instead. In this case, the final result of the group will be equal to the value indicated by the DoneWith argument. When the handler returns the DoneResult value, the group's final result may be tweaked inside the done handler's body by the returned value.

For a GroupDoneHandler of the DoneResult type, no additional handling is executed, and the group finishes unconditionally with the passed value of DoneResult, ignoring the group's workflow policy.

See also onGroupDone(), GroupSetupHandler, and QCustomTask::TaskDoneHandler.

### `[alias]` GroupItem::GroupSetupHandler

Type alias for `std::function<SetupResult()>`.

The GroupSetupHandler is an argument of the onGroupSetup() element. Any function with the above signature, when passed as a group setup handler, will be called by the running task tree when the group execution starts.

The return value of the handler instructs the running group on how to proceed after the handler's invocation is finished. The default return value of SetupResult::Continue instructs the group to continue running, that is, to start executing its child tasks. The return value of SetupResult::StopWithSuccess or SetupResult::StopWithError instructs the group to skip the child tasks' execution and finish immediately with success or an error, respectively.

When the return type is either SetupResult::StopWithSuccess or SetupResult::StopWithError, the group's done handler (if provided) is called synchronously immediately afterwards.

Note: Even if the group setup handler returns StopWithSuccess or StopWithError, the group's done handler is invoked. This behavior differs from that of task done handler and might change in the future.

The onGroupSetup() element accepts also functions in the shortened form of `std::function<void()>`, that is, the return value is `void`. In this case, it's assumed that the return value is SetupResult::Continue.

See also onGroupSetup(), GroupDoneHandler, and QCustomTask::TaskSetupHandler.

## Member Function Documentation

### GroupItem::GroupItem(const QtTaskTree::GroupItems &children)

Constructs a GroupItem element with a given list of children.

When this GroupItem element is parsed by the QTaskTree, it is simply replaced with its children.

This constructor is useful when constructing a Group element with lists of GroupItem elements:

     static GroupItems getItems();

     ...

     const Group root {
         parallel,
         finishAllAndSuccess,
         getItems(), // GroupItems list is wrapped into a single GroupItem element
         onGroupSetup(...),
         onGroupDone(...)
     };

If you want to create a subtree, use Group instead.

Note: Don't confuse this GroupItem with the Group element, as Group keeps its children nested after being parsed by the task tree, while this GroupItem does not.

See also Group.

### template <typename StorageStruct> GroupItem::GroupItem(const QtTaskTree::Storage<StorageStruct> &storage)

Constructs a GroupItem element holding the storage object.

When the Group element containing this GroupItem is entered by the running task tree, an instance of the `StorageStruct` is created dynamically.

When that group is about to be left after its execution, the previously instantiated `StorageStruct` is deleted.

The dynamically created instance of `StorageStruct` is accessible from inside any handler body of the parent Group element, including nested groups and its tasks, via the Storage::operator->(), Storage::operator*(), or Storage::activeStorage() method.

See also Storage.

### GroupItem::GroupItem(std::initializer_list<QtTaskTree::GroupItem> children)

This is an overloaded function.

See also GroupItem(const QtTaskTree::GroupItems &children).

### `[constexpr noexcept default]` GroupItem::GroupItem(QtTaskTree::GroupItem &&other)

Move-constructs an instance of GroupItem.