1 // Author: Kirill Gavrilov
2 // Copyright (c) 2017-2019 OPEN CASCADE SAS
4 // This file is part of Open CASCADE Technology software library.
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.
12 // Alternatively, this file may be used under the terms of Open CASCADE
13 // commercial license or contractual agreement.
15 #ifndef _XCAFPrs_DocumentExplorer_HeaderFile
16 #define _XCAFPrs_DocumentExplorer_HeaderFile
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>
24 class TDocStd_Document;
25 class XCAFDoc_ShapeTool;
26 class XCAFDoc_ColorTool;
28 typedef Standard_Integer XCAFPrs_DocumentExplorerFlags;
30 //! Document explorer flags.
33 XCAFPrs_DocumentExplorerFlags_None = 0x00, //!< no flags
34 XCAFPrs_DocumentExplorerFlags_OnlyLeafNodes = 0x01, //!< explore only leaf nodes (skip assembly nodes)
35 XCAFPrs_DocumentExplorerFlags_NoStyle = 0x02, //!< do not fetch styles
38 //! Document iterator through shape nodes.
39 class XCAFPrs_DocumentExplorer
41 public: //! @name string identification tools
43 //! Construct a unique string identifier for the given label.
44 //! The identifier is a concatenation of label entries (TDF_Tool::Entry() with tailing '.') of hierarchy from parent to child
45 //! joined via '/' and looking like this:
47 //! 0:1:1:1./0:1:1:1:9./0:1:1:5:7.
49 //! This generation scheme also allows finding originating labels using TDF_Tool::Label().
50 //! The tailing dot simplifies parent equality check.
51 //! @param theLabel child label to define id
52 //! @param theParentId parent string identifier defined by this method
53 Standard_EXPORT static TCollection_AsciiString DefineChildId (const TDF_Label& theLabel,
54 const TCollection_AsciiString& theParentId);
56 //! Find a shape entity based on a text identifier constructed from OCAF labels defining full path.
57 //! @sa DefineChildId()
58 Standard_EXPORT static TDF_Label FindLabelFromPathId (const Handle(TDocStd_Document)& theDocument,
59 const TCollection_AsciiString& theId,
60 TopLoc_Location& theParentLocation,
61 TopLoc_Location& theLocation);
63 //! Find a shape entity based on a text identifier constructed from OCAF labels defining full path.
64 //! @sa DefineChildId()
65 static TDF_Label FindLabelFromPathId (const Handle(TDocStd_Document)& theDocument,
66 const TCollection_AsciiString& theId,
67 TopLoc_Location& theLocation)
69 TopLoc_Location aDummy;
70 return FindLabelFromPathId (theDocument, theId, aDummy, theLocation);
73 //! Find a shape entity based on a text identifier constructed from OCAF labels defining full path.
74 //! @sa DefineChildId()
75 Standard_EXPORT static TopoDS_Shape FindShapeFromPathId (const Handle(TDocStd_Document)& theDocument,
76 const TCollection_AsciiString& theId);
80 //! Empty constructor.
81 Standard_EXPORT XCAFPrs_DocumentExplorer();
83 //! Constructor for exploring the whole document.
84 //! @param theDocument document to explore
85 //! @param theFlags iteration flags
86 //! @param theDefStyle default style for nodes with undefined style
87 Standard_EXPORT XCAFPrs_DocumentExplorer (const Handle(TDocStd_Document)& theDocument,
88 const XCAFPrs_DocumentExplorerFlags theFlags,
89 const XCAFPrs_Style& theDefStyle = XCAFPrs_Style());
91 //! Constructor for exploring specified list of root shapes in the document.
92 //! @param theDocument document to explore
93 //! @param theRoots root labels to explore within specified document
94 //! @param theFlags iteration flags
95 //! @param theDefStyle default style for nodes with undefined style
96 Standard_EXPORT XCAFPrs_DocumentExplorer (const Handle(TDocStd_Document)& theDocument,
97 const TDF_LabelSequence& theRoots,
98 const XCAFPrs_DocumentExplorerFlags theFlags,
99 const XCAFPrs_Style& theDefStyle = XCAFPrs_Style());
101 //! Initialize the iterator from a single root shape in the document.
102 //! @param theDocument document to explore
103 //! @param theRoot single root label to explore within specified document
104 //! @param theFlags iteration flags
105 //! @param theDefStyle default style for nodes with undefined style
106 Standard_EXPORT void Init (const Handle(TDocStd_Document)& theDocument,
107 const TDF_Label& theRoot,
108 const XCAFPrs_DocumentExplorerFlags theFlags,
109 const XCAFPrs_Style& theDefStyle = XCAFPrs_Style());
111 //! Initialize the iterator from the list of root shapes in the document.
112 //! @param theDocument document to explore
113 //! @param theRoots root labels to explore within specified document
114 //! @param theFlags iteration flags
115 //! @param theDefStyle default style for nodes with undefined style
116 Standard_EXPORT void Init (const Handle(TDocStd_Document)& theDocument,
117 const TDF_LabelSequence& theRoots,
118 const XCAFPrs_DocumentExplorerFlags theFlags,
119 const XCAFPrs_Style& theDefStyle = XCAFPrs_Style());
121 //! Return TRUE if iterator points to the valid node.
122 Standard_Boolean More() const { return myHasMore; }
124 //! Return current position.
125 const XCAFPrs_DocumentNode& Current() const { return myCurrent; }
127 //! Return current position.
128 XCAFPrs_DocumentNode& ChangeCurrent() { return myCurrent; }
130 //! Return current position within specified assembly depth.
131 const XCAFPrs_DocumentNode& Current (Standard_Integer theDepth) const
133 const Standard_Integer aCurrDepth = CurrentDepth();
134 if (theDepth == aCurrDepth)
139 Standard_OutOfRange_Raise_if (theDepth < 0 || theDepth > myTop,
140 "XCAFPrs_DocumentExplorer::Current() out of range");
141 return myNodeStack.Value (theDepth);
144 //! Return depth of the current node in hierarchy, starting from 0.
145 //! Zero means Root label.
146 Standard_Integer CurrentDepth() const { return myCurrent.IsAssembly ? myTop : myTop + 1; }
148 //! Go to the next node.
149 Standard_EXPORT void Next();
153 //! Initialize root label.
154 Standard_EXPORT void initRoot();
156 //! Initialize properties for a current label.
157 Standard_EXPORT void initCurrent (Standard_Boolean theIsAssmebly);
161 Handle(XCAFDoc_ColorTool) myColorTool; //!< color tool
162 TDF_LabelSequence myRoots; //!< sequence of root labels
163 TDF_LabelSequence::Iterator myRootIter; //!< current root label
164 NCollection_Vector<XCAFPrs_DocumentNode>
165 myNodeStack; //!< node stack
166 Standard_Integer myTop; //!< top position in the node stack
167 Standard_Boolean myHasMore; //!< global flag indicating that iterator points to the label
168 XCAFPrs_Style myDefStyle; //!< default style
169 XCAFPrs_DocumentNode myCurrent; //!< current label info
170 XCAFPrs_DocumentExplorerFlags myFlags; //!< iteration flags
174 #endif // _XCAFPrs_DocumentExplorer_HeaderFile