0029987: Request for translation of French comments in the code
[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
28 typedef Standard_Integer XCAFPrs_DocumentExplorerFlags;
29
30 //! Document explorer flags.
31 enum
32 {
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
36 };
37
38 //! Document iterator through shape nodes.
39 class XCAFPrs_DocumentExplorer
40 {
41 public: //! @name string identification tools
42
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:
46   //! @code
47   //!   0:1:1:1./0:1:1:1:9./0:1:1:5:7.
48   //! @endcode
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);
55
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);
62
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)
68   {
69     TopLoc_Location aDummy;
70     return FindLabelFromPathId (theDocument, theId, aDummy, theLocation);
71   }
72
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);
77
78 public:
79
80   //! Empty constructor.
81   Standard_EXPORT XCAFPrs_DocumentExplorer();
82
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());
90
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());
100
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());
110
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());
120
121   //! Return TRUE if iterator points to the valid node.
122   Standard_Boolean More() const { return myHasMore; }
123
124   //! Return current position.
125   const XCAFPrs_DocumentNode& Current() const { return myCurrent; }
126
127   //! Return current position.
128   XCAFPrs_DocumentNode& ChangeCurrent() { return myCurrent; }
129
130   //! Return current position within specified assembly depth.
131   const XCAFPrs_DocumentNode& Current (Standard_Integer theDepth) const
132   {
133     const Standard_Integer aCurrDepth = CurrentDepth();
134     if (theDepth == aCurrDepth)
135     {
136       return myCurrent;
137     }
138
139     Standard_OutOfRange_Raise_if (theDepth < 0 || theDepth > myTop,
140                                   "XCAFPrs_DocumentExplorer::Current() out of range");
141     return myNodeStack.Value (theDepth);
142   }
143
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; }
147
148   //! Go to the next node.
149   Standard_EXPORT void Next();
150
151 protected:
152
153   //! Initialize root label.
154   Standard_EXPORT void initRoot();
155
156   //! Initialize properties for a current label.
157   Standard_EXPORT void initCurrent (Standard_Boolean theIsAssmebly);
158
159 protected:
160
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
171
172 };
173
174 #endif // _XCAFPrs_DocumentExplorer_HeaderFile