进度管理器类

class Core::ProgressManager

进度管理器类用于在 Qt Creator 中显示运行任务的用户界面。更多...

头文件	#include <coreplugin/progressmanager/progressmanager.h>
继承	QObject

所有成员的列表，包括继承的成员

公共类型

枚举	ProgressFlag { KeepOnFinish, ShowInApplicationIcon }
flag	ProgressFlags

公共槽

void	cancelTasks(Utils::Id type)

信号

void	allTasksFinished(Utils::Id type)
void	taskStarted(Utils::Id type)

静态公共成员

Core::FutureProgress *	addTask(const QFuture<void> &future, const QString &title, Utils::Id type, Core::ProgressManager::ProgressFlags flags = {})
Core::FutureProgress *	addTimedTask(const QFutureInterface<void> &futureInterface, const QString &title, Utils::Id type, std::chrono::seconds expectedDuration, Core::ProgressManager::ProgressFlags flags = {})
Core::ProgressManager *	instance()
void	setApplicationLabel(const QString &text)

详细描述

进度管理器跟踪它被告知的任务的进度，并在 Qt Creator 主窗口的右下角向用户显示进度指示器。进度指示器还允许用户取消任务。

您可以通过 ProgressManager::instance() 函数获取此类的单个实例。

注册任务

进度管理器 API 使用 QtConcurrent 作为定义任务的基础。一个任务由以下属性组成

属性	类型	描述
任务抽象	`QFuture<void>`	一个 QFuture 对象，表示负责报告任务状态的进程。有关如何为本特定任务创建此对象的编程模式，请参见下文。
标题	`QString`	一个简短的标题，描述您的任务。这将在进度条上方显示。
类型	`QString`	一个字符串标识符，用于将属于同一组的不同任务分组。例如，所有搜索操作使用相同的类型标识符。
标志	ProgressManager::ProgressFlags	指定如何向用户展示进度条的附加标志。

要注册任务，您创建您的 QFuture<void> 对象，并调用 addTask()。此函数返回一个 FutureProgress 对象，您可以使用它来进一步自定义进度条的显示。请参阅 FutureProgress 文档以获取详细信息。

以下将介绍两种常见的模式来为您的任务创建 QFuture<void> 对象。

使用 QtConcurrent 创建线程化任务

第一种选择是直接使用 QtConcurrent 在不同的线程中并发启动一个任务。QtConcurrent 几个不同的函数可以在不同的线程中运行，例如运行一个类的函数。Qt Creator 本身在其 src/libs/utils/async.h 中增加了几个。QtConcurrent 运行并发任务的函数返回一个 QFuture 对象。这就是您要在 addTask() 函数中提供给 ProgressManager 的对象。

例如查看 Core::ILocatorFilter。定位过滤器实现一个函数 refresh()，该函数接受一个 QFutureInterface 对象作为参数。这些函数看起来如下所示

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

实际的刷新，它将所有过滤器的刷新函数在另一个线程中调用，如下所示

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

首先，我们要启动一个异步操作，该操作调用所有过滤器的刷新函数。之后，我们将返回的 QFuture 对象注册给 ProgressManager。

为您的线程手动创建 QtConcurrent 对象

如果您的任务有其创建和运行线程的方法，您需要自己创建必要的对象，并报告启动/停止状态。

// 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;

在第一行中，我们创建了一个 QFutureInterface 对象，这将是我们的报告任务状态的方式。首先我们报告的是进度值的预期范围。我们使用为我们 QFutureInterface 对象创建的内部 QFuture 对象将任务注册到 ProgressManager 中。接下来，我们报告任务已经开始，并开始实际工作，通过 QFutureInterface 中的函数定期报告进度。在耗时操作完成后，我们通过 QFutureInterface 对象进行报告，然后删除它。

自定义进度显示

您可以使用 FutureProgress 对象，它是由 addTask() 函数返回的，设置一个自定义小部件来显示在进度条本身下面。也可以使用此对象在用户点击进度指示器时通知。

成员类型文档

枚举 ProgressManager::ProgressFlag
标志 ProgressManager::ProgressFlags

额外的标志，用于指定行为细节。对于任务，默认情况下不设置任何这些标志。

常量	值	描述
`Core::ProgressManager::KeepOnFinish`	`0x01`	任务完成后的进度指示器仍然可见。
`Core::ProgressManager::ShowInApplicationIcon`	`0x02`	此任务的进度指示器还将在支持平台（目前是 Windows 7 和 Mac OS X）的系统任务栏或 dock 中的应用程序图标中显示。

ProgressFlags 类型是 QFlags<ProgressFlag> 的一种别名。它存储了 ProgressFlag 值的 OR 组合。

成员函数文档

`[静态]` Core::FutureProgress ProgressManager::addTask(const QFuture<void> &future, const QString &title, Utils::Id type, Core::ProgressManager::ProgressFlags flags* = {})

为由 QFuture 对象 future 给出的任务显示进度指示器。

进度指示器显示指定的 title 以及进度条。任务的 type 将指定与其他运行任务的逻辑分组合并。通过 flags 参数，例如您可以让进度指示器在任务完成后仍然可见。

返回一个表示创建的进度指示器的对象，可以用于进一步自定义。由 FutureProgress 对象的生命周期由 ProgressManager 管理，并且保证其生命周期仅到下一个事件循环周期，或者到下一个调用 addTask。

如果您想在调用此函数后不久再使用返回的 FutureProgress，则需要使用保护函数（例如将返回的对象包装在 QPointer 中并在使用时检查是否为 0）。

`[静态]` Core::FutureProgress ProgressManager::addTimedTask(const QFutureInterface<void> &futureInterface, const QString &title, Utils::Id type, std::chrono::seconds expectedDuration, Core::ProgressManager::ProgressFlags flags* = {})

为由 QFutureInterface 对象 futureInterface 给出的任务显示进度指示器。进度指示器显示指定的 title 以及进度条。进度指示器会随时间单调递增，在 expectedDuration 时大约达到 80%，然后以递减的速度继续增加。

任务的 type 将指定与其他运行任务的逻辑分组合并。通过 flags 参数，例如您可以让进度指示器在任务完成后仍然可见。

另请参阅addTask。

`[信号]` void ProgressManager::allTasksFinished(Utils::Id type)

当一个类型的所有任务都完成后发送。

`[静态槽]` void ProgressManager::cancelTasks(Utils::Id type)

安排取消给定类型下所有正在运行的任务。取消功能取决于运行任务确实检查了 QFuture::isCanceled 属性。

`[静态]` Core::ProgressManager *ProgressManager::instance()

返回一个进度管理器的单一实例。

`[静态]` void ProgressManager::setApplicationLabel(const QString &text)

以平台相关的方式在系统任务栏或码头中的应用程序图标中显示给定的text。这在Windows和macOS上用于显示构建错误的数量。

`[信号]` void ProgressManager::taskStarted(Utils::Id type)

当启动指定type的任务时，会发送该信号。

进度管理器类

公共类型

公共槽

信号

静态公共成员

详细描述

注册任务

使用 QtConcurrent 创建线程化任务

为您的线程手动创建 QtConcurrent 对象

自定义进度显示

成员类型文档

枚举 ProgressManager::ProgressFlag标志 ProgressManager::ProgressFlags

成员函数文档

[静态] Core::FutureProgress *ProgressManager::addTask(const QFuture<void> &future, const QString &title, Utils::Id type, Core::ProgressManager::ProgressFlags flags = {})

[静态] Core::FutureProgress *ProgressManager::addTimedTask(const QFutureInterface<void> &futureInterface, const QString &title, Utils::Id type, std::chrono::seconds expectedDuration, Core::ProgressManager::ProgressFlags flags = {})

[信号] void ProgressManager::allTasksFinished(Utils::Id type)

[静态槽] void ProgressManager::cancelTasks(Utils::Id type)

[静态] Core::ProgressManager *ProgressManager::instance()

[静态] void ProgressManager::setApplicationLabel(const QString &text)

[信号] void ProgressManager::taskStarted(Utils::Id type)