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