b311480e |
1 | -- Created on: 2002-02-20 |
2 | -- Created by: Andrey BETENEV |
3 | -- Copyright (c) 2002-2012 OPEN CASCADE SAS |
4 | -- |
5 | -- The content of this file is subject to the Open CASCADE Technology Public |
6 | -- License Version 6.5 (the "License"). You may not use the content of this file |
7 | -- except in compliance with the License. Please obtain a copy of the License |
8 | -- at http://www.opencascade.org and read it completely before using this file. |
9 | -- |
10 | -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its |
11 | -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France. |
12 | -- |
13 | -- The Original Code and all software distributed under the License is |
14 | -- distributed on an "AS IS" basis, without warranty of any kind, and the |
15 | -- Initial Developer hereby disclaims all such warranties, including without |
16 | -- limitation, any warranties of merchantability, fitness for a particular |
17 | -- purpose or non-infringement. Please see the License for the specific terms |
18 | -- and conditions governing the rights and limitations under the License. |
19 | |
7fd59977 |
20 | |
21 | |
22 | deferred class ProgressIndicator from Message inherits TShared from MMgt |
23 | |
24 | ---Purpose: Defines abstract interface from program to the "user". |
25 | -- That includes progress indication and user break mechanisms |
26 | -- |
27 | -- The interface to progress indicator represents it as a scale |
28 | -- for each range and step can be defined by the program that uses it. |
29 | -- The scale can be made "infinite", which means it will grow |
30 | -- non-linearly, end of scale will be approached asymptotically at |
31 | -- infinite number of steps. In that case value of scale range |
32 | -- gives a number of steps corresponding to position at 1/2 of scale. |
33 | -- The current position can be either set directly (in a range from |
34 | -- current position to maximum scale value), or incremented step |
35 | -- by step. |
36 | -- |
37 | -- Progress indication mechanism is adapted for convenient |
38 | -- usage in hiererchical processes that require indication of |
39 | -- progress at several (sub)levels of the process. |
40 | -- For that purpose, it is possible to create restricted sub-scope of |
41 | -- indication by specifying part of a current scale that is to be |
42 | -- used by the subprocess. |
43 | -- When subprocess works with progress indicator in the restricted |
44 | -- scope, it has the same interface to a scale, while actually it |
45 | -- deals only with part of the whole scale. |
46 | -- |
47 | -- NOTE: |
48 | -- Currently there is no support for concurrent progress |
49 | -- indicator that could be useful in multithreaded applications. |
50 | -- The main reason for this is that such implementation would be |
51 | -- too complex regarding forecasted lack of real need for such |
52 | -- support. |
53 | -- To support this it would require that ProgressScale keep its |
54 | -- own position and take care of incrementing main ProgressIndicator |
55 | -- in destructor. This would also require having cross-references |
56 | -- between nested instances of ProgressScale, ie. potential |
57 | -- problems with memory management. |
58 | -- In case of need of concurrent progress indicator two things can |
59 | -- be suggested: either creation of single spane with summary number |
60 | -- of steps, or usage of infinite scale. |
61 | -- |
62 | -- The user break is implemented as virtual function that might |
63 | -- return True in case if break signal from the user is obtained. |
64 | -- |
65 | -- The derived classes should take care of visualisation of the |
66 | -- progress indicator (e.g. show total position at the graphical bar, |
67 | -- and/or print all scopes in text mode), and for implementation |
68 | -- of user break mechanism (if defined). |
69 | |
70 | uses |
71 | HAsciiString from TCollection, |
72 | ProgressScale from Message, |
73 | SequenceOfProgressScale from Message |
74 | is |
75 | |
76 | ---Scope: Initialisations |
77 | |
78 | Initialize returns mutable ProgressIndicator from Message; |
79 | ---Purpose: Constructor, just calls own Reset() (not yet redefined) |
80 | |
81 | Reset (me: mutable) is virtual; |
82 | ---Purpose: Drops all scopes and sets scale from 0 to 100, step 1 |
83 | -- This scale has name "Step" |
84 | |
85 | ---Scope: Program API |
86 | |
87 | ------------------------------------------------------------------ |
88 | -- Management of current scale |
89 | |
90 | SetName (me: mutable; name: CString); |
91 | ---C++: inline |
92 | SetName (me: mutable; name: HAsciiString from TCollection); |
93 | ---C++: inline |
94 | ---Purpose: Set (optional) name for scale |
95 | |
96 | SetRange (me: mutable; min, max: Real); |
97 | ---C++: inline |
98 | ---Purpose: Set range for current scale |
99 | |
100 | SetStep (me: mutable; step: Real); |
101 | ---C++: inline |
102 | ---Purpose: Set step for current scale |
103 | |
104 | SetInfinite (me: mutable; isInf: Boolean = Standard_True); |
105 | ---C++: inline |
106 | ---Purpose: Set or drop infinite mode for the current scale |
107 | |
108 | SetScale (me: mutable; name: CString; min, max, step: Real; isInf: Boolean = Standard_False); |
109 | ---C++: inline |
110 | SetScale (me: mutable; min, max, step: Real; isInf: Boolean = Standard_False); |
111 | ---Purpose: Set all parameters for current scale |
112 | |
113 | GetScale (me; min, max, step: out Real; isInf: out Boolean); |
114 | ---Purpose: Returns all parameters for current scale |
115 | |
116 | ------------------------------------------------------------------ |
117 | -- Management of current progress value |
118 | |
119 | SetValue (me: mutable; val: Real); |
120 | GetValue (me) returns Real; |
121 | ---Purpose: Set and get progress value at current scale |
122 | -- If the value to be set is more than currently set one, or out |
123 | -- of range for the current scale, it is limited by that range |
124 | |
125 | Increment (me: mutable); |
126 | ---C++: inline |
127 | Increment (me: mutable; step: Real); |
128 | ---C++: inline |
129 | ---Purpose: Increment the progress value by the default of specified step |
130 | |
131 | ------------------------------------------------------------------ |
132 | -- Management of scopes |
133 | |
134 | NewScope (me: mutable; name: CString = 0) returns Boolean; |
135 | ---C++: inline |
136 | NewScope (me: mutable; name: HAsciiString from TCollection) returns Boolean; |
137 | ---C++: inline |
138 | NewScope (me: mutable; span: Real; name: CString = 0) returns Boolean; |
139 | ---C++: inline |
140 | NewScope (me: mutable; span: Real; name: HAsciiString from TCollection) returns Boolean; |
141 | ---Purpose: Creates new scope on a part of a current scale from current |
142 | -- position with span either equal to default step, or specified |
143 | -- The scale for the new scope will have specified name and |
144 | -- ranged from 0 to 100 with step 1 |
145 | -- Returns False if something is wrong in arguments or in current |
146 | -- position of progress indicator; scope is opened anyway |
147 | |
148 | EndScope (me: mutable) returns Boolean; |
149 | ---Purpose: Close the current scope and thus return to previous scale |
150 | -- Updates position to be at the end of the closing scope |
151 | -- Returns False if no scope is opened |
152 | |
153 | NextScope (me: mutable; name: CString = 0) returns Boolean; |
154 | ---C++: inline |
155 | NextScope (me: mutable; span: Real; name: CString = 0) returns Boolean; |
156 | ---Purpose: Optimized version of { return EndScope() && NewScope(); } |
157 | |
158 | ------------------------------------------------------------------ |
159 | -- User break mechanism |
160 | |
161 | UserBreak (me: mutable) returns Boolean is virtual; |
162 | ---Purpose: Should return True if user has send a break signal. |
163 | -- Default implementation returns False. |
164 | |
165 | |
166 | ---Scope: Deferred methods to be defined by descendants |
167 | |
168 | Show (me: mutable; force: Boolean = Standard_True) returns Boolean is deferred; |
169 | ---Purpose: Update presentation of the progress indicator |
170 | -- Called when progress position is changed |
171 | -- Flag force is intended for forcing update in case if it is |
172 | -- optimized; all internal calls from ProgressIndicator are |
173 | -- done with this flag equal to False |
174 | |
175 | ---Scope: Methods to request state of progress indicator (mainly for descendants) |
176 | |
177 | GetPosition (me) returns Real; |
178 | ---C++: inline |
179 | ---Purpose: Returns total progress position on the basic scale |
180 | -- ranged from 0. to 1. |
181 | |
182 | GetNbScopes (me) returns Integer; |
183 | ---Purpose: Returns current number of opened scopes |
184 | -- This number is always >=1 as top-level scale is always present |
185 | |
186 | GetScope (me; index: Integer) returns ProgressScale from Message; |
187 | ---C++: return const & |
188 | ---Purpose: Returns data for scale of index-th scope |
189 | -- The first scope is current one, the last is the top-level one |
190 | |
191 | fields |
192 | |
193 | myPosition: Real; |
194 | myScopes: SequenceOfProgressScale from Message; |
195 | |
196 | end ProgressIndicator; |