src/TopExp/TopExp_Explorer.cdl

   1 -- Created on: 1993-01-14
   2 -- Created by: Remi LEQUETTE
   3 -- Copyright (c) 1993-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 Explorer from TopExp
  24
  25         ---Purpose: An Explorer is a Tool to visit  a Topological Data
  26         --          Structure form the TopoDS package.
  27         --
  28         --          An Explorer is built with :
  29         --
  30         --            * The Shape to explore.
  31         --
  32         --            * The type of Shapes to find : e.g VERTEX, EDGE.
  33         --            This type cannot be SHAPE.
  34         --
  35         --            * The type of Shapes to avoid. e.g  SHELL, EDGE.
  36         --            By default   this type is  SHAPE which  means no
  37         --            restriction on the exploration.
  38         --
  39         --
  40         --          The Explorer  visits  all the  structure   to find
  41         --          shapes of the   requested  type  which   are   not
  42         --          contained in the type to avoid.
  43         --
  44         --          Example to find all the Faces in the Shape S :
  45         --
  46         --          TopExp_Explorer Ex;
  47         --          for (Ex.Init(S,TopAbs_FACE); Ex.More(); Ex.Next()) {
  48         --            ProcessFace(Ex.Current());
  49         --            }
  50         --
  51         --          // an other way
  52         --          TopExp_Explorer Ex(S,TopAbs_FACE);
  53         --          while (Ex.More()) {
  54         --            ProcessFace(Ex.Current());
  55         --            Ex.Next();
  56         --            }
  57         --
  58         --          To find all the vertices which are not in an edge :
  59         --
  60         --          for (Ex.Init(S,TopAbs_VERTEX,TopAbs_EDGE); ...)
  61         --
  62         --
  63         --          To  find all the faces  in   a SHELL, then all the
  64         --          faces not in a SHELL :
  65         --
  66         --          TopExp_Explorer Ex1, Ex2;
  67         --
  68         --          for (Ex1.Init(S,TopAbs_SHELL),...) {
  69         --            // visit all shells
  70         --            for (Ex2.Init(Ex1.Current(),TopAbs_FACE),...) {
  71         --              // visit all the faces of the current shell
  72         --              }
  73         --            }
  74         --
  75         --          for (Ex1.Init(S,TopAbs_FACE,TopAbs_SHELL),...) {
  76         --            // visit all faces not in a shell
  77         --            }
  78         --
  79         --
  80         --          If   the type  to avoid  is   the same  or is less
  81         --          complex than the type to find it has no effect.
  82         --
  83         --          For example searching edges  not in a vertex  does
  84         --          not make a difference.
  85         --
  86
  87 uses
  88     ShapeEnum       from TopAbs,
  89     Shape           from TopoDS,
  90     Stack           from TopExp
  91
  92 raises
  93     NoMoreObject from Standard,
  94     NoSuchObject from Standard
  95
  96 is
  97
  98     Create returns Explorer from TopExp;
  99         ---Purpose: Creates an empty explorer, becomes usefull after Init.
 100
 101     Create(S       : Shape     from TopoDS;
 102            ToFind  : ShapeEnum from TopAbs;
 103            ToAvoid : ShapeEnum from TopAbs = TopAbs_SHAPE)
 104     returns Explorer from TopExp;
 105         ---Purpose: Creates an Explorer on the Shape <S>.
 106         --
 107         --          <ToFind> is the type of shapes to search.
 108         --              TopAbs_VERTEX, TopAbs_EDGE, ...
 109         --
 110         --          <ToAvoid>   is the type   of shape to  skip in the
 111         --          exploration.   If   <ToAvoid>  is  equal  or  less
 112         --          complex than <ToFind> or if  <ToAVoid> is SHAPE it
 113         --          has no effect on the exploration.
 114         --
 115
 116     Init(me : in out; S       : Shape       from TopoDS;
 117                       ToFind  : ShapeEnum from TopAbs;
 118                       ToAvoid : ShapeEnum from TopAbs = TopAbs_SHAPE)
 119         ---Purpose: Resets this explorer on the shape S. It is initialized to
 120 -- search the shape S, for shapes of type ToFind, that
 121 -- are not part of a shape ToAvoid.
 122 -- If the shape ToAvoid is equal to TopAbs_SHAPE, or
 123 -- if it is the same as, or less complex than, the shape
 124 -- ToFind it has no effect on the search.
 125     is static;
 126
 127     More(me) returns Boolean
 128         ---Purpose: Returns  True if  there are   more  shapes in  the
 129         --          exploration.
 130         ---C++: inline
 131    is static;
 132
 133     Next(me : in out)
 134         ---Purpose: Moves to the next Shape in the exploration.
 135 -- Exceptions
 136 -- Standard_NoMoreObject if there are no more shapes to explore.
 137     raises
 138         NoMoreObject
 139     is static;
 140
 141     Current(me) returns Shape from TopoDS
 142         ---Purpose: Returns the current shape in the exploration.
 143  -- Exceptions
 144 -- Standard_NoSuchObject if this explorer has no more shapes to explore.
 145     raises NoSuchObject from Standard
 146     ---C++: return const &
 147     is static;
 148
 149     ReInit(me : in out)
 150         ---Purpose: Reinitialize  the    exploration with the original
 151         --          arguments.
 152     is static;
 153
 154     Depth(me) returns Integer
 155         ---Purpose: Returns the current depth of the exploration. 0 is
 156         --          the shape to explore itself.
 157         ---C++: inline
 158         is static;
 159
 160     Clear(me : in out)
 161         ---Purpose: Clears the content of the explorer. It will return
 162         --          False on More().
 163         ---C++: inline
 164     is static;
 165
 166     -- private implementation methods
 167
 168     Destroy(me : in out);
 169     ---C++: alias ~
 170
 171 fields
 172     myStack       : Stack           from TopExp;
 173     myTop         : Integer         from Standard;
 174     mySizeOfStack : Integer         from Standard;
 175     myShape       : Shape           from TopoDS;
 176     hasMore       : Boolean         from Standard;
 177     toFind        : ShapeEnum       from TopAbs;
 178     toAvoid       : ShapeEnum       from TopAbs;
 179
 180 end Explorer;