0031875: Draw Harness, ViewerTest - command vaspects -mostContinuity lacks g1 and...
[occt.git] / src / XCAFDoc / XCAFDoc_NotesTool.hxx
1 // Copyright (c) 2017-2018 OPEN CASCADE SAS
2 //
3 // This file is part of Open CASCADE Technology software library.
4 //
5 // This library is free software; you can redistribute it and/or modify it under
6 // the terms of the GNU Lesser General Public License version 2.1 as published
7 // by the Free Software Foundation, with special exception defined in the file
8 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
9 // distribution for complete text of the license and disclaimer of any warranty.
10 //
11 // Alternatively, this file may be used under the terms of Open CASCADE
12 // commercial license or contractual agreement.
13
14 #ifndef _XCAFDoc_NotesTool_HeaderFile
15 #define _XCAFDoc_NotesTool_HeaderFile
16
17 #include <Standard.hxx>
18 #include <Standard_Type.hxx>
19 #include <TDataStd_GenericEmpty.hxx>
20 #include <TDF_LabelSequence.hxx>
21
22 class OSD_File;
23 class Standard_GUID;
24 class TCollection_AsciiString;
25 class TCollection_ExtendedString;
26 #include <TColStd_HArray1OfByte.hxx>
27 class TDF_RelocationTable;
28 class XCAFDoc_Note;
29 class XCAFDoc_AssemblyItemId;
30 class XCAFDoc_AssemblyItemRef;
31
32 //! A tool to annotate items in the hierarchical product structure.
33 //! There are two basic entities, which operates the notes tool: notes
34 //! and annotated items. A note is a user defined data structure derived
35 //! from \ref XCAFDoc_Note attribute that is attached to a separate label under
36 //! the notes hive. An annotated item is represented by \ref XCAFDoc_AssemblyItemRef
37 //! attribute attached to a separate label under the annotated items
38 //! hive. Notes are linked with annotated items by means of \ref XCAFDoc_GraphNode
39 //! attribute. Notes play parent roles and annotated items - child roles.
40 //!
41 //! ------------------------
42 //! | XCAFDoc_DocumentTool |
43 //! |          0:1         |
44 //! ------------------------
45 //!             |1
46 //! ------------------------
47 //! |  XCAFDoc_NotesTool   |
48 //! |         0:1:9        |
49 //! ------------------------
50 //!             |1
51 //!             |   -------------------     ---------------------------
52 //!             +___|      Notes      |-----|       XCAFDoc_Note      |
53 //!             |  1|     0:1:9:1     |1   *|         0:1:9:1:*       |
54 //!             |   -------------------     ---------------------------
55 //!             |                                        !*
56 //!             |                              { XCAFDoc_GraphNode }
57 //!             |                                       *!
58 //!             |   -------------------     ---------------------------
59 //!             +___| Annotated items |-----| XCAFDoc_AssemblyItemRef |
60 //!                1|     0:1:9:2     |1   *|         0:1:9:2:*       |
61 //!                 -------------------     ---------------------------
62 //!
63 //! A typical annotation procedure is illustrated by the code example below:
64 //! \code{.c++}
65 //! // Get the notes tool from a XCAF document
66 //! Handle(XCAFDoc_NotesTool) aNotesTool = XCAFDoc_DocumentTool::NotesTool(aDoc->Main());
67 //! // Create new comment note
68 //! Handle(XCAFDoc_Note) aNote = aNotesTool->CreateComment(aUserName, aTimestamp, aComment);
69 //! if (!aNote.IsNull()) {
70 //!   Handle(XCAFDoc_AssemblyItemRef) aRef = aNotesTool->AddNote(aNote->Label(), anAssemblyItemId);
71 //!   if (aRef.IsNull()) {
72 //!     // Process error...
73 //!   }
74 //! }
75 //! \endcode
76 class XCAFDoc_NotesTool : public TDataStd_GenericEmpty
77 {
78 public:
79
80   DEFINE_DERIVED_ATTRIBUTE(XCAFDoc_NotesTool, TDataStd_GenericEmpty)
81
82   //! Returns default attribute GUID
83   Standard_EXPORT static const Standard_GUID& GetID();
84
85   //! Create (if not exist) a notes tool from XCAFDoc on theLabel.
86   Standard_EXPORT static Handle(XCAFDoc_NotesTool) Set(const TDF_Label& theLabel);
87
88   //! Creates an empty notes tool.
89   Standard_EXPORT XCAFDoc_NotesTool();
90
91   //! Returns the label of the notes hive.
92   Standard_EXPORT TDF_Label GetNotesLabel() const;
93
94   //! Returns the label of the annotated items hive.
95   Standard_EXPORT TDF_Label GetAnnotatedItemsLabel() const;
96
97   //! Returns the number of labels in the notes hive.
98   Standard_EXPORT Standard_Integer NbNotes() const;
99
100   //! Returns the number of labels in the annotated items hive.
101   Standard_EXPORT Standard_Integer NbAnnotatedItems() const;
102
103   //! Returns all labels from the notes hive.
104   //! The label sequence isn't cleared beforehand.
105   //! \param [out] theNoteLabels - sequence of labels.
106   Standard_EXPORT void GetNotes(TDF_LabelSequence& theNoteLabels) const;
107
108   //! Returns all labels from the annotated items hive.
109   //! The label sequence isn't cleared beforehand.
110   //! \param [out] theNoteLabels - sequence of labels.
111   Standard_EXPORT void GetAnnotatedItems(TDF_LabelSequence& theLabels) const;
112
113   //! Checks if the given assembly item is annotated.
114   //! \param [in] theItemId - assembly item ID.
115   //! \return true if the item is annotated, otherwise - false.
116   Standard_EXPORT Standard_Boolean IsAnnotatedItem(const XCAFDoc_AssemblyItemId& theItemId) const;
117
118   //! Checks if the given labeled item is annotated.
119   //! \param [in] theItemLabel - item label.
120   //! \return true if the item is annotated, otherwise - false.
121   Standard_EXPORT Standard_Boolean IsAnnotatedItem(const TDF_Label& theItemLabel) const;
122
123   //! @name Find annotated item functions
124   //! @{
125
126   //! Finds a label of the given assembly item ID in the annotated items hive.
127   //! \param [in] theItemId - assembly item ID.
128   //! \return annotated item label if it is found, otherwise - null label.
129   Standard_EXPORT TDF_Label FindAnnotatedItem(const XCAFDoc_AssemblyItemId& theItemId) const;
130
131   //! Finds a label of the given labeled item in the annotated items hive.
132   //! \param [in] theItemLabel - item label.
133   //! \return annotated item label if it is found, otherwise - null label.
134   Standard_EXPORT TDF_Label FindAnnotatedItem(const TDF_Label& theItemLabel) const;
135
136   //! Finds a label of the given assembly item's attribute in the annotated items hive.
137   //! \param [in] theItemId - assembly item ID.
138   //! \param [in] theGUID   - assembly item's attribute GUID.
139   //! \return annotated item label if it is found, otherwise - null label.
140   Standard_EXPORT TDF_Label FindAnnotatedItemAttr(const XCAFDoc_AssemblyItemId& theItemId,
141                                                   const Standard_GUID&          theGUID) const;
142
143   //! Finds a label of the given labeled item's attribute in the annotated items hive.
144   //! \param [in] theItemLabel - item label.
145   //! \param [in] theGUID      - item's attribute GUID.
146   //! \return annotated item label if it is found, otherwise - null label.
147   Standard_EXPORT TDF_Label FindAnnotatedItemAttr(const TDF_Label&     theItemLabel,
148                                                   const Standard_GUID& theGUID) const;
149
150   //! Finds a label of the given assembly item's subshape in the annotated items hive.
151   //! \param [in] theItemId        - assembly item ID.
152   //! \param [in] theSubshapeIndex - assembly item's subshape index.
153   //! \return annotated item label if it is found, otherwise - null label.
154   Standard_EXPORT TDF_Label FindAnnotatedItemSubshape(const XCAFDoc_AssemblyItemId& theItemId,
155                                                       Standard_Integer              theSubshapeIndex) const;
156
157   //! Finds a label of the given labeled item's subshape in the annotated items hive.
158   //! \param [in] theItemLabel     - item label.
159   //! \param [in] theSubshapeIndex - labeled item's subshape index.
160   //! \return annotated item label if it is found, otherwise - null label.
161   Standard_EXPORT TDF_Label FindAnnotatedItemSubshape(const TDF_Label& theItemLabel,
162                                                       Standard_Integer theSubshapeIndex) const;
163
164   //! @}
165
166   //! @name Note creation functions
167   //! @{
168
169   //! Create a new comment note.
170   //! Creates a new label under the notes hive and attaches \ref XCAFDoc_NoteComment 
171   //! attribute (derived ftom \ref XCAFDoc_Note).
172   //! \param [in] theUserName  - the user associated with the note.
173   //! \param [in] theTimeStamp - timestamp of the note.
174   //! \param [in] theComment   - textual comment.
175   //! \return a handle to the base note attribute.
176   Standard_EXPORT Handle(XCAFDoc_Note) CreateComment(const TCollection_ExtendedString& theUserName,
177                                                      const TCollection_ExtendedString& theTimeStamp,
178                                                      const TCollection_ExtendedString& theComment);
179
180   //! Create a new 'balloon' note.
181   //! Creates a new label under the notes hive and attaches \ref XCAFDoc_NoteBalloon 
182   //! attribute (derived ftom \ref XCAFDoc_Note).
183   //! \param [in] theUserName  - the user associated with the note.
184   //! \param [in] theTimeStamp - timestamp of the note.
185   //! \param [in] theComment   - textual comment.
186   //! \return a handle to the base note attribute.
187   Standard_EXPORT Handle(XCAFDoc_Note) CreateBalloon(const TCollection_ExtendedString& theUserName,
188                                                      const TCollection_ExtendedString& theTimeStamp,
189                                                      const TCollection_ExtendedString& theComment);
190
191   //! Create a new note with data loaded from a binary file.
192   //! Creates a new label under the notes hive and attaches \ref XCAFDoc_NoteComment 
193   //! attribute (derived ftom \ref XCAFDoc_Note).
194   //! \param [in] theUserName  - the user associated with the note.
195   //! \param [in] theTimeStamp - timestamp of the note.
196   //! \param [in] theTitle     - file title.
197   //! \param [in] theMIMEtype  - MIME type of the file.
198   //! \param [in] theFile      - input binary file.
199   //! \return a handle to the base note attribute.
200   Standard_EXPORT Handle(XCAFDoc_Note) CreateBinData(const TCollection_ExtendedString& theUserName,
201                                                      const TCollection_ExtendedString& theTimeStamp,
202                                                      const TCollection_ExtendedString& theTitle,
203                                                      const TCollection_AsciiString&    theMIMEtype,
204                                                      OSD_File&                         theFile);
205
206   //! Create a new note with data loaded from a byte data array.
207   //! Creates a new label under the notes hive and attaches \ref XCAFDoc_NoteComment 
208   //! attribute (derived ftom \ref XCAFDoc_Note).
209   //! \param [in] theUserName  - the user associated with the note.
210   //! \param [in] theTimeStamp - timestamp of the note.
211   //! \param [in] theTitle     - data title.
212   //! \param [in] theMIMEtype  - MIME type of the file.
213   //! \param [in] theData      - byte data array.
214   //! \return a handle to the base note attribute.
215   Standard_EXPORT Handle(XCAFDoc_Note) CreateBinData(const TCollection_ExtendedString&    theUserName,
216                                                      const TCollection_ExtendedString&    theTimeStamp,
217                                                      const TCollection_ExtendedString&    theTitle,
218                                                      const TCollection_AsciiString&       theMIMEtype,
219                                                      const Handle(TColStd_HArray1OfByte)& theData);
220
221   //! @}
222
223   //! @name Get notes from annotated items functions
224   //! @{
225
226   //! Gets all note labels of the assembly item.
227   //! Notes linked to item's subshapes or attributes aren't
228   //! taken into account. The label sequence isn't cleared beforehand.
229   //! \param [in] theItemId      - assembly item ID.
230   //! \param [out] theNoteLabels - sequence of labels.
231   //! \return number of added labels.
232   Standard_EXPORT Standard_Integer GetNotes(const XCAFDoc_AssemblyItemId& theItemId,
233                                             TDF_LabelSequence&            theNoteLabels) const;
234
235   //! Gets all note labels of the labeled item.
236   //! Notes linked to item's attributes aren't
237   //! taken into account. The label sequence isn't cleared beforehand.
238   //! \param [in] theItemLabel   - item label.
239   //! \param [out] theNoteLabels - sequence of labels.
240   //! \return number of added labels.
241   Standard_EXPORT Standard_Integer GetNotes(const TDF_Label&   theItemLabel,
242                                             TDF_LabelSequence& theNoteLabels) const;
243
244   //! Gets all note labels of the assembly item's attribute.
245   //! Notes linked to the item itself or to item's subshapes
246   //! aren't taken into account. The label sequence isn't cleared beforehand.
247   //! \param [in] theItemId      - assembly item ID.
248   //! \param [in] theGUID        - assembly item's attribute GUID.
249   //! \param [out] theNoteLabels - sequence of labels.
250   //! \return number of added labels.
251   Standard_EXPORT Standard_Integer GetAttrNotes(const XCAFDoc_AssemblyItemId& theItemId,
252                                                 const Standard_GUID&          theGUID,
253                                                 TDF_LabelSequence&            theNoteLabels) const;
254
255   //! Gets all note labels of the labeled item's attribute.
256   //! Notes linked to the item itself or to item's subshapes
257   //! aren't taken into account. The label sequence isn't cleared beforehand.
258   //! \param [in] theItemLabel   - item label.
259   //! \param [in] theGUID        - item's attribute GUID.
260   //! \param [out] theNoteLabels - sequence of labels.
261   //! \return number of added labels.
262   Standard_EXPORT Standard_Integer GetAttrNotes(const TDF_Label&     theItemLabel,
263                                                 const Standard_GUID& theGUID,
264                                                 TDF_LabelSequence&   theNoteLabels) const;
265
266   //! Gets all note labels of the annotated item.
267   //! Notes linked to the item itself or to item's attributes
268   //! taken into account. The label sequence isn't cleared beforehand.
269   //! \param [in] theItemId        - assembly item ID.
270   //! \param [in] theSubshapeIndex - assembly item's subshape index.
271   //! \param [out] theNoteLabels   - sequence of labels.
272   //! \return number of added labels.
273   Standard_EXPORT Standard_Integer GetSubshapeNotes(const XCAFDoc_AssemblyItemId& theItemId,
274                                                     Standard_Integer              theSubshapeIndex,
275                                                     TDF_LabelSequence&            theNoteLabels) const;
276
277   //! @}
278
279   //! @name Annotation functions
280   //! @{
281
282   //! Adds the given note to the assembly item.
283   //! \param [in] theNoteLabel - note label.
284   //! \param [in] theItemId    - assembly item ID.
285   //! \return a handle to the assembly reference attribute.
286   Standard_EXPORT Handle(XCAFDoc_AssemblyItemRef) AddNote(const TDF_Label&              theNoteLabel,
287                                                           const XCAFDoc_AssemblyItemId& theItemId);
288
289   //! Adds the given note to the labeled item.
290   //! \param [in] theNoteLabel - note label.
291   //! \param [in] theItemLabel - item label.
292   //! \return a handle to the assembly reference attribute.
293   Standard_EXPORT Handle(XCAFDoc_AssemblyItemRef) AddNote(const TDF_Label& theNoteLabel,
294                                                           const TDF_Label& theItemLabel);
295
296   //! Adds the given note to the assembly item's attribute.
297   //! \param [in] theNoteLabel - note label.
298   //! \param [in] theItemId    - assembly item ID.
299   //! \param [in] theGUID      - assembly item's attribute GUID.
300   //! \return a handle to the assembly reference attribute.
301   Standard_EXPORT Handle(XCAFDoc_AssemblyItemRef) AddNoteToAttr(const TDF_Label&              theNoteLabel,
302                                                                 const XCAFDoc_AssemblyItemId& theItemId,
303                                                                 const Standard_GUID&          theGUID);
304
305   //! Adds the given note to the labeled item's attribute.
306   //! \param [in] theNoteLabel - note label.
307   //! \param [in] theItemLabel - item label.
308   //! \param [in] theGUID      - assembly item's attribute GUID.
309   //! \return a handle to the assembly reference attribute.
310   Standard_EXPORT Handle(XCAFDoc_AssemblyItemRef) AddNoteToAttr(const TDF_Label&     theNoteLabel,
311                                                                 const TDF_Label&     theItemLabel,
312                                                                 const Standard_GUID& theGUID);
313
314   //! Adds the given note to the assembly item's subshape.
315   //! \param [in] theNoteLabel     - note label.
316   //! \param [in] theItemId        - assembly item ID.
317   //! \param [in] theSubshapeIndex - assembly item's subshape index.
318   //! \return a handle to the assembly reference attribute.
319   Standard_EXPORT Handle(XCAFDoc_AssemblyItemRef) AddNoteToSubshape(const TDF_Label&              theNoteLabel,
320                                                                     const XCAFDoc_AssemblyItemId& theItemId,
321                                                                     Standard_Integer              theSubshapeIndex);
322
323   //! Adds the given note to the labeled item's subshape.
324   //! \param [in] theNoteLabel     - note label.
325   //! \param [in] theItemLabel     - item label.
326   //! \param [in] theSubshapeIndex - assembly item's subshape index.
327   //! \return a handle to the assembly reference attribute.
328   Standard_EXPORT Handle(XCAFDoc_AssemblyItemRef) AddNoteToSubshape(const TDF_Label& theNoteLabel,
329                                                                     const TDF_Label& theItemLabel,
330                                                                     Standard_Integer theSubshapeIndex);
331
332   //! @}
333
334   //! @name Remove annotation functions
335   //! @{
336
337   //! Removes the given note from the assembly item.
338   //! \param [in] theNoteLabel   - note label.
339   //! \param [in] theItemId      - assembly item ID.
340   //! \param [in] theDelIfOrphan - deletes the note from the notes hive 
341   //!                              if there are no more assembly items
342   //!                              linked with the note.
343   //! \return true if the note is removed, otherwise - false.
344   Standard_EXPORT Standard_Boolean RemoveNote(const TDF_Label&              theNoteLabel,
345                                               const XCAFDoc_AssemblyItemId& theItemId,
346                                               Standard_Boolean              theDelIfOrphan = Standard_False);
347
348   //! Removes the given note from the labeled item.
349   //! \param [in] theNoteLabel   - note label.
350   //! \param [in] theItemLabel   - item label.
351   //! \param [in] theDelIfOrphan - deletes the note from the notes hive 
352   //!                              if there are no more labeled items
353   //!                              linked with the note.
354   //! \return true if the note is removed, otherwise - false.
355   Standard_EXPORT Standard_Boolean RemoveNote(const TDF_Label& theNoteLabel,
356                                               const TDF_Label& theItemLabel,
357                                               Standard_Boolean theDelIfOrphan = Standard_False);
358
359   //! Removes the given note from the assembly item's subshape.
360   //! \param [in] theNoteLabel     - note label.
361   //! \param [in] theItemId        - assembly item ID.
362   //! \param [in] theSubshapeIndex - assembly item's subshape index.
363   //! \param [in] theDelIfOrphan   - deletes the note from the notes hive 
364   //!                                if there are no more assembly item's
365   //!                                subshape linked with the note.
366   //! \return true if the note is removed, otherwise - false.
367   Standard_EXPORT Standard_Boolean RemoveSubshapeNote(const TDF_Label&              theNoteLabel,
368                                                       const XCAFDoc_AssemblyItemId& theItemId,
369                                                       Standard_Integer              theSubshapeIndex,
370                                                       Standard_Boolean              theDelIfOrphan = Standard_False);
371
372   //! Removes the given note from the labeled item's subshape.
373   //! \param [in] theNoteLabel     - note label.
374   //! \param [in] theItemLabel     - item label.
375   //! \param [in] theSubshapeIndex - labeled item's subshape index.
376   //! \param [in] theDelIfOrphan   - deletes the note from the notes hive 
377   //!                                if there are no more assembly item's
378   //!                                subshape linked with the note.
379   //! \return true if the note is removed, otherwise - false.
380   Standard_EXPORT Standard_Boolean RemoveSubshapeNote(const TDF_Label& theNoteLabel,
381                                                       const TDF_Label& theItemLabel,
382                                                       Standard_Integer theSubshapeIndex,
383                                                       Standard_Boolean theDelIfOrphan = Standard_False);
384
385   //! Removes a note from the assembly item's attribute.
386   //! \param [in] theNoteLabel   - note label.
387   //! \param [in] theItemId      - assembly item ID.
388   //! \param [in] theGUID        - assembly item's attribute GUID.
389   //! \param [in] theDelIfOrphan - deletes the note from the notes hive 
390   //!                              if there are no more assembly item's
391   //!                              attribute linked with the note.
392   //! \return true if the note is removed, otherwise - false.
393   Standard_EXPORT Standard_Boolean RemoveAttrNote(const TDF_Label&              theNoteLabel,
394                                                   const XCAFDoc_AssemblyItemId& theItemId,
395                                                   const Standard_GUID&          theGUID,
396                                                   Standard_Boolean              theDelIfOrphan = Standard_False);
397
398   //! Removes a note from the labeled item's attribute.
399   //! \param [in] theNoteLabel   - note label.
400   //! \param [in] theItemLabel   - item label.
401   //! \param [in] theGUID        - labeled item's attribute GUID.
402   //! \param [in] theDelIfOrphan - deletes the note from the notes hive 
403   //!                              if there are no more assembly item's
404   //!                              attribute linked with the note.
405   //! \return true if the note is removed, otherwise - false.
406   Standard_EXPORT Standard_Boolean RemoveAttrNote(const TDF_Label&     theNoteLabel,
407                                                   const TDF_Label&     theItemLabel,
408                                                   const Standard_GUID& theGUID,
409                                                   Standard_Boolean     theDelIfOrphan = Standard_False);
410
411   //! Removes all notes from the assembly item.
412   //! \param [in] theItemId      - assembly item ID.
413   //! \param [in] theDelIfOrphan - deletes removed notes from the notes
414   //!                              hive if there are no more annotated items
415   //!                              linked with the notes.
416   //! \return true if the notes are removed, otherwise - false.
417   Standard_EXPORT Standard_Boolean RemoveAllNotes(const XCAFDoc_AssemblyItemId& theItemId,
418                                                   Standard_Boolean              theDelIfOrphan = Standard_False);
419
420   //! Removes all notes from the labeled item.
421   //! \param [in] theItemLabel   - item label.
422   //! \param [in] theDelIfOrphan - deletes removed notes from the notes
423   //!                              hive if there are no more annotated items
424   //!                              linked with the notes.
425   //! \return true if the notes are removed, otherwise - false.
426   Standard_EXPORT Standard_Boolean RemoveAllNotes(const TDF_Label& theItemLabel,
427                                                   Standard_Boolean theDelIfOrphan = Standard_False);
428
429   //! Removes all notes from the assembly item's subshape.
430   //! \param [in] theItemId        - assembly item ID.
431   //! \param [in] theSubshapeIndex - assembly item's subshape index.
432   //! \param [in] theDelIfOrphan   - deletes removed notes from the notes
433   //!                                hive if there are no more annotated items
434   //!                                linked with the notes.
435   //! \return true if the notes are removed, otherwise - false.
436   Standard_EXPORT Standard_Boolean RemoveAllSubshapeNotes(const XCAFDoc_AssemblyItemId& theItemId,
437                                                           Standard_Integer              theSubshapeIndex,
438                                                           Standard_Boolean              theDelIfOrphan = Standard_False);
439
440   //! Removes all notes from the assembly item's attribute.
441   //! \param [in] theItemId      - assembly item ID.
442   //! \param [in] theGUID        - assembly item's attribute GUID.
443   //! \param [in] theDelIfOrphan - deletes removed notes from the notes
444   //!                              hive if there are no more annotated items
445   //!                              linked with the notes.
446   //! \return true if the notes are removed, otherwise - false.
447   Standard_EXPORT Standard_Boolean RemoveAllAttrNotes(const XCAFDoc_AssemblyItemId& theItemId,
448                                                       const Standard_GUID&          theGUID,
449                                                       Standard_Boolean              theDelIfOrphan = Standard_False);
450
451   //! Removes all notes from the labeled item's attribute.
452   //! \param [in] theItemLabel   - item label.
453   //! \param [in] theGUID        - labeled item's attribute GUID.
454   //! \param [in] theDelIfOrphan - deletes removed notes from the notes
455   //!                              hive if there are no more annotated items
456   //!                              linked with the notes.
457   //! \return true if the notes are removed, otherwise - false.
458   Standard_EXPORT Standard_Boolean RemoveAllAttrNotes(const TDF_Label&     theItemLabel,
459                                                       const Standard_GUID& theGUID,
460                                                       Standard_Boolean     theDelIfOrphan = Standard_False);
461
462   //! @}
463
464   //! @name Delete note functions
465   //! @{
466
467   //! Deletes the given note.
468   //! Removes all links with items annotated by the note.
469   //! \param [in] theNoteLabel - note label.
470   //! \return true if the note is deleted, otherwise - false.
471   Standard_EXPORT Standard_Boolean DeleteNote(const TDF_Label& theNoteLabel);
472
473   //! Deletes the given notes.
474   //! Removes all links with items annotated by the notes.
475   //! \param [in] theNoteLabels - note label sequence.
476   //! \return number of deleted notes.
477   Standard_EXPORT Standard_Integer DeleteNotes(TDF_LabelSequence& theNoteLabels);
478
479   //! Deletes all notes.
480   //! Clears all annotations.
481   //! \return number of deleted notes.
482   Standard_EXPORT Standard_Integer DeleteAllNotes();
483
484   //! @}
485
486   //! @name Orphan annotated items functions
487   //! @{
488
489   //! Returns number of notes that aren't linked to annotated items.
490   Standard_EXPORT Standard_Integer NbOrphanNotes() const;
491
492   //! Returns note labels that aren't linked to annotated items.
493   //! The label sequence isn't cleared beforehand.
494   //! \param [out] theNoteLabels - sequence of labels.
495   Standard_EXPORT void GetOrphanNotes(TDF_LabelSequence& theNoteLabels) const;
496   
497   //! Deletes all notes that aren't linked to annotated items.
498   //! \return number of deleted notes.
499   Standard_EXPORT Standard_Integer DeleteOrphanNotes();
500
501   //! @}
502
503 public:
504
505   // Overrides TDF_Attribute virtuals
506   Standard_EXPORT const Standard_GUID& ID() const Standard_OVERRIDE;
507   Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS) const Standard_OVERRIDE;
508   
509 };
510
511 DEFINE_STANDARD_HANDLE(XCAFDoc_NotesTool, TDataStd_GenericEmpty)
512
513 #endif // _XCAFDoc_NotesTool_HeaderFile