Extending Qt Creator Manual | ProgressManager

Extending Qt Creator Manual 4.4.0

# ProgressManager Class

(Core::ProgressManager)

The ProgressManager class is used to show a user interface for running tasks in Qt Creator. More...

Header: | #include <ProgressManager>

- List of all members, including inherited members

## Public Types

enum | ProgressFlag { KeepOnFinish, ShowInApplicationIcon }
flags | ProgressFlags

## Public Slots

void | cancelTasks(Id type)

## Signals

void | allTasksFinished(Core::Id type)
void | taskStarted(Core::Id type)

## Static Public Members

FutureProgress * | addTask(const QFuture<void> &future, const QString &title, Id type, ProgressFlags flags = 0)
FutureProgress * | addTimedTask(const QFutureInterface<void> &futureInterface, const QString &title, Id type, int expectedSeconds, ProgressFlags flags = 0)
ProgressManager * | instance()
void | setApplicationLabel(const QString &text)

## Detailed Description

The ProgressManager class is used to show a user interface for running tasks in Qt Creator.

It tracks the progress of a task that it is told about, and shows a progress indicator in the lower right 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:

Property | Type | Description
--- | --- | ---
Task abstraction | `QFuture<void>` | A `QFuture` object that represents the task which is responsible for reporting the state of the task. See below for coding patterns how to create this object for your specific task.
Title | `QString` | A very short title describing your task. This is shown as a title over the progress bar.
Type | `QString` | A string identifier that is used to group different tasks that belong together. For example, all the search operations use the same type identifier.
Flags | ProgressManager::ProgressFlags | Additional flags that specify how the progress bar should be presented to the user.

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/qtconcurrent/runextensions.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, 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(), 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.

## Member Type Documentation

### enum ProgressManager::ProgressFlag
flags ProgressManager::ProgressFlags

Additional flags that specify details in behavior. The default for a task is to not have any of these flags set.

Constant | Value | Description
--- | --- | ---
`Core::ProgressManager::KeepOnFinish` | `0x01` | The progress indicator stays visible after the task has finished.
`Core::ProgressManager::ShowInApplicationIcon` | `0x02` | The progress indicator for this task is additionally shown in the application icon in the system's task bar or dock, on platforms that support that (at the moment Windows 7 and Mac OS X).

The ProgressFlags type is a typedef for QFlags<ProgressFlag>. It stores an OR combination of ProgressFlag values.

## Member Function Documentation

### `[static]` FutureProgress *ProgressManager::addTask(const QFuture<void> &future, const QString &title, Id type, ProgressFlags flags = 0)

### `[static]` FutureProgress *ProgressManager::addTimedTask(const QFutureInterface<void> &futureInterface, const QString &title, Id type, int expectedSeconds, ProgressFlags flags = 0)

Shows a progress indicator for task given by the QFuture given by the QFutureInterface futureInterface. The progress indicator shows the specified title along with the progress bar. The progress indicator will increase monotonically with time, at expectedSeconds it will reach about 80%, and continue to increase with a decreasingly slower rate.

See also addTask.

### `[signal]` void ProgressManager::allTasksFinished(Core::Id type)

Sent when all tasks of a type have finished.

### `[static slot]` void ProgressManager::cancelTasks(Id type)

### `[static]` ProgressManager *ProgressManager::instance()

### `[static]` void ProgressManager::setApplicationLabel(const QString &text)

Shows the given text in a platform dependent way in the application icon in the system's task bar or dock. This is used to show the number of build errors on Windows 7 and Mac OS X.

### `[signal]` void ProgressManager::taskStarted(Core::Id type)

Sent whenever a task of a given type is started.