QProgressDialog类参考

QProgressDialog类提供了慢操作的进度的反馈。详情请见……

#include <qprogressdialog.h>

继承了QDialog。

所有成员函数的列表。

公有成员

QProgressDialog ( QWidget * creator = 0, const char * name = 0, bool modal = FALSE, WFlags f = 0 )
QProgressDialog ( const QString & labelText, const QString & cancelButtonText, int totalSteps, QWidget * creator = 0, const char * name = 0, bool modal = FALSE, WFlags f = 0 )
~QProgressDialog ()
void setLabel ( QLabel * label )
void setCancelButton ( QPushButton * cancelButton )
void setBar ( QProgressBar * bar )
bool wasCancelled () const
int totalSteps () const
int progress () const
virtual QSize sizeHint () const
QString labelText () const
void setAutoReset ( bool b )
bool autoReset () const
void setAutoClose ( bool b )
bool autoClose () const
int minimumDuration () const

公有槽

void cancel ()
void reset ()
void setTotalSteps ( int totalSteps )
void setProgress ( int progress )
void setLabelText ( const QString & )
void setCancelButtonText ( const QString & cancelButtonText )
void setMinimumDuration ( int ms )

信号

void cancelled ()

属性

bool autoClose - 通过reset()对话框是否隐藏
bool autoReset - 一旦progress()等于totalSteps()，进度对话框是否调用reset()
QString labelText - 标签的文本
int minimumDuration - 进度就应该在对话框打开之前运行的时间
int progress - 进度当前的进度
int totalSteps - 步数的总量
bool wasCancelled - 对话框是否被取消 （只读）

保护槽

void forceShow ()

详细描述

QProgressDialog类提供了慢操作的进度的反馈。

进度对话框用于给用户这个操作还要有多长时间的指示，并且证明这个应用程序还没有冻结。它也给用于一个中止这个操作运行的机会。

进度对话框的一个常见问题是很难知道什么时候使用它们，操作在不同的硬件会占用不同的时间。QProgessDialog提供了对这个问题的解决方案：它估计操作将占用的时间（基于没步的时间），并且如果它超过minimumDuration()（默认为4秒）才显示自己。

使用setTotalSteps()（或者在构造函数中）设置操作中的“步”数并且调用setProgress()作为操作进度。步值的选择是任意的。它可以是复制的文件数，接收的字节数，在你的算法的主循环中的反复次数，或者一些其它的适合单元。进度从0开始，并且当你把totalSteps()作为参数调用setProgress()，这个进度对话框会显示这个操作已经完成。

对话框会在操作结束的时候自动重置并且隐藏自己。使用setAutoReset()和setAutoClose()可以改变这个行为。

这里有使用QProgressDialog的两种方法：模式和非模式。

对于程序员，使用模式QProgressDialog是更简单的，但是你必须调用qApp->processEvents()来保持事件循环的运行来确保应用程序没有冻结。在循环中执行这个操作，在间隔中调用setProgress()，并且检查wasCancelled()的取消。例如：

QProgressDialog progress( "Copying files...", "Abort Copy", numFiles,
                          this, "progress", TRUE );
for ( int i = 0; i < numFiles; i++ ) {
    progress.setProgress( i );
    qApp->processEvents();

    if ( progress.wasCancelled() )
        break;
    //……复制文件
}
progress.setProgress( numFiles );

非模式进度对话框适合发生在后台的操作，用户还可以和应用程序进行交互。这样的操作通常是基于QTimer（或者QObject::timerEvent()）、QSocketNotifier或QUrlOperator，或者在一个独立的进度中执行。你的主窗口的状态条中的QProgressBar常常可以做为模式进度对话框的替代。

你需要拥有一个正在运行的时间循环，把cancelled()信号和停止这个操作的槽连接起来，并且在间隔中调用setProgress()。例如：

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

void Operation::perform()
{
    pd->setProgress( steps );
    //……执行操作的一个半分比
    steps++;
    if ( steps > pd->totalSteps() )
        t->stop();
}

void Operation::cancel()
{
    t->stop();
    //……清除
}

你可以通过使用setLabel()、setBar()和setCancelButton()用自定制的窗口部件来替换子窗口部件来定制这两种进度对话框。

也可以参考QDialog、QProgressBar、图形用户界面设计手册：进度指示器和Dialog Classes。

成员函数文档

QProgressDialog::QProgressDialog ( QWidget * creator = 0, const char * name = 0, bool modal = FALSE, WFlags f = 0 )

构造一个进度对话框。

默认设置：

标签文本为空。
取消按钮文本是（被翻译的）“Cancel”。
步数的总量是100。

creator窗口部件的顶级父对象变为这个对话框的父对象。name、modal和窗口部件标记f被传递给QDialog::QDialog()的构造函数。如果modal为假（默认），你必须有一个正在进行的事件循环来重新绘制这个对话框的变化。如果modal为真，这个对话框确保当需要的时候事件会被处理。

也可以参考labelText、setLabel()、setCancelButtonText()、setCancelButton()和totalSteps。

QProgressDialog::QProgressDialog ( const QString & labelText, const QString & cancelButtonText, int totalSteps, QWidget * creator = 0, const char * name = 0, bool modal = FALSE, WFlags f = 0 )

构造一个进度对话框。

labelText是用于提行用户什么正在进行的文本。

cancelButtonText是显示在取消按钮上的文本，或者如果没有取消按钮被显示就为0。

totalSteps是这个进度对话框显示进度的操作的总步数。例如，如果这个操作检测50个文件，这个值就应该为50。在检测第一个文件之前，调用setProgress(0)。每一个问卷被处理的时候，调用setProgress(1)、setProgress(2)等等，在检测完最后一个文件之后调用setProgress(50)。

name、modal和窗口部件标记f被传递给QDialog::QDialog()的构造函数。如果modal为假（默认），你必须有一个正在进行的事件循环来重新绘制这个对话框的变化。如果modal为真，这个对话框确保当需要的时候事件会被处理。

creator参数是用来做为这个对话框的父对象的窗口部件。如果creator不是一个顶级窗口部件，传递给QDialog构造函数的这个参数将为0。

也可以参考labelText、setLabel()、setCancelButtonText()、setCancelButton()和totalSteps。

QProgressDialog::~QProgressDialog ()

销毁这个进度对话框。

bool QProgressDialog::autoClose () const

如果通过reset()对话框是隐藏的，返回真，否则返回假。详细情况请参考“autoClose”属性。

bool QProgressDialog::autoReset () const

如果一旦progress()等于totalSteps()，进度对话框调用reset()，返回真，否则返回假。详细情况请参考“autoReset”属性。

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

重置这个进度对话框。知道这个进度对话框被重置了，wasCancelled()变为真。这个进度对话框变隐藏了。

void QProgressDialog::cancelled () `[信号]`

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

也可以参考wasCancelled。

实例：progress/progress.cpp。

void QProgressDialog::forceShow () `[保护槽]`

如果在算法已经开始并且minimumDuration毫秒数已经过去之后它还被隐藏，显示这个对话框。

也可以参考minimumDuration。

QString QProgressDialog::labelText () const

返回标签的文本。详细情况请参考“labelText”属性。

int QProgressDialog::minimumDuration () const

返回进度就应该在对话框打开之前运行的时间。详细情况请参考“minimumDuration”属性。

int QProgressDialog::progress () const

返回进度当前的进度。详细情况请参考“progress”属性。

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

重置这个进度对话框。如果autoClose()为真，进度对话框变为隐藏。

也可以参考autoClose和autoReset。

void QProgressDialog::setAutoClose ( bool b )

设置通过reset()对话框是否隐藏为b。详细情况请参考“autoClose”属性。

void QProgressDialog::setAutoReset ( bool b )

设置一旦progress()等于totalSteps()，进度对话框是否调用reset()为b。详细情况请参考“autoReset”属性。

void QProgressDialog::setBar ( QProgressBar * bar )

设置进度条窗口部件为bar。进度对话框会重新定义大小来适合它。进度对话框会得到进度条bar，bar当需要的时候会被删除，所以不要在使用在栈中分配的进度条。

void QProgressDialog::setCancelButton ( QPushButton * cancelButton )

设置取消按钮为推动按钮cancelButton。进度对话框会得到这个按钮，它当需要的时候会被删除，所以不要在使用在栈中分配的对象，也就是使用new()来创建这个按钮。

也可以参考setCancelButtonText()。

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

设置取消按钮的文本为cancelButtonText。

也可以参考setCancelButton()。

void QProgressDialog::setLabel ( QLabel * label )

设置标签为label。进度对话框会重新定义大小来适合它。进度对话框会得到这个标签，它当需要的时候会被删除，所以不要在使用在栈中分配的对象，也就是使用new()来创建这个标签。

也可以参考labelText。

实例：progress/progress.cpp。

void QProgressDialog::setLabelText ( const QString & ) `[槽]`

设置标签的文本。详细情况请参考“labelText”属性。

void QProgressDialog::setMinimumDuration ( int ms ) `[槽]`

设置进度就应该在对话框打开之前运行的时间为ms。详细情况请参考“minimumDuration”属性。

void QProgressDialog::setProgress ( int progress ) `[槽]`

设置进度当前的进度为progress。详细情况请参考“progress”属性。

void QProgressDialog::setTotalSteps ( int totalSteps ) `[槽]`

设置步数的总量为totalSteps。详细情况请参考“totalSteps”属性。

QSize QProgressDialog::sizeHint () const `[虚]`

返回适合这个进度对话框内容的大小。如果需要进度对话框重新定义自己的大小，所以你应该不需要自己调用这个。

int QProgressDialog::totalSteps () const

返回步数的总量。详细情况请参考“totalSteps”属性。

bool QProgressDialog::wasCancelled () const

如果对话框被取消，返回真，否则返回假。详细情况请参考“wasCancelled”属性。

属性文档

bool autoClose

这个属性保存的是通过reset()对话框是否隐藏。

默认为真。

也可以参考autoReset。

通过setAutoClose()设置属性值并且通过autoClose()来获得属性值。

bool autoReset

这个属性保存的是一旦progress()等于totalSteps()，进度对话框是否调用reset()。

默认为真。

也可以参考autoClose。

通过setAutoReset()设置属性值并且通过autoReset()来获得属性值。

QString labelText

这个属性保存的是标签的文本。

默认文本为QString::null。

通过setLabelText()设置属性值并且通过labelText()来获得属性值。

int minimumDuration

这个属性保存的是进度就应该在对话框打开之前运行的时间。

如果正在进行的进度任务的被期待持续时间小于这个最小持续时间，对话框将不会显示。

如果被设置为0，一旦任何进度被设置，这个对话框就一直被显示。默认为4000毫秒。

通过setMinimumDuration()设置属性值并且通过minimumDuration()来获得属性值。

int progress

这个属性保存的是进度当前的进度。

对于正如所期望的运行的进度对话框，你应该初始化设置这个属性为0并且最后把它设置为QProgressDialog::totalSteps()，你可以在这之间调用setProgress()任意次。

警告： 如果进度对话框是模式的（请参考QProgressDialog::QProgressDialog())），这个函数调用QApplication::processEvents()，所以注意这个函数不会导致不受欢迎的重新进入你的代码。例如，不要在paintEvent()中使用QProgressDialog！

也可以参考totalSteps。

通过setProgress()设置属性值并且通过progress()来获得属性值。

int totalSteps

这个属性保存的是步数的总量。

默认为0。

通过setTotalSteps()设置属性值并且通过totalSteps()来获得属性值。

bool wasCancelled

这个属性保存的是对话框是否被取消。

也可以参考progress。

Trademarks

译者:Cavendish

Qt 3.0.5版