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