src/TopExp/TopExp_Explorer.hxx

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