ProgressManager Class

Detailed Description

The progress manager tracks the progress of a task that it is told about, and shows a progress indicator in the lower right corner of Qt Creator's main window to the user. The progress indicator also allows the user to cancel the task.

You get the single instance of this class via the ProgressManager::instance() function.

Registering a task

The ProgressManager API uses QtConcurrent as the basis for defining tasks. A task consists of the following properties:

To register a task you create your QFuture<void> object, and call addTask(). This function returns a FutureProgress object that you can use to further customize the progress bar's appearance. See the FutureProgress documentation for details.

In the following you will learn about two common patterns how to create the QFuture<void> object for your task.

Create a threaded task with QtConcurrent

The first option is to directly use QtConcurrent to actually start a task concurrently in a different thread. QtConcurrent has several different functions to run e.g. a class function in a different thread. Qt Creator itself adds a few more in src/libs/utils/async.h. The QtConcurrent functions to run a concurrent task return a QFuture object. This is what you want to give the ProgressManager in the addTask() function.

Have a look at e.g Core::ILocatorFilter. Locator filters implement a function refresh() which takes a QFutureInterface object as a parameter. These functions look something like:

void Filter::refresh(QFutureInterface<void> &future) {
    future.setProgressRange(0, MAX);
    ...
    while (!future.isCanceled()) {
        // Do a part of the long stuff
        ...
        future.setProgressValue(currentProgress);
        ...
    }
}

The actual refresh, which calls all the filters' refresh functions in a different thread, looks like this:

QFuture<void> task = Utils::map(filters, &ILocatorFilter::refresh);
Core::FutureProgress *progress = Core::ProgressManager::addTask(task, ::Core::Tr::tr("Indexing"),
                                                                Locator::Constants::TASK_INDEX);

First, we to start an asynchronous operation which calls all the filters' refresh function. After that we register the returned QFuture object with the ProgressManager.

Manually create QtConcurrent objects for your thread

If your task has its own means to create and run a thread, you need to create the necessary objects yourselves, and report the start/stop state.

// We are already running in a different thread here
QFutureInterface<void> *progressObject = new QFutureInterface<void>;
progressObject->setProgressRange(0, MAX);
Core::ProgressManager::addTask(progressObject->future(), ::Core::Tr::tr("DoIt"), MYTASKTYPE);
progressObject->reportStarted();
// Do something
...
progressObject->setProgressValue(currentProgress);
...
// We have done what we needed to do
progressObject->reportFinished();
delete progressObject;

In the first line we create the QFutureInterface object that will be our way for reporting the task's state. The first thing we report is the expected range of the progress values. We register the task with the ProgressManager, using the internal QFuture object that has been created for our QFutureInterface object. Next we report that the task has begun and start doing our actual work, regularly reporting the progress via the functions in QFutureInterface. After the long taking operation has finished, we report so through the QFutureInterface object, and delete it afterwards.

Customizing progress appearance

You can set a custom widget to show below the progress bar itself, using the FutureProgress object returned by the addTask() function. Also use this object to get notified when the user clicks on the progress indicator.