Integration of OCCT 6.5.0 from SVN
[occt.git] / src / XSControl / XSControl_TransferReader.cdl
1 -- File:        XSControl_TransferReader.cdl
2 -- Created:     Tue Dec  5 10:50:44 1995
3 -- Author:      Christian CAILLET
4 --              <cky@fidox>
5 ---Copyright:    Matra Datavision 1995
6
7
8 class TransferReader  from XSControl  inherits TShared
9
10     ---Purpose : A TransferReader performs, manages, handles results of,
11     --           transfers done when reading a file (i.e. from entities of an
12     --           InterfaceModel, to objects for Imagine)
13     --           
14     --           Running is organised around basic tools : TransientProcess and
15     --           its Actor, results are Binders and CheckIterators. It implies
16     --           control by a Controller (which prepares the Actor as required)
17     --           
18     --           Getting results can be done directly on TransientProcess, but
19     --           these are immediate "last produced" results. Each transfer of
20     --           an entity gives a final result, but also possible intermediate
21     --           data, and checks, which can be attached to sub-entities.
22     --           
23     --           Hence, final results (which intermediates and checks) are
24     --           recorded as ResultFromModel and can be queried individually.
25     --           
26     --           Some more direct access are given for results which are
27     --           Transient or Shapes
28
29 uses CString, AsciiString, Transient,
30      DataMapOfIntegerTransient, HSequenceOfTransient, DictionaryOfTransient,
31      InterfaceModel, CheckIterator, Graph, HGraph,
32      TransientProcess, ActorOfTransientProcess, Binder, ResultFromModel,
33      CheckStatus from Interface, Controller from XSControl,
34      Shape from TopoDS, HSequenceOfShape from TopTools
35
36 is
37
38     Create returns mutable TransferReader;
39     ---Purpose : Creates a TransferReader, empty
40
41         --    General Management    --
42
43     SetController (me : mutable; control : mutable Controller from XSControl);
44     ---Purpose : Sets a Controller. It is required to generate the Actor.
45     --           Elsewhere, the Actor must be provided directly
46
47     SetActor (me : mutable; actor : mutable ActorOfTransientProcess);
48     ---Purpose : Sets the Actor directly : this value will be used if the
49     --           Controller is not set
50
51     Actor    (me : mutable) returns mutable ActorOfTransientProcess;
52     ---Purpose : Returns the Actor, determined by the Controller, or if this
53     --           one is unknown, directly set.
54     --           Once it has been defined, it can then be edited.
55
56     SetModel (me : mutable; model : InterfaceModel);
57     ---Purpose : Sets an InterfaceModel. This causes former results, computed
58     --           from another one, to be lost (see also Clear)
59
60     SetGraph (me : mutable; graph : HGraph);
61     ---Purpose : Sets a Graph and its InterfaceModel (calls SetModel)
62
63     Model    (me) returns InterfaceModel;
64     ---Purpose : Returns the currently set InterfaceModel
65
66     SetContext (me : mutable; name : CString; ctx : Transient);
67     ---Purpose : Sets a Context : according to receiving appli, to be
68     --           interpreted by the Actor
69
70     GetContext (me; name : CString; type : Type; ctx : out Transient)
71         returns Boolean;
72     ---Purpose : Returns the Context attached to a name, if set and if it is
73     --           Kind of the type, else a Null Handle
74     --           Returns True if OK, False if no Context
75
76     Context    (me : mutable) returns DictionaryOfTransient;
77     ---Purpose : Returns (modifiable) the whole definition of Context
78     --           Rather for internal use (ex.: preparing and setting in once)
79     ---C++ : return &
80
81     SetFileName (me : mutable; name : CString);
82     ---Purpose : Sets a new value for (loaded) file name
83
84     FileName (me) returns CString;
85     ---Purpose : Returns actual value of file name
86
87     Clear    (me : mutable; mode : Integer);
88     ---Purpose : Clears data, according mode :
89     --           -1 all
90     --            0 nothing done
91     --           +1 final results
92     --           +2 working data (model, context, transfer process)
93
94     TransientProcess (me) returns mutable TransientProcess;
95     ---Purpose : Returns the currently used TransientProcess
96     --           It is computed from the model by TransferReadRoots, or by
97     --           BeginTransferRead
98
99     SetTransientProcess (me : mutable; TP : mutable TransientProcess);
100     ---Purpose : Forces the TransientProcess
101     --           Remark : it also changes the Model and the Actor, from those
102     --           recorded in the new TransientProcess
103
104
105         --    Recording and Querying Results    --
106         --    these methods work mainly on recorded data
107         --    i.e. they don't need Controller and Actor
108
109     RecordResult (me : mutable; ent : Transient) returns Boolean;
110     ---Purpose : Records a final result of transferring an entity
111     --           This result is recorded as a ResultFromModel, taken from
112     --           the TransientProcess
113     --           Returns True if a result is available, False else
114
115     IsRecorded   (me; ent : Transient) returns Boolean;
116     ---Purpose : Returns True if a final result is recorded for an entity
117     --           Remark that it can bring no effective result if transfer has
118     --           completely failed (FinalResult brings only fail messages ...)
119
120     HasResult    (me; ent : Transient) returns Boolean;
121     ---Purpose : Returns True if a final result is recorded AND BRINGS AN
122     --           EFFECTIVE RESULT (else, it brings only fail messages)
123
124     RecordedList (me) returns HSequenceOfTransient;
125     ---Purpose : Returns the list of entities to which a final result is
126     --           attached (i.e. processed by RecordResult)
127
128     Skip         (me : mutable; ent : Transient) returns Boolean;
129     ---Purpose : Note that an entity has been required for transfer but no
130     --           result at all is available (typically : case not implemented)
131     --           It is not an error, but it gives a specific status : Skipped
132     --           Returns True if done, False if <ent> is not in starting model
133
134     IsSkipped    (me; ent : Transient) returns Boolean;
135     ---Purpose : Returns True if an entity is noted as skipped
136
137     IsMarked     (me; ent : Transient) returns Boolean;
138     ---Purpose : Returns True if an entity has been asked for transfert, hence
139     --           it is marked, as : Recorded (a computation has ran, with or
140     --           without an effective result), or Skipped (case ignored)
141
142
143     FinalResult  (me; ent : Transient) returns ResultFromModel;
144     ---Purpose : Returns the final result recorded for an entity, as such
145
146     FinalEntityLabel  (me; ent : Transient) returns CString;
147     ---Purpose : Returns the label attached to an entity recorded for final,
148     --           or an empty string if not recorded
149
150     FinalEntityNumber (me; ent : Transient) returns Integer;
151     ---Purpose : Returns the number attached to the entity recorded for final,
152     --           or zero if not recorded (looks in the ResultFromModel)
153
154     ResultFromNumber  (me; num : Integer) returns ResultFromModel;
155     ---Purpose : Returns the final result recorded for a NUMBER of entity
156     --           (internal use). Null if out of range
157
158     TransientResult   (me; ent : Transient) returns mutable Transient;
159     ---Purpose : Returns the resulting object as a Transient
160     --           Null Handle if no result or result not transient
161
162     ShapeResult       (me; ent : Transient) returns Shape from TopoDS;
163     ---Purpose : Returns the resulting object as a Shape
164     --           Null Shape if no result or result not a shape
165
166     ClearResult (me : mutable; ent : Transient; mode : Integer) returns Boolean;
167     ---Purpose : Clears recorded result for an entity, according mode
168     --           <mode> = -1 : true, complete, clearing (erasing result)
169     --           <mode> >= 0 : simple "stripping", see ResultFromModel,
170     --             in particular, 0 for simple internal strip,
171     --             10 for all but final result,
172     --             11 for all : just label, status and filename are kept
173     --           Returns True when done, False if nothing was to clear
174
175
176     EntityFromResult (me; res : Transient; mode : Integer=0) returns Transient;
177     ---Purpose : Returns an entity from which a given result was produced.
178     --           If <mode> = 0 (D), searches in last root transfers
179     --           If <mode> = 1,     searches in last (root & sub) transfers
180     --           If <mode> = 2,     searches in root recorded results
181     --           If <mode> = 3,     searches in all (root & sub) recordeds
182     --           <res> can be, either a transient object (result itself) or
183     --           a binder. For a binder of shape, calls EntityFromShapeResult
184     --           Returns a Null Handle if <res> not recorded
185
186     EntityFromShapeResult (me; res : Shape from TopoDS; mode : Integer=0)
187         returns Transient;
188     ---Purpose : Returns an entity from which a given shape result was produced
189     --           Returns a Null Handle if <res> not recorded or not a Shape
190
191     EntitiesFromShapeList (me; res : HSequenceOfShape from TopTools; mode : Integer = 0)
192         returns HSequenceOfTransient from TColStd;
193     ---Purpose : Returns the list of entities from which some shapes were
194     --           produced : it corresponds to a loop on EntityFromShapeResult,
195     --           but is optimised
196
197
198     CheckList (me; ent : Transient; level : Integer = 0) returns CheckIterator;
199     ---Purpose : Returns the CheckList resulting from transferring <ent>, i.e.
200     --           stored in its recorded form ResultFromModel
201     --           (empty if transfer successful or not recorded ...)
202     --           
203     --           If <ent> is the Model, returns the complete cumulated
204     --           check-list, <level> is ignored
205     --           
206     --           If <ent> is an entity of the Model, <level> applies as follows
207     --           <level> : -1 for <ent> only, LAST transfer (TransientProcess)
208     --           <level> : 0  for <ent> only (D)
209     --                     1  for <ent> and its immediate subtransfers, if any
210     --                     2  for <ent> and subtransferts at all levels
211
212     HasChecks (me; ent : Transient; failsonly : Boolean) returns Boolean;
213     ---Purpose : Returns True if an entity (with a final result) has checks :
214     --           - failsonly = False : any kind of check message
215     --           - failsonly = True  : fails only
216     --           Returns False if <ent> is not recorded
217
218     CheckedList (me; ent : Transient;
219         withcheck : CheckStatus = Interface_CheckAny; result : Boolean = Standard_True)
220             returns HSequenceOfTransient;
221     ---Purpose : Returns the list of starting entities to which a given check
222     --           status is attached, IN FINAL RESULTS
223     --           <ent> can be an entity, or the model to query all entities
224     --           Below, "entities" are, either <ent> plus its sub-transferred,
225     --           or all the entities of the model
226     --           
227     --           <check> = -2 , all entities whatever the check (see result)
228     --           <check> = -1 , entities with no fail (warning allowed)
229     --           <check> =  0 , entities with no check at all
230     --           <check> =  1 , entities with warning but no fail
231     --           <check> =  2 , entities with fail
232     --           <result> : if True, only entities with an attached result
233     --           Remark : result True and check=0 will give an empty list
234
235         --  Actions for Transfer (Read)  --
236
237     BeginTransfer (me : mutable) returns Boolean;
238     ---Purpose : Defines a new TransferProcess for reading transfer
239     --           Returns True if done, False if data are not properly defined
240     --           (the Model, the Actor for Read)
241
242     Recognize     (me : mutable; ent : Transient) returns Boolean;
243     ---Purpose : Tells if an entity is recognized as a valid candidate for
244     --           Transfer. Calls method Recognize from the Actor (if known)
245
246     TransferOne   (me : mutable; ent : Transient;
247                    rec : Boolean = Standard_True) returns Integer;
248     ---Purpose : Commands the transfer on reading for an entity to data for
249     --           Imagine, using the selected Actor for Read
250     --           Returns count of transferred entities, ok or with fails (0/1)
251     --           If <rec> is True (D), the result is recorded by RecordResult
252
253     TransferList  (me : mutable; list : HSequenceOfTransient;
254                    rec : Boolean = Standard_True) returns Integer;
255     ---Purpose : Commands the transfer on reading for a list of entities to
256     --           data for Imagine, using the selected Actor for Read
257     --           Returns count of transferred entities, ok or with fails (0/1)
258     --           If <rec> is True (D), the results are recorded by RecordResult
259
260     TransferRoots (me : mutable; G : Graph) returns Integer;
261     ---Purpose : Transfers the content of the current Interface Model to
262     --           data handled by Imagine, starting from its Roots (determined
263     --           by the Graph <G>),  using the selected Actor for Read
264     --           Returns the count of performed root transfers (i.e. 0 if none)
265     --           or -1 if no actor is defined
266
267     TransferClear (me : mutable; ent : Transient; level : Integer = 0);
268     ---Purpose : Clears the results attached to an entity
269     --           if <ents> equates the starting model, clears all results
270
271     PrintStats (me; what : Integer; mode : Integer = 0);
272     ---Purpose : Prints statistics on current Trace File, according <what> and
273     --           <mode>.  See PrintStatsProcess for details
274
275         --    Querying last transfer (i.e. TransientProcess)    --
276
277     LastCheckList    (me) returns CheckIterator;
278     ---Purpose : Returns the CheckList resulting from last TransferRead
279     --           i.e. from TransientProcess itself, recorded from last Clear
280
281     LastTransferList (me; roots : Boolean) returns HSequenceOfTransient;
282     ---Purpose : Returns the list of entities recorded as lastly transferred
283     --           i.e. from TransientProcess itself, recorded from last Clear
284     --           If <roots> is True , considers only roots of transfer
285     --           If <roots> is False, considers all entities bound with result
286
287     ShapeResultList (me : mutable; rec : Boolean)
288         returns HSequenceOfShape from TopTools;
289     ---Purpose : Returns a list of result Shapes
290     --           If <rec> is True , sees RecordedList
291     --           If <rec> is False, sees LastTransferList (last ROOT transfers)
292     --           For each one, if it is a Shape, it is cumulated to the list
293     --           If no Shape is found, returns an empty Sequence
294
295     PrintStatsProcess (myclass; TP : TransientProcess;
296                        what : Integer; mode : Integer = 0);
297     ---Purpose : This routines prints statistics about a TransientProcess
298     --           It can be called, by a TransferReader, or isolately
299     --           Prints are done on the default trace file
300     --           <what> defines what kind of statistics are to be printed :
301     --           0 : basic figures
302     --           1 : root results
303     --           2 : all recorded (roots, intermediate, checked entities)
304     --           3 : abnormal records
305     --           4 : check messages (warnings and fails)
306     --           5 : fail messages
307     --           
308     --           <mode> is used according <what> :
309     --           <what> = 0 : <mode> is ignored
310     --           <what> = 1,2,3 : <mode> as follows :
311     --           0 (D) : just lists numbers of concerned entities in the model
312     --           1 : for each entity, gives number,label, type and result
313     --                  type and/or status (fail/warning...)
314     --           2 : for each entity, gives maximal information (i.e. checks)
315     --           3 : counts per type of starting entity (class type)
316     --           4 : counts per result type and/or status
317     --           5 : counts per couple (starting type / result type/status)
318     --           6 : idem plus gives for each item, the list of numbers of
319     --                  entities in the starting model
320     --           
321     --           <what> = 4,5 : modes relays on an enum PrintCount :
322     --           0 (D) : ItemsByEntity (sequential list by entity)
323     --           1 : CountByItem
324     --           2 : ShortByItem       (count + 5 first numbers)
325     --           3 : ListByItem        (count + entity numbers)
326     --           4 : EntitiesByItem    (count + entity numbers and labels)
327
328     PrintStatsOnList (myclass; TP : TransientProcess;
329                        list : HSequenceOfTransient;
330                        what : Integer; mode : Integer = 0);
331     ---Purpose : Works as PrintStatsProcess, but displays data only on the
332     --           entities which are in <list> (filter)
333
334 fields
335
336     theController  : Controller;
337
338     theFilename    : AsciiString;
339     theModel       : InterfaceModel;
340     theGraph       : HGraph;
341     theContext     : DictionaryOfTransient;
342
343     theActor       : ActorOfTransientProcess;
344     theTransfer    : TransientProcess;
345
346     theResults     : DataMapOfIntegerTransient;
347     theShapeResult : HSequenceOfShape from TopTools;
348
349 end TransferReader;