From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/qprogressdialog.html | 409 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 409 insertions(+) create mode 100644 doc/html/qprogressdialog.html (limited to 'doc/html/qprogressdialog.html') diff --git a/doc/html/qprogressdialog.html b/doc/html/qprogressdialog.html new file mode 100644 index 000000000..604f4ff6c --- /dev/null +++ b/doc/html/qprogressdialog.html @@ -0,0 +1,409 @@ + + + + + +TQProgressDialog Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

TQProgressDialog Class Reference

+ +

The TQProgressDialog class provides feedback on the progress of a slow operation. +More... +

#include <qprogressdialog.h> +

Inherits TQDialog. +

List of all member functions. +

Public Members

+ +

Public Slots

+ +

Signals

+ +

Properties

+ +

Protected Slots

+ +

Detailed Description

+ + +The TQProgressDialog class provides feedback on the progress of a slow operation. + + +

A progress dialog is used to give the user an indication of how long +an operation is going to take, and to demonstrate that the +application has not frozen. It can also give the user an opportunity +to abort the operation. +

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. TQProgressDialog 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 seconds by default). +

Use setTotalSteps() (or the constructor) to set the number of +"steps" in the operation and call setProgress() as the operation +progresses. The step value 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 0, and the progress dialog shows +that the operation has finished when you call setProgress() with +totalSteps() as its argument. +

The dialog automatically resets and hides itself at the end of the +operation. Use setAutoReset() and setAutoClose() to change this +behavior. +

There are two ways of using TQProgressDialog: modal and modeless. +

Using a modal TQProgressDialog is simpler for the programmer, but you +must call TQApplication::processEvents() or +TQEventLoop::processEvents(ExcludeUserInput) to keep the event loop +running to ensure that the application doesn't freeze. Do the +operation in a loop, call setProgress() at intervals, and check +for cancellation with wasCanceled(). For example: +

+TQProgressDialog progress( "Copying files...", "Abort Copy", numFiles,
+                          this, "progress", TRUE );
+for ( int i = 0; i < numFiles; i++ ) {
+    progress.setProgress( i );
+    qApp->processEvents();
+
+    if ( progress.wasCanceled() )
+        break;
+    //... copy one file
+}
+progress.setProgress( 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 TQTimer (or +TQObject::timerEvent()), TQSocketNotifier, or TQUrlOperator; or performed +in a separate thread. A TQProgressBar 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 setProgress() at intervals. For example: +

+Operation::Operation( TQObject *parent = 0 )
+    : TQObject( parent ), steps( 0 )
+{
+    pd = new TQProgressDialog( "Operation in progress.", "Cancel", 100 );
+    connect( pd, SIGNAL(canceled()), this, SLOT(cancel()) );
+    t = new TQTimer( this );
+    connect( t, SIGNAL(timeout()), this, SLOT(perform()) );
+    t->start( 0 );
+}
+
+void Operation::perform()
+{
+    pd->setProgress( steps );
+    //... perform one percent of the operation
+    steps++;
+    if ( steps > pd->totalSteps() )
+        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(), and setCancelButton(). +The functions setLabelText() and setCancelButtonText() +set the texts shown. +

+

See also TQDialog, TQProgressBar, GUI Design Handbook: Progress Indicator, and Dialog Classes. + +

Member Function Documentation

+

TQProgressDialog::TQProgressDialog ( TQWidget * creator = 0, const char * name = 0, bool modal = FALSE, WFlags f = 0 ) +

+Constructs a progress dialog. +

Default settings: +

+

The creator argument is the widget to use as the dialog's parent. +The name, modal, and the widget flags, f, are +passed to the TQDialog::TQDialog() constructor. If modal is FALSE (the +default), you must have an event loop proceeding for any redrawing +of the dialog to occur. If modal is TRUE, the dialog ensures that +events are processed when needed. +

See also labelText, setLabel(), setCancelButtonText(), setCancelButton(), and totalSteps. + +

TQProgressDialog::TQProgressDialog ( const TQString & labelText, const TQString & cancelButtonText, int totalSteps, TQWidget * creator = 0, const char * name = 0, bool modal = FALSE, WFlags f = 0 ) +

+Constructs a progress dialog. +

The labelText is text used to remind the user what is progressing. +

The cancelButtonText is the text to display on the cancel button, +or 0 if no cancel button is to be shown. +

The totalSteps is the total 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 would be 50. Before +examining the first file, call setProgress(0). As each file is +processed call setProgress(1), setProgress(2), etc., finally +calling setProgress(50) after examining the last file. +

The creator argument is the widget to use as the dialog's parent. +The name, modal, and widget flags, f, are passed to the +TQDialog::TQDialog() constructor. If modal is FALSE (the default), +you will must have an event loop proceeding for any redrawing of +the dialog to occur. If modal is TRUE, the dialog ensures that +events are processed when needed. +

See also labelText, setLabel(), setCancelButtonText(), setCancelButton(), and totalSteps. + +

TQProgressDialog::~TQProgressDialog () +

+Destroys the progress dialog. + +

bool TQProgressDialog::autoClose () const +

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

bool TQProgressDialog::autoReset () const +

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

void TQProgressDialog::cancel () [slot] +

+Resets the progress dialog. wasCanceled() becomes TRUE until +the progress dialog is reset. +The progress dialog becomes hidden. + +

void TQProgressDialog::canceled () [signal] +

+ +

This signal is emitted when the cancel button is clicked. +It is connected to the cancel() slot by default. +

See also wasCanceled. + +

void TQProgressDialog::cancelled () [signal] +

+ +

This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code. +

Use canceled() instead. + +

Examples: network/ftpclient/ftpmainwindow.ui.h and progress/progress.cpp. +

void TQProgressDialog::forceShow () [protected slot] +

+Shows the dialog if it is still hidden after the algorithm has been started +and minimumDuration milliseconds have passed. +

See also minimumDuration. + +

TQString TQProgressDialog::labelText () const +

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

int TQProgressDialog::minimumDuration () const +

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

int TQProgressDialog::progress () const +

Returns the current amount of progress made. +See the "progress" property for details. +

void TQProgressDialog::reset () [slot] +

+Resets the progress dialog. +The progress dialog becomes hidden if autoClose() is TRUE. +

See also autoClose and autoReset. + +

Example: network/ftpclient/ftpmainwindow.ui.h. +

void TQProgressDialog::setAutoClose ( bool b ) +

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

void TQProgressDialog::setAutoReset ( bool b ) +

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

void TQProgressDialog::setBar ( TQProgressBar * bar ) +

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

void TQProgressDialog::setCancelButton ( TQPushButton * cancelButton ) +

+Sets the cancel button to the push button, cancelButton. The +progress dialog takes ownership of this button which will be deleted +when necessary, so do not pass the address of an object that is on +the stack, i.e. use new() to create the button. +

See also setCancelButtonText(). + +

void TQProgressDialog::setCancelButtonText ( const TQString & cancelButtonText ) [slot] +

+Sets the cancel button's text to cancelButtonText. +

See also setCancelButton(). + +

void TQProgressDialog::setLabel ( TQLabel * label ) +

+Sets the label to label. The progress dialog resizes to fit. The +label becomes owned by the progress dialog and will be deleted when +necessary, so do not pass the address of an object on the stack. +

See also labelText. + +

Example: progress/progress.cpp. +

void TQProgressDialog::setLabelText ( const TQString & ) [slot] +

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

void TQProgressDialog::setMinimumDuration ( int ms ) [slot] +

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

void TQProgressDialog::setProgress ( int progress ) [slot] +

Sets the current amount of progress made to progress. +See the "progress" property for details. +

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

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Sets the current amount of progress to progress and the total number of +steps to totalSteps. +

See also totalSteps. + +

void TQProgressDialog::setTotalSteps ( int totalSteps ) [slot] +

Sets the total number of steps to totalSteps. +See the "totalSteps" property for details. +

TQSize TQProgressDialog::sizeHint () const [virtual] +

+Returns a size that fits the contents of the progress dialog. +The progress dialog resizes itself as retquired, so you should not +need to call this yourself. + +

int TQProgressDialog::totalSteps () const +

Returns the total number of steps. +See the "totalSteps" property for details. +

bool TQProgressDialog::wasCanceled () const +

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

bool TQProgressDialog::wasCancelled () const +

Returns TRUE if the dialog was canceled; otherwise returns FALSE. +See the "wasCancelled" property for details. +

Property Documentation

+

bool autoClose

+

This property holds whether the dialog gets hidden by reset(). +

The default is TRUE. +

See also autoReset. + +

Set this property's value with setAutoClose() and get this property's value with autoClose(). +

bool autoReset

+

This property holds whether the progress dialog calls reset() as soon as progress() equals totalSteps(). +

The default is TRUE. +

See also autoClose. + +

Set this property's value with setAutoReset() and get this property's value with autoReset(). +

TQString labelText

+

This property holds the label's text. +

The default text is TQString::null. + +

Set this property's value with setLabelText() and get this property's value with labelText(). +

int minimumDuration

+

This property holds the time that must pass before the dialog appears. +

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 tquickly 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. +

If set to 0, the dialog is always shown as soon as any progress is +set. The default is 4000 milliseconds. + +

Set this property's value with setMinimumDuration() and get this property's value with minimumDuration(). +

int progress

+

This property holds the current amount of progress made. +

For the progress dialog to work as expected, you should initially set +this property to 0 and finally set it to +TQProgressDialog::totalSteps(); you can call setProgress() any number of times +in-between. +

Warning: If the progress dialog is modal +(see TQProgressDialog::TQProgressDialog()), +this function calls TQApplication::processEvents(), so take care that +this does not cause undesirable re-entrancy in your code. For example, +don't use a TQProgressDialog inside a paintEvent()! +

See also totalSteps. + +

Set this property's value with setProgress() and get this property's value with progress(). +

int totalSteps

+

This property holds the total number of steps. +

The default is 0. + +

Set this property's value with setTotalSteps() and get this property's value with totalSteps(). +

bool wasCanceled

+

This property holds whether the dialog was canceled. +

Get this property's value with wasCanceled(). +

See also progress. + +

bool wasCancelled

+

This property holds whether the dialog was canceled. +

This property is obsolete. It is provided to keep old source working. We strongly advise against using it in new code. +

Use wasCanceled instead. + +

Get this property's value with wasCancelled(). + +

+This file is part of the TQt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.

+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.1