0023595: XCAFDoc_ShapeTool extended with two methods - SetAutoNaming() and AutoNaming()
[occt.git] / src / XCAFDoc / XCAFDoc_ShapeTool.cdl
1 -- Created on: 2000-06-15
2 -- Created by: Edward AGAPOV
3 -- Copyright (c) 2000-2012 OPEN CASCADE SAS
4 --
5 -- The content of this file is subject to the Open CASCADE Technology Public
6 -- License Version 6.5 (the "License"). You may not use the content of this file
7 -- except in compliance with the License. Please obtain a copy of the License
8 -- at http://www.opencascade.org and read it completely before using this file.
9 --
10 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
11 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
12 --
13 -- The Original Code and all software distributed under the License is
14 -- distributed on an "AS IS" basis, without warranty of any kind, and the
15 -- Initial Developer hereby disclaims all such warranties, including without
16 -- limitation, any warranties of merchantability, fitness for a particular
17 -- purpose or non-infringement. Please see the License for the specific terms
18 -- and conditions governing the rights and limitations under the License.
19
20
21
22 class ShapeTool from XCAFDoc inherits Attribute from TDF
23
24     ---Purpose:  A tool to store shapes in an XDE
25 -- document in the form of assembly structure, and to maintain this structure.
26 -- The API provided by this class allows to work with this
27 -- structure regardless of its low-level implementation.
28 -- All the shapes are stored on child labels of a main label which is
29 -- XCAFDoc_DocumentTool::LabelShapes(). The label for assembly also has
30 -- sub-labels, each of which represents the instance of
31 -- another shape in that assembly (component). Such sub-label
32 -- stores reference to the label of the original shape in the form
33 -- of TDataStd_TreeNode with GUID XCAFDoc::ShapeRefGUID(), and its
34 -- location encapsulated into the NamedShape.
35 -- For correct work with an XDE document, it is necessary to use
36 -- methods for analysis and methods for working with shapes.
37 -- For example:
38 -- if ( STool->IsAssembly(aLabel) )
39 -- { Standard_Boolean subchilds = Standard_False; (default) 
40 -- Standard_Integer nbc = STool->NbComponents
41 -- (aLabel[,subchilds]); 
42 -- }
43 -- If subchilds is True, commands also consider sub-levels. By
44 -- default, only level one is checked.
45 -- In this example, number of children from the first level of
46 -- assembly will be returned. Methods for creation and initialization:
47 -- Constructor: 
48 -- XCAFDoc_ShapeTool::XCAFDoc_ShapeTool() 
49 -- Getting a guid:
50 -- Standard_GUID GetID (); 
51 -- Creation (if does not exist) of ShapeTool on label L: 
52 -- Handle(XCAFDoc_ShapeTool) XCAFDoc_ShapeTool::Set(const TDF_Label& L)  
53 --   Analyze whether shape is a simple shape or an instance or a
54 -- component of an assembly or it is an assembly ( methods of analysis).
55 -- For example:
56 -- STool->IsShape(aLabel) ;
57 -- Analyze that the label represents a shape (simple
58 -- shape, assembly or reference) or 
59 -- STool->IsTopLevel(aLabel);
60 -- Analyze that the label is a label of a top-level shape.
61 --   Work with simple shapes, assemblies and instances (
62 -- methods for work with shapes).
63 -- For example:
64 --   Add shape:
65 -- Standard_Boolean makeAssembly;
66 -- // True to interpret a Compound as an Assembly, False to take it
67 -- as a whole
68 -- aLabel = STool->AddShape(aShape, makeAssembly);
69 --        Get shape:
70 -- TDF_Label aLabel...
71 -- // A label must be present if
72 --  (aLabel.IsNull()) { ... no such label : abandon .. }
73 -- TopoDS_Shape aShape;
74 -- aShape = STool->GetShape(aLabel);
75 -- if (aShape.IsNull())
76 -- { ... this label is not for a Shape ... }
77 --   To get a label from shape.
78 -- Standard_Boolean findInstance = Standard_False;
79 -- (this is default value)
80 -- aLabel = STool->FindShape(aShape [,findInstance]);
81 -- if (aLabel.IsNull()) 
82 --  { ... no label found for this shape ... }
83
84 uses
85     Document from TDocStd,
86     TreeNode from TDataStd,
87     Location from TopLoc,
88     Label from TDF,
89     LabelSequence from TDF,
90     LabelMap from TDF,
91     Shape from TopoDS,
92     SequenceOfShape from TopTools,
93     HAsciiString from TCollection,
94     RelocationTable from TDF,
95     SequenceOfHAsciiString from TColStd,
96     GraphNode from XCAFDoc,
97     AttributeSequence from TDF,
98     DataMapOfShapeLabel from XCAFDoc
99     
100 is
101     GetID (myclass)   
102     ---C++: return const &  
103     returns GUID from Standard;    
104
105
106     Set (myclass; L : Label from TDF) returns ShapeTool from XCAFDoc;
107     ---Purpose: Create (if not exist) ShapeTool from XCAFDoc on <L>.
108
109
110     
111     
112     Create returns ShapeTool from XCAFDoc;
113         ---Purpose: Creates an empty tool
114     
115     --Create (Doc: Document from TDocStd) returns ShapeTool from XCAFDoc;
116         ---Purpose: Creates a tool to work with a document <Doc>
117         --          Attaches to label XCAFDoc::LabelShapes()
118
119     
120     
121     ---API: Analysis
122
123     IsTopLevel (me; L: Label from TDF) returns Boolean;
124         ---Purpose: Returns True if the label is a label of top-level shape,
125         --          as opposed to component of assembly or subshape
126
127     IsFree (myclass; L: Label from TDF) returns Boolean;
128         ---Purpose: Returns True if the label is not used by any assembly, i.e.
129         --          contains sublabels which are assembly components
130         --          This is relevant only if IsShape() is True
131         --                  (There  is  no  Father TreeNode on  this  <L>)
132
133     IsShape (myclass; L: Label from TDF) returns Boolean;
134         ---Purpose: Returns True if the label represents a shape (simple shape,
135         --          assembly or reference)
136
137     IsSimpleShape (myclass; L: Label from TDF) returns Boolean;
138         ---Purpose: Returns True if the label is a label of simple shape
139
140     IsReference (myclass; L: Label from TDF) returns Boolean;
141         ---Purpose: Return true if <L> is a located instance of other shape 
142         --          i.e. reference
143     
144     IsAssembly (myclass; L: Label from TDF) returns Boolean;
145         ---Purpose: Returns True if the label is a label of assembly, i.e.
146         --          contains sublabels which are assembly components
147         --          This is relevant only if IsShape() is True
148
149     IsComponent (myclass; L: Label from TDF) returns Boolean;
150         ---Purpose: Return true if <L> is reference serving as component 
151         --          of assembly
152     
153     IsCompound (myclass; L: Label from TDF) returns Boolean;
154         ---Purpose: Returns True if the label is a label of compound, i.e.
155         --          contains some sublabels
156         --          This is relevant only if IsShape() is True
157
158     IsSubShape (myclass; L: Label from TDF) returns Boolean;
159         ---Purpose: Return true if <L> is subshape of the top-level shape
160     
161     IsSubShape (me; shapeL: Label from TDF; 
162                     sub: Shape from TopoDS) 
163     returns Boolean;
164         ---Purpose: Checks whether shape <sub> is subshape of shape stored on
165         --          label shapeL
166
167     ---API: Work with top-level structure of shapes 
168
169     SearchUsingMap (me; S: Shape from TopoDS; L: out Label from TDF;
170                         findWithoutLoc: Boolean; findSubshape: Boolean)
171     returns Boolean from Standard;
172
173     Search (me; S: Shape from TopoDS; L: out Label from TDF; 
174                 findInstance: Boolean = Standard_True;
175                 findComponent: Boolean = Standard_True;
176                 findSubshape: Boolean = Standard_True)
177     returns Boolean from Standard;
178         ---Purpose: General tool to find a (sub) shape in the document
179         --        * If findInstance is True, and S has a non-null location,
180         --          first tries to find the shape among the top-level shapes 
181         --          with this location
182         --        * If not found, and findComponent is True, tries to find the shape
183         --          among the components of assemblies
184         --        * If not found, tries to find the shape without location
185         --          among top-level shapes 
186         --        * If not found and findSubshape is True, tries to find a 
187         --          shape as a subshape of top-level simple shapes
188         --          Returns False if nothing is found
189     
190     FindShape (me; S: Shape from TopoDS; L: out Label from TDF; 
191                    findInstance: Boolean = Standard_False) 
192     returns Boolean from Standard;
193         ---Purpose: Returns the label corresponding to shape S
194         --          (searches among top-level shapes, not including subcomponents
195         --          of assemblies)
196         --          If findInstance is False (default), searches for the 
197         --          non-located shape (i.e. among original shapes)
198         --          If findInstance is True, searches for the shape with the same 
199         --          location, including shape instances
200         --          Return True if <S> is found.
201     
202     FindShape (me; S: Shape from TopoDS; 
203                    findInstance: Boolean = Standard_False) 
204     returns Label from TDF;
205         ---Purpose: Does the same as previous method
206         --          Returns Null label if not found
207     
208     GetShape (myclass; L: Label from TDF;
209                        S: out Shape from TopoDS) returns Boolean from Standard;
210         ---Purpose: To get TopoDS_Shape from shape's label
211         --          For component, returns new shape with correct location
212         --          Returns False if label does not contain shape
213     
214     GetShape (myclass; L: Label from TDF) returns Shape from TopoDS;
215         ---Purpose: To get TopoDS_Shape from shape's label
216         --          For component, returns new shape with correct location
217         --          Returns Null shape if label does not contain shape
218
219     NewShape (me) returns Label from TDF;
220         ---Purpose: Creates new (empty) top-level shape.
221         --          Initially it holds empty TopoDS_Compound
222
223     SetShape (me:mutable; L: Label from TDF; S: Shape from TopoDS);
224         ---Purpose: Sets representation (TopoDS_Shape) for top-level shape
225
226     AddShape (me:mutable; S: Shape from TopoDS; 
227                           makeAssembly: Boolean = Standard_True;
228                           makePrepare : Boolean = Standard_True)
229     returns Label from TDF;
230         ---Purpose: Adds a new top-level (creates and returns a new label)
231         --          If makeAssembly is True, treats TopAbs_COMPOUND shapes 
232         --          as assemblies (creates assembly structure).
233         --          NOTE: <makePrepare> replace components without location
234         --          in assmebly by located components to avoid some problems.
235         --          If AutoNaming() is True then automatically attaches names.
236
237     addShape (me:mutable; S: Shape from TopoDS;
238               makeAssembly: Boolean = Standard_True)
239     returns Label from TDF is private;
240         ---Purpose: Adds a new top-level (creates and returns a new label)
241         --          For internal use. Used by public method AddShape.
242
243     RemoveShape (me; L: Label from TDF;
244                  removeCompletely: Boolean = Standard_True)
245     returns Boolean;
246         ---Purpose: Removes shape (whole label and all its sublabels)
247     --          If removeCompletely is true, removes complete shape
248         --          If removeCompletely is false, removes instance(location) only
249         --          Returns False (and does nothing) if shape is not free
250         --          or is not top-level shape
251     
252     Init (me: mutable);
253         ---Purpose: set hasComponents into false
254
255     SetAutoNaming (myclass; V: Boolean);
256         ---Purpose: Sets auto-naming mode to <V>. If True then for added
257         --          shapes, links, assemblies and SHUO's, the TDataStd_Name attribute
258         --          is automatically added. For shapes it contains a shape type
259         --          (e.g. "SOLID", "SHELL", etc); for links it has a form
260         --          "=>[0:1:1:2]" (where a tag is a label containing a shape
261         --          without a location); for assemblies it is "ASSEMBLY", and
262         --          "SHUO" for SHUO's.
263         --          This setting is global; it cannot be made a member function
264         --          as it is used by static methods as well.
265         --          By default, auto-naming is enabled.
266         --          See also AutoNaming().
267     
268     AutoNaming (myclass) returns Boolean;
269         ---Purpose: Returns current auto-naming mode. See SetAutoNaming() for
270         --          description.
271     
272     ComputeShapes (me: mutable; L: Label from TDF);
273         ---Purpose: recursive
274
275     ComputeSimpleShapes (me: mutable);
276         ---Purpose: Compute a sequence of simple shapes
277     
278     GetShapes (me; Labels: out LabelSequence from TDF);
279         ---Purpose: Returns a sequence of all top-level shapes
280     
281     GetFreeShapes (me; FreeLabels : out LabelSequence from TDF);
282         ---Purpose: Returns a sequence of all top-level shapes
283         --          which are free (i.e. not referred by any other)
284     
285     GetUsers (myclass; L: Label from TDF;
286                        Labels : out LabelSequence from TDF; 
287                        getsubchilds: Boolean from Standard = Standard_False)
288     returns Integer;
289         ---Purpose: Returns list of labels which refer shape L as component
290         --          Returns number of users (0 if shape is free)
291
292     GetLocation (myclass; L: Label from TDF)
293     returns Location from TopLoc;
294         ---Purpose: Returns location of instance
295
296     GetReferredShape (myclass; L: Label from TDF; 
297                                Label: out Label from TDF)
298     returns Boolean;
299         ---Purpose: Returns label which corresponds to a shape referred by L
300         --          Returns False if label is not reference
301
302     ---API: Work with assembly structure 
303
304     NbComponents (myclass; L: Label from TDF; 
305                        getsubchilds: Boolean from Standard = Standard_False)
306     returns Integer; 
307         ---Purpose: Returns number of Assembles components
308
309     GetComponents (myclass; L: Label from TDF;
310                             Labels : out LabelSequence from TDF;
311                             getsubchilds: Boolean from Standard = Standard_False)
312     returns Boolean;
313         ---Purpose: Returns list of components of assembly
314         --          Returns False if label is not assembly
315
316     AddComponent (me; assembly, comp: Label from TDF; 
317                       Loc: Location from TopLoc) 
318     returns  Label  from  TDF;
319         ---Purpose: Adds a component given by its label and location to the assembly
320         --          Note: assembly must be IsAssembly() or IsSimpleShape()
321
322     AddComponent (me:mutable; assembly: Label from TDF; 
323                       comp: Shape from TopoDS; expand: Boolean = Standard_False) 
324     returns  Label  from  TDF;
325         ---Purpose: Adds a shape (located) as a component to the assembly
326         --          If necessary, creates an additional top-level shape for 
327         --          component and return the Label of component. 
328         --          If expand is True and component is Compound, it will
329         --          be created as assembly also
330         --          Note: assembly must be IsAssembly() or IsSimpleShape()
331
332     RemoveComponent (me; comp: Label from TDF);
333         ---Purpose: Removes a component from its assembly
334
335     UpdateAssembly (me; L: Label from TDF);
336         ---Purpose: Update an assembly at label <L>
337
338     ---API: work with sub-shapes of shape
339
340     FindSubShape (me; shapeL: Label from TDF; 
341                       sub: Shape from TopoDS;
342                       L: out Label from TDF) 
343     returns Boolean;
344         ---Purpose: Finds a label for subshape <sub> of shape stored on
345         --          label shapeL
346         --          Returns Null label if it is not found
347
348     AddSubShape (me; shapeL: Label from TDF; 
349                      sub: Shape from TopoDS) 
350     returns Label from TDF;
351         ---Purpose: Adds a label for subshape <sub> of shape stored on
352         --          label shapeL
353         --          Returns Null label if it is not subshape
354
355     FindMainShapeUsingMap (me; sub: Shape from TopoDS) 
356     returns Label from TDF;
357
358     FindMainShape (me; sub: Shape from TopoDS) 
359     returns Label from TDF;
360         ---Purpose: Performs a search among top-level shapes to find
361         --          the shape containing <sub> as subshape
362         --          Checks only simple shapes, and returns the first found
363         --          label (which should be the only one for valid model)
364
365     GetSubShapes (myclass; L: Label from TDF;
366                            Labels : out LabelSequence from TDF)
367     returns Boolean;
368         ---Purpose: Returns list of labels identifying subshapes of the given shape
369         --          Returns False if no subshapes are placed on that label
370
371     ---API: Auxiliary
372
373     BaseLabel(me) returns Label from TDF;
374         ---Purpose: returns the label under which shapes are stored
375     
376     Dump(me; deep : Boolean from Standard = Standard_False);
377     
378     DumpShape(myclass; L:  Label from TDF;
379                        level :Integer from Standard = 0;
380                        deep : Boolean from Standard = Standard_False);
381     ---Purpose: Print in cout type of shape found on <L> label
382     --          and the entry of <L>, with <level> tabs before.
383     --          If <deep>, print also TShape and Location addresses
384         
385     --- Private
386     
387     MakeReference (myclass; L, refL: Label from TDF; loc: Location from TopLoc)
388     is private;
389         ---Purpose: Makes a shape on label L to be a reference to shape refL
390         --          with location loc
391
392     
393             ---Category: TDF_Attribute methods
394     --           =====================
395     
396     ID (me)
397         ---C++: return const & 
398     returns GUID from Standard;
399
400     Restore (me: mutable; with : Attribute from TDF);
401
402     NewEmpty (me)
403     returns mutable Attribute from TDF;
404
405     Paste (me; into : mutable Attribute from TDF;
406                RT   : mutable RelocationTable from TDF);    
407
408     IsExternRef (myclass; L: Label from TDF) returns Boolean;
409         ---Purpose: Returns True if the label is a label of external references, i.e.
410         --          there are some reference on the no-step files, which are
411         --          described in document only their names
412
413     SetExternRefs (me; SHAS: SequenceOfHAsciiString from TColStd) returns Label from TDF;
414         ---Purpose: Sets the names of references on the no-step files
415
416     SetExternRefs (me; L: Label from TDF; SHAS: SequenceOfHAsciiString from TColStd);
417         ---Purpose: Sets the names of references on the no-step files
418
419     GetExternRefs (myclass; L: Label from TDF; SHAS: in out SequenceOfHAsciiString from TColStd);
420         ---Purpose: Gets the names of references on the no-step files
421
422     ---API: Work with SHUO (Specified Higher Usage Occurrance) structure
423
424     SetSHUO (me; Labels : LabelSequence from TDF;
425              MainSHUOAttr : in out GraphNode from XCAFDoc)
426     returns Boolean;
427         ---Purpose: Sets the SHUO structure between upper_usage and next_usage
428         --          create multy-level (if number of labels > 2) SHUO from first to last
429         --          Initialise out <MainSHUOAttr> by main upper_usage SHUO attribute.
430         --          Returns FALSE if some of labels in not component label
431              
432     GetSHUO (myclass; SHUOLabel : Label from TDF;
433              aSHUOAttr : in out GraphNode from XCAFDoc)
434     returns Boolean;
435         ---Purpose: Returns founded SHUO GraphNode attribute <aSHUOAttr>
436         --          Returns false in other case
437     
438     GetAllComponentSHUO (myclass; CompLabel : Label from TDF;
439                          SHUOAttrs : in out AttributeSequence from TDF)
440     returns Boolean;
441         ---Purpose: Returns founded SHUO GraphNodes of indicated component
442         --          Returns false in other case
443     
444     GetSHUOUpperUsage (myclass; NextUsageL: Label from TDF;
445                        Labels : out LabelSequence from TDF)
446     returns Boolean;
447         ---Purpose: Returns the sequence of labels of SHUO attributes,
448         --          which is upper_usage for this next_usage SHUO attribute
449         --                                          (that indicated by label)
450         --          NOTE: returns upper_usages only on one level (not recurse)
451         --          NOTE: do not clear the sequence before filling
452     
453     GetSHUONextUsage (myclass; UpperUsageL: Label from TDF;
454                        Labels : out LabelSequence from TDF)
455     returns Boolean;
456         ---Purpose: Returns the sequence of labels of SHUO attributes,
457         --          which is next_usage for this upper_usage SHUO attribute
458         --                                          (that indicated by label)
459         --          NOTE: returns next_usages only on one level (not recurse)
460         --          NOTE: do not clear the sequence before filling
461
462     RemoveSHUO (me; SHUOLabel : Label from TDF)
463     returns Boolean;
464         ---Purpose: Remove SHUO from component sublabel, 
465         --                                remove all dependencies on other SHUO.
466         --          Returns FALSE if cannot remove SHUO dependencies.
467         --          NOTE: remove any styles that associated with this SHUO.
468
469     FindComponent (me; theShape : Shape from TopoDS;
470                    Labels : out LabelSequence from TDF)
471     returns Boolean;
472         ---Purpose: Serach the path of labels in the document,
473         --          that corresponds the component from any assembly
474         --          Try to search the sequence of labels with location that
475         --          produce this shape as component of any assembly
476         --          NOTE: Clear sequence of labels before filling
477
478     GetSHUOInstance (me; theSHUO : GraphNode from XCAFDoc)
479     returns Shape from TopoDS;
480         ---Purpose: Search for the component shape that styled by shuo
481         --          Returns null shape if no any shape is found.
482         
483     SetInstanceSHUO (me; theShape : Shape from TopoDS)
484     returns GraphNode from XCAFDoc;
485         ---Purpose: Search for the component shape by labelks path
486         --          and set SHUO structure for founded label structure
487         --          Returns null attribute if no component in any assembly found.
488
489     GetAllSHUOInstances (me; theSHUO : GraphNode from XCAFDoc;
490                          theSHUOShapeSeq : in out SequenceOfShape from TopTools)
491     returns Boolean from Standard;
492         ---Purpose: Seaching for component shapes that styled by shuo
493         --          Returns empty sequence of shape if no any shape is found.
494         
495     FindSHUO (myclass; Labels : LabelSequence from TDF;
496               theSHUOAttr : in out GraphNode from XCAFDoc)
497     returns Boolean from Standard;
498         ---Purpose: Searchs the SHUO by labels of components
499         --          from upper_usage componet to next_usage
500         --          Returns null attribute if no SHUO found
501         
502 fields
503     myShapeLabels   : DataMapOfShapeLabel from XCAFDoc; --skl 15.10.2003
504     mySubShapes     : DataMapOfShapeLabel from XCAFDoc;
505     mySimpleShapes  : DataMapOfShapeLabel from XCAFDoc;
506     hasSimpleShapes : Boolean from Standard;
507
508 end ShapeTool;