42cf5bc1 |
1 | // Created on: 2002-02-20 |
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_ProgressIndicator_HeaderFile |
17 | #define _Message_ProgressIndicator_HeaderFile |
18 | |
19 | #include <Standard.hxx> |
20 | #include <Standard_Type.hxx> |
21 | |
22 | #include <Standard_Real.hxx> |
23 | #include <Message_SequenceOfProgressScale.hxx> |
25e59720 |
24 | #include <Standard_Transient.hxx> |
42cf5bc1 |
25 | #include <Standard_CString.hxx> |
26 | #include <Standard_Boolean.hxx> |
27 | #include <Standard_Integer.hxx> |
28 | class TCollection_HAsciiString; |
29 | class Message_ProgressScale; |
30 | |
31 | |
32 | class Message_ProgressIndicator; |
25e59720 |
33 | DEFINE_STANDARD_HANDLE(Message_ProgressIndicator, Standard_Transient) |
42cf5bc1 |
34 | |
35 | //! Defines abstract interface from program to the "user". |
6b55f8e3 |
36 | //! This includes progress indication and user break mechanisms. |
42cf5bc1 |
37 | //! |
6b55f8e3 |
38 | //! The process that uses the progress indicator interacts with it as |
39 | //! with a scale whose range and step can be configured according to |
40 | //! the nature of the process. |
42cf5bc1 |
41 | //! The scale can be made "infinite", which means it will grow |
6b55f8e3 |
42 | //! non-linearly, and end of scale will be approached asymptotically at |
43 | //! infinite number of steps. In that case the range defines |
44 | //! a number of steps corresponding to position at 1/2 of scale. |
42cf5bc1 |
45 | //! The current position can be either set directly (in a range from |
46 | //! current position to maximum scale value), or incremented step |
47 | //! by step. |
48 | //! |
49 | //! Progress indication mechanism is adapted for convenient |
50 | //! usage in hiererchical processes that require indication of |
6b55f8e3 |
51 | //! progress at several levels of the process nesting. |
42cf5bc1 |
52 | //! For that purpose, it is possible to create restricted sub-scope of |
6b55f8e3 |
53 | //! indication by specifying part of a current scale to be |
42cf5bc1 |
54 | //! used by the subprocess. |
55 | //! When subprocess works with progress indicator in the restricted |
56 | //! scope, it has the same interface to a scale, while actually it |
57 | //! deals only with part of the whole scale. |
6b55f8e3 |
58 | //! |
59 | //! The recommended way to implement progress indication in the algorithm |
60 | //! is to use class Message_ProgressSentry that provides iterator-like |
61 | //! interface for incrementing progress and opening nested scopes. |
42cf5bc1 |
62 | //! |
63 | //! NOTE: |
64 | //! Currently there is no support for concurrent progress |
65 | //! indicator that could be useful in multithreaded applications. |
42cf5bc1 |
66 | //! |
6b55f8e3 |
67 | //! The user break is implemented as virtual function that should |
68 | //! return True in case if break signal from the user is received. |
42cf5bc1 |
69 | //! |
6b55f8e3 |
70 | //! The derived class should take care of visualisation of the |
42cf5bc1 |
71 | //! progress indicator (e.g. show total position at the graphical bar, |
6b55f8e3 |
72 | //! print scopes in text mode, or else), and for implementation |
73 | //! of user break mechanism (if necessary). |
74 | |
25e59720 |
75 | class Message_ProgressIndicator : public Standard_Transient |
42cf5bc1 |
76 | { |
77 | |
78 | public: |
79 | |
80 | |
81 | //! Drops all scopes and sets scale from 0 to 100, step 1 |
82 | //! This scale has name "Step" |
83 | Standard_EXPORT virtual void Reset(); |
84 | |
85 | void SetName (const Standard_CString name); |
86 | |
87 | //! Set (optional) name for scale |
88 | void SetName (const Handle(TCollection_HAsciiString)& name); |
89 | |
90 | //! Set range for current scale |
91 | void SetRange (const Standard_Real min, const Standard_Real max); |
92 | |
93 | //! Set step for current scale |
94 | void SetStep (const Standard_Real step); |
95 | |
96 | //! Set or drop infinite mode for the current scale |
97 | void SetInfinite (const Standard_Boolean isInf = Standard_True); |
98 | |
99 | void SetScale (const Standard_CString name, const Standard_Real min, const Standard_Real max, const Standard_Real step, const Standard_Boolean isInf = Standard_False); |
100 | |
101 | //! Set all parameters for current scale |
102 | Standard_EXPORT void SetScale (const Standard_Real min, const Standard_Real max, const Standard_Real step, const Standard_Boolean isInf = Standard_False); |
103 | |
104 | //! Returns all parameters for current scale |
105 | Standard_EXPORT void GetScale (Standard_Real& min, Standard_Real& max, Standard_Real& step, Standard_Boolean& isInf) const; |
106 | |
107 | Standard_EXPORT void SetValue (const Standard_Real val); |
108 | |
109 | //! Set and get progress value at current scale |
110 | //! If the value to be set is more than currently set one, or out |
111 | //! of range for the current scale, it is limited by that range |
112 | Standard_EXPORT Standard_Real GetValue() const; |
113 | |
114 | void Increment(); |
115 | |
116 | //! Increment the progress value by the default of specified step |
117 | void Increment (const Standard_Real step); |
118 | |
119 | Standard_Boolean NewScope (const Standard_CString name = 0); |
120 | |
121 | Standard_Boolean NewScope (const Handle(TCollection_HAsciiString)& name); |
122 | |
123 | Standard_Boolean NewScope (const Standard_Real span, const Standard_CString name = 0); |
124 | |
125 | //! Creates new scope on a part of a current scale from current |
126 | //! position with span either equal to default step, or specified |
127 | //! The scale for the new scope will have specified name and |
128 | //! ranged from 0 to 100 with step 1 |
129 | //! Returns False if something is wrong in arguments or in current |
130 | //! position of progress indicator; scope is opened anyway |
131 | Standard_EXPORT Standard_Boolean NewScope (const Standard_Real span, const Handle(TCollection_HAsciiString)& name); |
132 | |
133 | //! Close the current scope and thus return to previous scale |
134 | //! Updates position to be at the end of the closing scope |
135 | //! Returns False if no scope is opened |
136 | Standard_EXPORT Standard_Boolean EndScope(); |
137 | |
138 | Standard_Boolean NextScope (const Standard_CString name = 0); |
139 | |
140 | //! Optimized version of { return EndScope() && NewScope(); } |
141 | Standard_EXPORT Standard_Boolean NextScope (const Standard_Real span, const Standard_CString name = 0); |
142 | |
143 | //! Should return True if user has send a break signal. |
144 | //! Default implementation returns False. |
145 | Standard_EXPORT virtual Standard_Boolean UserBreak(); |
146 | |
147 | //! Update presentation of the progress indicator |
148 | //! Called when progress position is changed |
149 | //! Flag force is intended for forcing update in case if it is |
150 | //! optimized; all internal calls from ProgressIndicator are |
151 | //! done with this flag equal to False |
152 | Standard_EXPORT virtual Standard_Boolean Show (const Standard_Boolean force = Standard_True) = 0; |
153 | |
154 | //! Returns total progress position on the basic scale |
155 | //! ranged from 0. to 1. |
156 | Standard_Real GetPosition() const; |
157 | |
158 | //! Returns current number of opened scopes |
159 | //! This number is always >=1 as top-level scale is always present |
be5c3602 |
160 | Standard_Integer GetNbScopes() const; |
42cf5bc1 |
161 | |
162 | //! Returns data for scale of index-th scope |
163 | //! The first scope is current one, the last is the top-level one |
be5c3602 |
164 | const Message_ProgressScale& GetScope (const Standard_Integer index) const; |
42cf5bc1 |
165 | |
166 | |
167 | |
168 | |
25e59720 |
169 | DEFINE_STANDARD_RTTIEXT(Message_ProgressIndicator,Standard_Transient) |
42cf5bc1 |
170 | |
171 | protected: |
172 | |
173 | |
174 | //! Constructor, just calls own Reset() (not yet redefined) |
175 | Standard_EXPORT Message_ProgressIndicator(); |
176 | |
177 | |
178 | |
179 | private: |
180 | |
181 | |
182 | Standard_Real myPosition; |
183 | Message_SequenceOfProgressScale myScopes; |
184 | |
185 | |
186 | }; |
187 | |
188 | |
189 | #include <Message_ProgressIndicator.lxx> |
190 | |
191 | |
192 | |
193 | |
194 | |
195 | #endif // _Message_ProgressIndicator_HeaderFile |