Message_ProgressIndicator Class Reference

Defines abstract interface from program to the user. This includes progress indication and user break mechanisms. More...

#include <Message_ProgressIndicator.hxx>

Inheritance diagram for Message_ProgressIndicator:

Protected Member Functions
Virtual methods to be defined by descendant.
virtual Standard_Boolean	UserBreak ()
	Should return True if user has sent a break signal.
virtual void	Show (const Message_ProgressScope &theScope, const Standard_Boolean isForce)=0
	Virtual method to be defined by descendant. Should update presentation of the progress indicator.
virtual void	Reset ()
	Call-back method called by Start(), can be redefined by descendants if some actions are needed when the indicator is restarted.

Auxiliary methods
Standard_Real	GetPosition () const
	Returns total progress position ranged from 0 to 1. Should not be called concurrently while the progress is advancing, except from implementation of method Show().
	~Message_ProgressIndicator ()
	Destructor.
	Message_ProgressIndicator ()
	Constructor.

Initialization of progress indication
Message_ProgressRange	Start ()
	Resets the indicator to zero, calls Reset(), and returns the range. This range refers to the scope that has no name and is initialized with max value 1 and step 1. Use this method to get the top level range for progress indication.
static Message_ProgressRange	Start (const Handle< Message_ProgressIndicator > &theProgress)
	If argument is non-null handle, returns theProgress->Start(). Otherwise, returns dummy range that can be safely used in the algorithms but not bound to progress indicator.

Additional Inherited Members
Public Types inherited from Standard_Transient
typedef void	base_type
	Returns a type descriptor about this object.
Public Member Functions inherited from Standard_Transient
	Standard_Transient ()
	Empty constructor.
	Standard_Transient (const Standard_Transient &)
	Copy constructor – does nothing.
Standard_Transient &	operator= (const Standard_Transient &)
	Assignment operator, needed to avoid copying reference counter.
virtual	~Standard_Transient ()
	Destructor must be virtual.
virtual const opencascade::handle< Standard_Type > &	DynamicType () const
	Returns a type descriptor about this object.
Standard_Boolean	IsInstance (const opencascade::handle< Standard_Type > &theType) const
	Returns a true value if this is an instance of Type.
Standard_Boolean	IsInstance (const Standard_CString theTypeName) const
	Returns a true value if this is an instance of TypeName.
Standard_Boolean	IsKind (const opencascade::handle< Standard_Type > &theType) const
	Returns true if this is an instance of Type or an instance of any class that inherits from Type. Note that multiple inheritance is not supported by OCCT RTTI mechanism.
Standard_Boolean	IsKind (const Standard_CString theTypeName) const
	Returns true if this is an instance of TypeName or an instance of any class that inherits from TypeName. Note that multiple inheritance is not supported by OCCT RTTI mechanism.
Standard_Transient *	This () const
	Returns non-const pointer to this object (like const_cast). For protection against creating handle to objects allocated in stack or call from constructor, it will raise exception Standard_ProgramError if reference counter is zero.
Standard_Integer	GetRefCount () const noexcept
	Get the reference counter of this object.
void	IncrementRefCounter () noexcept
	Increments the reference counter of this object.
Standard_Integer	DecrementRefCounter () noexcept
	Decrements the reference counter of this object; returns the decremented value.
virtual void	Delete () const
	Memory deallocator for transient classes.
Static Public Member Functions inherited from Standard_Transient
static constexpr const char *	get_type_name ()
	Returns a type descriptor about this object.
static const opencascade::handle< Standard_Type > &	get_type_descriptor ()
	Returns type descriptor of Standard_Transient class.

Detailed Description

Defines abstract interface from program to the user. This includes progress indication and user break mechanisms.

The progress indicator controls the progress scale with range from 0 to 1.

Method Start() should be called once, at the top level of the call stack, to reset progress indicator and get access to the root range:

Handle(Message_ProgressIndicator) aProgress = ...;
anAlgorithm.Perform (aProgress->Start());

To advance the progress indicator in the algorithm, use the class Message_ProgressScope that provides iterator-like interface for incrementing progress; see documentation of that class for details. The object of class Message_ProgressRange will automatically advance the indicator if it is not passed to any Message_ProgressScope.

The progress indicator supports concurrent processing and can be used in multithreaded applications.

The derived class should be created to connect this interface to actual implementation of progress indicator, to take care of visualization of the progress (e.g. show total position at the graphical bar, print scopes in text mode, or else), and for implementation of user break mechanism (if necessary).

See details in documentation of methods Show() and UserBreak().

Constructor & Destructor Documentation

~Message_ProgressIndicator()

Message_ProgressIndicator::~Message_ProgressIndicator

(

)

Destructor.

Message_ProgressIndicator()

Message_ProgressIndicator::Message_ProgressIndicator ( )

protected

Constructor.

Member Function Documentation

GetPosition()

Standard_Real Message_ProgressIndicator::GetPosition ( ) const

inline

Returns total progress position ranged from 0 to 1. Should not be called concurrently while the progress is advancing, except from implementation of method Show().

Reset()

virtual void Message_ProgressIndicator::Reset ( )

inlineprotectedvirtual

Call-back method called by Start(), can be redefined by descendants if some actions are needed when the indicator is restarted.

Reimplemented in Draw_ProgressIndicator.

Show()

virtual void Message_ProgressIndicator::Show ( const Message_ProgressScope & theScope, const Standard_Boolean isForce )

protectedpure virtual

Virtual method to be defined by descendant. Should update presentation of the progress indicator.

It is called whenever progress position is changed. Calls to this method from progress indicator are protected by mutex so that it is never called concurrently for the same progress indicator instance. Show() should return as soon as possible to reduce thread contention in multithreaded algorithms.

It is recommended to update (redraw, output etc.) only if progress is advanced by at least 1% from previous update.

Flag isForce is intended for forcing update in case if it is required at particular step of the algorithm; all calls to it from inside the core mechanism (Message_Progress... classes) are done with this flag equal to False.

The parameter theScope is the current scope being advanced; it can be used to show the names and ranges of the on-going scope and its parents, providing more visibility of the current stage of the process.

Implemented in Draw_ProgressIndicator.

Start() [1/2]

Message_ProgressRange Message_ProgressIndicator::Start

(

)

Resets the indicator to zero, calls Reset(), and returns the range. This range refers to the scope that has no name and is initialized with max value 1 and step 1. Use this method to get the top level range for progress indication.

Start() [2/2]

static Message_ProgressRange Message_ProgressIndicator::Start ( const Handle< Message_ProgressIndicator > & theProgress )

static

If argument is non-null handle, returns theProgress->Start(). Otherwise, returns dummy range that can be safely used in the algorithms but not bound to progress indicator.

UserBreak()

virtual Standard_Boolean Message_ProgressIndicator::UserBreak ( )

inlineprotectedvirtual

Should return True if user has sent a break signal.

This method can be called concurrently, thus implementation should be thread-safe. It should not call Show() or Position() to avoid possible data races. The method should return as soon as possible to avoid delaying the calling algorithm.

Default implementation returns False.

Reimplemented in Draw_ProgressIndicator.

---

The documentation for this class was generated from the following file:

• Message_ProgressIndicator.hxx