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 () 设置展示文本。
另请参阅 QDialog , QProgressBar , GUI 设计手册:进度指示器 , 查找文件范例 ,和 像素器范例 .
此特性保持对话框是否被隐藏,通过 reset ()
默认为 true。
访问函数:
bool | autoClose () const |
void | setAutoClose (bool close ) |
另请参阅 setAutoReset ().
此特性保持进度对话框是否调用 reset () 尽快 value () 等于 maximum ()
默认为 true。
访问函数:
bool | autoReset () const |
void | setAutoReset (bool reset ) |
另请参阅 setAutoClose ().
此特性保持标签的文本
默认文本为空字符串。
访问函数:
QString | labelText () const |
void | setLabelText (const QString & text ) |
此特性保持由进度条表示的最高值
默认为 100。
访问函数:
int | maximum () const |
void | setMaximum (int maximum ) |
此特性保持由进度条表示的最低值
默认为 0。
访问函数:
int | minimum () const |
void | setMinimum (int minimum ) |
此特性保持在对话框出现之前必须经过的时间
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 ) |
此特性保持当前已取得的进度数量。
为使进度对话框如期望般工作,应把此特性初始设为 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 ) |
[read-only]
wasCanceled
: const
bool
此特性保持对话框是否被取消
访问函数:
bool | wasCanceled () const |
构造进度对话框。
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 ().
构造进度对话框。
默认设置:
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 ().
[virtual]
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).
打开对话框并连接其 canceled () 信号到槽,指定通过 receiver and member .
将从槽断开信号连接,当关闭对话框时。
[override virtual protected]
void
QProgressDialog::
resizeEvent
(
QResizeEvent
*
event
)
重实现: QDialog::resizeEvent (QResizeEvent *).
将进度栏小部件设为 bar 。进度对话框会重置尺寸以拟合。进度对话框拥有其所有权对于进度 bar 会被删除当有必要时,因此不要使用分配在堆栈中的进度条。
将取消按钮设为 Push Button (按钮)
cancelButton
。进度对话框拥有此按钮 (会被删除当有必要时) 的所有权,因此,勿传递堆栈中的对象地址,即:使用 new() 去创建按钮。若
nullptr
被传递,则取消按钮不会被展示。
另请参阅 setCancelButtonText ().
把标签设为 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.