QProgressBar、QProgressDialog

QProgressBar

一、描述

进度条控件，用于向用户指示操作的进度，并向他们保证应用程序仍在运行。

如果最小值和最大值都设置为 0，则条形图显示忙碌指示符，而不是步数百分比。

二、类型成员

1、enum QProgressBar::Direction：指定垂直进度条的文本阅读方向。

• TopToBottom：文本顺时针旋转 90 度。
• BottomToTop：文本逆时针旋转 90 度。 

请注意，是否绘制文本取决于样式。

三、属性成员

1、alignment : Qt::Alignment

进度条的对齐方式。

2、format : QString

用于生成当前文本的字符串，默认值为“%p%”。

%p - 替换为完成的百分比。%v - 被当前值替换。%m - 替换为总步数。

3、invertedAppearance : bool

进度条是否显示其进度反转。

如果此属性为true，则进度条向另一个方向增长（例如，从右到左）。

4、maximum : int / minimum : int

进度条的最大值 / 最小值。设置此属性时，如有必要，会调整 minimum / maximum 以确保范围保持有效。如果当前值超出新范围，则使用 reset() 重置进度条。

      value : int

进度条的当前值。尝试将当前值更改为最小-最大范围之外的值对当前值没有影响。

5、orientation : Qt::Orientation

进度条的方向。

6、text : const QString

与进度条一起显示的描述性文本。

返回的文本与显示在进度条中心（或某些样式的左侧）的文本相同。

7、textDirection : Direction

垂直进度条文本的阅读方向。默认为 QProgressBar::TopToBottom。

此属性对水平进度条没有影响。

8、textVisible : bool

是否应显示文本。样式可能会忽略此属性（例如，QMacStyle 从不绘制文本）。

四、成员函数

1、void reset()

重置进度条。

 

2、void setRange(int minimum, int maximum)

设置范围。可以使用 setRange(0, 0) 将 QProgressBar 设置为未确定状态。

如果 maximum 小于 minimum，则 minimum 成为唯一的合法值。

如果当前值超出新范围，则使用 reset() 重置进度条。

3、【信号】void valueChanged(int value)

当进度条中显示的值发生变化时，会发出此信号。value 是进度条显示的新值。

4、void initStyleOption(QStyleOptionProgressBar *option)

使用此 QProgressBar 中的值初始化选项。当子类需要一个 QStyleOptionProgressBar 但又不想自己填写所有信息时，此方法很有用。

---

 QProgressDialog

一、描述

进度对话框继承自 QDialog，用于向用户指示操作将花费多长时间，并证明应用程序尚未冻结。它还可以给用户一个中止操作的机会。

进度对话框的一个常见问题是很难知道何时使用它们。操作在不同的硬件上花费不同的时间。 QProgressDialog 为这个问题提供了一个解决方案：它估计操作将花费的时间（基于步骤的时间），并且仅在估计超出 minimumDuration() （默认为 4 秒）时才显示自己。

对话框会在操作结束时自动重置并隐藏。使用 setAutoReset() 和 setAutoClose() 来改变这种行为。请注意，如果设置了等于当前 value() 的新最大值，则无论如何都不会关闭对话框。

QProgressDialog 有两种使用方式：模态和非模态。

模态模式使用示例：

在循环中执行操作，间隔调用 setValue()，并使用 wasCanceled() 检查取消。

    QProgressDialog progress("正在复制文件...", "Abort Copy", 0, numFiles, this);
    progress.setWindowModality(Qt::WindowModal);

    for (int i = 0; i < numFiles; i++) {
        progress.setValue(i);

        if (progress.wasCanceled())
            break;
        //...
    }
    progress.setValue(numFiles);

非模态的进度对话框适用于发生在后台的操作，用户可以在后台与应用程序进行交互。此类操作通常基于 QTimer（或 QObject::timerEvent()）或 QSocketNotifier； 或在单独的线程中执行。

非模态模式使用示例：

需要运行一个事件循环，将 cancelled() 信号连接到一个停止操作的槽，并每隔一段时间调用 setValue()。 例如：

Operation::Operation(QObject *parent)
    : QObject(parent), steps(0)
{
    pd = new QProgressDialog("Operation in progress.", "Cancel", 0, 100);
    connect(pd, &QProgressDialog::canceled, this, &Operation::cancel);
    t = new QTimer(this);
    connect(t, &QTimer::timeout, this, &Operation::perform);
    t->start(0);
}

void Operation::perform()
{
    pd->setValue(steps);
    //... 
    steps++;
    if (steps > pd->maximum())
        t->stop();
}

void Operation::cancel()
{
    t->stop();
    //... cleanup
}

二、属性成员

1、autoClose : bool

进度对话框是否被 reset() 隐藏。默认为 true。

2、autoReset : bool

进度对话框是否在 value() 等于 maximum() 时立即调用 reset()。默认为 true。

3、labelText : QString

标签的文本。

4、maximum : int

进度条表示的最大值。默认为 100。

5、minimum : int

进度条表示的最小值。默认值为 0。

6、minimumDuration : int

进度对话框出现之前必须经过的时间。如果任务的预期持续时间小于 minimumDuration，则根本不会出现对话框。 这可以防止为快速结束的任务弹出对话框。

如果设置为 0，则在设置任何进度后始终显示对话框。默认值为 4000 毫秒。

7、value : int

当前进度值。

要使进度对话框按预期工作，应该首先将此属性设置为 minimum()，最后将其设置为 maximum()。可以在两者之间调用 setValue() 任意次数。

如果进度对话框是模态的，setValue() 会调用 QCoreApplication::processEvents()。

8、wasCanceled : const bool

进度对话框是否被取消 。

三、成员函数

1、QProgressDialog(const QString &labelText, const QString &cancelButtonText, int minimum, int maximum, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())

构造一个进度对话框。

labelText 是用于提醒用户正在进行的内容的文本。

cancelButtonText 是要在取消按钮上显示的文本。如果为 QString()，则不显示取消按钮。

2、void cancel()

重置进度对话框。 wasCanceled() 变为true，进度对话框变为隐藏。

3、【信号】void canceled()

 单击取消按钮时会发出此信号。它默认连接到 cancel() 槽。

4、void forceShow()

如果在算法启动并且 minimumDuration 毫秒过去后它仍然隐藏，则显示对话框。

5、void reset()

重置进度对话框。 如果 autoClose() 为true，则进度对话框将隐藏。

6、void setCancelButtonText(const QString &cancelButtonText)

将取消按钮的文本设置为 cancelButtonText。如果文本设置为 QString() 那么它将导致取消按钮被隐藏和删除。

7、void open(QObject *receiver, const char *member)

打开对话框并将其 cancelled() 信号连接到 receiver 和 member 指定的槽。

当对话框关闭时，信号将与槽断开连接。

8、void setBar(QProgressBar *bar)

设置进度条小部件。进度对话框调整大小以适应。进度对话框拥有进度条的所有权，必要时将删除该进度条，因此不要使用在堆栈上分配的进度条。

9、void setCancelButton(QPushButton *cancelButton)

 将取消按钮设置为按钮cancelButton。进度对话框拥有此按钮的所有权，该按钮将在必要时被删除，因此不要传递堆栈上对象的地址。 如果传递了 nullptr，则不会显示取消按钮。

10、void setLabel(QLabel *label)

设置标签。进度对话框调整大小以适应。 标签归进度对话框所有，必要时将被删除，因此不要传递堆栈上对象的地址。