diff --git a/src/XCAFDoc/XCAFDoc.hxx b/src/XCAFDoc/XCAFDoc.hxx index a6c8760408..fe6efd5828 100644 --- a/src/XCAFDoc/XCAFDoc.hxx +++ b/src/XCAFDoc/XCAFDoc.hxx @@ -98,7 +98,7 @@ public: Standard_EXPORT static Standard_GUID MaterialRefGUID(); - //! Return GUIDs for TreeNode representing types of Note + //! Return GUIDs for representing notes Standard_EXPORT static Standard_GUID NoteRefGUID(); Standard_EXPORT static Standard_GUID InvisibleGUID(); diff --git a/src/XCAFDoc/XCAFDoc_AssemblyItemId.hxx b/src/XCAFDoc/XCAFDoc_AssemblyItemId.hxx index 881a94cf4c..94b8c040f3 100644 --- a/src/XCAFDoc/XCAFDoc_AssemblyItemId.hxx +++ b/src/XCAFDoc/XCAFDoc_AssemblyItemId.hxx @@ -19,28 +19,62 @@ #include #include +//! Unique item identifier in the hierarchical product structure. +//! A full path to an assembly component in the “part-of” graph starting from +//! the root node. class XCAFDoc_AssemblyItemId { public: + //! Constructs an empty item ID. Standard_EXPORT XCAFDoc_AssemblyItemId(); + + //! Constructs an item ID from a list of strings, where every + //! string is a label entry. + //! \param [in] thePath - list of label entries. Standard_EXPORT XCAFDoc_AssemblyItemId(const TColStd_ListOfAsciiString& thePath); + + //! Constructs an item ID from a formatted path, where label entries + //! are separated by '/' symbol. + //! \param [in] theString - formatted full path. Standard_EXPORT XCAFDoc_AssemblyItemId(const TCollection_AsciiString& theString); + //! Initializes the item ID from a list of strings, where every + //! string is a label entry. + //! \param [in] thePath - list of label entries. Standard_EXPORT void Init(const TColStd_ListOfAsciiString& thePath); + + //! Initializes the item ID from a formatted path, where label entries + //! are separated by '/' symbol. + //! \param [in] theString - formatted full path. Standard_EXPORT void Init(const TCollection_AsciiString& theString); + //! Returns true if the full path is empty, otherwise - false. Standard_EXPORT Standard_Boolean IsNull() const; + + //! Clears the full path. Standard_EXPORT void Nullify(); + //! Checks if this item is a child of the given item. + //! \param [in] theOther - potentially ancestor item. + //! \return true if the item is a child of theOther item, otherwise - false. Standard_EXPORT Standard_Boolean IsChild(const XCAFDoc_AssemblyItemId& theOther) const; + + //! Checks if this item is a direct child of the given item. + //! \param [in] theOther - potentially parent item. + //! \return true if the item is a direct child of theOther item, otherwise - false. Standard_EXPORT Standard_Boolean IsDirectChild(const XCAFDoc_AssemblyItemId& theOther) const; + //! Checks for item IDs equality. + //! \param [in] theOther - the item ID to check equality with. + //! \return true if this ID is equal to theOther, otherwise - false. Standard_EXPORT Standard_Boolean IsEqual(const XCAFDoc_AssemblyItemId& theOther) const; + //! Returns the full path as a list of label entries. Standard_EXPORT const TColStd_ListOfAsciiString& GetPath() const; + //! Returns the full pass as a formatted string. Standard_EXPORT TCollection_AsciiString ToString() const; struct Hasher @@ -60,7 +94,7 @@ public: private: - TColStd_ListOfAsciiString myPath; + TColStd_ListOfAsciiString myPath; ///< List of label entries }; diff --git a/src/XCAFDoc/XCAFDoc_AssemblyItemRef.cxx b/src/XCAFDoc/XCAFDoc_AssemblyItemRef.cxx index 2e100a975d..9059998e78 100644 --- a/src/XCAFDoc/XCAFDoc_AssemblyItemRef.cxx +++ b/src/XCAFDoc/XCAFDoc_AssemblyItemRef.cxx @@ -199,6 +199,7 @@ XCAFDoc_AssemblyItemRef::SetItem(const XCAFDoc_AssemblyItemId& theItemId) { Backup(); myItemId = theItemId; + ClearExtraRef(); } void @@ -206,6 +207,7 @@ XCAFDoc_AssemblyItemRef::SetItem(const TColStd_ListOfAsciiString& thePath) { Backup(); myItemId.Init(thePath); + ClearExtraRef(); } void @@ -213,6 +215,7 @@ XCAFDoc_AssemblyItemRef::SetItem(const TCollection_AsciiString& theString) { Backup(); myItemId.Init(theString); + ClearExtraRef(); } void XCAFDoc_AssemblyItemRef::SetGUID(const Standard_GUID& theAttrGUID) diff --git a/src/XCAFDoc/XCAFDoc_AssemblyItemRef.hxx b/src/XCAFDoc/XCAFDoc_AssemblyItemRef.hxx index f404398c34..9f4eb60540 100644 --- a/src/XCAFDoc/XCAFDoc_AssemblyItemRef.hxx +++ b/src/XCAFDoc/XCAFDoc_AssemblyItemRef.hxx @@ -28,6 +28,8 @@ class TDF_RelocationTable; class XCAFDoc_AssemblyItemRef; DEFINE_STANDARD_HANDLE(XCAFDoc_AssemblyItemRef, TDF_Attribute) +//! An attribute that describes a weak reference to an assembly item +//! or to a subshape or to an assembly label attribute. class XCAFDoc_AssemblyItemRef : public TDF_Attribute { @@ -37,55 +39,115 @@ public: Standard_EXPORT static const Standard_GUID& GetID(); + //! Finds a reference attribute on the given label and returns it, if it is found Standard_EXPORT static Handle(XCAFDoc_AssemblyItemRef) Get(const TDF_Label& theLabel); + //! @name Set reference attribute functions. + //! @{ + + //! Create (if not exist) a reference to an assembly item. + //! \param [in] theLabel - label to add the attribute. + //! \param [in] theItemId - assembly item ID. + //! \return A handle to the attribute instance. Standard_EXPORT static Handle(XCAFDoc_AssemblyItemRef) Set(const TDF_Label& theLabel, const XCAFDoc_AssemblyItemId& theItemId); + + //! Create (if not exist) a reference to an assembly item's label attribute. + //! \param [in] theLabel - label to add the attribute. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theGUID - assembly item's label attribute ID. + //! \return A handle to the attribute instance. Standard_EXPORT static Handle(XCAFDoc_AssemblyItemRef) Set(const TDF_Label& theLabel, const XCAFDoc_AssemblyItemId& theItemId, const Standard_GUID& theGUID); + + //! Create (if not exist) a reference to an assembly item's subshape. + //! \param [in] theLabel - label to add the attribute. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theShapeIndex - assembly item's subshape index. + //! \return A handle to the attribute instance. Standard_EXPORT static Handle(XCAFDoc_AssemblyItemRef) Set(const TDF_Label& theLabel, const XCAFDoc_AssemblyItemId& theItemId, const Standard_Integer theShapeIndex); + //! @} + + //! Creates an empty reference attribute. Standard_EXPORT XCAFDoc_AssemblyItemRef(); + //! Checks if the reference points to a really existing item in XDE document. Standard_EXPORT Standard_Boolean IsOrphan() const; + //! @name Extra reference functions. + //! @{ + + //! Checks if the reference points on an item's shapeindex or attribute. Standard_EXPORT Standard_Boolean HasExtraRef() const; + + //! Checks is the reference points to an item's attribute. Standard_EXPORT Standard_Boolean IsGUID() const; + + //! Checks is the reference points to an item's subshape. Standard_EXPORT Standard_Boolean IsSubshapeIndex() const; - Standard_EXPORT const XCAFDoc_AssemblyItemId& GetItem() const; + //! Returns the assembly item's attribute that the reference points to. + //! If the reference doesn't point to an attribute, returns an empty GUID. Standard_EXPORT Standard_GUID GetGUID() const; + + //! Returns the assembly item's subshape that the reference points to. + //! If the reference doesn't point to a subshape, returns 0. Standard_EXPORT Standard_Integer GetSubshapeIndex() const; + + //! @} + + //! Returns the assembly item ID that the reference points to. + Standard_EXPORT const XCAFDoc_AssemblyItemId& GetItem() const; + //! @name Set reference data functions. + //! @{ + + //! Sets the assembly item ID that the reference points to. + //! Extra reference data (if any) will be cleared. Standard_EXPORT void SetItem(const XCAFDoc_AssemblyItemId& theItemId); + + //! Sets the assembly item ID from a list of label entries + //! that the reference points to. + //! Extra reference data (if any) will be cleared. Standard_EXPORT void SetItem(const TColStd_ListOfAsciiString& thePath); + + //! Sets the assembly item ID from a formatted path + //! that the reference points to. + //! Extra reference data (if any) will be cleared. Standard_EXPORT void SetItem(const TCollection_AsciiString& theString); + + //! Sets the assembly item's label attribute that the reference points to. + //! The base assembly item will not change. Standard_EXPORT void SetGUID(const Standard_GUID& theAttrGUID); + + //! Sets the assembly item's subshape that the reference points to. + //! The base assembly item will not change. Standard_EXPORT void SetSubshapeIndex(Standard_Integer theShapeIndex); + //! @} + + //! Reverts the reference to empty state. Standard_EXPORT void ClearExtraRef(); public: + // Overrides TDF_Attribute pure virtuals Standard_EXPORT const Standard_GUID& ID() const Standard_OVERRIDE; - Standard_EXPORT Handle(TDF_Attribute) NewEmpty() const Standard_OVERRIDE; - Standard_EXPORT void Restore(const Handle(TDF_Attribute)& theAttrFrom) Standard_OVERRIDE; - Standard_EXPORT void Paste(const Handle(TDF_Attribute)& theAttrInto, const Handle(TDF_RelocationTable)& theRT) const Standard_OVERRIDE; - Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS) const Standard_OVERRIDE; private: - XCAFDoc_AssemblyItemId myItemId; - Standard_Integer myExtraRef; - TCollection_AsciiString myExtraId; + XCAFDoc_AssemblyItemId myItemId; ///< Assembly item ID + Standard_Integer myExtraRef; ///< Type of extra reference: subshape or attribute + TCollection_AsciiString myExtraId; ///< Extra reference data }; diff --git a/src/XCAFDoc/XCAFDoc_Note.hxx b/src/XCAFDoc/XCAFDoc_Note.hxx index f83486b7cc..524e2d6346 100644 --- a/src/XCAFDoc/XCAFDoc_Note.hxx +++ b/src/XCAFDoc/XCAFDoc_Note.hxx @@ -29,42 +29,54 @@ class TDF_RelocationTable; class XCAFDoc_Note; DEFINE_STANDARD_HANDLE(XCAFDoc_Note, TDF_Attribute) +//! A base note attribute. +//! Any note contains the name of the user created the note +//! and the creation timestamp. class XCAFDoc_Note : public TDF_Attribute { public: DEFINE_STANDARD_RTTIEXT(XCAFDoc_Note, TDF_Attribute) + //! Checks if the given label represents a note. Standard_EXPORT static Standard_Boolean IsMine(const TDF_Label& theLabel); + //! Finds a reference attribute on the given label and returns it, if it is found Standard_EXPORT static Handle(XCAFDoc_Note) Get(const TDF_Label& theLabel); - Standard_EXPORT void Set(const TCollection_ExtendedString& theUserName, - const TCollection_ExtendedString& theTimeStamp); - + //! Returns the user name, who created the note. Standard_EXPORT const TCollection_ExtendedString& UserName() const; + //! Returns the timestamp of the note. Standard_EXPORT const TCollection_ExtendedString& TimeStamp() const; + //! Checks if the note isn't linked to annotated items. Standard_EXPORT Standard_Boolean IsOrphan() const; public: + // Overrides TDF_Attribute virtuals Standard_EXPORT void Restore(const Handle(TDF_Attribute)& theAttrFrom) Standard_OVERRIDE; - Standard_EXPORT void Paste(const Handle(TDF_Attribute)& theAttrInto, const Handle(TDF_RelocationTable)& theRT) const Standard_OVERRIDE; - Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS) const Standard_OVERRIDE; protected: + //! Sets the user name and the timestamp of the note. + //! \param [in] theUserName - the user associated with the note. + //! \param [in] theTimeStamp - timestamp of the note. + //! \return A handle to the attribute instance. + Standard_EXPORT void Set(const TCollection_ExtendedString& theUserName, + const TCollection_ExtendedString& theTimeStamp); + + //! Creates an empty note. Standard_EXPORT XCAFDoc_Note(); private: - TCollection_ExtendedString myUserName; - TCollection_ExtendedString myTimeStamp; + TCollection_ExtendedString myUserName; ///< Name of the user, who created the note. + TCollection_ExtendedString myTimeStamp; ///< Timestamp, when the note was created. }; #endif // _XCAFDoc_Note_HeaderFile diff --git a/src/XCAFDoc/XCAFDoc_NoteBinData.hxx b/src/XCAFDoc/XCAFDoc_NoteBinData.hxx index 27160988f7..dc902be3c8 100644 --- a/src/XCAFDoc/XCAFDoc_NoteBinData.hxx +++ b/src/XCAFDoc/XCAFDoc_NoteBinData.hxx @@ -34,8 +34,20 @@ public: Standard_EXPORT static const Standard_GUID& GetID(); + //! Finds a binary data attribute on the given label and returns it, if it is found Standard_EXPORT static Handle(XCAFDoc_NoteBinData) Get(const TDF_Label& theLabel); + //! @name Set attribute functions. + //! @{ + + //! Create (if not exist) a binary note with data loaded from a binary file. + //! \param [in] theLabel - label to add the attribute. + //! \param [in] theUserName - the name of the user, who created the note. + //! \param [in] theTimeStamp - creation timestamp of the note. + //! \param [in] theTitle - file title. + //! \param [in] theMIMEtype - MIME type of the file. + //! \param [in] theFile - input binary file. + //! \return A handle to the attribute instance. Standard_EXPORT static Handle(XCAFDoc_NoteBinData) Set(const TDF_Label& theLabel, const TCollection_ExtendedString& theUserName, const TCollection_ExtendedString& theTimeStamp, @@ -43,6 +55,14 @@ public: const TCollection_AsciiString& theMIMEtype, OSD_File& theFile); + //! Create (if not exist) a binary note byte data array. + //! \param [in] theLabel - label to add the attribute. + //! \param [in] theUserName - the name of the user, who created the note. + //! \param [in] theTimeStamp - creation timestamp of the note. + //! \param [in] theTitle - data title. + //! \param [in] theMIMEtype - MIME type of data. + //! \param [in] theData - byte data array. + //! \return A handle to the attribute instance. Standard_EXPORT static Handle(XCAFDoc_NoteBinData) Set(const TDF_Label& theLabel, const TCollection_ExtendedString& theUserName, const TCollection_ExtendedString& theTimeStamp, @@ -50,41 +70,60 @@ public: const TCollection_AsciiString& theMIMEtype, const Handle(TColStd_HArray1OfByte)& theData); + //! @} + + //! Creates an empty binary data note. Standard_EXPORT XCAFDoc_NoteBinData(); - Standard_EXPORT Standard_Boolean Set(const TCollection_ExtendedString& theTitle, + //! @name Set attribute data functions. + //! @{ + + //! Sets title, MIME type and data from a binary file. + //! \param [in] theTitle - file title. + //! \param [in] theMIMEtype - MIME type of the file. + //! \param [in] theFile - input binary file. + Standard_EXPORT Standard_Boolean Set(const TCollection_ExtendedString& theTitle, const TCollection_AsciiString& theMIMEtype, OSD_File& theFile); + //! Sets title, MIME type and data from a byte array. + //! \param [in] theTitle - data title. + //! \param [in] theMIMEtype - MIME type of data. + //! \param [in] theData - byte data array. Standard_EXPORT void Set(const TCollection_ExtendedString& theTitle, const TCollection_AsciiString& theMIMEtype, const Handle(TColStd_HArray1OfByte)& theData); + //! @} + + //! Returns the note title. Standard_EXPORT const TCollection_ExtendedString& Title() const; + + //! Returns data MIME type. Standard_EXPORT const TCollection_AsciiString& MIMEtype() const; + //! Size of data in bytes. Standard_EXPORT Standard_Integer Size() const; + //! Returns byte data array. Standard_EXPORT const Handle(TColStd_HArray1OfByte)& Data() const; public: + // Overrides TDF_Attribute virtuals Standard_EXPORT const Standard_GUID& ID() const Standard_OVERRIDE; - Standard_EXPORT Handle(TDF_Attribute) NewEmpty() const Standard_OVERRIDE; - Standard_EXPORT void Restore(const Handle(TDF_Attribute)& theAttrFrom) Standard_OVERRIDE; - Standard_EXPORT void Paste(const Handle(TDF_Attribute)& theAttrInto, const Handle(TDF_RelocationTable)& theRT) const Standard_OVERRIDE; - Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS) const Standard_OVERRIDE; protected: - TCollection_ExtendedString myTitle; - TCollection_AsciiString myMIMEtype; - Handle(TColStd_HArray1OfByte) myData; + TCollection_ExtendedString myTitle; ///< Note title. + TCollection_AsciiString myMIMEtype; ///< MIME type of data. + Handle(TColStd_HArray1OfByte) myData; ///< Byte data array. + }; #endif // _XCAFDoc_NoteBinData_HeaderFile diff --git a/src/XCAFDoc/XCAFDoc_NoteComment.hxx b/src/XCAFDoc/XCAFDoc_NoteComment.hxx index a8154a919a..8232750698 100644 --- a/src/XCAFDoc/XCAFDoc_NoteComment.hxx +++ b/src/XCAFDoc/XCAFDoc_NoteComment.hxx @@ -21,6 +21,8 @@ class XCAFDoc_NoteComment; DEFINE_STANDARD_HANDLE(XCAFDoc_NoteComment, XCAFDoc_Note) +//! A comment note attribute. +//! Contains a textual comment. class XCAFDoc_NoteComment : public XCAFDoc_Note { public: @@ -29,35 +31,42 @@ public: Standard_EXPORT static const Standard_GUID& GetID(); + //! Finds a reference attribute on the given label and returns it, if it is found Standard_EXPORT static Handle(XCAFDoc_NoteComment) Get(const TDF_Label& theLabel); + //! Create (if not exist) a comment note on the given label. + //! \param [in] theLabel - note label. + //! \param [in] theUserName - the name of the user, who created the note. + //! \param [in] theTimeStamp - creation timestamp of the note. + //! \param [in] theComment - comment text. Standard_EXPORT static Handle(XCAFDoc_NoteComment) Set(const TDF_Label& theLabel, const TCollection_ExtendedString& theUserName, const TCollection_ExtendedString& theTimeStamp, const TCollection_ExtendedString& theComment); + //! Creates an empty comment note. Standard_EXPORT XCAFDoc_NoteComment(); + //! Sets the comment text. Standard_EXPORT void Set(const TCollection_ExtendedString& theComment); + //! Returns the comment text. Standard_EXPORT const TCollection_ExtendedString& Comment() const; public: + // Overrides TDF_Attribute virtuals Standard_EXPORT const Standard_GUID& ID() const Standard_OVERRIDE; - Standard_EXPORT Handle(TDF_Attribute) NewEmpty() const Standard_OVERRIDE; - Standard_EXPORT void Restore(const Handle(TDF_Attribute)& theAttrFrom) Standard_OVERRIDE; - Standard_EXPORT void Paste(const Handle(TDF_Attribute)& theAttrInto, const Handle(TDF_RelocationTable)& theRT) const Standard_OVERRIDE; - Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS) const Standard_OVERRIDE; protected: - TCollection_ExtendedString myComment; + TCollection_ExtendedString myComment; ///< Comment text. + }; #endif // _XCAFDoc_NoteComment_HeaderFile diff --git a/src/XCAFDoc/XCAFDoc_NotesTool.hxx b/src/XCAFDoc/XCAFDoc_NotesTool.hxx index 6a1c3c70c6..013e84febc 100644 --- a/src/XCAFDoc/XCAFDoc_NotesTool.hxx +++ b/src/XCAFDoc/XCAFDoc_NotesTool.hxx @@ -34,6 +34,50 @@ class XCAFDoc_AssemblyItemRef; class XCAFDoc_NotesTool; DEFINE_STANDARD_HANDLE(XCAFDoc_NotesTool, TDF_Attribute) +//! A tool to annotate items in the hierarchical product structure. +//! There are two basic entities, which operates the notes tool: notes +//! and annotated items. A note is a user defined data structure derived +//! from \ref XCAFDoc_Note attribute that is attached to a separate label under +//! the notes hive. An annotated item is represented by \ref XCAFDoc_AssemblyItemRef +//! attribute attached attached to a separate label under the annotated items +//! hive. Notes are linked with annotated items by means of \ref XCAFDoc_GraphNode +//! attribute. Notes play parent roles and annotated items - child roles. +//! +//! ------------------------ +//! | XCAFDoc_DocumentTool | +//! | 0:1 | +//! ------------------------ +//! |1 +//! ------------------------ +//! | XCAFDoc_NotesTool | +//! | 0:1:9 | +//! ------------------------ +//! |1 +//! | ------------------- --------------------------- +//! +___| Notes |-----| XCAFDoc_Note | +//! | 1| 0:1:9:1 |1 *| 0:1:9:1:* | +//! | ------------------- --------------------------- +//! | !* +//! | { XCAFDoc_GraphNode } +//! | *! +//! | ------------------- --------------------------- +//! +___| Annotated items |-----| XCAFDoc_AssemblyItemRef | +//! 1| 0:1:9:2 |1 *| 0:1:9:2:* | +//! ------------------- --------------------------- +//! +//! A typical annotation procedure is illustrated by the code example below: +//! \code{.c++} +//! // Get the notes tool from a XCAF document +//! Handle(XCAFDoc_NotesTool) aNotesTool = XCAFDoc_DocumentTool::NotesTool(aDoc->Main()); +//! // Create new comment note +//! Handle(XCAFDoc_Note) aNote = aNotesTool->CreateComment(aUserName, aTimestamp, aComment); +//! if (!aNote.IsNull()) { +//! Handle(XCAFDoc_AssemblyItemRef) aRef = aNotesTool->AddNote(aNote->Label(), anAssemblyItemId); +//! if (aRef.IsNull()) { +//! // Process error... +//! } +//! } +//! \endcode class XCAFDoc_NotesTool : public TDF_Attribute { public: @@ -42,91 +86,290 @@ public: Standard_EXPORT static const Standard_GUID& GetID(); + //! Create (if not exist) a notes tool from XCAFDoc on theLabel. Standard_EXPORT static Handle(XCAFDoc_NotesTool) Set(const TDF_Label& theLabel); + //! Creates an empty notes tool. Standard_EXPORT XCAFDoc_NotesTool(); + //! Returns the label of the notes hive. Standard_EXPORT TDF_Label GetNotesLabel() const; + + //! Returns the label of the annotated items hive. Standard_EXPORT TDF_Label GetAnnotatedItemsLabel() const; + //! Returns the number of labels in the notes hive. Standard_EXPORT Standard_Integer NbNotes() const; + + //! Returns the number of labels in the annotated items hive. Standard_EXPORT Standard_Integer NbAnnotatedItems() const; + //! Returns all labels from the notes hive. + //! The label sequence isn't cleared beforehand. + //! \param [out] theNoteLabels - sequence of labels. Standard_EXPORT void GetNotes(TDF_LabelSequence& theNoteLabels) const; + + //! Returns all labels from the annotated items hive. + //! The label sequence isn't cleared beforehand. + //! \param [out] theNoteLabels - sequence of labels. Standard_EXPORT void GetAnnotatedItems(TDF_LabelSequence& theLabels) const; + //! Checks if the given assembly item is annotated. + //! \param [in] theItemId - assembly item ID. + //! \return true if the item is annotated, otherwise - false. Standard_EXPORT Standard_Boolean IsAnnotatedItem(const XCAFDoc_AssemblyItemId& theItemId) const; + + //! @name Find annotated item functions + //! @{ + + //! Finds a label of the given assembly item ID in the annotated items hive. + //! \param [in] theItemId - assembly item ID. + //! \return annotated item label if it is found, otherwise - null label. Standard_EXPORT TDF_Label FindAnnotatedItem(const XCAFDoc_AssemblyItemId& theItemId) const; + + //! Finds a label of the given assembly item's attribute in the annotated items hive. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theGUID - assembly item's attribute GUID. + //! \return annotated item label if it is found, otherwise - null label. Standard_EXPORT TDF_Label FindAnnotatedItemAttr(const XCAFDoc_AssemblyItemId& theItemId, const Standard_GUID& theGUID) const; + + //! Finds a label of the given assembly item's subshape in the annotated items hive. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theSubshapeIndex - assembly item's subshape index. + //! \return annotated item label if it is found, otherwise - null label. Standard_EXPORT TDF_Label FindAnnotatedItemSubshape(const XCAFDoc_AssemblyItemId& theItemId, Standard_Integer theSubshapeIndex) const; + //! @} + + //! @name Note creation functions + //! @{ + + //! Create a new comment note. + //! Creates a new label under the notes hive and attaches \ref XCAFDoc_NoteComment + //! attribute (derived ftom \ref XCAFDoc_Note). + //! \param [in] theUserName - the user associated with the note. + //! \param [in] theTimeStamp - timestamp of the note. + //! \param [in] theComment - textual comment. + //! \return a handle to the base note attribute. Standard_EXPORT Handle(XCAFDoc_Note) CreateComment(const TCollection_ExtendedString& theUserName, const TCollection_ExtendedString& theTimeStamp, const TCollection_ExtendedString& theComment); + //! Create a new note with data loaded from a binary file. + //! Creates a new label under the notes hive and attaches \ref XCAFDoc_NoteComment + //! attribute (derived ftom \ref XCAFDoc_Note). + //! \param [in] theUserName - the user associated with the note. + //! \param [in] theTimeStamp - timestamp of the note. + //! \param [in] theTitle - file title. + //! \param [in] theMIMEtype - MIME type of the file. + //! \param [in] theFile - input binary file. + //! \return a handle to the base note attribute. Standard_EXPORT Handle(XCAFDoc_Note) CreateBinData(const TCollection_ExtendedString& theUserName, const TCollection_ExtendedString& theTimeStamp, const TCollection_ExtendedString& theTitle, const TCollection_AsciiString& theMIMEtype, OSD_File& theFile); + //! Create a new note with data loaded from a byte data array. + //! Creates a new label under the notes hive and attaches \ref XCAFDoc_NoteComment + //! attribute (derived ftom \ref XCAFDoc_Note). + //! \param [in] theUserName - the user associated with the note. + //! \param [in] theTimeStamp - timestamp of the note. + //! \param [in] theTitle - data title. + //! \param [in] theMIMEtype - MIME type of the file. + //! \param [in] theData - byte data array. + //! \return a handle to the base note attribute. Standard_EXPORT Handle(XCAFDoc_Note) CreateBinData(const TCollection_ExtendedString& theUserName, const TCollection_ExtendedString& theTimeStamp, const TCollection_ExtendedString& theTitle, const TCollection_AsciiString& theMIMEtype, const Handle(TColStd_HArray1OfByte)& theData); + //! @} + + //! @name Get notes from annotated items functions + //! @{ + + //! Gets all note labels of the assembly item. + //! Notes linked to item's subshapes or attributes aren't + //! taken into account. The label sequence isn't cleared beforehand. + //! \param [in] theItemId - assembly item ID. + //! \param [out] theNoteLabels - sequence of labels. + //! \return number of added labels. Standard_EXPORT Standard_Integer GetNotes(const XCAFDoc_AssemblyItemId& theItemId, TDF_LabelSequence& theNoteLabels) const; + + //! Gets all note labels of the assembly item's attribute. + //! Notes linked to the item itself or to item's subshapes + //! taken into account. The label sequence isn't cleared beforehand. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theGUID - assembly item's attribute GUID. + //! \param [out] theNoteLabels - sequence of labels. + //! \return number of added labels. Standard_EXPORT Standard_Integer GetAttrNotes(const XCAFDoc_AssemblyItemId& theItemId, const Standard_GUID& theGUID, TDF_LabelSequence& theNoteLabels) const; + + //! Gets all note labels of the annotated item. + //! Notes linked to the item itself or to item's attributes + //! taken into account. The label sequence isn't cleared beforehand. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theSubshapeIndex - assembly item's subshape index. + //! \param [out] theNoteLabels - sequence of labels. + //! \return number of added labels. Standard_EXPORT Standard_Integer GetSubshapeNotes(const XCAFDoc_AssemblyItemId& theItemId, Standard_Integer theSubshapeIndex, TDF_LabelSequence& theNoteLabels) const; + //! @} + + //! @name Annotation functions + //! @{ + + //! Adds the given note to the assembly item. + //! \param [in] theNoteLabel - note label. + //! \param [in] theItemId - assembly item ID. + //! \return a handle to the assembly reference attribute. Standard_EXPORT Handle(XCAFDoc_AssemblyItemRef) AddNote(const TDF_Label& theNoteLabel, const XCAFDoc_AssemblyItemId& theItemId); + + //! Adds the given note to the assembly item's attribute. + //! \param [in] theNoteLabel - note label. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theGUID - assembly item's attribute GUID. + //! \return a handle to the assembly reference attribute. Standard_EXPORT Handle(XCAFDoc_AssemblyItemRef) AddNoteToAttr(const TDF_Label& theNoteLabel, const XCAFDoc_AssemblyItemId& theItemId, const Standard_GUID& theGUID); + + //! Adds the given note to the assembly item's subshape. + //! \param [in] theNoteLabel - note label. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theSubshapeIndex - assembly item's subshape index. + //! \return a handle to the assembly reference attribute. Standard_EXPORT Handle(XCAFDoc_AssemblyItemRef) AddNoteToSubshape(const TDF_Label& theNoteLabel, const XCAFDoc_AssemblyItemId& theItemId, Standard_Integer theSubshapeIndex); + //! @} + + //! @name Remove annotation functions + //! @{ + + //! Removes the given note from the assembly item. + //! \param [in] theNoteLabel - note label. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theDelIfOrphan - deletes the note from the notes hive + //! if there are no more assembly items + //! linked with the note. + //! \return true if the note is removed, otherwise - false. Standard_EXPORT Standard_Boolean RemoveNote(const TDF_Label& theNoteLabel, const XCAFDoc_AssemblyItemId& theItemId, Standard_Boolean theDelIfOrphan = Standard_False); + + //! Removes the given note from the assembly item's subshape. + //! \param [in] theNoteLabel - note label. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theSubshapeIndex - assembly item's subshape index. + //! \param [in] theDelIfOrphan - deletes the note from the notes hive + //! if there are no more assembly item's + //! subshape linked with the note. + //! \return true if the note is removed, otherwise - false. Standard_EXPORT Standard_Boolean RemoveSubshapeNote(const TDF_Label& theNoteLabel, const XCAFDoc_AssemblyItemId& theItemId, Standard_Integer theSubshapeIndex, Standard_Boolean theDelIfOrphan = Standard_False); + + //! Removes a note from the assembly item's attribute. + //! \param [in] theNoteLabel - note label. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theGUID - assembly item's attribute GUID. + //! \param [in] theDelIfOrphan - deletes the note from the notes hive + //! if there are no more assembly item's + //! attribute linked with the note. + //! \return true if the note is removed, otherwise - false. Standard_EXPORT Standard_Boolean RemoveAttrNote(const TDF_Label& theNoteLabel, const XCAFDoc_AssemblyItemId& theItemId, const Standard_GUID& theGUID, Standard_Boolean theDelIfOrphan = Standard_False); + + //! Removes all notes from the assembly item. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theDelIfOrphan - deletes removed notes from the notes + //! hive if there are no more annotated items + //! linked with the notes. + //! \return true if the notes are removed, otherwise - false. Standard_EXPORT Standard_Boolean RemoveAllNotes(const XCAFDoc_AssemblyItemId& theItemId, Standard_Boolean theDelIfOrphan = Standard_False); + + //! Removes all notes from the assembly item's subshape. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theSubshapeIndex - assembly item's subshape index. + //! \param [in] theDelIfOrphan - deletes removed notes from the notes + //! hive if there are no more annotated items + //! linked with the notes. + //! \return true if the notes are removed, otherwise - false. Standard_EXPORT Standard_Boolean RemoveAllSubshapeNotes(const XCAFDoc_AssemblyItemId& theItemId, Standard_Integer theSubshapeIndex, Standard_Boolean theDelIfOrphan = Standard_False); + + //! Removes all notes from the assembly item's attribute. + //! \param [in] theItemId - assembly item ID. + //! \param [in] theGUID - assembly item's attribute GUID. + //! \param [in] theDelIfOrphan - deletes removed notes from the notes + //! hive if there are no more annotated items + //! linked with the notes. + //! \return true if the notes are removed, otherwise - false. Standard_EXPORT Standard_Boolean RemoveAllAttrNotes(const XCAFDoc_AssemblyItemId& theItemId, const Standard_GUID& theGUID, Standard_Boolean theDelIfOrphan = Standard_False); + //! @} + + //! @name Delete note functions + //! @{ + + //! Deletes the given note. + //! Removes all links with items annotated by the note. + //! \param [in] theNoteLabel - note label. + //! \return true if the note is deleted, otherwise - false. Standard_EXPORT Standard_Boolean DeleteNote(const TDF_Label& theNoteLabel); + + //! Deletes the given notes. + //! Removes all links with items annotated by the notes. + //! \param [in] theNoteLabels - note label sequence. + //! \return number of deleted notes. Standard_EXPORT Standard_Integer DeleteNotes(TDF_LabelSequence& theNoteLabels); + + //! Deletes all notes. + //! Clears all annotations. + //! \return number of deleted notes. Standard_EXPORT Standard_Integer DeleteAllNotes(); + //! @} + + //! @name Orphan annotated items functions + //! @{ + + //! Returns number of notes that aren't linked to annotated items. Standard_EXPORT Standard_Integer NbOrphanNotes() const; + + //! Returns note labels that aren't linked to annotated items. + //! The label sequence isn't cleared beforehand. + //! \param [out] theNoteLabels - sequence of labels. Standard_EXPORT void GetOrphanNotes(TDF_LabelSequence& theNoteLabels) const; + + //! Deletes all notes that aren't linked to annotated items. + //! \return number of deleted notes. Standard_EXPORT Standard_Integer DeleteOrphanNotes(); + //! @} + public: - // Overrides TDF_Attribute pure virtuals + // Overrides TDF_Attribute virtuals Standard_EXPORT const Standard_GUID& ID() const Standard_OVERRIDE; Standard_EXPORT Handle(TDF_Attribute) NewEmpty() const Standard_OVERRIDE; Standard_EXPORT void Restore(const Handle(TDF_Attribute)& theAttrFrom) Standard_OVERRIDE;