1 -- Created on: 1997-02-04
2 -- Created by: DAUTRY Philippe
3 -- Copyright (c) 1997-1999 Matra Datavision
4 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
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.
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.
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.
23 --Version Date Purpose
24 -- 0.0 Feb 4 1997 Creation
29 ---Purpose: This class provides basic operations to define
30 -- a label in a data structure.
31 -- A label is a feature in the feature hierarchy. A
32 -- label is always connected to a Data from TDF.
33 -- To a label is attached attributes containing the
34 -- software components information.
38 -- It is possible to know the tag, the father, the
39 -- depth in the tree of the label, if the label is
40 -- root, null or equal to another label.
43 -- Some methods useful on a label.
47 -- It is possible to get an attribute in accordance
48 -- to an ID, or the yougest previous version of a
54 LabelNodePtr from TDF,
58 AttributeIndexedMap from TDF
62 DomainError from Standard,
63 OutOfRange from Standard,
64 NullObject from Standard
67 Create returns Label from TDF;
68 ---Purpose: Constructs an empty label object.
70 Create(aNode : LabelNodePtr from TDF) returns Label from TDF
72 ---Purpose: Reserved to the friends.
76 ---Purpose: Nullifies the label.
80 ---Category:Label information
81 -- ==========================
83 Data(me) returns Data from TDF;
84 ---Purpose: Returns the Data owning <me>.
88 Tag(me) returns Integer;
89 ---Purpose: Returns the tag of the label.
90 -- This is the integer assigned randomly to a label
91 -- in a data framework. This integer is used to
92 -- identify this label in an entry.
96 Father(me) returns Label from TDF;
97 ---Purpose: Returns the label father. This label may be null
98 -- if the label is root.
103 IsNull(me) returns Boolean from Standard;
104 ---Purpose: Returns True if the <aLabel> is null, i.e. it has
105 -- not been included in the data framework.
109 Imported(me; aStatus : Boolean from Standard);
110 ---Purpose: Sets or unsets <me> and all its descendants as
111 -- imported label, according to <aStatus>.
113 IsImported(me) returns Boolean from Standard;
114 ---Purpose: Returns True if the <aLabel> is imported.
118 IsEqual(me; aLabel : Label from TDF) returns Boolean from Standard;
119 ---Purpose: Returns True if the <aLabel> is equal to me (same
122 ---C++: alias operator ==
124 IsDifferent(me; aLabel : Label from TDF) returns Boolean from Standard;
125 ---Puprpose: Returns True if the <aLabel> is different than me
126 -- (not same LabelNode*).
129 ---C++: alias operator !=
131 IsRoot(me) returns Boolean from Standard;
132 ---Puprpose: Returns True if the label is root.
136 ---Category: Attribute methods
137 -- ===========================
139 ---Warning: : becomes obsolete week 10
140 -- IsA (me; anID : GUID from Standard) returns Boolean from Standard;
141 -- Resume (me; anAttribute : Attribute from TDF) raises DomainError from Standard;
142 -- Add (me; anAttribute : Attribute from TDF) raises DomainError from Standard;
143 -- Forget (me; anAttribute : Attribute from TDF) raises DomainError from Standard;
144 -- Forget (me; aguid : GUID from Standard) returns Boolean from Standard;
145 -- ForgetAll (me; clearChildren : Boolean from Standard = Standard_True);
148 IsAttribute (me; anID : GUID from Standard) returns Boolean from Standard;
149 ---Purpose: Returns true if <me> owns an attribute with <anID> as ID.
151 AddAttribute (me; anAttribute : Attribute from TDF)
152 ---Purpose: Adds an Attribute to the current label. Raises if
153 -- there is already one.
154 raises DomainError from Standard;
156 ForgetAttribute (me; anAttribute : Attribute from TDF)
157 ---Purpose: Forgets an Attribute from the current label,
158 -- setting its forgotten status true and its valid
159 -- status false. Raises if the attribute is not in
161 raises DomainError from Standard;
163 ForgetAttribute (me; aguid : GUID from Standard)
164 ---Purpose: Forgets the Attribute of GUID <aguid> from the
165 -- current label . If the attribute doesn't exist
166 -- returns False. Otherwise returns True.
167 returns Boolean from Standard;
169 ForgetAllAttributes (me; clearChildren : Boolean from Standard = Standard_True);
170 ---Purpose: Forgets all the attributes. Does it on also on the
171 -- sub-labels if <clearChildren> is set to true. Of
172 -- course, this method is compatible with Transaction
173 -- & Delta mecanisms.
175 ResumeAttribute (me; anAttribute : Attribute from TDF)
176 ---Purpose: Undo Forget action, setting its forgotten status
177 -- false and its valid status true. Raises if the
178 -- attribute is not in the structure.
179 raises DomainError from Standard;
182 anID : GUID from Standard;
183 anAttribute : in out Attribute from TDF)
184 returns Boolean from Standard;
185 ---Purpose: Finds an attribute of the current label, according
187 -- If anAttribute is not a valid one, false is returned.
189 -- The method returns True if found, False otherwise.
191 -- A removed attribute cannot be found.
194 anID : GUID from Standard;
195 aTransaction : Integer from Standard;
196 anAttribute : in out Attribute from TDF)
197 returns Boolean from Standard;
198 ---Purpose: Finds an attribute of the current label, according
199 -- to <anID> and <aTransaction>. This attribute
200 -- has/had to be a valid one for the given
201 -- transaction index . So, this attribute is not
202 -- necessary a valid one.
204 -- The method returns True if found, False otherwise.
206 -- A removed attribute cannot be found nor a backuped
207 -- attribute of a removed one.
210 returns Boolean from Standard;
211 ---Purpose: Returns true if <me> or a DESCENDANT of <me> owns
212 -- attributes not yet available in transaction 0. It
213 -- means at least one of their attributes is new,
214 -- modified or deleted.
218 AttributesModified(me)
219 returns Boolean from Standard;
220 ---Purpose: Returns true if <me> owns attributes not yet
221 -- available in transaction 0. It means at least one
222 -- attribute is new, modified or deleted.
226 HasAttribute(me) returns Boolean from Standard;
227 ---Purpose: Returns true if this label has at least one attribute.
229 NbAttributes(me) returns Integer;
230 ---Purpose: Returns the number of attributes.
233 ---Category: Label comfort methods
234 --================================
236 Depth(me) returns Integer from Standard;
237 ---Purpose: Returns the depth of the label in the data framework.
238 -- This corresponds to the number of fathers which
239 -- this label has, and is used in determining
240 -- whether a label is root, null or equivalent to another label.
242 -- Standard_NullObject if this label is null. This is
243 -- because a null object can have no depth.
245 IsDescendant(me; aLabel : Label from TDF) returns Boolean from Standard;
246 ---Purpose: Returns True if <me> is a descendant of
247 -- <aLabel>. Attention: every label is its own
250 Root(me) returns Label from TDF;
251 ---Purpose: Returns the root label Root of the data structure.
252 -- This has a depth of 0.
254 -- Standard_NullObject if this label is null. This is
255 -- because a null object can have no depth.
258 HasChild(me) returns Boolean from Standard;
259 ---Purpose: Returns true if this label has at least one child.
262 NbChildren(me) returns Integer;
263 ---Purpose: Returns the number of children.
265 FindChild(me; aTag : Integer from Standard;
266 create : Boolean from Standard = Standard_True)
267 returns Label from TDF
268 raises NullObject, DomainError, OutOfRange from Standard;
269 ---Purpose: Finds a child label having <aTag> as tag. Creates
270 -- The tag aTag identifies the label which will be the parent.
271 -- If create is true and no child label is found, a new one is created.
273 -- //creating a label with tag 10 at Root
274 -- TDF_Label lab1 = aDF->Root().FindChild(10);
275 -- //creating labels 7 and 2 on label 10
276 -- TDF_Label lab2 = lab1.FindChild(7);
277 -- TDF_Label lab3 = lab1.FindChild(2);
280 returns Label from TDF
281 raises NullObject, DomainError, OutOfRange from Standard;
282 ---Purpose: Create a new child label of me using autoamtic
283 -- delivery tags provided by TagSource.
288 ---Category: Miscelleaneous
289 -- ========================
292 Transaction(me) returns Integer from Standard;
293 ---Purpose: Returns the current transaction index.
296 HasLowerNode(me; otherLabel : Label from TDF)
297 returns Boolean from Standard;
298 ---Purpose: Returns true if node address of <me> is lower than
299 -- <otherLabel> one. Used to quickly sort labels (not
300 -- on entry criterion).
304 HasGreaterNode(me; otherLabel : Label from TDF)
305 returns Boolean from Standard;
306 ---Purpose: Returns true if node address of <me> is greater
307 -- than <otherLabel> one. Used to quickly sort labels
308 -- (not on entry criterion).
312 Dump(me; anOS : in out OStream from Standard)
313 returns OStream from Standard;
314 ---Purpose: Dumps the minimum information about <me> on
318 ---C++: alias operator<<
322 anOS : in out OStream from Standard;
323 aFilter : IDFilter from TDF;
324 aMap : in out AttributeIndexedMap from TDF);
325 ---Purpose: Dumps the label on <aStream> and its attributes
326 -- rank in <aMap> if their IDs are kept by <IDFilter>.
329 EntryDump(me; anOS : in out OStream from Standard);
330 ---Purpose: Dumps the label entry.
333 ---Category: Private methods
334 -- =========================
338 AddToNode(me; toNode : LabelNodePtr from TDF;
339 anAttribute : Attribute from TDF)
340 raises DomainError from Standard
342 ---Purpose: Adds an Attribute to <toNode>. Raises if there is
345 ForgetFromNode(me; fromNode : LabelNodePtr from TDF;
346 anAttribute : Attribute from TDF)
347 raises DomainError from Standard
349 ---Purpose: Forgets an Attribute from <fromNode>. Raises if
350 -- the attribute is not in the structure.
352 ResumeToNode (me; fromNode : LabelNodePtr from TDF;
353 anAttribute : Attribute from TDF)
354 raises DomainError, NullObject from Standard
356 ---Purpose: Resumes a forgotten Attribute to <toNode>. Raises
357 -- if the attribute is not in the structure.
359 FindOrAddChild(me; aTag : Integer from Standard;
360 create : Boolean from Standard)
361 returns LabelNodePtr from TDF
364 InternalDump(me; anOS : in out OStream from Standard;
365 aFilter : IDFilter from TDF;
366 aMap : in out AttributeIndexedMap from TDF;
367 extended : Boolean from Standard)
373 myLabelNode : LabelNodePtr from TDF;
377 class ChildIterator from TDF,
378 class Attribute from TDF,
379 class AttributeIterator from TDF,
381 class LabelMapHasher from TDF