1 // Created on: 2002-02-20
2 // Created by: Andrey BETENEV
3 // Copyright (c) 2002-2014 OPEN CASCADE SAS
5 // This file is part of Open CASCADE Technology software library.
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.
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
16 #ifndef _Message_ProgressIndicator_HeaderFile
17 #define _Message_ProgressIndicator_HeaderFile
19 #include <Standard.hxx>
20 #include <Standard_Type.hxx>
22 #include <Standard_Real.hxx>
23 #include <Message_SequenceOfProgressScale.hxx>
24 #include <Standard_Transient.hxx>
25 #include <Standard_CString.hxx>
26 #include <Standard_Boolean.hxx>
27 #include <Standard_Integer.hxx>
28 class TCollection_HAsciiString;
29 class Message_ProgressScale;
32 class Message_ProgressIndicator;
33 DEFINE_STANDARD_HANDLE(Message_ProgressIndicator, Standard_Transient)
35 //! Defines abstract interface from program to the "user".
36 //! That includes progress indication and user break mechanisms
38 //! The interface to progress indicator represents it as a scale
39 //! for each range and step can be defined by the program that uses it.
40 //! The scale can be made "infinite", which means it will grow
41 //! non-linearly, end of scale will be approached asymptotically at
42 //! infinite number of steps. In that case value of scale range
43 //! gives a number of steps corresponding to position at 1/2 of scale.
44 //! The current position can be either set directly (in a range from
45 //! current position to maximum scale value), or incremented step
48 //! Progress indication mechanism is adapted for convenient
49 //! usage in hiererchical processes that require indication of
50 //! progress at several (sub)levels of the process.
51 //! For that purpose, it is possible to create restricted sub-scope of
52 //! indication by specifying part of a current scale that is to be
53 //! used by the subprocess.
54 //! When subprocess works with progress indicator in the restricted
55 //! scope, it has the same interface to a scale, while actually it
56 //! deals only with part of the whole scale.
59 //! Currently there is no support for concurrent progress
60 //! indicator that could be useful in multithreaded applications.
61 //! The main reason for this is that such implementation would be
62 //! too complex regarding forecasted lack of real need for such
64 //! To support this it would require that ProgressScale keep its
65 //! own position and take care of incrementing main ProgressIndicator
66 //! in destructor. This would also require having cross-references
67 //! between nested instances of ProgressScale, ie. potential
68 //! problems with memory management.
69 //! In case of need of concurrent progress indicator two things can
70 //! be suggested: either creation of single spane with summary number
71 //! of steps, or usage of infinite scale.
73 //! The user break is implemented as virtual function that might
74 //! return True in case if break signal from the user is obtained.
76 //! The derived classes should take care of visualisation of the
77 //! progress indicator (e.g. show total position at the graphical bar,
78 //! and/or print all scopes in text mode), and for implementation
79 //! of user break mechanism (if defined).
80 class Message_ProgressIndicator : public Standard_Transient
86 //! Drops all scopes and sets scale from 0 to 100, step 1
87 //! This scale has name "Step"
88 Standard_EXPORT virtual void Reset();
90 void SetName (const Standard_CString name);
92 //! Set (optional) name for scale
93 void SetName (const Handle(TCollection_HAsciiString)& name);
95 //! Set range for current scale
96 void SetRange (const Standard_Real min, const Standard_Real max);
98 //! Set step for current scale
99 void SetStep (const Standard_Real step);
101 //! Set or drop infinite mode for the current scale
102 void SetInfinite (const Standard_Boolean isInf = Standard_True);
104 void SetScale (const Standard_CString name, const Standard_Real min, const Standard_Real max, const Standard_Real step, const Standard_Boolean isInf = Standard_False);
106 //! Set all parameters for current scale
107 Standard_EXPORT void SetScale (const Standard_Real min, const Standard_Real max, const Standard_Real step, const Standard_Boolean isInf = Standard_False);
109 //! Returns all parameters for current scale
110 Standard_EXPORT void GetScale (Standard_Real& min, Standard_Real& max, Standard_Real& step, Standard_Boolean& isInf) const;
112 Standard_EXPORT void SetValue (const Standard_Real val);
114 //! Set and get progress value at current scale
115 //! If the value to be set is more than currently set one, or out
116 //! of range for the current scale, it is limited by that range
117 Standard_EXPORT Standard_Real GetValue() const;
121 //! Increment the progress value by the default of specified step
122 void Increment (const Standard_Real step);
124 Standard_Boolean NewScope (const Standard_CString name = 0);
126 Standard_Boolean NewScope (const Handle(TCollection_HAsciiString)& name);
128 Standard_Boolean NewScope (const Standard_Real span, const Standard_CString name = 0);
130 //! Creates new scope on a part of a current scale from current
131 //! position with span either equal to default step, or specified
132 //! The scale for the new scope will have specified name and
133 //! ranged from 0 to 100 with step 1
134 //! Returns False if something is wrong in arguments or in current
135 //! position of progress indicator; scope is opened anyway
136 Standard_EXPORT Standard_Boolean NewScope (const Standard_Real span, const Handle(TCollection_HAsciiString)& name);
138 //! Close the current scope and thus return to previous scale
139 //! Updates position to be at the end of the closing scope
140 //! Returns False if no scope is opened
141 Standard_EXPORT Standard_Boolean EndScope();
143 Standard_Boolean NextScope (const Standard_CString name = 0);
145 //! Optimized version of { return EndScope() && NewScope(); }
146 Standard_EXPORT Standard_Boolean NextScope (const Standard_Real span, const Standard_CString name = 0);
148 //! Should return True if user has send a break signal.
149 //! Default implementation returns False.
150 Standard_EXPORT virtual Standard_Boolean UserBreak();
152 //! Update presentation of the progress indicator
153 //! Called when progress position is changed
154 //! Flag force is intended for forcing update in case if it is
155 //! optimized; all internal calls from ProgressIndicator are
156 //! done with this flag equal to False
157 Standard_EXPORT virtual Standard_Boolean Show (const Standard_Boolean force = Standard_True) = 0;
159 //! Returns total progress position on the basic scale
160 //! ranged from 0. to 1.
161 Standard_Real GetPosition() const;
163 //! Returns current number of opened scopes
164 //! This number is always >=1 as top-level scale is always present
165 Standard_Integer GetNbScopes() const;
167 //! Returns data for scale of index-th scope
168 //! The first scope is current one, the last is the top-level one
169 const Message_ProgressScale& GetScope (const Standard_Integer index) const;
174 DEFINE_STANDARD_RTTIEXT(Message_ProgressIndicator,Standard_Transient)
179 //! Constructor, just calls own Reset() (not yet redefined)
180 Standard_EXPORT Message_ProgressIndicator();
187 Standard_Real myPosition;
188 Message_SequenceOfProgressScale myScopes;
194 #include <Message_ProgressIndicator.lxx>
200 #endif // _Message_ProgressIndicator_HeaderFile