src/XCAFPrs/XCAFPrs_DocumentExplorer.hxx

   1 // Author: Kirill Gavrilov
   2 // Copyright (c) 2017-2019 OPEN CASCADE SAS
   3 //
   4 // This file is part of Open CASCADE Technology software library.
   5 //
   6 // This library is free software; you can redistribute it and/or modify it under
   7 // the terms of the GNU Lesser General Public License version 2.1 as published
   8 // by the Free Software Foundation, with special exception defined in the file
   9 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  10 // distribution for complete text of the license and disclaimer of any warranty.
  11 //
  12 // Alternatively, this file may be used under the terms of Open CASCADE
  13 // commercial license or contractual agreement.
  14
  15 #ifndef _XCAFPrs_DocumentExplorer_HeaderFile
  16 #define _XCAFPrs_DocumentExplorer_HeaderFile
  17
  18 #include <NCollection_Vector.hxx>
  19 #include <NCollection_Sequence.hxx>
  20 #include <XCAFPrs_DocumentNode.hxx>
  21 #include <TDF_LabelSequence.hxx>
  22 #include <TopoDS_Shape.hxx>
  23
  24 class TDocStd_Document;
  25 class XCAFDoc_ShapeTool;
  26 class XCAFDoc_ColorTool;
  27 class XCAFDoc_VisMaterialTool;
  28
  29 typedef Standard_Integer XCAFPrs_DocumentExplorerFlags;
  30
  31 //! Document explorer flags.
  32 enum
  33 {
  34   XCAFPrs_DocumentExplorerFlags_None          = 0x00, //!< no flags
  35   XCAFPrs_DocumentExplorerFlags_OnlyLeafNodes = 0x01, //!< explore only leaf nodes (skip assembly nodes)
  36   XCAFPrs_DocumentExplorerFlags_NoStyle       = 0x02, //!< do not fetch styles
  37 };
  38
  39 //! Document iterator through shape nodes.
  40 class XCAFPrs_DocumentExplorer
  41 {
  42 public: //! @name string identification tools
  43
  44   //! Construct a unique string identifier for the given label.
  45   //! The identifier is a concatenation of label entries (TDF_Tool::Entry() with tailing '.') of hierarchy from parent to child
  46   //! joined via '/' and looking like this:
  47   //! @code
  48   //!   0:1:1:1./0:1:1:1:9./0:1:1:5:7.
  49   //! @endcode
  50   //! This generation scheme also allows finding originating labels using TDF_Tool::Label().
  51   //! The tailing dot simplifies parent equality check.
  52   //! @param theLabel child label to define id
  53   //! @param theParentId parent string identifier defined by this method
  54   Standard_EXPORT static TCollection_AsciiString DefineChildId (const TDF_Label& theLabel,
  55                                                                 const TCollection_AsciiString& theParentId);
  56
  57   //! Find a shape entity based on a text identifier constructed from OCAF labels defining full path.
  58   //! @sa DefineChildId()
  59   Standard_EXPORT static TDF_Label FindLabelFromPathId (const Handle(TDocStd_Document)& theDocument,
  60                                                         const TCollection_AsciiString& theId,
  61                                                         TopLoc_Location& theParentLocation,
  62                                                         TopLoc_Location& theLocation);
  63
  64   //! Find a shape entity based on a text identifier constructed from OCAF labels defining full path.
  65   //! @sa DefineChildId()
  66   static TDF_Label FindLabelFromPathId (const Handle(TDocStd_Document)& theDocument,
  67                                         const TCollection_AsciiString& theId,
  68                                         TopLoc_Location& theLocation)
  69   {
  70     TopLoc_Location aDummy;
  71     return FindLabelFromPathId (theDocument, theId, aDummy, theLocation);
  72   }
  73
  74   //! Find a shape entity based on a text identifier constructed from OCAF labels defining full path.
  75   //! @sa DefineChildId()
  76   Standard_EXPORT static TopoDS_Shape FindShapeFromPathId (const Handle(TDocStd_Document)& theDocument,
  77                                                            const TCollection_AsciiString& theId);
  78
  79 public:
  80
  81   //! Empty constructor.
  82   Standard_EXPORT XCAFPrs_DocumentExplorer();
  83
  84   //! Constructor for exploring the whole document.
  85   //! @param theDocument document to explore
  86   //! @param theFlags    iteration flags
  87   //! @param theDefStyle default style for nodes with undefined style
  88   Standard_EXPORT XCAFPrs_DocumentExplorer (const Handle(TDocStd_Document)& theDocument,
  89                                             const XCAFPrs_DocumentExplorerFlags theFlags,
  90                                             const XCAFPrs_Style& theDefStyle = XCAFPrs_Style());
  91
  92   //! Constructor for exploring specified list of root shapes in the document.
  93   //! @param theDocument  document to explore
  94   //! @param theRoots     root labels to explore within specified document
  95   //! @param theFlags     iteration flags
  96   //! @param theDefStyle  default style for nodes with undefined style
  97   Standard_EXPORT XCAFPrs_DocumentExplorer (const Handle(TDocStd_Document)& theDocument,
  98                                             const TDF_LabelSequence& theRoots,
  99                                             const XCAFPrs_DocumentExplorerFlags theFlags,
 100                                             const XCAFPrs_Style& theDefStyle = XCAFPrs_Style());
 101
 102   //! Initialize the iterator from a single root shape in the document.
 103   //! @param theDocument  document to explore
 104   //! @param theRoot      single root label to explore within specified document
 105   //! @param theFlags     iteration flags
 106   //! @param theDefStyle  default style for nodes with undefined style
 107   Standard_EXPORT void Init (const Handle(TDocStd_Document)& theDocument,
 108                              const TDF_Label& theRoot,
 109                              const XCAFPrs_DocumentExplorerFlags theFlags,
 110                              const XCAFPrs_Style& theDefStyle = XCAFPrs_Style());
 111
 112   //! Initialize the iterator from the list of root shapes in the document.
 113   //! @param theDocument  document to explore
 114   //! @param theRoots     root labels to explore within specified document
 115   //! @param theFlags     iteration flags
 116   //! @param theDefStyle  default style for nodes with undefined style
 117   Standard_EXPORT void Init (const Handle(TDocStd_Document)& theDocument,
 118                              const TDF_LabelSequence& theRoots,
 119                              const XCAFPrs_DocumentExplorerFlags theFlags,
 120                              const XCAFPrs_Style& theDefStyle = XCAFPrs_Style());
 121
 122   //! Return TRUE if iterator points to the valid node.
 123   Standard_Boolean More() const { return myHasMore; }
 124
 125   //! Return current position.
 126   const XCAFPrs_DocumentNode& Current() const { return myCurrent; }
 127
 128   //! Return current position.
 129   XCAFPrs_DocumentNode& ChangeCurrent() { return myCurrent; }
 130
 131   //! Return current position within specified assembly depth.
 132   const XCAFPrs_DocumentNode& Current (Standard_Integer theDepth) const
 133   {
 134     const Standard_Integer aCurrDepth = CurrentDepth();
 135     if (theDepth == aCurrDepth)
 136     {
 137       return myCurrent;
 138     }
 139
 140     Standard_OutOfRange_Raise_if (theDepth < 0 || theDepth > myTop,
 141                                   "XCAFPrs_DocumentExplorer::Current() out of range");
 142     return myNodeStack.Value (theDepth);
 143   }
 144
 145   //! Return depth of the current node in hierarchy, starting from 0.
 146   //! Zero means Root label.
 147   Standard_Integer CurrentDepth() const { return myCurrent.IsAssembly ? myTop : myTop + 1; }
 148
 149   //! Go to the next node.
 150   Standard_EXPORT void Next();
 151
 152   //! Return color tool.
 153   const Handle(XCAFDoc_ColorTool)& ColorTool() const { return myColorTool; }
 154
 155   //! Return material tool.
 156   const Handle(XCAFDoc_VisMaterialTool)& VisMaterialTool() const { return myVisMatTool; }
 157
 158 protected:
 159
 160   //! Initialize root label.
 161   Standard_EXPORT void initRoot();
 162
 163   //! Initialize properties for a current label.
 164   Standard_EXPORT void initCurrent (Standard_Boolean theIsAssmebly);
 165
 166 protected:
 167
 168   Handle(XCAFDoc_ColorTool)       myColorTool;  //!< color tool
 169   Handle(XCAFDoc_VisMaterialTool) myVisMatTool; //!< visual material tool
 170   TDF_LabelSequence               myRoots;      //!< sequence of root labels
 171   TDF_LabelSequence::Iterator     myRootIter;   //!< current root label
 172   NCollection_Vector<XCAFPrs_DocumentNode>
 173                                   myNodeStack;  //!< node stack
 174   Standard_Integer                myTop;        //!< top position in the node stack
 175   Standard_Boolean                myHasMore;    //!< global flag indicating that iterator points to the label
 176   XCAFPrs_Style                   myDefStyle;   //!< default style
 177   XCAFPrs_DocumentNode            myCurrent;    //!< current label info
 178   XCAFPrs_DocumentExplorerFlags   myFlags;      //!< iteration flags
 179
 180 };
 181
 182 #endif // _XCAFPrs_DocumentExplorer_HeaderFile