QProgressDialog 类

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

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

所有成员列表，包括继承成员
QProgressDialog is part of 标准对话框 .

特性

autoClose : bool
autoReset : bool
labelText : QString
maximum : int

minimum : int
minimumDuration : int
value : int
wasCanceled : const bool

公共函数

	QProgressDialog (QWidget * parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
	QProgressDialog (const QString & labelText , const QString & cancelButtonText , int minimum , int maximum , 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 ，和像素器范例 .

特性文档编制

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

成员函数文档编制

`[explicit]` QProgressDialog:: QProgressDialog ( QWidget * parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())

构造进度对话框。

默认设置：

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

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

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

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

构造进度对话框。

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

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

The 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.

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

销毁进度对话框。

`[slot]` void QProgressDialog:: cancel ()

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

`[signal]` void QProgressDialog:: canceled ()

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

另请参阅 wasCanceled ().

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

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

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

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

`[protected slot]` void QProgressDialog:: forceShow ()

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

另请参阅 setMinimumDuration ().

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

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

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

`[slot]` void QProgressDialog:: reset ()

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

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

`[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 ().

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

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

另请参阅 setCancelButton ().

void QProgressDialog:: setLabel ( QLabel * label )

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

另请参阅 setLabelText ().

`[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 .

`[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.

QProgressDialog 类

特性

公共函数

重实现公共函数

公共槽

信号

重实现保护函数

保护槽

详细描述

特性文档编制

autoClose : bool

autoReset : bool

labelText : QString

maximum : int

minimum : int

minimumDuration : int

value : int

[read-only] wasCanceled : const bool

成员函数文档编制

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

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

[虚拟] QProgressDialog:: ~QProgressDialog ()

[slot] void QProgressDialog:: cancel ()

[signal] void QProgressDialog:: canceled ()

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

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

[protected slot] void QProgressDialog:: forceShow ()

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

[slot] void QProgressDialog:: reset ()

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

void QProgressDialog:: setBar ( QProgressBar * bar )

void QProgressDialog:: setCancelButton ( QPushButton * cancelButton )

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

void QProgressDialog:: setLabel ( QLabel * label )

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

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

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

内容

`[read-only]` wasCanceled : const bool

`[explicit]` QProgressDialog:: QProgressDialog ( QWidget * parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())

`[虚拟]` QProgressDialog:: ~QProgressDialog ()

`[slot]` void QProgressDialog:: cancel ()

`[signal]` void QProgressDialog:: canceled ()

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

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

`[protected slot]` void QProgressDialog:: forceShow ()

`[slot]` void QProgressDialog:: reset ()

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

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

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

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

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