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