src/Interface/Interface_Graph.cdl

   1 -- Created on: 1992-09-22
   2 -- Created by: Christian CAILLET
   3 -- Copyright (c) 1992-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
  23 class Graph from Interface
  24
  25         ---Purpose : Gives basic data structure for operating and storing
  26         --           graph results (usage is normally internal)
  27         --           Entities are Mapped according their Number in the Model
  28         --
  29         --           Each Entity from the Model can be known as "Present" or
  30         --           not; if it is, it is Mapped with a Status : an Integer
  31         --           which can be used according to needs of each algorithm
  32         --           In addition, the Graph brings a BitMap which can be used
  33         --           by any caller
  34         --
  35         --           Also, it is bound with two lists : a list of Shared
  36         --           Entities (in fact, their Numbers in the Model) which is
  37         --           filled by a ShareTool, and a list of Sharing Entities,
  38         --           computed by deduction from the Shared Lists
  39         --
  40         --           Moreover, it is possible to redefine the list of Entities
  41         --           Shared by an Entity (instead of standard answer by general
  42         --           service Shareds) : this new list can be empty; it can
  43         --           be changed or reset (i.e. to come back to standard answer)
  44
  45 uses  Transient, Type,
  46       HArray1OfInteger from TColStd,
  47       HArray1OfTransient from TColStd,
  48       HSequenceOfTransient from TColStd,
  49       HArray1OfListOfInteger  from TColStd,
  50       AsciiString from TCollection, HAsciiString from TCollection,
  51       Protocol from Interface,  GeneralLib,      InterfaceModel,   GTool,
  52       EntityIterator, BitMap
  53
  54 raises DomainError
  55
  56 is
  57
  58     Create (amodel : InterfaceModel; lib : GeneralLib; theModeStats : Boolean = Standard_True ) returns Graph;
  59     ---Purpose : Creates an empty graph, ready to receive Entities from amodel
  60     --           Note that this way of Creation allows <me> to verify that
  61     --           Entities to work with are contained in <amodel>
  62     --           Basic Shared and Sharing lists are obtained from a General
  63     --           Services Library, given directly as an argument
  64
  65     Create (amodel : InterfaceModel; protocol : Protocol from Interface;
  66     theModeStats : Boolean = Standard_True)
  67         returns Graph;
  68     ---Purpose : Same as above, but the Library is defined through a Protocol
  69
  70     Create (amodel : InterfaceModel; gtool    : GTool from Interface;
  71                 theModeStats : Boolean = Standard_True)
  72         returns Graph;
  73     ---Purpose : Same as above, but the Library is defined through a Protocol
  74
  75     Create (amodel : InterfaceModel;theModeStats : Boolean = Standard_True) returns Graph;
  76     ---Purpose : Same a above but works with the Protocol recorded in the Model
  77
  78      Create (agraph : Graph; copied : Boolean = Standard_False) returns Graph;
  79     ---Purpose : Creates a Graph from another one, getting all its data
  80     --           Remark that status are copied from <agraph>, but the other
  81     --           lists (sharing/shared) are copied only if <copied> = True
  82
  83
  84     Evaluate (me : in out )  is static private;
  85     ---Purpose : Performs the Evaluation of the Graph, from an initial Library,
  86     --           either defined through a Protocol, or given dierctly
  87     --           Called by the non-empty Constructors
  88     --
  89     --           Normally, gtool suffices. But if a Graph is created from a
  90     --           GeneralLib directly, it cannot be used
  91     --           If <gtool> is defined, it has priority
  92
  93
  94     Reset (me : in out)  is static;
  95     ---Purpose : Erases data, making graph ready to rebegin from void
  96     --           (also resets Shared lists redefinitions)
  97
  98     ResetStatus (me : in out)  is static;
  99     ---Purpose : Erases Status (Values and Flags of Presence), making graph
 100     --           ready to rebegin from void. Does not concerns Shared lists
 101
 102     Size (me) returns Integer  is static;
 103     ---Purpose : Returns size (max nb of entities, i.e. Model's nb of entities)
 104
 105         -- --    Fine Actions    -- --
 106
 107         NbStatuses(me) returns Integer;
 108          ---Purpose : Returns size of array of statuses
 109
 110     EntityNumber (me; ent : Transient) returns Integer  is static;
 111     ---Purpose : Returns the Number of the entity in the Map, computed at
 112     --           creation time (Entities loaded from the Model)
 113     --           Returns 0 if <ent> not contained by Model used to create <me>
 114     --           (that is, <ent> is unknown from <me>)
 115
 116     IsPresent (me; num : Integer) returns Boolean  is static;
 117     ---Purpose : Returns True if an Entity is noted as present in the graph
 118     --           (See methods Get... which determine this status)
 119     --           Returns False if <num> is out of range too
 120
 121     IsPresent (me; ent : Transient) returns Boolean;
 122     ---Purpose : Same as above but directly on an Entity <ent> : if it is not
 123     --           contained in the Model, returns False. Else calls
 124     --            IsPresent(num)  with <num> given by EntityNumber
 125
 126     Entity (me; num : Integer) returns any Transient  is static;
 127     ---Purpose : Returns mapped Entity given its no (if it is present)
 128     ---C++ : return const &
 129
 130     Status (me; num : Integer) returns Integer  is static;
 131     ---Purpose : Returns Status associated to a numero (only to read it)
 132
 133     SetStatus (me : in out; num : Integer; stat : Integer)  is static;
 134     ---Purpose : Modifies Status associated to a numero
 135
 136     RemoveItem (me : in out; num : Integer)  is static;
 137     ---Purpose : Clears Entity and sets Status to 0, for a numero
 138
 139     ChangeStatus (me : in out; oldstat, newstat : Integer)  is static;
 140     ---Purpose : Changes all status which value is oldstat to new value newstat
 141
 142     RemoveStatus (me : in out; stat : Integer)  is static;
 143     ---Purpose : Removes all items of which status has a given value stat
 144
 145     BitMap (me) returns BitMap;
 146     ---Purpose : Returns the Bit Map in order to read or edit flag values
 147     ---C++ : return const &
 148
 149     CBitMap (me : in out) returns BitMap;
 150     ---Purpose : Returns the Bit Map in order to edit it (add new flags)
 151     ---C++ : return &
 152
 153         -- --    General Actions    -- --
 154
 155     Model (me) returns InterfaceModel  is static;
 156     ---Purpose : Returns the Model with which this Graph was created
 157     ---C++ : return const &
 158
 159     GetFromModel (me : in out)  is static;
 160     ---Purpose : Loads Graph with all Entities contained in the Model
 161
 162     GetFromEntity (me : in out; ent : Transient; shared : Boolean;
 163                newstat : Integer = 0)  is static;
 164     ---Purpose : Gets an Entity, plus its shared ones (at every level) if
 165     --           "shared" is True. New items are set to status "newstat"
 166     --           Items already present in graph remain unchanged
 167     --           Of course, redefinitions of Shared lists are taken into
 168     --           account if there are some
 169
 170     GetFromEntity (me : in out; ent : Transient; shared : Boolean;
 171              newstat, overlapstat : Integer; cumul : Boolean)
 172          is static;
 173     ---Purpose : Gets an Entity, plus its shared ones (at every level) if
 174     --           "shared" is True. New items are set to status "newstat".
 175     --           Items already present in graph are processed as follows :
 176     --           - if they already have status "newstat", they remain unchanged
 177     --           - if they have another status, this one is modified :
 178     --             if cumul is True,  to former status + overlapstat (cumul)
 179     --             if cumul is False, to overlapstat (enforce)
 180
 181     GetFromIter (me : in out; iter : EntityIterator; newstat : Integer)
 182         is static;
 183     ---Purpose : Gets Entities given by an EntityIterator. Entities which were
 184     --           not yet present in the graph are mapped with status "newstat"
 185     --           Entities already present remain unchanged
 186
 187     GetFromIter (me : in out; iter : EntityIterator;
 188              newstat, overlapstat : Integer; cumul : Boolean)
 189          is static;
 190     ---Purpose : Gets Entities given by an EntityIterator and distinguishes
 191     --           those already present in the Graph :
 192     --           - new entities added to the Graph with status "newstst"
 193     --           - entities already present with status = "newstat" remain
 194     --             unchanged
 195     --           - entities already present with status different form
 196     --             "newstat" have their status modified :
 197     --             if cumul is True,  to former status + overlapstat (cumul)
 198     --             if cumul is False, to overlapstat (enforce)
 199     --             (Note : works as GetEntity, shared = False, for each entity)
 200
 201     GetFromGraph (me : in out; agraph : Graph)
 202     ---Purpose : Gets all present items from another graph
 203         raises DomainError  is static;
 204     --           Error if the other graph has not been created with same Model
 205
 206     GetFromGraph (me : in out; agraph : Graph; stat : Integer)
 207     ---Purpose : Gets items from another graph which have a specific Status
 208         raises DomainError  is static;
 209     --           Error if the other graph has not been created with same Model
 210
 211         -- --    Shared Lists    -- --
 212
 213     HasShareErrors (me; ent : Transient) returns Boolean  is static;
 214     ---Purpose : Returns True if <ent> or the list of entities shared by <ent>
 215     --           (not redefined) contains items unknown from this Graph
 216     --           Remark : apart from the status HasShareError, these items
 217     --           are ignored
 218
 219     GetShareds(me; ent : Transient) returns HSequenceOfTransient;
 220         ---Purpose : Returns the sequence of Entities Shared by an Entity
 221
 222     Shareds (me; ent : Transient) returns EntityIterator
 223     ---Purpose : Returns the list of Entities Shared by an Entity, as recorded
 224     --           by the Graph. That is, by default Basic Shared List, else it
 225     --           can be redefined by methods SetShare, SetNoShare ... see below
 226         raises DomainError  is static;
 227     --           Error if <ent> is not contained by the model used for Creation
 228
 229
 230     Sharings (me; ent : Transient) returns EntityIterator
 231     ---Purpose : Returns the list of Entities which Share an Entity, computed
 232     --           from the Basic or Redefined Shared Lists
 233         raises DomainError  is static;
 234     --           Error if <ent> is not contained by the model used for Creation
 235
 236
 237         GetSharings(me; ent : Transient) returns HSequenceOfTransient;
 238         ---Purpose : Returns the sequence of Entities Sharings by an Entity
 239
 240         TypedSharings (me; ent : Transient; type : Type) returns EntityIterator;
 241     ---Purpose : Returns the list of sharings entities, AT ANY LEVEL, which are
 242     --           kind of a given type. A sharing entity kind of this type
 243     --           ends the exploration of its branch
 244
 245     RootEntities (me) returns EntityIterator  is static;
 246     ---Purpose : Returns the Entities which are not Shared (their Sharing List
 247     --           is empty) in the Model
 248
 249         -- --    Redefinitions of Shared-Sharing Lists    -- --
 250
 251
 252     Name (me; ent : Transient) returns HAsciiString;
 253     ---Purpose : Determines the name attached to an entity, by using the
 254     --           general service Name in GeneralModule
 255     --           Returns a null handle if no name could be computed or if
 256     --           the entity is not in the model
 257
 258
 259     SharingTable (me) returns  HArray1OfListOfInteger  from TColStd; --HArray1OfTransient from TColStd ;
 260     ---C++ : return const &
 261     ---Purpose : Returns the Table of Sharing lists. Used to Create
 262     --           another Graph from <me>
 263
 264     InitStats(me : in out) is protected;
 265     ---Purpose : Initialize statuses and flags
 266
 267     ModeStat(me) returns Boolean;
 268     ---Purpose : Returns mode resposible for computation of statuses;
 269
 270 fields
 271
 272     themodel    : InterfaceModel is protected ;   -- Model which contains the Entities
 273     thepresents : AsciiString from TCollection is protected ; -- flags present/or not
 274     thestats    : HArray1OfInteger from TColStd is protected; -- numeric status
 275     theflags    : BitMap;                       -- logical flags status
 276     thesharings : HArray1OfListOfInteger  from TColStd is protected;       --HArray1OfTransient from TColStd is protected;
 277
 278 end Graph;