Test for 0022778: Bug in BRepMesh
[occt.git] / src / XSControl / XSControl_Controller.cdl
1 -- Created on: 1995-03-13
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 deferred class Controller  from XSControl  inherits TShared
24
25     ---Purpose : This class allows a general X-STEP engine to run generic
26     --           functions on any interface norm, in the same way. It includes
27     --           the transfer operations. I.e. it gathers the already available
28     --           general modules, the engine has just to know it
29     --           
30     --           The important point is that a given X-STEP Controller is
31     --           attached to a given couple made of an Interface Norm (such as
32     --           IGES-5.1) and an application data model (CasCade Shapes for
33     --           instance).
34     --           
35     --           A Controller brings a Profile, this allows to have several
36     --           variants on the same basic definition, for instance keep the
37     --           norm definition but give several transfer actors, etc
38     --           
39     --           Finally, Controller can be gathered in a general dictionary then
40     --           retreived later by a general call (method Recorded)
41     --           
42     --           It does not manage the produced data, but the Actors make the
43     --           link between the norm and the application
44
45 uses CString,  AsciiString, SequenceOfTransient, SequenceOfInteger,
46      DictionaryOfTransient, DictionaryOfInteger,
47      HArray1OfHAsciiString   from Interface,
48      HSequenceOfHAsciiString from TColStd,
49      Protocol         from Interface,
50      Signature        from IFSelect,
51      InterfaceModel   from Interface,
52      CheckIterator    from Interface,
53      ActorOfTransientProcess from Transfer,
54      ActorOfFinderProcess    from Transfer,
55      FinderProcess    from Transfer,
56      Shape            from TopoDS,
57      WorkLibrary      from IFSelect,
58      Profile          from IFSelect,
59      WorkSession      from XSControl,
60      ReturnStatus     from IFSelect
61
62 raises DomainError
63
64 is
65
66     Initialize (longname, shortname : CString);
67     ---Purpose : Initializing with names
68     --           <longname>  is for the complete, official, long  name
69     --           <shortname> is for the short name used for resources
70
71     SetNames   (me : mutable; longname, shortname : CString);
72     ---Purpose : Changes names
73     --           if a name is empty, the formerly set one remains
74     --           Remark : Does not call Record or AutoRecord
75
76     AutoRecord (me)  raises DomainError;
77     ---Purpose : Records <me> is a general dictionary under Short and Long
78     --           Names (see method Name)
79
80     Record   (me; name : CString)  raises DomainError;
81     ---Purpose : Records <me> in a general dictionary under a name
82     --           Error if <name> already used for another one
83
84     Recorded (myclass; name : CString) returns mutable Controller;
85     ---Purpose : Returns the Controller attached to a given name
86     --           Returns a Null Handle if <name> is unknown
87
88     ListRecorded (myclass; mode : Integer = 0) returns HSequenceOfHAsciiString;
89     ---Purpose : Returns the list of names of recorded norms, according to mode
90     --           = 0 (D) : all the recorded names
91     --           < 0 : for each distinct norm, its resource (short) name
92     --           > 0 : for each distinct norm, its complete (long)  name
93
94     Name          (me; rsc : Boolean = Standard_False) returns CString;
95     ---Purpose : Returns a name, as given when initializing :
96     --           rsc = False (D) : True Name attached to the Norm (long name)
97     --           rsc = True : Name of the ressource set (i.e. short name)
98
99     Profile       (me) returns Profile from IFSelect;
100     ---Purpose : Returns the Profile
101     --           It starts with a first configuration Base (empty) and the
102     --           following options :
103     --           protocol    for the Protocol
104     --           sign-type   for the SignType (Default Signature for Type)
105     --           access      for the WorkLibrary
106     --           tr-read  for ActorRead  (import processor)
107     --           tr-write for ActorWrite (export processor)
108
109     DefineProfile (me : mutable; confname : CString);
110     ---Purpose : Considers the current state of the Controller as defining a
111     --           configuration, newly created or already existing
112
113     SetProfile (me : mutable; confname : CString) returns Boolean;
114     ---Purpose : Sets the Controller in a given Configuration of its Profile
115     --           Calls SettingProfile (which can be redefined)
116     --           
117     --           Returns True if done, False if <confname> unknown
118
119     SettingProfile (me : mutable; confname : CString)
120         returns Boolean  is virtual;
121     ---Purpose : This method is called by SetProfile, it can be redefined
122     --           for specific sub-class of Controller
123     --           The default does nothing
124
125     ApplyProfile (me : mutable; WS : WorkSession from XSControl; confname : CString)
126         returns Boolean;
127     ---Purpose : Applies a Configuration of the Profile to the WorkSession
128     --           I.E. calls SetProfile then fills WorkSession with definitions
129
130     ApplyingProfile (me : mutable; WS : WorkSession from XSControl; confname : CString)
131         returns Boolean  is virtual;
132     ---Purpose : Called by ApplyProfile, can be redefined for specific
133     --           sub-class of Controller
134     --           The default does nothing
135
136
137     Protocol      (me) returns Protocol from Interface;
138     ---Purpose : Returns the Protocol attached to the Norm (from field)
139
140     SignType      (me) returns Signature from IFSelect;
141     ---Purpose : Returns the SignType attached to the norm (from field)
142
143     WorkLibrary   (me) returns WorkLibrary from IFSelect;
144     ---Purpose : Returns the WorkLibrary attached to the Norm. Remark that it
145     --           has to be in phase with the Protocol  (read from field)
146
147     NewModel      (me) returns mutable InterfaceModel from Interface  is deferred;
148     ---Purpose : Creates a new empty Model ready to receive data of the Norm
149     --           Used to write data from Imagine to an interface file
150
151     ActorRead     (me; model : InterfaceModel)
152                  returns mutable ActorOfTransientProcess from Transfer  is deferred;
153     ---Purpose : Returns the Actor for Read attached to the pair (norm,appli)
154     --           It can be adapted for data of the input Model, as required
155     --           Can be read from field then adapted with Model as required
156
157     ActorWrite    (me) returns mutable ActorOfFinderProcess from Transfer
158         is virtual;
159     ---Purpose : Returns the Actor for Write attached to the pair (norm,appli)
160     --           Read from field. Can be redefined
161
162     UpdateStatics (me; mode : Integer; criter : CString = "")  is virtual;
163     ---Purpose : Updates static values
164     --           <mode> precises the kind of updating : (see Items from Static)
165     --           -1 : a precise static item : criter = its name
166     --           0  : all items of a family : criter = the family name
167     --           1  : all items which match regexp name : criter = regexp name
168     --           By default (criter empty) should consider all relevant statics
169     --           If <name> is defined, can consider only this static item
170     --           The provided default method does nothing, to be redefined
171
172
173         --  Writing Actions (can be redefined from ActorWrite using)
174         --  These actions are ran under control of a TransferWriter
175
176     SetModeWrite (me : mutable; modemin, modemax : Integer; shape : Boolean = Standard_True);
177     ---Purpose : Sets mininum and maximum values for modetrans (write)
178     --           Erases formerly recorded bounds and values
179     --           Actually only for shape
180     --           Then, for each value a little help can be attached
181
182     SetModeWriteHelp (me : mutable; modetrans : Integer; help : CString;
183                       shape : Boolean = Standard_True);
184     ---Purpose : Attaches a short line of help to a value of modetrans (write)
185
186     ModeWriteBounds (me; modemin, modemax : out Integer;
187                      shape : Boolean = Standard_True)    returns Boolean;
188     ---Purpose : Returns recorded min and max values for modetrans (write)
189     --           Actually only for shapes
190     --           Returns True if bounds are set, False else (then, free value)
191
192     IsModeWrite (me; modetrans : Integer; shape : Boolean = Standard_True)
193         returns Boolean;
194     ---Purpose : Tells if a value of <modetrans> is a good value(within bounds)
195     --           Actually only for shapes
196
197     ModeWriteHelp (me; modetrans : Integer; shape : Boolean = Standard_True)
198         returns CString;
199     ---Purpose : Returns the help line recorded for a value of modetrans
200     --           empty if help not defined or not within bounds or if values are free
201
202
203     RecognizeWriteTransient (me; obj : Transient; modetrans : Integer = 0)
204         returns Boolean  is virtual;
205     ---Purpose : Tells if <obj> (an application object) is a valid candidate
206     --           for a transfer to a Model.
207     --           By default, asks the ActorWrite if known (through a
208     --           TransientMapper). Can be redefined
209
210     TransferWriteTransient (me; obj : Transient;
211                         FP        : mutable FinderProcess  from Transfer;
212                         model     : mutable InterfaceModel from Interface;
213                         modetrans : Integer = 0)
214         returns ReturnStatus  is virtual;
215     ---Purpose : Takes one Transient Object and transfers it to an
216     --             InterfaceModel (already created, e.g. by NewModel)
217     --           (result is recorded in the model by AddWithRefs)
218     --           FP records produced results and checks
219     --           
220     --           Default uses ActorWrite; can be redefined as necessary
221     --           Returned value is a status, as follows :
222     --             0  OK ,  1 No Result ,  2 Fail (e.g. exception raised)
223     --             -1 bad conditions ,  -2 bad model or null model
224     --           For type of object not recognized : should return 1
225
226     RecognizeWriteShape (me; shape : Shape from TopoDS; modetrans: Integer = 0)
227         returns Boolean  is virtual;
228     ---Purpose : Tells if a shape is valid for a transfer to a model
229     --           Asks the ActorWrite (through a ShapeMapper)
230
231     TransferWriteShape (me; shape : Shape from TopoDS;
232                         FP        : mutable FinderProcess  from Transfer;
233                         model     : mutable InterfaceModel from Interface;
234                         modetrans : Integer = 0)
235         returns ReturnStatus  is virtual;
236     ---Purpose : Takes one Shape and transfers it to an
237     --             InterfaceModel (already created, e.g. by NewModel)
238     --           Default uses ActorWrite; can be redefined as necessary
239     --           Returned value is a status, as follows :
240     --             Done  OK ,  Void : No Result ,  Fail : Fail (e.g. exception)
241     --             Error : bad conditions , bad model or null model
242         --  Resolution of file clusters
243         --  According to each norm, there can (or not) be files of which
244         --  definition is not complete but refers to other files : this defines
245         --  a file cluster.
246         --  It can then be resolved by two calls :
247         --  - ClusterContext prepares the resolution, specific of each case
248         --  - ResolveCluster performs the resolution, its result consists in
249         --    having all data gathered in one final model
250
251     ClusterContext (me; WS : WorkSession) returns mutable Transient is virtual;
252     ---Purpose : Prepares and returns a context to resolve a cluster
253     --           All data to be used are detained by the WorkSession
254     --           The definition of this context is free and proper to each case
255     --           remark that it is aimed to be used in ResolveCluster
256     --           
257     --           The context must be prepared, but resolution must not have
258     --           began
259     --           
260     --           If no cluster has to be resolved, should return a null handle
261     --           This is the default case, which can be redefined
262
263     ResolveCluster (me; WS : mutable WorkSession; context : mutable Transient)
264         returns CheckIterator  is virtual;
265     ---Purpose : Performs the resolution itself, from the starting data and
266     --           the cluster context
267     --           
268     --           Can fill a CheckList as necessary (especially when one or
269     --           more references remain unresolved)
270     --           
271     --           Default does nothing and returns an empty CheckList
272
273         --  Additional Items as required (free list), each item is named
274
275     AddControlItem (me : mutable; item : any Transient; name : CString);
276     ---Purpose : Adds an item in the control list
277     --           A control item of a controller is accessed by its name which
278     --           is specific of a kind of item (i.e. a kind of functionnality)
279     --           Adds or replaces if <name> is already recorded
280
281     ControlItem (me; name : CString) returns any Transient;
282     ---Purpose : Returns a control item from its name, Null if <name> unknown
283     --           To be used then, it just remains to be down-casted
284
285         --  To Help Session Customising  --
286
287     TraceStatic    (me : mutable; name : CString; use : Integer);
288     ---Purpose : Records the name of a Static to be traced for a given use
289
290     AddSessionItem (me : mutable; item : Transient; name : CString;
291                     setapplied : CString = "");
292     ---Purpose : Records a Session Item, to be added for customisation of the
293     --           Work Session. It must have a specific name.
294     --           <setapplied> is used if <item> is a GeneralModifier, to decide
295     --           to which hook list it will be applied, if not empty (else,
296     --           not applied to any hook list)
297     --           ACTUAL : only one hook list is managed : "send"
298     --           Remark : this method is to be called at Create time, the
299     --           recorded items will be used by Customise
300     --  Warning : if <name> conflicts, the last recorded item is kept
301
302     SessionItem (me; name : CString) returns Transient;
303     ---Purpose : Returns an item given its name to record in a Session
304     --           If <name> is unknown, returns a Null Handle
305
306     IsApplied (me; item : Transient) returns Boolean;
307     ---Purpose : Returns True if <item> is recorded as <setapplied = True>
308
309     Customise (me: mutable; WS : in out WorkSession) is virtual;
310     ---Purpose : Customises a WorkSession, by adding to it the recorded items
311     --           (by AddSessionItem), then by calling a specific method
312     --           Customising, set by default to do nothing
313
314     Customising (me : mutable; WS : in out WorkSession);    -- is virtual
315     ---Purpose : Specific customisation method, which can be redefined
316     --           Default does nothing
317     AdaptorSession(me) returns DictionaryOfTransient;
318     
319 fields
320
321     theProfile  : Profile;
322
323     theShortName       : AsciiString  is protected;
324     theLongName        : AsciiString  is protected;
325
326     theAdaptorLibrary  : WorkLibrary  is protected;
327     theAdaptorProtocol : Protocol     is protected;
328     theSignType        : Signature    is protected;
329     theAdaptorRead     : ActorOfTransientProcess  is protected;
330     theAdaptorWrite    : ActorOfFinderProcess     is protected;
331
332     theItems : DictionaryOfTransient;
333
334     theAdaptorSession  : DictionaryOfTransient    is protected;
335     theAdaptorApplied  : SequenceOfTransient;
336     theAdaptorHooks    : HSequenceOfHAsciiString from TColStd;
337     theParams          : SequenceOfTransient from TColStd;
338     theParamUses       : SequenceOfInteger   from TColStd;
339
340     theModeWriteShapeN : HArray1OfHAsciiString   from Interface;
341
342 end Controller;