0031139: Data Exchange - fix misprint in RWObj_CafReader
[occt.git] / 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