src/TopExp/TopExp_Explorer.cdl

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