Revision control
++ // Copyright (C) 2025 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example tasktree/imagescaling
++ \meta tags {widgets, threads, network}
++ \examplecategory {Data Processing & I/O}
++ \examplecategory {Networking}
++ \title TaskTree Image Scaling
++ \ingroup tasktree_examples
++ \brief Demonstrates how to run For loop iterations in parallel
++ to asynchronously download and scale images using TaskTree.
++
++ This example shows how to use Qt TaskTree classes to download a collection
++ of images from the network and scale them without blocking the UI. It
++ demonstrates how to use the \l {QtTaskTree::}{For} element to run subtasks
++ in a parallel loop over QList items, and how to use the
++ \l {QtTaskTree::}{Storage} element to share data between tasks.
++
++ This example provides an alternative implementation for the image scaling
++ example in \l {Image Scaling}{Qt Concurrent}.
++
++ \image tasktree-imagescaling-example.png
++ {Grid of downloaded images with Finished status}
++
++ \section1 Application workflow
++
++ When the user presses the \uicontrol {Add URLs} button, the following method
++ runs:
++
++ \snippet tasktree/imagescaling/imagescaling.cpp 0
++
++ The method runs \c DownloadDialog. When the user accepts the dialog, the
++ method gets the list of selected URLs, clears the displayed images, and
++ prepares a grid for new images by calling \c initLayout(urls.size()).
++
++ For each item in the \c urls list, the app:
++ \list
++ \li Downloads the image for a given address using
++ \l {QtTaskTree::} {QNetworkReplyWrapper} and stores the received
++ \l QByteArray data locally.
++ \li Uses \l {QtTaskTree::} {QThreadFunction} to convert the
++ \l QByteArray data to a \l QImage and scales it to a thumbnail
++ in a separate thread.
++ \li Displays the resulting thumbnail in the grid.
++ \endlist
++
++ To iterate over the \c urls list, the app uses an \c iterator element of
++ \l {QtTaskTree::}{ListIterator} type. The \l QByteArray data received
++ after downloading is stored in the \c storage element of
++ \l {QtTaskTree::}{Storage}<QByteArray> type, which is used to
++ pass the data to the scale function.
++
++ \snippet tasktree/imagescaling/imagescaling.cpp 1
++
++ The \c recipe that describes the workflow looks like this:
++
++ \snippet tasktree/imagescaling/imagescaling.cpp 2
++
++ Here is a summary of all elements used in the recipe:
++
++ \table
++ \header
++ \li Element
++ \li Purpose
++ \row
++ \li \l {QtTaskTree::} {For}
++ \li Top level loop iterating over a list of \c urls.
++ \row
++ \li \l {QtTaskTree::} {Do}
++ \li Describes the body of each iteration.
++ \row
++ \li \l {QtTaskTree::} {finishAllAndSuccess}
++ \li Instructs the task tree to continue running
++ despite errors and report success when finished.
++ \row
++ \li \l {QtTaskTree::} {parallel}
++ \li Causes all direct children of the \l{QtTaskTree::}{Do} body
++ to run in parallel, including all iterations of the
++ top-level \l{QtTaskTree::}{For} element.
++
++ This means that all iterations will start simultaneously.
++ \row
++ \li \l {QtTaskTree::} {onGroupSetup}(onRootSetup)
++ \li Invokes \c onRootSetup handler when the first iteration
++ is about to be executed.
++ \row
++ \li \l {QtTaskTree::} {onGroupDone}(onRootDone)
++ \li Invokes \c onRootDone handler when all the iterations are finished.
++ \row
++ \li \l {QtTaskTree::} {Group}
++ \li A subgroup, executed for each iteration.
++ By default, all its children execute in sequence.
++ \row
++ \li \c storage
++ \li Instructs the running task tree to instantiate the underlying
++ QByteArray instance when entering the subgroup.
++
++ This means the running task tree instantiates
++ a separate QByteArray copy for each iteration.
++ \row
++ \li QNetworkReplyWrapperTask
++ \li The first asynchronous task that runs in sequence for each iteration.
++
++ Starts downloading the QByteArray data for a given \c url.
++ When the download is about to start, the \c onDownloadSetup
++ is invoked to setup the input \c url for download.
++
++ When it's finished, the \c onDownloadDone is invoked.
++ In case of successful execution, the downloaded QByteArray data
++ is stored inside \c storage element.
++ \row
++ \li QThreadFunctionTask<QImage>
++ \li The second asynchronous task executed in sequence for each iteration.
++ It's executed only after successful execution of the first task.
++
++ Executes a function in a separate thread, passing the stored QByteArray
++ data of the downloaded image. When the function is about to start,
++ the \c onScaleSetup is invoked to setup the QByteArray data for scaling.
++
++ When it's finished, the \c onScaleDone is invoked.
++ In case of successful execution it displays the thumbnail in a grid.
++ \endtable
++
++ \section1 Update the status bar
++
++ The following shows how all handlers are implemented:
++
++ \snippet tasktree/imagescaling/imagescaling.cpp 3
++
++ When the first iteration starts, the \c onRootSetup handler updates the
++ status bar message and enables the \uicontrol Cancel button. When the last
++ iteration finishes, the \c onRootDone handler updates the status bar
++ message and disables the \uicontrol Cancel button.
++
++ \section1 Download and scale images
++
++ Each iteration runs in parallel with others and consists of two sequential
++ tasks. The first task in each iteration is
++ \l {QtTaskTree::} {QNetworkReplyWrapperTask}.
++ Here is how its setup and done handlers are implemented:
++
++ \snippet tasktree/imagescaling/imagescaling.cpp 4
++
++ The \c onDownloadSetup handler runs when
++ \l {QtTaskTree::} {QNetworkReplyWrapper} is about to
++ start. It sets up the network access manager and network request. The
++ handler captures the \c iterator, which gives access to the current address
++ from the \c urls list.
++
++ The \c onDownloadDone handler runs when
++ \l {QtTaskTree::} {QNetworkReplyWrapper} finishes. It
++ captures the \c storage and \c iterator. If the task succeeds, it stores
++ the received \l QByteArray data in \c storage. The task tree creates a
++ separate \l QByteArray instance for each iteration. Dereferencing \c storage
++ gives access to the \l QByteArray instance for the current iteration. If the
++ task fails or is canceled, the handler shows the error message for the
++ label immediately. The index of the current iteration is returned by
++ \c {iterator.iteration()}.
++
++ The second task in each iteration is
++ \l {QtTaskTree::} {QThreadFunctionTask}<QImage>. Its
++ setup and done handlers are as follows:
++
++ \snippet tasktree/imagescaling/imagescaling.cpp 5
++
++ Inside \c onScaleSetup, the handler schedules a call to the
++ \c scale function, passing the \l QByteArray data received from the first
++ task as an argument. This is done by dereferencing the captured \c storage.
++ The \c scale function runs in a separate thread.
++
++ The \c onScaleDone handler runs when the \c scale function finishes.
++ \c onScaleDone is called from the main thread. If scaling succeeds, the
++ handler assigns the scaled image to the appropriate label. Otherwise, the
++ handler shows an error message.
++
++ The following shows how the \c scale function is implemented:
++
++ \snippet tasktree/imagescaling/imagescaling.cpp 6
++
++ The function takes a \l QPromise to the result type as an argument. The
++ \c promise is used to return the final result or to issue an error by
++ canceling the promise's future.
++
++ \include examples-run.qdocinc
++ */