cadex::ProgressScope Class Reference

Represents a node in a hierarchy of progress scopes. More...

#include <cadex/Base/ProgressScope.hxx>

Public Member Functions
	ProgressScope (const ProgressStatus &theStatus, double theScaleInParent=-1)
	ProgressScope (const ProgressScope &theParentScope, double theScaleInParent)
	~ProgressScope ()
double	Value () const
void	SetRange (double theMin, double theMax)
void	SetRange (double theMax)
template<typename T >
void	SetRange (T theMax)
double	MinValue () const
double	MaxValue () const
ProgressStatus &	Owner () const
ProgressScope &	Parent () const
bool	IsRoot () const

Detailed Description

Represents a node in a hierarchy of progress scopes.

Scopes can be used to recursively split the range of ProgressStatus object. Scopes can only be created on stack (i.e. they cannot be dynamically allocated on heap). Base_ProgressStatus internally maintains a stack of created scopes. Whenever a scope is destroyed it notifies its parent by incrementing its value, the parent notifies its own parent and so on up to the ProgressStatus object itself.

Each scope has a range which is by default [0, 100]. A child scope is created as a portion of the parent scope (specified in the constructor). This weight information is used to compute increment in the parent range when the child scope's value changes.

The scope can be created either specifying a ProgressStatus object (in this case a parent scope will be automatically found) or with explicitly defined parent. The latter approach is required to support multi-threaded mode.

Example of usage:

ProgressStatus& aStatus;
ProgressScope aTopScope (aStatus); //take entire remaining range (in this case 100%)
{
    ProgressScope aScope (aStatus, 25); //25% of TopRange
    // Read the file
}
{
    ProgressScope aScope (aStatus); //remaining 75% of TopRange
    // Transfer the file data
}

As there can be only one current scope in the current thread, then the scope must be destroyed before its sibling can be created. Otherwise the sibling will interpret the previous scope as its parent resulting in wrong updated value. To do so, the explicit C++ scope constructions can be used as demonstrated in the example above.

Constructor & Destructor Documentation

ProgressScope() [1/2]

cadex::ProgressScope::ProgressScope	(	const ProgressStatus &	theStatus,
		double	theScaleInParent = -1 )

Creates a scope as a portion of the latest created scope in theStatus in the current thread.

theScaleInParent specifies a portion of the parent scope's remaining range, which this scope corresponds to. theScaleInParent is specified in parent's range units. If it is negative then the entire parent's range will be used by this child scope.

Before creating a child scope a parent scope must already be set up with SetRange().

To create a child scope for a parent scope created in another thread use another constructor which explcitly accepts a parent scope.

ProgressScope() [2/2]

cadex::ProgressScope::ProgressScope	(	const ProgressScope &	theParent,
		double	theScaleInParent )

Creates a scope as a portion of the explicitly specified parent scope.

This constructor must be used in multi-threaded mode if the parent scope has been created in another thread.

theScaleInParent specifies a portion of the parent scope's remaining range, which this scope corresponds to. theScaleInParent is specified in parent's range units. If it is negative then the entire parent's range will be used by this child scope.

Before creating a child scope a parent scope must already be set up with SetRange().

~ProgressScope()

cadex::ProgressScope::~ProgressScope

(

)

During destruction the parent scope will be notified and parent value will be incremented.