src/TDF/TDF_Label.cdl

   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
   5 --
   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.
  10 --
  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.
  13 --
  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.
  20
  21
  22 ---Version:     0.0
  23 --Version Date            Purpose
  24 --              0.0     Feb  4 1997     Creation
  25
  26
  27 class Label from TDF
  28
  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.
  35         --
  36         --          Label information:
  37         --
  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.
  41         --
  42         --          Comfort methods:
  43         --          Some methods useful on a label.
  44         --
  45         --          Attributes:
  46         --
  47         --          It is possible to get an attribute in accordance
  48         --          to an ID, or the yougest previous version of a
  49         --          current attribute.
  50
  51 uses
  52
  53     GUID         from Standard,
  54     LabelNodePtr        from TDF,
  55     Data                from TDF,
  56     Attribute           from TDF,
  57     IDFilter            from TDF,
  58     AttributeIndexedMap from TDF
  59
  60 raises
  61
  62     DomainError  from Standard,
  63     OutOfRange   from Standard,
  64     NullObject   from Standard
  65
  66 is
  67     Create returns Label from TDF;
  68         ---Purpose: Constructs an empty label object.
  69
  70     Create(aNode : LabelNodePtr from TDF) returns Label from TDF
  71         is private;
  72         ---Purpose: Reserved to the friends.
  73
  74
  75     Nullify(me : in out);
  76         ---Purpose: Nullifies the label.
  77         --
  78         ---C++: inline
  79
  80     ---Category:Label information
  81     -- ==========================
  82
  83     Data(me) returns Data from TDF;
  84         ---Purpose: Returns the Data owning <me>.
  85         --
  86         ---C++: inline
  87
  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.
  93         --
  94         ---C++: inline
  95
  96     Father(me) returns Label from TDF;
  97         ---Purpose: Returns the label father. This label may be null
  98         --          if the label is root.
  99         --
 100         ---C++: inline
 101         ---C++: return const
 102
 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.
 106         --
 107         ---C++: inline
 108
 109     Imported(me; aStatus : Boolean from Standard);
 110         ---Purpose: Sets or unsets <me> and all its descendants as
 111         --          imported label, according to <aStatus>.
 112
 113     IsImported(me) returns Boolean from Standard;
 114         ---Purpose: Returns True if the <aLabel> is imported.
 115         --
 116         ---C++: inline
 117
 118     IsEqual(me; aLabel : Label from TDF) returns Boolean from Standard;
 119         ---Purpose: Returns True if the <aLabel> is equal to me (same
 120         --           LabelNode*).
 121         ---C++: inline
 122         ---C++: alias operator ==
 123
 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*).
 127         --
 128         ---C++: inline
 129         ---C++: alias operator !=
 130
 131     IsRoot(me) returns Boolean from Standard;
 132         ---Puprpose: Returns True if the label is root.
 133         ---C++: inline
 134
 135
 136     ---Category: Attribute methods
 137     -- ===========================
 138
 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);
 146
 147
 148     IsAttribute (me; anID : GUID from Standard) returns Boolean from Standard;
 149     ---Purpose: Returns true if <me> owns an attribute with <anID> as ID.
 150
 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;
 155
 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
 160         --          the structure.
 161     raises DomainError from Standard;
 162
 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;
 168
 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.
 174
 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;
 180
 181     FindAttribute (me;
 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
 186         --          to <anID>.
 187     -- If anAttribute is not a valid one, false is returned.
 188         --
 189         --        The method returns True if found, False otherwise.
 190         --
 191         --          A removed attribute cannot be found.
 192
 193     FindAttribute (me;
 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.
 203         --
 204         --          The method returns True if found, False otherwise.
 205         --
 206         --          A removed attribute cannot be found nor a backuped
 207         --          attribute of a removed one.
 208
 209     MayBeModified(me)
 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.
 215         --
 216         ---C++: inline
 217
 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.
 223         --
 224         ---C++: inline
 225
 226     HasAttribute(me) returns Boolean from Standard;
 227         ---Purpose: Returns true if this label has at least one attribute.
 228
 229     NbAttributes(me) returns Integer;
 230         ---Purpose: Returns the number of attributes.
 231
 232
 233     ---Category: Label comfort methods
 234     --================================
 235
 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.
 241         -- Exceptions:
 242         -- Standard_NullObject if this label is null. This is
 243         -- because a null object can have no depth.
 244
 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
 248         --          descendant.
 249
 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.
 253         -- Exceptions:
 254         -- Standard_NullObject if this label is null. This is
 255         -- because a null object can have no depth.
 256         ---C++:  return const
 257
 258     HasChild(me) returns Boolean from Standard;
 259         ---Purpose: Returns true if this label has at least one child.
 260         ---C++: inline
 261
 262     NbChildren(me) returns Integer;
 263         ---Purpose: Returns the number of children.
 264
 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.
 272         -- Example:
 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);
 278
 279     NewChild (me)
 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.
 284         ---C++: inline
 285
 286
 287
 288     ---Category: Miscelleaneous
 289     -- ========================
 290
 291
 292     Transaction(me) returns Integer from Standard;
 293         ---Purpose: Returns the current transaction index.
 294
 295
 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).
 301         --
 302         -- -C++: inline
 303
 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).
 309         --
 310         -- -C++: inline
 311
 312     Dump(me; anOS : in out OStream from Standard)
 313         returns OStream from Standard;
 314         ---Purpose: Dumps the minimum information about <me> on
 315         --          <aStream>.
 316         --
 317         ---C++: return &
 318         ---C++: alias operator<<
 319
 320
 321     ExtendedDump(me;
 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>.
 327
 328
 329     EntryDump(me; anOS : in out OStream from Standard);
 330         ---Purpose: Dumps the label entry.
 331
 332
 333     ---Category: Private methods
 334     -- =========================
 335
 336
 337
 338     AddToNode(me; toNode : LabelNodePtr from TDF;
 339                   anAttribute : Attribute from TDF)
 340         raises DomainError from Standard
 341         is private;
 342         ---Purpose: Adds an Attribute to <toNode>. Raises if there is
 343         --          already one.
 344
 345     ForgetFromNode(me; fromNode : LabelNodePtr from TDF;
 346                        anAttribute : Attribute from TDF)
 347         raises DomainError from Standard
 348         is private;
 349         ---Purpose: Forgets an Attribute from <fromNode>.  Raises if
 350         --          the attribute is not in the structure.
 351
 352     ResumeToNode (me; fromNode : LabelNodePtr from TDF;
 353                       anAttribute : Attribute from TDF)
 354         raises DomainError, NullObject from Standard
 355         is private;
 356         ---Purpose: Resumes a forgotten Attribute to <toNode>.  Raises
 357         --          if the attribute is not in the structure.
 358
 359     FindOrAddChild(me; aTag : Integer from Standard;
 360                        create : Boolean from Standard)
 361         returns LabelNodePtr from TDF
 362         is private;
 363
 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)
 368         is private;
 369
 370
 371 fields
 372
 373     myLabelNode : LabelNodePtr from TDF;
 374
 375 friends
 376
 377     class ChildIterator      from TDF,
 378     class Attribute          from TDF,
 379     class AttributeIterator  from TDF,
 380     class Data               from TDF,
 381     class LabelMapHasher     from TDF
 382
 383 end Label;