0026155: TNaming, CurrentShape: order of shapes in Modification compound is unpredictable
[occt.git] / src / TNaming / TNaming_Tool.cdl
1 -- Created on: 1996-12-24
2 -- Created by: Yves FRICAUD
3 -- Copyright (c) 1996-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 class Tool from TNaming 
18
19         ---Purpose: A tool to get information on the topology of a
20         -- named shape attribute.
21         -- This information is typically a TopoDS_Shape object.
22         --  Using this tool, relations between named shapes
23         --  are also accessible.
24
25         
26 uses 
27     Label             from TDF,
28     LabelList         from TDF,
29     LabelMap          from TDF,
30     NamedShape        from TNaming,     
31     UsedShapes        from TNaming,
32     Evolution         from TNaming,
33     MapOfNamedShape   from TNaming,     
34     ListOfShape       from TopTools,     
35     Shape             from TopoDS,
36     OldShapeIterator  from TNaming,
37     IndexedMapOfShape from TopTools
38
39 is
40     
41     
42     CurrentShape (myclass ; NS : NamedShape from TNaming)
43         ---Purpose: Returns the last Modification of <NS>.
44         -- Returns the shape CurrentShape contained in
45         -- the named shape attribute NS.
46         -- CurrentShape is the current state of the entities
47         -- if they have been modified in other attributes of the same data structure.
48         -- Each call to this function creates a new compound.
49     returns Shape from TopoDS;                      
50
51     CurrentShape (myclass ; NS      : NamedShape from TNaming;
52                             Updated : LabelMap   from TDF)
53         ---Purpose: Returns the shape CurrentShape contained in
54         -- the named shape attribute NS, and present in
55         -- the updated attribute map Updated.
56         -- CurrentShape is the current state of the entities
57         -- if they have been modified in other attributes of the same data structure.
58         -- Each call to this function creates a new compound.
59         -- Warning
60         -- Only the contents of Updated are searched.R
61     returns Shape from TopoDS;                      
62
63     
64     
65     CurrentNamedShape (myclass ; NS      : NamedShape from TNaming;
66                                  Updated : LabelMap   from TDF)
67         ---Purpose: Returns the NamedShape of the last Modification of <NS>.
68         --          This shape is identified by a label.
69     returns NamedShape from TNaming;
70
71     CurrentNamedShape (myclass ; NS      : NamedShape from TNaming)
72         ---Purpose: Returns NamedShape the last Modification of <NS>.
73     returns NamedShape from TNaming;
74
75     NamedShape (myclass; aShape  : Shape from TopoDS;
76                          anAcces : Label from TDF)
77         ---Purpose: Returns the named shape attribute defined by
78         -- the shape aShape and the label anAccess.
79         -- This attribute is returned as a new shape.
80         -- You call this function, if you need to create a
81         -- topological attribute for existing data.
82         -- Example
83         -- class MyPkg_MyClass
84         --  {
85         --  public: Standard_Boolean
86         -- SameEdge(const
87         -- Handle(OCafTest_Line)& , const
88         -- Handle(CafTest_Line)& );
89         -- };
90         --
91         -- Standard_Boolean
92         -- MyPkg_MyClass::SameEdge
93         -- (const Handle(OCafTest_Line)& L1
94         -- const Handle(OCafTest_Line)& L2)
95         -- { Handle(TNaming_NamedShape)
96         -- NS1 = L1->NamedShape();
97         --     Handle(TNaming_NamedShape)
98         -- NS2 = L2->NamedShape();
99         --
100         --     return
101         -- BRepTools::Compare(NS1->Get(),NS2->Get());
102         -- }
103         -- In the example above, the function SameEdge is
104         -- created to compare the edges having two lines
105         -- for geometric supports. If these edges are found
106         -- by BRepTools::Compare to be within the same
107         -- tolerance, they are considered to be the same.
108         -- Warning
109         -- To avoid sharing of names, a SELECTED
110         -- attribute will not be returned. Sharing of names
111         -- makes it harder to manage the data structure.
112         -- When the user of the name is removed, for
113         -- example, it is difficult to know whether the name
114         -- should be destroyed.
115     returns NamedShape from TNaming;
116
117
118     GetShape     (myclass ; NS : NamedShape from TNaming)
119         ---Purpose: Returns the entities stored in the named shape attribute NS.
120         -- If there is only one old-new pair, the new shape
121         -- is returned. Otherwise, a Compound is returned.
122         -- This compound is made out of all the new shapes found.
123         -- Each call to this function creates a new compound.
124     returns Shape from TopoDS;  
125     
126     OriginalShape (myclass ; NS : NamedShape from TNaming)
127         --- Purpose: Returns the shape contained as OldShape in <NS>
128     returns Shape from TopoDS;  
129    
130     GeneratedShape (myclass; S : Shape from TopoDS;
131                              Generation : NamedShape from TNaming)
132         ---Purpose:  Returns the shape generated from S or by a
133         -- modification of S and contained in the named
134         -- shape Generation.
135     returns Shape from TopoDS;
136
137                              
138     Collect (myclass; NS        :     NamedShape      from TNaming;
139                       Labels    : out MapOfNamedShape from TNaming;
140                       OnlyModif :     Boolean    = Standard_True);
141
142     HasLabel(myclass; access :     Label  from TDF;
143                       aShape :     Shape  from TopoDS) 
144         ---Purpose: Returns True if <aShape> appears under a label.(DP)               
145     returns Boolean from Standard;
146
147     Label (myclass; access   :        Label      from TDF;
148                     aShape   :        Shape      from TopoDS;
149                     TransDef : in out Integer    from Standard) 
150     returns Label from TDF;
151         ---Purpose:  Returns  the label  of   the first apparition  of
152         --          <aShape>.  Transdef  is a value of the transaction
153         --          of the first apparition of <aShape>.
154
155     InitialShape (myclass ; aShape  :        Shape      from TopoDS ;
156                             anAcces :        Label      from TDF;
157                             Labels  : in out LabelList  from TDF)
158         ---Purpose: 
159         -- Returns the shape created from the shape
160         -- aShape contained in the attribute anAcces.
161     returns Shape from TopoDS;
162  
163     
164     
165     ValidUntil (myclass; access : Label      from TDF;
166                          S      : Shape from TopoDS)
167         ---Purpose: Returns the last transaction where the creation of S
168         --          is valid.
169     returns Integer from Standard;                              
170
171     FindShape  (myclass;
172                 Valid    :        LabelMap   from TDF;
173                 Forbiden :        LabelMap   from TDF;
174                 Arg      :        NamedShape from TNaming;
175                 S        : in out Shape      from TopoDS); 
176     ---Purpose: Returns the current shape (a Wire or a Shell) built (in the data framework)  
177     --          from the the shapes of the argument named shape.         
178     --          It is used for IDENTITY name type computation.             
179
180
181
182
183     ---Category: private methods
184     --           ===============
185     
186     HasLabel(myclass; Shapes  :     UsedShapes from TNaming;
187                       aShape  :     Shape      from TopoDS) 
188         ---Purpose: Returns True if <aShape> appears under a label.                   
189     returns Boolean from Standard
190     is private;
191     
192
193     ValidUntil (myclass; S  : Shape from TopoDS;
194                          US : UsedShapes  from TNaming)
195         ---Purpose: Returns the last transaction where the creation of S
196         --          is valid.
197     returns Integer from Standard
198     is private;
199     
200     Label(myclass; Shapes   :        UsedShapes from TNaming;
201                    aShape   :        Shape      from TopoDS;
202                    TransDef : in out Integer    from Standard) 
203     returns Label from TDF
204     is private;
205         ---Purpose:  Returns  the label  of   the first apparition  of
206         --          <aShape>.  Transdef  is a value of the transaction
207         --          of the first apparition of <aShape>.  
208
209     FirstOlds (myclass; Shapes :        UsedShapes from TNaming;
210                         S      :        Shape from TopoDS;
211                         it     : in out OldShapeIterator from TNaming;
212                         MS     : in out IndexedMapOfShape from TopTools;
213                         Labels : in out LabelList from TDF)
214     is private;
215
216
217 friends
218
219     class Localizer  from TNaming,
220     class NamedShape from TNaming,
221     class OldShapeIterator from TNaming
222         
223 end Tool;