1 // Created by: DAUTRY Philippe
2 // Copyright (c) 1997-1999 Matra Datavision
3 // Copyright (c) 1999-2014 OPEN CASCADE SAS
5 // This file is part of Open CASCADE Technology software library.
7 // This library is free software; you can redistribute it and/or modify it under
8 // the terms of the GNU Lesser General Public License version 2.1 as published
9 // by the Free Software Foundation, with special exception defined in the file
10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
11 // distribution for complete text of the license and disclaimer of any warranty.
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
16 #ifndef _TDF_Attribute_HeaderFile
17 #define _TDF_Attribute_HeaderFile
19 #include <Standard.hxx>
20 #include <Standard_Type.hxx>
22 #include <TDF_LabelNodePtr.hxx>
23 #include <Standard_Integer.hxx>
24 #include <Standard_Transient.hxx>
25 #include <Standard_OStream.hxx>
26 #include <TDF_AttributeIndexedMap.hxx>
28 class TDF_DeltaOnForget;
30 class TDF_AttributeDelta;
31 class TDF_DeltaOnAddition;
32 class TDF_DeltaOnResume;
33 class TDF_DeltaOnModification;
34 class TDF_DeltaOnRemoval;
35 class TDF_RelocationTable;
41 DEFINE_STANDARD_HANDLE(TDF_Attribute, Standard_Transient)
43 //! A class each application has to implement. It is
44 //! used to contain the application data.
45 //! This abstract class, alongwith Label,
46 //! is one of the cornerstones of Model Editor.
47 //! The groundwork is to define the root of
48 //! information. This information is to be
49 //! attached to a Label, and could be of any of
50 //! the following types:
58 //! Each software component who'd like to attach its
59 //! own information to a label has to inherit from
60 //! this class and has to add its own information as
61 //! fields of this new class.
66 //! An attribute can be identified by its ID. Every
67 //! attributes used with the same meaning (for
68 //! example: Integer, String, Topology...) have the
69 //! same worldwide unique ID.
74 //! An attribute can be added to a label only if there
75 //! is no attribute yet with the same ID. Call-back
76 //! methods are offered, called automatically before
77 //! and after the addition action.
82 //! An attribute can be removed from a label only if
83 //! there is an attribute yet with the same
84 //! ID. Call-back methods are offered, called
85 //! automatically before and after the removal
86 //! action. A removed attribute cannot be found
87 //! again. After a removal, only an addition of an
88 //! attribute with the sane ID is possible (no
91 //! Modification & Transaction:
92 //! ---------------------------
94 //! An attribute can be backuped before a
95 //! modification. Only one backup attribute by
96 //! transaction is possible. The modification can be
97 //! forgotten (abort transaction) or validated (commit
100 //! BackupCopy and restore are methods used by the backup or
101 //! abort transaction actions. BackupCopy is called by
102 //! Backup to generate an attribute with the same
103 //! contents as the current one. Restore is called
104 //! when aborting a transaction to transfer the
105 //! backuped contents into the current
106 //! attribute. These methods must be implemented by
107 //! end use inheriting classes.
109 //! A standard implementation of BackupCopy is provided, but
110 //! it is not necessary a good one for any use.
112 //! Copy use methods:
113 //! -----------------
115 //! Paste and NewEmpty methods are used by the copy
116 //! algorithms. The goal of "Paste" is to transfer an
117 //! attribute new contents into another attribute. The
118 //! goal of "NewEmpty" is to create an attribute
119 //! without contents, to be further filled with the
120 //! new contents of another one. These 2 methods must
121 //! be implemented by end use inheriting classes.
126 //! An AttributeDelta is the difference between to
127 //! attribute values states. These methods must be
128 //! implemented by end use inheriting classes, to
129 //! profit from the delta services.
130 class TDF_Attribute : public Standard_Transient
136 //! Returns the ID of the attribute.
137 Standard_EXPORT virtual const Standard_GUID& ID() const = 0;
139 //! Sets specific ID of the attribute (supports several attributes
140 //! of one type at the same label feature).
141 virtual void SetID (const Standard_GUID& /*theGuid*/) {}
143 //! Sets default ID defined in nested class (to be used for attributes having User ID feature).
144 virtual void SetID() {}
146 //! Returns the label to which the attribute is
147 //! attached. If the label is not included in a DF,
148 //! the label is null. See Label.
150 //! If the label is not included in a data
151 //! framework, it is null.
152 //! This function should not be redefined inline.
153 Standard_EXPORT const TDF_Label Label() const;
155 //! Returns the transaction index in which the
156 //! attribute has been created or modified.
157 Standard_Integer Transaction() const;
159 //! Returns the upper transaction index until which
160 //! the attribute is/was valid. This number may
161 //! vary. A removed attribute validity range is
162 //! reduced to its transaction index.
163 Standard_EXPORT Standard_Integer UntilTransaction() const;
165 //! Returns true if the attribute is valid; i.e. not a
166 //! backuped or removed one.
167 Standard_Boolean IsValid() const;
169 //! Returns true if the attribute has no backup
170 Standard_Boolean IsNew() const;
172 //! Returns true if the attribute forgotten status is
175 //! ShortCut Methods concerning associated attributes
176 //! =================================================
177 Standard_Boolean IsForgotten() const;
179 //! Returns true if it exists an associated attribute
180 //! of <me> with <anID> as ID.
181 Standard_EXPORT Standard_Boolean IsAttribute (const Standard_GUID& anID) const;
183 //! Finds an associated attribute of <me>, according
184 //! to <anID>. the returned <anAttribute> is a valid
185 //! one. The method returns True if found, False
186 //! otherwise. A removed attribute cannot be found using
188 Standard_EXPORT Standard_Boolean FindAttribute (const Standard_GUID& anID, Handle(TDF_Attribute)& anAttribute) const;
190 //! Safe variant for arbitrary type of argument
192 Standard_Boolean FindAttribute (const Standard_GUID& theID, Handle(T)& theAttr) const
194 Handle(TDF_Attribute) anAttr = theAttr;
195 return FindAttribute (theID, anAttr) && ! (theAttr = Handle(T)::DownCast(anAttr)).IsNull();
198 //! Adds an Attribute <other> to the label of
199 //! <me>.Raises if there is already one of the same
200 //! GUID fhan <other>.
201 Standard_EXPORT void AddAttribute (const Handle(TDF_Attribute)& other) const;
203 //! Forgets the Attribute of GUID <aguid> associated
204 //! to the label of <me>. Be careful that if <me> is
205 //! the attribute of <guid>, <me> will have a null label
206 //! after this call. If the attribute doesn't exist
207 //! returns False. Otherwise returns True.
208 Standard_EXPORT Standard_Boolean ForgetAttribute (const Standard_GUID& aguid) const;
210 //! Forgets all the attributes attached to the label
211 //! of <me>. Does it on the sub-labels if
212 //! <clearChildren> is set to true. Of course, this
213 //! method is compatible with Transaction & Delta
214 //! mechanisms. Be careful that if <me> will have a
215 //! null label after this call
216 Standard_EXPORT void ForgetAllAttributes (const Standard_Boolean clearChildren = Standard_True) const;
218 //! Something to do after adding an Attribute to a label.
219 Standard_EXPORT virtual void AfterAddition();
221 //! Something to do before removing an Attribute from
223 Standard_EXPORT virtual void BeforeRemoval();
225 //! Something to do before forgetting an Attribute to a
227 Standard_EXPORT virtual void BeforeForget();
229 //! Something to do after resuming an Attribute from
231 Standard_EXPORT virtual void AfterResume();
233 //! Something to do AFTER creation of an attribute by
234 //! persistent-transient translation. The returned
235 //! status says if AfterUndo has been performed (true)
236 //! or if this callback must be called once again
237 //! further (false). If <forceIt> is set to true, the
238 //! method MUST perform and return true. Does nothing
239 //! by default and returns true.
240 Standard_EXPORT virtual Standard_Boolean AfterRetrieval (const Standard_Boolean forceIt = Standard_False);
242 //! Something to do before applying <anAttDelta>. The
243 //! returned status says if AfterUndo has been
244 //! performed (true) or if this callback must be
245 //! called once again further (false). If <forceIt> is
246 //! set to true, the method MUST perform and return
247 //! true. Does nothing by default and returns true.
248 Standard_EXPORT virtual Standard_Boolean BeforeUndo (const Handle(TDF_AttributeDelta)& anAttDelta, const Standard_Boolean forceIt = Standard_False);
250 //! Something to do after applying <anAttDelta>. The
251 //! returned status says if AfterUndo has been
252 //! performed (true) or if this callback must be
253 //! called once again further (false). If <forceIt> is
254 //! set to true, the method MUST perform and return
255 //! true. Does nothing by default and returns true.
256 Standard_EXPORT virtual Standard_Boolean AfterUndo (const Handle(TDF_AttributeDelta)& anAttDelta, const Standard_Boolean forceIt = Standard_False);
259 //! By default does nothing.
260 //! It is called by TDF_Data::CommitTransaction() method.
261 Standard_EXPORT virtual void BeforeCommitTransaction();
263 //! Backups the attribute. The backuped attribute is
264 //! flagged "Backuped" and not "Valid".
266 //! The method does nothing:
268 //! 1) If the attribute transaction number is equal to
269 //! the current transaction number (the attribute has
270 //! already been backuped).
272 //! 2) If the attribute is not attached to a label.
273 Standard_EXPORT void Backup();
275 //! Returns true if the attribute backup status is
276 //! set. This status is set/unset by the
278 Standard_Boolean IsBackuped() const;
280 //! Copies the attribute contents into a new other
281 //! attribute. It is used by Backup().
282 Standard_EXPORT virtual Handle(TDF_Attribute) BackupCopy() const;
284 //! Restores the backuped contents from <anAttribute>
285 //! into this one. It is used when aborting a
287 Standard_EXPORT virtual void Restore (const Handle(TDF_Attribute)& anAttribute) = 0;
289 //! Makes an AttributeDelta because <me>
290 //! appeared. The only known use of a redefinition of
291 //! this method is to return a null handle (no delta).
292 Standard_EXPORT virtual Handle(TDF_DeltaOnAddition) DeltaOnAddition() const;
294 //! Makes an AttributeDelta because <me> has been
296 Standard_EXPORT virtual Handle(TDF_DeltaOnForget) DeltaOnForget() const;
298 //! Makes an AttributeDelta because <me> has been
300 Standard_EXPORT virtual Handle(TDF_DeltaOnResume) DeltaOnResume() const;
302 //! Makes a DeltaOnModification between <me> and
304 Standard_EXPORT virtual Handle(TDF_DeltaOnModification) DeltaOnModification (const Handle(TDF_Attribute)& anOldAttribute) const;
306 //! Applies a DeltaOnModification to <me>.
307 Standard_EXPORT virtual void DeltaOnModification (const Handle(TDF_DeltaOnModification)& aDelta);
309 //! Makes a DeltaOnRemoval on <me> because <me> has
310 //! disappeared from the DS.
311 Standard_EXPORT virtual Handle(TDF_DeltaOnRemoval) DeltaOnRemoval() const;
313 //! Returns an new empty attribute from the good end
314 //! type. It is used by the copy algorithm.
315 Standard_EXPORT virtual Handle(TDF_Attribute) NewEmpty() const = 0;
317 //! This method is different from the "Copy" one,
318 //! because it is used when copying an attribute from
319 //! a source structure into a target structure. This
320 //! method may paste the contents of <me> into
323 //! The given pasted attribute can be full or empty of
324 //! its contents. But don't make a NEW! Just set the
327 //! It is possible to use <aRelocationTable> to
328 //! get/set the relocation value of a source
330 Standard_EXPORT virtual void Paste (const Handle(TDF_Attribute)& intoAttribute, const Handle(TDF_RelocationTable)& aRelocationTable) const = 0;
332 //! Adds the first level referenced attributes and labels
335 //! For this, use the AddLabel or AddAttribute of
338 //! If there is none, do not implement the method.
339 Standard_EXPORT virtual void References (const Handle(TDF_DataSet)& aDataSet) const;
341 //! Dumps the minimum information about <me> on
343 Standard_EXPORT virtual Standard_OStream& Dump (Standard_OStream& anOS) const;
344 Standard_OStream& operator<< (Standard_OStream& anOS) const
349 //! Dumps the attribute content on <aStream>, using
350 //! <aMap> like this: if an attribute is not in the
351 //! map, first put add it to the map and then dump it.
352 //! Use the map rank instead of dumping each attribute
354 Standard_EXPORT virtual void ExtendedDump (Standard_OStream& anOS, const TDF_IDFilter& aFilter, TDF_AttributeIndexedMap& aMap) const;
356 //! Forgets the attribute. <aTransaction> is the
357 //! current transaction in which the forget is done. A
358 //! forgotten attribute is also flagged not "Valid".
360 //! A forgotten attribute is invisible. Set also the
361 //! "Valid" status to False. Obvioulsy, DF cannot
362 //! empty an attribute (this has a semantic
363 //! signification), but can remove it from the
364 //! structure. So, a forgotten attribute is NOT an empty
365 //! one, but a soon DEAD one.
367 //! Should be private.
368 Standard_EXPORT void Forget (const Standard_Integer aTransaction);
370 //! Dumps the content of me into the stream
371 Standard_EXPORT virtual void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
374 friend class TDF_Data;
375 friend class TDF_Label;
376 friend class TDF_LabelNode;
377 friend class TDF_AttributeIterator;
378 friend class TDF_DeltaOnForget;
381 DEFINE_STANDARD_RTTIEXT(TDF_Attribute,Standard_Transient)
386 //! Initializes fields.
387 Standard_EXPORT TDF_Attribute();
394 //! Set the "Valid" status with <aStatus>.
395 void Validate (const Standard_Boolean aStatus);
397 //! Resumes the attribute (undos Forget action).
398 Standard_EXPORT void Resume();
400 //! Set the "backuped" status with <aStatus>.
401 void Backup (const Standard_Boolean aStatus);
403 //! Removes the last backup attribute, if it exists.
404 Standard_EXPORT void RemoveBackup();
406 TDF_LabelNodePtr myLabelNode;
407 Standard_Integer myTransaction;
408 Standard_Integer mySavedTransaction;
409 Standard_Integer myFlags;
410 Handle(TDF_Attribute) myNext;
411 Handle(TDF_Attribute) myBackup;
417 #include <TDF_Attribute.lxx>
423 #endif // _TDF_Attribute_HeaderFile