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