src/Message/Message_ProgressSentry.hxx

   1 // Created on: 2002-02-22
   2 // Created by: Andrey BETENEV
   3 // Copyright (c) 2002-2014 OPEN CASCADE SAS
   4 //
   5 // This file is part of Open CASCADE Technology software library.
   6 //
   7 // This library is free software; you can redistribute it and/or modify it under
   8 // the terms of the GNU Lesser General Public License version 2.1 as published
   9 // by the Free Software Foundation, with special exception defined in the file
  10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 // distribution for complete text of the license and disclaimer of any warranty.
  12 //
  13 // Alternatively, this file may be used under the terms of Open CASCADE
  14 // commercial license or contractual agreement.
  15
  16 #ifndef _Message_ProgressSentry_HeaderFile
  17 #define _Message_ProgressSentry_HeaderFile
  18
  19 #include <Standard.hxx>
  20 #include <Standard_DefineAlloc.hxx>
  21 #include <Standard_Handle.hxx>
  22
  23 #include <Standard_Boolean.hxx>
  24 #include <Standard_CString.hxx>
  25 #include <Standard_Real.hxx>
  26 class Message_ProgressIndicator;
  27 class TCollection_HAsciiString;
  28
  29
  30 //! This class is a tool allowing to manage opening/closing
  31 //! scopes in the ProgressIndicator in convenient and safe way.
  32 //!
  33 //! Its main features are:
  34 //! - Set all parameters for the current scale on the given
  35 //! ProgressIndicator and open a new scope at one line
  36 //! - Iterator-like interface to opening next scopes and
  37 //! check for user break
  38 //! - Automatic scope closing in destructor
  39 //! - Safe for NULL ProgressIndicator (just does nothing)
  40 //!
  41 //! Example of usage in nested process:
  42 //!
  43 //! @code{.cpp}
  44 //!   Handle(Draw_ProgressIndicator) aProgress = ...;
  45 //!
  46 //!   // Outer cycle
  47 //!   Message_ProgressSentry anOuter (aProgress, "Outer", 0, nbOuter, 1);
  48 //!   for (int i = 0; i < nbOuter && anOuter.More(); i++, anOuter.Next())
  49 //!   {
  50 //!     // Inner cycle
  51 //!     Message_ProgressSentry anInner (aProgress, "Inner", 0, nbInner, 1);
  52 //!     for (int j = 0; j < nbInner && anInner.More(); j++, anInner.Next())
  53 //!     {
  54 //!       // Cycle body
  55 //!     }
  56 //!   }
  57 //! @endcode
  58
  59 class Message_ProgressSentry
  60 {
  61 public:
  62
  63   DEFINE_STANDARD_ALLOC
  64
  65
  66   Standard_EXPORT Message_ProgressSentry(const Handle(Message_ProgressIndicator)& PI, const Standard_CString name, const Standard_Real min, const Standard_Real max, const Standard_Real step, const Standard_Boolean isInf = Standard_False, const Standard_Real newScopeSpan = 0.0);
  67
  68   //! Creates an instance of ProgressSentry attaching it to
  69   //! the specified ProgressIndicator, selects parameters of
  70   //! the current scale, and opens a new scope with specified
  71   //! span (equal to step by default)
  72   Standard_EXPORT Message_ProgressSentry(const Handle(Message_ProgressIndicator)& PI, const Handle(TCollection_HAsciiString)& name, const Standard_Real min, const Standard_Real max, const Standard_Real step, const Standard_Boolean isInf = Standard_False, const Standard_Real newScopeSpan = 0.0);
  73
  74   //! Moves progress indicator to the end of the current scale
  75   //! and relieves sentry from its duty. Methods other than Show()
  76   //! will do nothing after this one is called.
  77     void Relieve();
  78 ~Message_ProgressSentry()
  79 {
  80   Relieve();
  81 }
  82
  83     void Next (const Standard_CString name = 0) const;
  84
  85     void Next (const Standard_Real span, const Standard_CString name = 0) const;
  86
  87   //! Closes current scope and opens next one
  88   //! with either specified or default span
  89     void Next (const Standard_Real span, const Handle(TCollection_HAsciiString)& name) const;
  90
  91   //! Returns False if ProgressIndicator signals UserBreak
  92     Standard_Boolean More() const;
  93
  94   //! Forces update of progress indicator display
  95     void Show() const;
  96
  97
  98
  99
 100 protected:
 101
 102
 103
 104
 105
 106 private:
 107
 108
 109
 110   Handle(Message_ProgressIndicator) myProgress;
 111   Standard_Boolean myActive;
 112
 113
 114 };
 115
 116
 117 #include <Message_ProgressSentry.lxx>
 118
 119
 120
 121
 122
 123 #endif // _Message_ProgressSentry_HeaderFile