liboce-foundation-dev 0.17.1-1 / usr / include / oce / Message_ProgressIndicator.hxx

// This file is generated by WOK (CPPExt).
// Please do not edit this file; modify original file instead.
// The copyright and license terms as defined for the original file apply to 
// this header file considered to be the "object code" form of the original source.

#ifndef _Message_ProgressIndicator_HeaderFile
#define _Message_ProgressIndicator_HeaderFile

#include <Standard.hxx>
#include <Standard_DefineHandle.hxx>
#include <Handle_Message_ProgressIndicator.hxx>

#include <Standard_Real.hxx>
#include <Message_SequenceOfProgressScale.hxx>
#include <MMgt_TShared.hxx>
#include <Standard_CString.hxx>
#include <Handle_TCollection_HAsciiString.hxx>
#include <Standard_Boolean.hxx>
#include <Standard_Integer.hxx>
class TCollection_HAsciiString;
class Message_ProgressScale;


//! Defines abstract interface from program to the "user".
//! That includes progress indication and user break mechanisms
//!
//! The interface to progress indicator represents it as a scale
//! for each range and step can be defined by the program that uses it.
//! The scale can be made "infinite", which means it will grow
//! non-linearly, end of scale will be approached asymptotically at
//! infinite number of steps. In that case value of scale range
//! gives a number of steps corresponding to position at 1/2 of scale.
//! The current position can be either set directly (in a range from
//! current position to maximum scale value), or incremented step
//! by step.
//!
//! Progress indication mechanism is adapted for convenient
//! usage in hiererchical processes that require indication of
//! progress at several (sub)levels of the process.
//! For that purpose, it is possible to create restricted sub-scope of
//! indication by specifying part of a current scale that is to be
//! used by the subprocess.
//! When subprocess works with progress indicator in the restricted
//! scope, it has the same interface to a scale, while actually it
//! deals only with part of the whole scale.
//!
//! NOTE:
//! Currently there is no support for concurrent progress
//! indicator that could be useful in multithreaded applications.
//! The main reason for this is that such implementation would be
//! too complex regarding forecasted lack of real need for such
//! support.
//! To support this it would require that ProgressScale keep its
//! own position and take care of incrementing main ProgressIndicator
//! in destructor. This would also require having cross-references
//! between nested instances of ProgressScale, ie. potential
//! problems with memory management.
//! In case of need of concurrent progress indicator two things can
//! be suggested: either creation of single spane with summary number
//! of steps, or usage of infinite scale.
//!
//! The user break is implemented as virtual function that might
//! return True in case if break signal from the user is obtained.
//!
//! The derived classes should take care of visualisation of the
//! progress indicator (e.g. show total position at the graphical bar,
//! and/or print all scopes in text mode), and for implementation
//! of user break mechanism (if defined).
class Message_ProgressIndicator : public MMgt_TShared
{

public:

  
  //! Drops all scopes and sets scale from 0 to 100, step 1
  //! This scale has name "Step"
  Standard_EXPORT virtual   void Reset() ;
  
      void SetName (const Standard_CString name) ;
  
  //! Set (optional) name for scale
      void SetName (const Handle(TCollection_HAsciiString)& name) ;
  
  //! Set range for current scale
      void SetRange (const Standard_Real min, const Standard_Real max) ;
  
  //! Set step for current scale
      void SetStep (const Standard_Real step) ;
  
  //! Set or drop infinite mode for the current scale
      void SetInfinite (const Standard_Boolean isInf = Standard_True) ;
  
      void SetScale (const Standard_CString name, const Standard_Real min, const Standard_Real max, const Standard_Real step, const Standard_Boolean isInf = Standard_False) ;
  
  //! Set all parameters for current scale
  Standard_EXPORT   void SetScale (const Standard_Real min, const Standard_Real max, const Standard_Real step, const Standard_Boolean isInf = Standard_False) ;
  
  //! Returns all parameters for current scale
  Standard_EXPORT   void GetScale (Standard_Real& min, Standard_Real& max, Standard_Real& step, Standard_Boolean& isInf)  const;
  
  Standard_EXPORT   void SetValue (const Standard_Real val) ;
  
  //! Set and get progress value at current scale
  //! If the value to be set is more than currently set one, or out
  //! of range for the current scale, it is limited by that range
  Standard_EXPORT   Standard_Real GetValue()  const;
  
      void Increment() ;
  
  //! Increment the progress value by the default of specified step
      void Increment (const Standard_Real step) ;
  
      Standard_Boolean NewScope (const Standard_CString name = 0) ;
  
      Standard_Boolean NewScope (const Handle(TCollection_HAsciiString)& name) ;
  
      Standard_Boolean NewScope (const Standard_Real span, const Standard_CString name = 0) ;
  
  //! Creates new scope on a part of a current scale from current
  //! position with span either equal to default step, or specified
  //! The scale for the new scope will have specified name and
  //! ranged from 0 to 100 with step 1
  //! Returns False if something is wrong in arguments or in current
  //! position of progress indicator; scope is opened anyway
  Standard_EXPORT   Standard_Boolean NewScope (const Standard_Real span, const Handle(TCollection_HAsciiString)& name) ;
  
  //! Close the current scope and thus return to previous scale
  //! Updates position to be at the end of the closing scope
  //! Returns False if no scope is opened
  Standard_EXPORT   Standard_Boolean EndScope() ;
  
      Standard_Boolean NextScope (const Standard_CString name = 0) ;
  
  //! Optimized version of { return EndScope() && NewScope(); }
  Standard_EXPORT   Standard_Boolean NextScope (const Standard_Real span, const Standard_CString name = 0) ;
  
  //! Should return True if user has send a break signal.
  //! Default implementation returns False.
  Standard_EXPORT virtual   Standard_Boolean UserBreak() ;
  
  //! Update presentation of the progress indicator
  //! Called when progress position is changed
  //! Flag force is intended for forcing update in case if it is
  //! optimized; all internal calls from ProgressIndicator are
  //! done with this flag equal to False
  Standard_EXPORT virtual   Standard_Boolean Show (const Standard_Boolean force = Standard_True)  = 0;
  
  //! Returns total progress position on the basic scale
  //! ranged from 0. to 1.
      Standard_Real GetPosition()  const;
  
  //! Returns current number of opened scopes
  //! This number is always >=1 as top-level scale is always present
  Standard_EXPORT   Standard_Integer GetNbScopes()  const;
  
  //! Returns data for scale of index-th scope
  //! The first scope is current one, the last is the top-level one
  Standard_EXPORT  const  Message_ProgressScale& GetScope (const Standard_Integer index)  const;




  DEFINE_STANDARD_RTTI(Message_ProgressIndicator)

protected:

  
  //! Constructor, just calls own Reset() (not yet redefined)
  Standard_EXPORT Message_ProgressIndicator();



private: 


  Standard_Real myPosition;
  Message_SequenceOfProgressScale myScopes;


};


#include <Message_ProgressIndicator.lxx>





#endif // _Message_ProgressIndicator_HeaderFile