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