1QProgressDialog(3qt)                                      QProgressDialog(3qt)
2
3
4

NAME

6       QProgressDialog - Feedback on the progress of a slow operation
7

SYNOPSIS

9       #include <qprogressdialog.h>
10
11       Inherits QDialog.
12
13   Public Members
14       QProgressDialog ( QWidget * creator = 0, const char * name = 0, bool
15           modal = FALSE, WFlags f = 0 )
16       QProgressDialog ( const QString & labelText, const QString &
17           cancelButtonText, int totalSteps, QWidget * creator = 0, const char
18           * name = 0, bool modal = FALSE, WFlags f = 0 )
19       ~QProgressDialog ()
20       void setLabel ( QLabel * label )
21       void setCancelButton ( QPushButton * cancelButton )
22       void setBar ( QProgressBar * bar )
23       bool wasCancelled () const  (obsolete)
24       bool wasCanceled () const
25       int totalSteps () const
26       int progress () const
27       virtual QSize sizeHint () const
28       QString labelText () const
29       void setAutoReset ( bool b )
30       bool autoReset () const
31       void setAutoClose ( bool b )
32       bool autoClose () const
33       int minimumDuration () const
34
35   Public Slots
36       void cancel ()
37       void reset ()
38       void setTotalSteps ( int totalSteps )
39       void setProgress ( int progress )
40       void setProgress ( int progress, int totalSteps )
41       void setLabelText ( const QString & )
42       void setCancelButtonText ( const QString & cancelButtonText )
43       void setMinimumDuration ( int ms )
44
45   Signals
46       void cancelled ()  (obsolete)
47       void canceled ()
48
49   Properties
50       bool autoClose - whether the dialog gets hidden by reset()
51       bool autoReset - whether the progress dialog calls reset() as soon as
52           progress() equals totalSteps()
53       QString labelText - the label's text
54       int minimumDuration - the time that must pass before the dialog appears
55       int progress - the current amount of progress made
56       int totalSteps - the total number of steps
57       bool wasCanceled - whether the dialog was canceled  (read only)
58       bool wasCancelled - whether the dialog was canceled  (read only)
59           (obsolete)
60
61   Protected Slots
62       void forceShow ()
63

DESCRIPTION

65       The QProgressDialog class provides feedback on the progress of a slow
66       operation.
67
68       A progress dialog is used to give the user an indication of how long an
69       operation is going to take, and to demonstrate that the application has
70       not frozen. It can also give the user an opportunity to abort the
71       operation.
72
73       A common problem with progress dialogs is that it is difficult to know
74       when to use them; operations take different amounts of time on
75       different hardware. QProgressDialog offers a solution to this problem:
76       it estimates the time the operation will take (based on time for
77       steps), and only shows itself if that estimate is beyond
78       minimumDuration() (4 seconds by default).
79
80       Use setTotalSteps() (or the constructor) to set the number of" steps"
81       in the operation and call setProgress() as the operation progresses.
82       The step value can be chosen arbitrarily. It can be the number of files
83       copied, the number of bytes received, the number of iterations through
84       the main loop of your algorithm, or some other suitable unit. Progress
85       starts at 0, and the progress dialog shows that the operation has
86       finished when you call setProgress() with totalSteps() as its argument.
87
88       The dialog automatically resets and hides itself at the end of the
89       operation. Use setAutoReset() and setAutoClose() to change this
90       behavior.
91
92       There are two ways of using QProgressDialog: modal and modeless.
93
94       Using a modal QProgressDialog is simpler for the programmer, but you
95       must call QApplication::processEvents() or
96       QEventLoop::processEvents(ExcludeUserInput) to keep the event loop
97       running to ensure that the application doesn't freeze. Do the operation
98       in a loop, call setProgress() at intervals, and check for cancellation
99       with wasCanceled(). For example:
100
101       QProgressDialog progress( "Copying files...", "Abort Copy", numFiles,
102                                 this, "progress", TRUE );
103       for ( int i = 0; i < numFiles; i++ ) {
104           progress.setProgress( i );
105           qApp->processEvents();
106           if ( progress.wasCanceled() )
107               break;
108           //... copy one file
109       }
110       progress.setProgress( numFiles );
111
112       A modeless progress dialog is suitable for operations that take place
113       in the background, where the user is able to interact with the
114       application. Such operations are typically based on QTimer (or
115       QObject::timerEvent()), QSocketNotifier, or QUrlOperator; or performed
116       in a separate thread. A QProgressBar in the status bar of your main
117       window is often an alternative to a modeless progress dialog.
118
119       You need to have an event loop to be running, connect the canceled()
120       signal to a slot that stops the operation, and call setProgress() at
121       intervals. For example:
122
123       Operation::Operation( QObject *parent = 0 )
124           : QObject( parent ), steps( 0 )
125       {
126           pd = new QProgressDialog( "Operation in progress.", "Cancel", 100 );
127           connect( pd, SIGNAL(canceled()), this, SLOT(cancel()) );
128           t = new QTimer( this );
129           connect( t, SIGNAL(timeout()), this, SLOT(perform()) );
130           t->start( 0 );
131       }
132       void Operation::perform()
133       {
134           pd->setProgress( steps );
135           //... perform one percent of the operation
136           steps++;
137           if ( steps > pd->totalSteps() )
138               t->stop();
139       }
140       void Operation::cancel()
141       {
142           t->stop();
143           //... cleanup
144       }
145
146       In both modes the progress dialog may be customized by replacing the
147       child widgets with custom widgets by using setLabel(), setBar(), and
148       setCancelButton(). The functions setLabelText() and
149       setCancelButtonText() set the texts shown.
150
151                                   [Image Omitted]
152
153                                   [Image Omitted]
154
155       See also QDialog, QProgressBar, GUI Design Handbook: Progress
156       Indicator, and Dialog Classes.
157

MEMBER FUNCTION DOCUMENTATION

QProgressDialog::QProgressDialog ( QWidget * creator = 0, const char * name =

160       0, bool modal = FALSE, WFlags f = 0 )
161       Constructs a progress dialog.
162
163       Default settings:
164
165       The label text is empty.
166
167       The cancel button text is (translated) "Cancel".
168
169       The total number of steps is 100.
170
171       The creator argument is the widget to use as the dialog's parent. The
172       name, modal, and the widget flags, f, are passed to the
173       QDialog::QDialog() constructor. If modal is FALSE (the default), you
174       must have an event loop proceeding for any redrawing of the dialog to
175       occur. If modal is TRUE, the dialog ensures that events are processed
176       when needed.
177
178       See also labelText, setLabel(), setCancelButtonText(),
179       setCancelButton(), and totalSteps.
180

QProgressDialog::QProgressDialog ( const QString & labelText, const QString &

182       cancelButtonText, int totalSteps, QWidget * creator = 0, const char *
183       name = 0, bool modal = FALSE, WFlags f = 0 )
184       Constructs a progress dialog.
185
186       The labelText is text used to remind the user what is progressing.
187
188       The cancelButtonText is the text to display on the cancel button, or 0
189       if no cancel button is to be shown.
190
191       The totalSteps is the total number of steps in the operation for which
192       this progress dialog shows progress. For example, if the operation is
193       to examine 50 files, this value would be 50. Before examining the first
194       file, call setProgress(0). As each file is processed call
195       setProgress(1), setProgress(2), etc., finally calling setProgress(50)
196       after examining the last file.
197
198       The creator argument is the widget to use as the dialog's parent. The
199       name, modal, and widget flags, f, are passed to the QDialog::QDialog()
200       constructor. If modal is FALSE (the default), you will must have an
201       event loop proceeding for any redrawing of the dialog to occur. If
202       modal is TRUE, the dialog ensures that events are processed when
203       needed.
204
205       See also labelText, setLabel(), setCancelButtonText(),
206       setCancelButton(), and totalSteps.
207

QProgressDialog::~QProgressDialog ()

209       Destroys the progress dialog.
210

bool QProgressDialog::autoClose () const

212       Returns TRUE if the dialog gets hidden by reset(); otherwise returns
213       FALSE. See the "autoClose" property for details.
214

bool QProgressDialog::autoReset () const

216       Returns TRUE if the progress dialog calls reset() as soon as progress()
217       equals totalSteps(); otherwise returns FALSE. See the "autoReset"
218       property for details.
219

void QProgressDialog::cancel () [slot]

221       Resets the progress dialog. wasCanceled() becomes TRUE until the
222       progress dialog is reset. The progress dialog becomes hidden.
223

void QProgressDialog::canceled () [signal]

225       This signal is emitted when the cancel button is clicked. It is
226       connected to the cancel() slot by default.
227
228       See also wasCanceled.
229

void QProgressDialog::cancelled () [signal]

231       This function is obsolete. It is provided to keep old source working.
232       We strongly advise against using it in new code.
233
234       Use canceled() instead.
235
236       Examples:
237

void QProgressDialog::forceShow () [protected slot]

239       Shows the dialog if it is still hidden after the algorithm has been
240       started and minimumDuration milliseconds have passed.
241
242       See also minimumDuration.
243

QString QProgressDialog::labelText () const

245       Returns the label's text. See the "labelText" property for details.
246

int QProgressDialog::minimumDuration () const

248       Returns the time that must pass before the dialog appears. See the
249       "minimumDuration" property for details.
250

int QProgressDialog::progress () const

252       Returns the current amount of progress made. See the "progress"
253       property for details.
254

void QProgressDialog::reset () [slot]

256       Resets the progress dialog. The progress dialog becomes hidden if
257       autoClose() is TRUE.
258
259       See also autoClose and autoReset.
260
261       Example: network/ftpclient/ftpmainwindow.ui.h.
262

void QProgressDialog::setAutoClose ( bool b )

264       Sets whether the dialog gets hidden by reset() to b. See the
265       "autoClose" property for details.
266

void QProgressDialog::setAutoReset ( bool b )

268       Sets whether the progress dialog calls reset() as soon as progress()
269       equals totalSteps() to b. See the "autoReset" property for details.
270

void QProgressDialog::setBar ( QProgressBar * bar )

272       Sets the progress bar widget to bar. The progress dialog resizes to
273       fit. The progress dialog takes ownership of the progress bar which will
274       be deleted when necessary, so do not use a progress bar allocated on
275       the stack.
276

void QProgressDialog::setCancelButton ( QPushButton * cancelButton )

278       Sets the cancel button to the push button, cancelButton. The progress
279       dialog takes ownership of this button which will be deleted when
280       necessary, so do not pass the address of an object that is on the
281       stack, i.e. use new() to create the button.
282
283       See also setCancelButtonText().
284

void QProgressDialog::setCancelButtonText ( const QString & cancelButtonText )

286       [slot]
287       Sets the cancel button's text to cancelButtonText.
288
289       See also setCancelButton().
290

void QProgressDialog::setLabel ( QLabel * label )

292       Sets the label to label. The progress dialog resizes to fit. The label
293       becomes owned by the progress dialog and will be deleted when
294       necessary, so do not pass the address of an object on the stack.
295
296       See also labelText.
297
298       Example: progress/progress.cpp.
299

void QProgressDialog::setLabelText ( const QString & ) [slot]

301       Sets the label's text. See the "labelText" property for details.
302

void QProgressDialog::setMinimumDuration ( int ms ) [slot]

304       Sets the time that must pass before the dialog appears to ms. See the
305       "minimumDuration" property for details.
306

void QProgressDialog::setProgress ( int progress ) [slot]

308       Sets the current amount of progress made to progress. See the
309       "progress" property for details.
310

void QProgressDialog::setProgress ( int progress, int totalSteps ) [slot]

312       This is an overloaded member function, provided for convenience. It
313       behaves essentially like the above function.
314
315       Sets the current amount of progress to progress and the total number of
316       steps to totalSteps.
317
318       See also totalSteps.
319

void QProgressDialog::setTotalSteps ( int totalSteps ) [slot]

321       Sets the total number of steps to totalSteps. See the "totalSteps"
322       property for details.
323

QSize QProgressDialog::sizeHint () const [virtual]

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

int QProgressDialog::totalSteps () const

330       Returns the total number of steps. See the "totalSteps" property for
331       details.
332

bool QProgressDialog::wasCanceled () const

334       Returns TRUE if the dialog was canceled; otherwise returns FALSE. See
335       the "wasCanceled" property for details.
336

bool QProgressDialog::wasCancelled () const

338       Returns TRUE if the dialog was canceled; otherwise returns FALSE. See
339       the "wasCancelled" property for details.
340
341   Property Documentation

bool autoClose

343       This property holds whether the dialog gets hidden by reset().
344
345       The default is TRUE.
346
347       See also autoReset.
348
349       Set this property's value with setAutoClose() and get this property's
350       value with autoClose().
351

bool autoReset

353       This property holds whether the progress dialog calls reset() as soon
354       as progress() equals totalSteps().
355
356       The default is TRUE.
357
358       See also autoClose.
359
360       Set this property's value with setAutoReset() and get this property's
361       value with autoReset().
362

QString labelText

364       This property holds the label's text.
365
366       The default text is QString::null.
367
368       Set this property's value with setLabelText() and get this property's
369       value with labelText().
370

int minimumDuration

372       This property holds the time that must pass before the dialog appears.
373
374       If the expected duration of the task is less than the minimumDuration,
375       the dialog will not appear at all. This prevents the dialog popping up
376       for tasks that are quickly over. For tasks that are expected to exceed
377       the minimumDuration, the dialog will pop up after the minimumDuration
378       time or as soon as any progress is set.
379
380       If set to 0, the dialog is always shown as soon as any progress is set.
381       The default is 4000 milliseconds.
382
383       Set this property's value with setMinimumDuration() and get this
384       property's value with minimumDuration().
385

int progress

387       This property holds the current amount of progress made.
388
389       For the progress dialog to work as expected, you should initially set
390       this property to 0 and finally set it to QProgressDialog::totalSteps();
391       you can call setProgress() any number of times in-between.
392
393       Warning: If the progress dialog is modal (see
394       QProgressDialog::QProgressDialog()), this function calls
395       QApplication::processEvents(), so take care that this does not cause
396       undesirable re-entrancy in your code. For example, don't use a
397       QProgressDialog inside a paintEvent()!
398
399       See also totalSteps.
400
401       Set this property's value with setProgress() and get this property's
402       value with progress().
403

int totalSteps

405       This property holds the total number of steps.
406
407       The default is 0.
408
409       Set this property's value with setTotalSteps() and get this property's
410       value with totalSteps().
411

bool wasCanceled

413       This property holds whether the dialog was canceled.
414
415       Get this property's value with wasCanceled().
416
417       See also progress.
418

bool wasCancelled

420       This property holds whether the dialog was canceled.
421
422       This property is obsolete. It is provided to keep old source working.
423       We strongly advise against using it in new code.
424
425       Use wasCanceled instead.
426
427       Get this property's value with wasCancelled().
428
429

SEE ALSO

431       http://doc.trolltech.com/qprogressdialog.html
432       http://www.trolltech.com/faq/tech.html
433
435       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
436       license file included in the distribution for a complete license
437       statement.
438

AUTHOR

440       Generated automatically from the source code.
441

BUGS

443       If you find a bug in Qt, please report it as described in
444       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
445       help you. Thank you.
446
447       The definitive Qt documentation is provided in HTML format; it is
448       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
449       web browser. This man page is provided as a convenience for those users
450       who prefer man pages, although this format is not officially supported
451       by Trolltech.
452
453       If you find errors in this manual page, please report them to qt-
454       bugs@trolltech.com.  Please include the name of the manual page
455       (qprogressdialog.3qt) and the Qt version (3.3.8).
456
457
458
459Trolltech AS                    2 February 2007           QProgressDialog(3qt)
Impressum