1QProgressDialog(3qt) QProgressDialog(3qt)
2
6 QProgressDialog - Feedback on the progress of a slow operation
7
9 #include <qprogressdialog.h>
10 Inherits QDialog.
12 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 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 Signals
46 void cancelled () (obsolete)
47 void canceled ()
48 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 Protected Slots
62 void forceShow ()
63
65 The QProgressDialog class provides feedback on the progress of a slow
66 operation.
67 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 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 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 The dialog automatically resets and hides itself at the end of the
89 operation. Use setAutoReset() and setAutoClose() to change this
90 behavior.
91 There are two ways of using QProgressDialog: modal and modeless.
93 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 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 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 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 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 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 [Image Omitted]
152 [Image Omitted]
154 See also QDialog, QProgressBar, GUI Design Handbook: Progress
156 Indicator, and Dialog Classes.
157
160 0, bool modal = FALSE, WFlags f = 0 )
161 Constructs a progress dialog.
162 Default settings:
164 The label text is empty.
166 The cancel button text is (translated) "Cancel".
168 The total number of steps is 100.
170 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 See also labelText, setLabel(), setCancelButtonText(),
179 setCancelButton(), and totalSteps.
180
182 cancelButtonText, int totalSteps, QWidget * creator = 0, const char *
183 name = 0, bool modal = FALSE, WFlags f = 0 )
184 Constructs a progress dialog.
185 The labelText is text used to remind the user what is progressing.
187 The cancelButtonText is the text to display on the cancel button, or 0
189 if no cancel button is to be shown.
190 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 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 See also labelText, setLabel(), setCancelButtonText(),
206 setCancelButton(), and totalSteps.
207
209 Destroys the progress dialog.
210
212 Returns TRUE if the dialog gets hidden by reset(); otherwise returns
213 FALSE. See the "autoClose" property for details.
214
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
221 Resets the progress dialog. wasCanceled() becomes TRUE until the
222 progress dialog is reset. The progress dialog becomes hidden.
223
225 This signal is emitted when the cancel button is clicked. It is
226 connected to the cancel() slot by default.
227 See also wasCanceled.
229
231 This function is obsolete. It is provided to keep old source working.
232 We strongly advise against using it in new code.
233 Use canceled() instead.
235 Examples:
237
239 Shows the dialog if it is still hidden after the algorithm has been
240 started and minimumDuration milliseconds have passed.
241 See also minimumDuration.
243
245 Returns the label's text. See the "labelText" property for details.
246
248 Returns the time that must pass before the dialog appears. See the
249 "minimumDuration" property for details.
250
252 Returns the current amount of progress made. See the "progress"
253 property for details.
254
256 Resets the progress dialog. The progress dialog becomes hidden if
257 autoClose() is TRUE.
258 See also autoClose and autoReset.
260 Example: network/ftpclient/ftpmainwindow.ui.h.
262
264 Sets whether the dialog gets hidden by reset() to b. See the
265 "autoClose" property for details.
266
268 Sets whether the progress dialog calls reset() as soon as progress()
269 equals totalSteps() to b. See the "autoReset" property for details.
270
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
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 See also setCancelButtonText().
284
286 [slot]
287 Sets the cancel button's text to cancelButtonText.
288 See also setCancelButton().
290
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 See also labelText.
297 Example: progress/progress.cpp.
299
301 Sets the label's text. See the "labelText" property for details.
302
304 Sets the time that must pass before the dialog appears to ms. See the
305 "minimumDuration" property for details.
306
308 Sets the current amount of progress made to progress. See the
309 "progress" property for details.
310
312 This is an overloaded member function, provided for convenience. It
313 behaves essentially like the above function.
314 Sets the current amount of progress to progress and the total number of
316 steps to totalSteps.
317 See also totalSteps.
319
321 Sets the total number of steps to totalSteps. See the "totalSteps"
322 property for details.
323
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
330 Returns the total number of steps. See the "totalSteps" property for
331 details.
332
334 Returns TRUE if the dialog was canceled; otherwise returns FALSE. See
335 the "wasCanceled" property for details.
336
338 Returns TRUE if the dialog was canceled; otherwise returns FALSE. See
339 the "wasCancelled" property for details.
340 Property Documentation
343 This property holds whether the dialog gets hidden by reset().
344 The default is TRUE.
346 See also autoReset.
348 Set this property's value with setAutoClose() and get this property's
350 value with autoClose().
351
353 This property holds whether the progress dialog calls reset() as soon
354 as progress() equals totalSteps().
355 The default is TRUE.
357 See also autoClose.
359 Set this property's value with setAutoReset() and get this property's
361 value with autoReset().
362
364 This property holds the label's text.
365 The default text is QString::null.
367 Set this property's value with setLabelText() and get this property's
369 value with labelText().
370
372 This property holds the time that must pass before the dialog appears.
373 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 If set to 0, the dialog is always shown as soon as any progress is set.
381 The default is 4000 milliseconds.
382 Set this property's value with setMinimumDuration() and get this
384 property's value with minimumDuration().
385
387 This property holds the current amount of progress made.
388 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 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 See also totalSteps.
400 Set this property's value with setProgress() and get this property's
402 value with progress().
403
405 This property holds the total number of steps.
406 The default is 0.
408 Set this property's value with setTotalSteps() and get this property's
410 value with totalSteps().
411
413 This property holds whether the dialog was canceled.
414 Get this property's value with wasCanceled().
416 See also progress.
418
420 This property holds whether the dialog was canceled.
421 This property is obsolete. It is provided to keep old source working.
423 We strongly advise against using it in new code.
424 Use wasCanceled instead.
426 Get this property's value with wasCancelled().
428
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
440 Generated automatically from the source code.
441
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 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 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).
456Trolltech AS 2 February 2007 QProgressDialog(3qt)