class Progress

This is a wrapper around QProgressDialog for classes which want to report progress information, but don't want to know whether there's a QApplication which needs to have processEvents() called, or whether other chunks of code already have a progress dialog up, etc. More...

Full namefun::Progress
Definition#include <fun/Progress.h>
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Methods

Public Static Methods


Detailed Description

This is a wrapper around QProgressDialog for classes which want to report progress information, but don't want to know whether there's a QApplication which needs to have processEvents() called, or whether other chunks of code already have a progress dialog up, etc.

If there are places where you notice multiple progress dialogs popping up in series, you can fix that by nesting them in an outer start()/finish() pair. For example, when loubetomy loads a map, it performs three steps:

  1. creates a SerialTree from the given file.
  2. deserializes the HexMap from the resulting SerialTree.
  3. gives the resulting HexMap to HexMapView so that the necessary graphic bits can be created.
All of those steps are performed by chunks of library code which don't know about each other--and loubetomy doesn't want to know which of them, if any, report progress information--so loubetomy calls Progress::start(), does the first step, calls Progress::update() (which tells it whether the user hit the cancel button while SerialTree was doing its thing), then deserializes the HexMap, then calls Progress::update() again (which, again, tells it whether the user hit the cancel button while the HexMap was deserializing itself), then gives the map to its HexMapView, & finally calls Progress::finish() to make the dialog go away (if one was displayed).

(If the library code was responsible for fondling the progress dialog itself, it would be more complicated, and either there would be gaps when the program was busy but no dialog was up, or there would be points when two progress dialogs were up, & in either case it would be messier for loubetomy to know whether the user had hit "cancel" in the dialog displayed by the library.)

void  start (const QString &operation, int steps, bool canCancel = true)

start

[static]

Indicates that some operation is starting for which progress will be reported. Whether this does anything depends on a couple of things:

Parameters:
operationA description of the operation being performed. This will be displayed in the progress dialog, if any.
stepsThe number of steps in this operation.
canCancelWhether or not this operation can be cancelled by the user.

void  begin (const QString &operation, int steps, bool canCancel = true)

begin

[static]

Same as start(), so that you don't have to remember whether it's "start" or "begin".

bool  update (int step)

update

[static]

This updates the existing progress dialog, if any. If a progress dialog is up, and the user has hit cancel (or if the user hit cancel during some nested operation), this returns true; otherwise it returns false.

If the user has inidicated that they want to cancel the operation, you still need to call finish().

If no QApplication has been passed to setQApplication(), then update() doesn't do anything, and just returns false.

Parameters:
stepwhich step has been completed.

void  finish ()

finish

[static]

Indicates that the operation is done (even if it's "done" because it was cancelled by the user). What this does depends on several things:

void  end ()

end

[static]

Same as finish(), so that you don't have to remember whether it's "finish" or "end".

void  suspend ()

suspend

[static]

Causes the progress dialog, if any, to become hidden. You want to do this if you need to pop up a confirmation dialog in the middle of some operation; otherwise the progress dialog is probably going to be rather rude about popping up in front of the confirmation dialog & demanding attention. Regardless of subsequent calls to update(), the progress dialog will not be shown again until resume() or finish() is called. (In the case of finish(), the dialog won't be shown again until the start of the next non-nested operation.)

suspend()/resume() pairs can be nested. Calling suspend() before start() has no effect.

void  resume ()

resume

[static]

Prints a randomly-selected QUB developer's resumé on stdout. Err, wait, apparently it causes the progress dialog, if any, to resume being shown after a call to suspend(). (It may not actually show itself until the next call to update().)

Note that suspend()/resume() calls may be nested; the dialog will not actually be displayed until after the outermost resume() call.

bool  cancelled ()

cancelled

[static]

Returns true if this operation (or a nested one) has been cancelled. (The other way to find this out is from the return value from update().)

void  setQApplication (QApplication *)

setQApplication

[static]

Sets the QApplication whose processEvents() will be called during update(). If you create a QApplication, just call this in your main() and forget about it.

If this is never called (or is called with a NULL QApplication), the other progress methods don't really do anything.

 ~Progress ()

~Progress


Generated by: stephan on cheyenne on Mon Aug 11 14:06:52 2003, using kdoc 2.0a54.