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