ProgressMeter.h

Classes

ProgressMeter -- Visual indication of a tasks progress. (full description)

class ProgressMeter

Interface

Public Members
ProgressMeter()
ProgressMeter(Double min, Double max, const String &title, const String &subtitle, const String &minlabel, const String &maxlabel, Bool estimateTime = True, Int updateEvery=1)
~ProgressMeter()
void update(Double value, Bool force=False)
Double min() const
Double max() const
Private Members
static Int (*creation_function_p)(Double, Double, const String &, const String &, const String &, const String &, Bool)
static void (*update_function_p)(Int, Double)
ProgressMeter(const ProgressMeter &)
ProgressMeter &operator=(const ProgressMeter &)

Description

Review Status

Date Reviewed:
yyyy/mm/dd

Synopsis

This class is used to provide a visual indication to the user of the progress of his task. If the process is not connected to the DO system, calls to the progress meter are NO-OP's, so you can safely use this class in general library code and it won't cause problems for processes which are not attached to the distributed object system. It also won't cause any extra stuff to be linked in to your executable in this case.

The progress meter will usually be removed from the screen once the maximum value is set, so you should not reuse the ProgressMeter after that has happened. It is harmless, but it will not result in any visual feedback for the user.

While the "min" is usually less than "max", if in fact it is greater than "max" the progress meter will count down correctly.

Example

    void calculate(uInt n) {
      Int skip = n / 200;
      ProgressMeter meter(0, n, "Title", "Subtitle", "", "", True, skip);
      for (uInt i=0; i<n; i++) {
          ... calculate ...
          meter.update(i);
      }
    }
    

Motivation

Give the user visual indication of a long-running tasks progress.

To Do

Member Description

ProgressMeter()

Makes a null progress meter, i.e. no updates to the screen are generated.

ProgressMeter(Double min, Double max, const String &title, const String &subtitle, const String &minlabel, const String &maxlabel, Bool estimateTime = True, Int updateEvery=1)

Create a progress meter with the given min and max values and labels. if estimateTime is True, an estimate of the time remaining will be made for the user. This estimate assumes that the remaining portion will compute at the same rate as the portion completed so far, so the time should not be estimated for processes which are non-linear.

Any labels which are set to the empty string will have sensible defaults supplied. In particular, minlabel and maxlabel will be set to the display the minimum and maximum values.

Normally the progress bar will be updated with every call to update(). If however you will be sending many events then you might want to update the GUI every updateEvery'th event for efficiency. Generally there's no point updating more than a couple of hundred times since the eye can't distinguish differences in the progress bar position at that level. If updateEvery is <=0, it is set to 1 for you.

~ProgressMeter()

The destruction of the meter will cause an update to be sent with the maximum value. This will usually cause the GUI window to be removed from the screen. Thus the progress meter should generally live as long as the calculation it is tracking.

void update(Double value, Bool force=False)

Double min() const

Display the min and max values of the progress meter.

Double max() const

static Int (*creation_function_p)(Double, Double, const String &, const String &, const String &, const String &, Bool)

These are set by ObjectController for executables that have the tasking system in them, otherwise they are null and this class just does no-ops.

static void (*update_function_p)(Int, Double)

ProgressMeter(const ProgressMeter &)

Undefined and inaccessible

ProgressMeter &operator=(const ProgressMeter &)