对话框(09)：【类】QProgressDialog [官翻]

QProgressDialog Class

QProgressDialog类提供有关缓慢操作进度的反馈。

Header	#include < QProgressDialog >
qmake	QT += widgets
Inherits	QDialog
Inherited By

详细说明

进度对话框用于向用户指示操作需要多长时间，并演示应用程序尚未冻结。它还可以为用户提供中止操作的机会。

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

使用setMinimum() 和setMaximum() 或构造函数设置操作中的“步数”，并在操作进行时调用setValue() 。步数可以任意选择。它可以是复制的文件数、接收的字节数、通过算法主循环的迭代次数，或者其他合适的单位。Progress从setMinimum() 设置的值开始，当以setMaximum() 设置的值作为参数调用setValue() 时，Progress对话框显示操作已完成。

对话框在操作结束时自动重置并隐藏自身。使用setAutoReset() 和setAutoClose() 更改此行为。请注意，如果您设置了一个等于当前值() 的新最大值（使用setMaximum() 或setRange() ），则对话框将不会关闭。

有两种使用QProgressDialog的方法:模态和无模态。

与无模式QProgressDialog相比，模式QProgressDialog更易于程序员使用。在循环中执行该操作，每隔一段时间调用setValue() ，并使用wasCanceled() 检查是否取消。例如:

     QProgressDialog progress("Copying files...", "Abort Copy", 0, numFiles, this);
     progress.setWindowModality(Qt::WindowModal);

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

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

无模式进度对话框适用于在后台进行的操作，用户可以在后台与应用程序进行交互。此类操作通常基于QTimer（或QObject::timerEvent() ）或QSocketNotifier；或者在单独的线程中执行。主窗口状态栏中的QProgressBar通常是无模式进度对话框的替代方法。

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

 // Operation constructor
 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);
     //... perform one percent of the operation
     steps++;
     if (steps > pd->maximum())
         t->stop();
 }

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

在这两种模式下，可以通过使用setLabel() 、setBar() 和setCancelButton() 将子窗口小部件替换为自定义窗口小部件来自定义进度对话框。函数setLabelText() 和setCancelButtonText() 设置显示的文本。

属性

1. autoClose: bool 保存对话框是否被reset() 隐藏
   默认值为true。

   • bool autoClose() const
   • void setAutoClose(bool close)

2. autoReset: bool 保存进程对话框是否在value() 等于maximum() 时调用reset()
   默认值为true。

   • bool autoReset() const
   • void setAutoReset(bool reset)

3. labelText: QString 保存标签的文本
   默认文本为空字符串。

   • QString labelText() const
   • void setLabelText(const QString &text)

4. maximum: int 包含由进度条表示的最大值

   默认值为100。

   • int maximum() const
   • void setMaximum(int maximum)

5. minimum: int 包含由进度条表示的最小值

   • int minimum() const
   • void setMinimum(int minimum)

6. minimumDuration: int 对话框出现之前必须经过的时间

   如果任务的预期持续时间小于minimumDuration，则根本不会出现对话框。这样可以防止快速结束的任务弹出对话框。对于预期超过minimumDuration的任务，该对话框将在minimumDuration时间之后或设置任何进度后立即弹出。

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

   • int minimumDuration() const
   • void setMinimumDuration(int ms)

7. value: int 保存当前的进度
   要使“进度”对话框按预期工作，首先应将此属性设置为QProgressDialog::minimum() ，最后将其设置为QProgressDialog::maximum() ；其间可以调用setValue() 任意次数。

   警告:如果进度对话框是模态的（请参见QProgressDialog::QProgressDialog() ），setValue() 将调用QCoreApplication::processEvents() ，因此请注意这不会导致代码中出现不需要的重入。例如，不要在paintEvent() 中使用QProgressDialog！

   • int value() const
   • void setValue(int progress)

8. wasCanceled: const bool 对话框是否已取消

   • bool wasCanceled() const

公共函数

构造和析构

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

属性相关

• bool autoClose() const
  void setAutoClose(bool close)
• bool autoReset() const
  void setAutoReset(bool reset)
• QString labelText() const
  void setLabelText(const QString &text)
• int maximum() const
  void setMaximum(int maximum)
• int minimum() const
  void setMinimum(int minimum)
• int minimumDuration() const
  void setMinimumDuration(int ms)
• int value() const
  void setValue(int progress)
• bool wasCanceled() const

其它

• void open(QObject *receiver, const char *member)

• void setBar(QProgressBar *bar) 将进度条小部件设置为“进度条”

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

• void setCancelButton(QPushButton *cancelButton) 将“cancelButton”按钮设置为“取消”按钮

  “进度”对话框拥有此按钮的所有权，必要时将删除此按钮，因此不要传递堆栈上对象的地址，即使用new（）创建按钮。如果nullptr通过，则不显示取消按钮。

• void setLabel(QLabel *label) 将label设置为“标签”

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

重写的公共函数

• virtual QSize sizeHint() const override

公共槽

• void cancel()
• void reset()
• void setCancelButtonText(const QString &cancelButtonText)
• void setLabelText(const QString &text)
• void setMaximum(int maximum)
• void setMinimum(int minimum)
• void setMinimumDuration(int ms)
• void setRange(int minimum, int maximum)
• void setValue(int progress)

信号

• void canceled()

重写的受保护的函数

• virtual void changeEvent(QEvent *ev) override
• virtual void closeEvent(QCloseEvent *e) override
• virtual void resizeEvent(QResizeEvent *event) override
• virtual void showEvent(QShowEvent *e) override

受保护的函数

• void forceShow()

参考

• Find Files Example
• Pixelator Example