Open CASCADE Technology  7.7.0.dev

Message_ProgressIndicator Class Referenceabstract

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:
Inheritance graph
[legend]

Protected Member Functions

Virtual methods to be defined by descendant.
virtual Standard_Boolean UserBreak ()
 Should return True if user has sent a break signal. More...
 
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. More...
 
virtual void Reset ()
 Call-back method called by Start(), can be redefined by descendants if some actions are needed when the indicator is restarted. More...
 

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(). More...
 
 ~Message_ProgressIndicator ()
 Destructor. More...
 
 Message_ProgressIndicator ()
 Constructor. More...
 

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. More...
 
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. More...
 

Additional Inherited Members

- Public Types inherited from Standard_Transient
typedef void base_type
 Returns a type descriptor about this object. More...
 
- Public Member Functions inherited from Standard_Transient
 Standard_Transient ()
 Empty constructor. More...
 
 Standard_Transient (const Standard_Transient &)
 Copy constructor – does nothing. More...
 
Standard_Transientoperator= (const Standard_Transient &)
 Assignment operator, needed to avoid copying reference counter. More...
 
virtual ~Standard_Transient ()
 Destructor must be virtual. More...
 
virtual void Delete () const
 Memory deallocator for transient classes. More...
 
virtual const opencascade::handle< Standard_Type > & DynamicType () const
 Returns a type descriptor about this object. More...
 
Standard_Boolean IsInstance (const opencascade::handle< Standard_Type > &theType) const
 Returns a true value if this is an instance of Type. More...
 
Standard_Boolean IsInstance (const Standard_CString theTypeName) const
 Returns a true value if this is an instance of TypeName. More...
 
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. More...
 
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. More...
 
Standard_TransientThis () 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. More...
 
Standard_Integer GetRefCount () const
 Get the reference counter of this object. More...
 
void IncrementRefCounter () const
 Increments the reference counter of this object. More...
 
Standard_Integer DecrementRefCounter () const
 Decrements the reference counter of this object; returns the decremented value. More...
 
- Static Public Member Functions inherited from Standard_Transient
static const char * get_type_name ()
 Returns a type descriptor about this object. More...
 
static const opencascade::handle< Standard_Type > & get_type_descriptor ()
 Returns type descriptor of Standard_Transient class. More...
 

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:

anAlgorithm.Perform (aProgress->Start());
#define Handle(Class)
Define Handle() macro.
Definition: Standard_Handle.hxx:399
Defines abstract interface from program to the user. This includes progress indication and user break...
Definition: Message_ProgressIndicator.hxx:60

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 ( void  )
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: