就业培训     下载中心     Wiki     联络 登录   注册
  1. 首页
  2. Qt 6.2.1
  3. Qt Widgets
  4. C++ 类
  5. QProgressDialog

内容

QProgressDialog 类

QProgressDialog 类提供慢操作进度反馈。 更多...

头： #include <QProgressDialog>
CMake: find_package(Qt6 COMPONENTS Widgets REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
继承： QDialog

特性

公共函数

  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
bool autoReset () const
QString labelText () const
int maximum () const
int minimum () const
int minimumDuration () const
void open (QObject * receiver , const char * member )
void setAutoClose (bool close )
void setAutoReset (bool reset )
void setBar (QProgressBar * bar )
void setCancelButton (QPushButton * cancelButton )
void setLabel (QLabel * label )
int value () const
bool wasCanceled () const

重实现公共函数

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 ()

详细描述

进度对话框用于给予用户操作将花费多长时间的指示，并演示应用程序没有被冻结。它还可以让用户有机会中止操作。

A common problem with progress dialogs is that it is difficult to know when to use them; operations take different amounts of time on different hardware. QProgressDialog offers a solution to this problem: it estimates the time the operation will take (based on time for steps), and only shows itself if that estimate is beyond minimumDuration () (默认 4 秒)。

使用 setMinimum () 和 setMaximum () or the constructor to set the number of "steps" in the operation and call setValue () as the operation progresses. The number of steps can be chosen arbitrarily. It can be the number of files copied, the number of bytes received, the number of iterations through the main loop of your algorithm, or some other suitable unit. Progress starts at the value set by setMinimum (), and the progress dialog shows that the operation has finished when you call setValue () with the value set by setMaximum () as its argument.

对话框在操作结束时自动重置并隐藏本身。使用 setAutoReset () 和 setAutoClose () 能改变这种行为。注意：若设置新的最大 (使用 setMaximum () 或 setRange ()) that equals your current value ()，对话框将不会被关闭 (不管怎样)。

有两种使用 QProgressDialog 的办法：模态和非模态。

Compared to a modeless QProgressDialog, a modal QProgressDialog is simpler to use for the programmer. Do the operation in a loop, call setValue () at intervals, and check for cancellation with 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);

A modeless progress dialog is suitable for operations that take place in the background, where the user is able to interact with the application. Such operations are typically based on QTimer (或 QObject::timerEvent ()) or QSocketNotifier ; or performed in a separate thread. A QProgressBar in the status bar of your main window is often an alternative to a modeless progress dialog.

You need to have an event loop to be running, connect the canceled () signal to a slot that stops the operation, and call setValue () at intervals. For example: 

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

In both modes the progress dialog may be customized by replacing the child widgets with custom widgets by using setLabel (), setBar ()，和 setCancelButton ()。函数 setLabelText () 和 setCancelButtonText () 设置展示文本。

A progress dialog shown in the Fusion widget style.

另请参阅 QDialog , QProgressBar , GUI 设计手册：进度指示器 , 查找文件范例 ，和 像素器范例 .

特性文档编制

autoClose : bool

此特性保持对话框是否被隐藏，通过 reset ()

默认为 true。

访问函数：

bool autoClose () const
void setAutoClose (bool close )

另请参阅 setAutoReset ().

autoReset : bool

此特性保持进度对话框是否调用 reset () 尽快 value () 等于 maximum ()

默认为 true。

访问函数：

bool autoReset () const
void setAutoReset (bool reset )

另请参阅 setAutoClose ().

labelText : QString

此特性保持标签的文本

默认文本为空字符串。

访问函数：

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

maximum : int

此特性保持由进度条表示的最高值

默认为 100。

访问函数：

int maximum () const
void setMaximum (int maximum )

另请参阅 minimum and setRange ().

minimum : int

此特性保持由进度条表示的最低值

默认为 0。

访问函数：

int minimum () const
void setMinimum (int minimum )

另请参阅 maximum and setRange ().

minimumDuration : int

此特性保持在对话框出现之前必须经过的时间

If the expected duration of the task is less than the minimumDuration, the dialog will not appear at all. This prevents the dialog popping up for tasks that are quickly over. For tasks that are expected to exceed the minimumDuration, the dialog will pop up after the minimumDuration time or as soon as any progress is set.

若设为 0，始终一设置任何进度，就会尽快展示对话框。默认为 4000 毫秒。

访问函数：

int minimumDuration () const
void setMinimumDuration (int ms )

value : int

此特性保持当前已取得的进度数量。

为使进度对话框如期望般工作，应把此特性初始设为 QProgressDialog::minimum () 并把它最终设为 QProgressDialog::maximum ()；可以调用 setValue() 任意多次在两者之间。

警告： 若进度对话框是模态的 (见 QProgressDialog::QProgressDialog ())，setValue() 调用 QCoreApplication::processEvents (), so take care that this does not cause undesirable re-entrancy in your code. For example, don't use a QProgressDialog 在 paintEvent ()!

访问函数：

int value () const
void setValue (int progress )

另请参阅 minimum and maximum .

[read-only] wasCanceled : const bool

此特性保持对话框是否被取消

访问函数：

bool wasCanceled () const

成员函数文档编制

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

构造进度对话框。

labelText 是用于提醒用户进展如何的文本。

cancelButtonText 是要在取消按钮上显示的文本。若传递的是 QString()，则不展示取消按钮。

minimum and maximum is the number of steps in the operation for which this progress dialog shows progress. For example, if the operation is to examine 50 files, this value minimum value would be 0, and the maximum would be 50. Before examining the first file, call setValue (0). As each file is processed call setValue (1), setValue (2), etc., finally calling setValue (50) after examining the last file.

parent argument is the dialog's parent widget. The parent, parent , and widget flags, f , are passed to the QDialog::QDialog () constructor.

另请参阅 setLabelText (), setLabel (), setCancelButtonText (), setCancelButton (), setMinimum ()，和 setMaximum ().

QProgressDialog:: QProgressDialog ( QWidget * parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())

构造进度对话框。

默认设置：

  • 标签文本为空。
  • 取消按钮文本是 (翻译) Cancel。
  • 最小为 0；
  • 最大为 100

parent argument is dialog's parent widget. The widget flags, f , are passed to the QDialog::QDialog () constructor.

另请参阅 setLabelText (), setCancelButtonText (), setCancelButton (), setMinimum ()，和 setMaximum ().

[slot] void QProgressDialog:: cancel ()

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

[signal] void QProgressDialog:: canceled ()

此信号被发射当取消按钮被点击时。它被连接到 cancel () 槽，默认情况下。

另请参阅 wasCanceled ().

[protected slot] void QProgressDialog:: forceShow ()

展示对话框，若算法被启动后其仍被隐藏和 minimumDuration 毫秒已过去。

另请参阅 setMinimumDuration ().

[slot] void QProgressDialog:: reset ()

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

另请参阅 setAutoClose () 和 setAutoReset ().

[slot] void QProgressDialog:: setCancelButtonText (const QString & cancelButtonText )

将取消按钮的文本设为 cancelButtonText 。若文本被设为 QString()，它将导致取消按钮被隐藏并被删除。

另请参阅 setCancelButton ().

[slot] void QProgressDialog:: setRange ( int minimum , int maximum )

Sets the progress dialog's minimum and maximum values to minimum and maximum ，分别。

若 maximum 小于 minimum , minimum 变为唯一合法值。

If the current value falls outside the new range, the progress dialog is reset with reset ().

另请参阅 minimum and maximum .

[虚拟] QProgressDialog:: ~QProgressDialog ()

销毁进度对话框。

[override virtual protected] void QProgressDialog:: changeEvent ( QEvent * ev )

重实现： QWidget::changeEvent (QEvent *event).

[override virtual protected] void QProgressDialog:: closeEvent ( QCloseEvent * e )

重实现： QDialog::closeEvent (QCloseEvent *e).

void QProgressDialog:: open ( QObject * receiver , const char * member )

打开对话框并连接其 canceled () 信号到槽，指定通过 receiver and member .

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

[override virtual protected] void QProgressDialog:: resizeEvent ( QResizeEvent * event )

重实现： QDialog::resizeEvent (QResizeEvent *).

void QProgressDialog:: setBar ( QProgressBar * bar )

将进度栏小部件设为 bar 。进度对话框会重置尺寸以拟合。进度对话框拥有其所有权对于进度 bar 会被删除当有必要时，因此不要使用分配在堆栈中的进度条。

void QProgressDialog:: setCancelButton ( QPushButton * cancelButton )

将取消按钮设为 Push Button (按钮) cancelButton 。进度对话框拥有此按钮 (会被删除当有必要时) 的所有权，因此，勿传递堆栈中的对象地址，即：使用 new() 去创建按钮。若 nullptr 被传递，则取消按钮不会被展示。

另请参阅 setCancelButtonText ().

void QProgressDialog:: setLabel ( QLabel * label )

把标签设为 label 。进度对话框会重置尺寸以拟合。标签变为由进度对话框所有，且会被删除当有必要时，因此，不要把对象地址传递给堆栈。

另请参阅 setLabelText ().

[override virtual protected] void QProgressDialog:: showEvent ( QShowEvent * e )

重实现： QDialog::showEvent (QShowEvent *event).

[override virtual] QSize QProgressDialog:: sizeHint () const

重实现： QDialog::sizeHint () const.

Returns a size that fits the contents of the progress dialog. The progress dialog resizes itself as required, so you should not need to call this yourself.