0029590: Coding - avoid usage of Standard_EXPORT attribute for inline methods
[occt.git] / src / TDF / TDF_Attribute.hxx
1 // Created by: DAUTRY Philippe
2 // Copyright (c) 1997-1999 Matra Datavision
3 // Copyright (c) 1999-2014 OPEN CASCADE SAS
4 //
5 // This file is part of Open CASCADE Technology software library.
6 //
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.
12 //
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
15
16 #ifndef _TDF_Attribute_HeaderFile
17 #define _TDF_Attribute_HeaderFile
18
19 #include <Standard.hxx>
20 #include <Standard_Type.hxx>
21
22 #include <TDF_LabelNodePtr.hxx>
23 #include <Standard_Integer.hxx>
24 #include <Standard_Transient.hxx>
25 #include <Standard_Boolean.hxx>
26 #include <Standard_OStream.hxx>
27 #include <TDF_AttributeIndexedMap.hxx>
28 class Standard_DomainError;
29 class TDF_Data;
30 class TDF_Label;
31 class TDF_LabelNode;
32 class TDF_AttributeIterator;
33 class TDF_DeltaOnForget;
34 class Standard_GUID;
35 class TDF_AttributeDelta;
36 class TDF_DeltaOnAddition;
37 class TDF_DeltaOnResume;
38 class TDF_DeltaOnModification;
39 class TDF_DeltaOnRemoval;
40 class TDF_RelocationTable;
41 class TDF_DataSet;
42 class TDF_IDFilter;
43
44
45 class TDF_Attribute;
46 DEFINE_STANDARD_HANDLE(TDF_Attribute, Standard_Transient)
47
48 //! A class each application has to implement. It is
49 //! used to contain the application data.
50 //! This abstract class, alongwith Label,
51 //! is one of the cornerstones of Model Editor.
52 //! The groundwork is to define the root of
53 //! information. This information is to be
54 //! attached to a Label, and could be of any of
55 //! the following types:
56 //! -   a feature
57 //! -   a constraint
58 //! -   a comment
59 //!
60 //! Contents:
61 //! ---------
62 //!
63 //! Each software component who'd like to attach its
64 //! own information to a label has to inherit from
65 //! this class and has to add its own information as
66 //! fields of this new class.
67 //!
68 //! Identification:
69 //! ---------------
70 //!
71 //! An attribute can be identified by its ID. Every
72 //! attributes used with the same meaning (for
73 //! exemple: Integer, String, Topology...) have the
74 //! same worldwide unique ID.
75 //!
76 //! Addition:
77 //! ---------
78 //!
79 //! An attribute can be added to a label only if there
80 //! is no attribute yet with the same ID. Call-back
81 //! methods are offered, called automatically before
82 //! and after the addition action.
83 //!
84 //! Removal:
85 //! --------
86 //!
87 //! An attribute can be removed from a label only if
88 //! there is an attribute yet with the same
89 //! ID. Call-back methods are offered, called
90 //! automatically before and after the removal
91 //! action. A removed attribute cannot be found
92 //! again. After a removal, only an addition of an
93 //! attribute with the sane ID is possible (no
94 //! backup...).
95 //!
96 //! Modification & Transaction:
97 //! ---------------------------
98 //!
99 //! An attribute can be backuped before a
100 //! modification. Only one backup attribute by
101 //! transaction is possible. The modification can be
102 //! forgotten (abort transaction) or validated (commit
103 //! transaction).
104 //!
105 //! BackupCopy and restore are methods used by the backup or
106 //! abort transaction actions. BackupCopy is called by
107 //! Backup to generate an attribute with the same
108 //! contents as the current one. Restore is called
109 //! when aborting a transaction to transfer the
110 //! backuped contents into the current
111 //! attribute. These methods must be implemented by
112 //! end use inheriting classes.
113 //!
114 //! A standard implementation of BackupCopy is provided, but
115 //! it is not necessary a good one for any use.
116 //!
117 //! Copy use methods:
118 //! -----------------
119 //!
120 //! Paste and NewEmpty methods are used by the copy
121 //! algorithms. The goal of "Paste" is to transfer an
122 //! attribute new contents into another attribute. The
123 //! goal of "NewEmpty" is to create an attribute
124 //! whithout contents, to be further filled with the
125 //! new contents of another one. These 2 methods must
126 //! be implemented by end use inheriting classes.
127 //!
128 //! AttributeDelta:
129 //! ---------------
130 //!
131 //! An AttributeDelta is the difference between to
132 //! attribute values states.  These methods must be
133 //! implemented by end use inheriting classes, to
134 //! profit from the delta services.
135 class TDF_Attribute : public Standard_Transient
136 {
137
138 public:
139
140   
141   //! Returns the ID of the attribute.
142   Standard_EXPORT virtual const Standard_GUID& ID() const = 0;
143
144   //! Sets specific ID of the attribute (supports several attributes 
145   //! of one type at the same label feature).
146   virtual void SetID (const Standard_GUID& /*theGuid*/) {}
147
148   //! Sets default ID defined in nested class (to be used for attributes having User ID feature).
149   virtual void SetID() {}
150
151   //! Returns   the   label to which  the   attribute is
152   //! attached. If the  label is not  included in a  DF,
153   //! the label is null. See Label.
154   //! Warning
155   //! If the label is not included in a data
156   //! framework, it is null.
157   //! This function should not be redefined inline.
158   Standard_EXPORT const TDF_Label Label() const;
159   
160   //! Returns the transaction index in which the
161   //! attribute has been created or modified.
162     Standard_Integer Transaction() const;
163   
164   //! Returns the upper transaction index until which
165   //! the attribute is/was valid. This number may
166   //! vary. A removed attribute validity range is
167   //! reduced to its transaction index.
168   Standard_EXPORT Standard_Integer UntilTransaction() const;
169   
170   //! Returns true if the attribute is valid; i.e. not a
171   //! backuped or removed one.
172     Standard_Boolean IsValid() const;
173   
174   //! Returns true if the attribute has no backup
175     Standard_Boolean IsNew() const;
176   
177   //! Returns true if the attribute forgotten status is
178   //! set.
179   //!
180   //! ShortCut Methods concerning associated attributes
181   //! =================================================
182     Standard_Boolean IsForgotten() const;
183   
184   //! Returns true if it  exists an associated attribute
185   //! of <me> with <anID> as ID.
186   Standard_EXPORT Standard_Boolean IsAttribute (const Standard_GUID& anID) const;
187   
188   //! Finds an associated  attribute of  <me>, according
189   //! to <anID>.  the returned <anAttribute> is a  valid
190   //! one. The  method  returns  True if   found,  False
191   //! otherwise.   A removed attribute  cannot be found using
192   //! this  method.
193   Standard_EXPORT Standard_Boolean FindAttribute (const Standard_GUID& anID, Handle(TDF_Attribute)& anAttribute) const;
194   
195   //! Safe variant for arbitrary type of argument
196   template <class T> 
197   Standard_Boolean FindAttribute (const Standard_GUID& theID, Handle(T)& theAttr) const
198   {
199     Handle(TDF_Attribute) anAttr = theAttr;
200     return FindAttribute (theID, anAttr) && ! (theAttr = Handle(T)::DownCast(anAttr)).IsNull();
201   }
202
203   //! Adds   an   Attribute <other>  to  the   label  of
204   //! <me>.Raises if there is  already  one of the same
205   //! GUID fhan <other>.
206   Standard_EXPORT void AddAttribute (const Handle(TDF_Attribute)& other) const;
207   
208   //! Forgets  the Attribute of  GUID <aguid> associated
209   //! to the label of <me>. Be  carefull that if <me> is
210   //! the attribute of <guid>, <me> will have a null label
211   //! after this call.  If  the attribute doesn't  exist
212   //! returns False. Otherwise returns True.
213   Standard_EXPORT Standard_Boolean ForgetAttribute (const Standard_GUID& aguid) const;
214   
215   //! Forgets all the  attributes attached to  the label
216   //! of <me>.    Does   it   on  the  sub-labels   if
217   //! <clearChildren> is set  to true.  Of  course, this
218   //! method  is  compatible with Transaction  &  Delta
219   //! mecanisms. Be carefull  that  if <me> will have a
220   //! null label after this call
221   Standard_EXPORT void ForgetAllAttributes (const Standard_Boolean clearChildren = Standard_True) const;
222   
223   //! Something to do after adding an Attribute to a label.
224   Standard_EXPORT virtual void AfterAddition();
225   
226   //! Something to do before removing an Attribute from
227   //! a label.
228   Standard_EXPORT virtual void BeforeRemoval();
229   
230   //! Something to do before forgetting an Attribute to a
231   //! label.
232   Standard_EXPORT virtual void BeforeForget();
233   
234   //! Something to do after resuming an Attribute from
235   //! a label.
236   Standard_EXPORT virtual void AfterResume();
237   
238   //! Something to do AFTER creation of an attribute by
239   //! persistent-transient translation. The returned
240   //! status says if AfterUndo has been performed (true)
241   //! or if this callback must be called once again
242   //! further (false). If <forceIt> is set to true, the
243   //! method MUST perform and return true. Does nothing
244   //! by default and returns true.
245   Standard_EXPORT virtual Standard_Boolean AfterRetrieval (const Standard_Boolean forceIt = Standard_False);
246   
247   //! Something to do before applying <anAttDelta>. The
248   //! returned status says if AfterUndo has been
249   //! performed (true) or if this callback must be
250   //! called once again further (false). If <forceIt> is
251   //! set to true, the method MUST perform and return
252   //! true. Does nothing by default and returns true.
253   Standard_EXPORT virtual Standard_Boolean BeforeUndo (const Handle(TDF_AttributeDelta)& anAttDelta, const Standard_Boolean forceIt = Standard_False);
254   
255   //! Something to do after applying <anAttDelta>. The
256   //! returned status says if AfterUndo has been
257   //! performed (true) or if this callback must be
258   //! called once again further (false). If <forceIt> is
259   //! set to true, the method MUST perform and return
260   //! true. Does nothing by default and returns true.
261   Standard_EXPORT virtual Standard_Boolean AfterUndo (const Handle(TDF_AttributeDelta)& anAttDelta, const Standard_Boolean forceIt = Standard_False);
262   
263   //! A callback.
264   //! By default does nothing.
265   //! It is called by TDF_Data::CommitTransaction() method.
266   Standard_EXPORT virtual void BeforeCommitTransaction();
267   
268   //! Backups the attribute. The backuped attribute is
269   //! flagged "Backuped" and not "Valid".
270   //!
271   //! The method does nothing:
272   //!
273   //! 1) If the attribute transaction number is equal to
274   //! the current transaction number (the attribute has
275   //! already been backuped).
276   //!
277   //! 2) If the attribute is not attached to a label.
278   Standard_EXPORT void Backup();
279   
280   //! Returns true if the attribute backup status is
281   //! set. This status is set/unset by the
282   //! Backup() method.
283     Standard_Boolean IsBackuped() const;
284   
285   //! Copies  the attribute  contents into  a  new other
286   //! attribute. It is used by Backup().
287   Standard_EXPORT virtual Handle(TDF_Attribute) BackupCopy() const;
288   
289   //! Restores the backuped contents from <anAttribute>
290   //! into this one. It is used when aborting a
291   //! transaction.
292   Standard_EXPORT virtual void Restore (const Handle(TDF_Attribute)& anAttribute) = 0;
293   
294   //! Makes an AttributeDelta because <me>
295   //! appeared. The only known use of a redefinition of
296   //! this method is to return a null handle (no delta).
297   Standard_EXPORT virtual Handle(TDF_DeltaOnAddition) DeltaOnAddition() const;
298   
299   //! Makes an AttributeDelta because <me> has been
300   //! forgotten.
301   Standard_EXPORT virtual Handle(TDF_DeltaOnForget) DeltaOnForget() const;
302   
303   //! Makes an AttributeDelta because <me> has been
304   //! resumed.
305   Standard_EXPORT virtual Handle(TDF_DeltaOnResume) DeltaOnResume() const;
306   
307   //! Makes a DeltaOnModification between <me> and
308   //! <anOldAttribute.
309   Standard_EXPORT virtual Handle(TDF_DeltaOnModification) DeltaOnModification (const Handle(TDF_Attribute)& anOldAttribute) const;
310   
311   //! Applies a DeltaOnModification to <me>.
312   Standard_EXPORT virtual void DeltaOnModification (const Handle(TDF_DeltaOnModification)& aDelta);
313   
314   //! Makes a DeltaOnRemoval on <me> because <me> has
315   //! disappeared from the DS.
316   Standard_EXPORT virtual Handle(TDF_DeltaOnRemoval) DeltaOnRemoval() const;
317   
318   //! Returns an new empty attribute from the good end
319   //! type. It is used by the copy algorithm.
320   Standard_EXPORT virtual Handle(TDF_Attribute) NewEmpty() const = 0;
321   
322   //! This method is different from the "Copy" one,
323   //! because it is used when copying an attribute from
324   //! a source structure into a target structure. This
325   //! method may paste the contents of <me> into
326   //! <intoAttribute>.
327   //!
328   //! The given pasted attribute can be full or empty of
329   //! its contents. But don't make a NEW! Just set the
330   //! contents!
331   //!
332   //! It is possible to use <aRelocationTable> to
333   //! get/set the relocation value of a source
334   //! attribute.
335   Standard_EXPORT virtual void Paste (const Handle(TDF_Attribute)& intoAttribute, const Handle(TDF_RelocationTable)& aRelocationTable) const = 0;
336   
337   //! Adds the first level referenced attributes and labels
338   //! to <aDataSet>.
339   //!
340   //! For this, use the AddLabel or AddAttribute of
341   //! DataSet.
342   //!
343   //! If there is none, do not implement the method.
344   Standard_EXPORT virtual void References (const Handle(TDF_DataSet)& aDataSet) const;
345   
346   //! Dumps the minimum information about <me> on
347   //! <aStream>.
348   Standard_EXPORT virtual Standard_OStream& Dump (Standard_OStream& anOS) const;
349 Standard_OStream& operator<< (Standard_OStream& anOS) const
350 {
351   return Dump(anOS);
352 }
353   
354   //! Dumps the attribute content on <aStream>, using
355   //! <aMap> like this: if an attribute is not in the
356   //! map, first put add it to the map and then dump it.
357   //! Use the map rank instead of dumping each attribute
358   //! field.
359   Standard_EXPORT virtual void ExtendedDump (Standard_OStream& anOS, const TDF_IDFilter& aFilter, TDF_AttributeIndexedMap& aMap) const;
360   
361   //! Forgets the attribute. <aTransaction> is the
362   //! current transaction in which the forget is done. A
363   //! forgotten attribute is also flagged not "Valid".
364   //!
365   //! A forgotten attribute is invisible. Set also the
366   //! "Valid" status to False. Obvioulsy, DF cannot
367   //! empty an attribute (this has a semantic
368   //! signification), but can remove it from the
369   //! structure. So, a forgotten attribute is NOT an empty
370   //! one, but a soon DEAD one.
371   //!
372   //! Should be private.
373   Standard_EXPORT void Forget (const Standard_Integer aTransaction);
374
375
376 friend class TDF_Data;
377 friend class TDF_Label;
378 friend class TDF_LabelNode;
379 friend class TDF_AttributeIterator;
380 friend class TDF_DeltaOnForget;
381
382
383   DEFINE_STANDARD_RTTIEXT(TDF_Attribute,Standard_Transient)
384
385 protected:
386
387   
388   //! Initializes fields.
389   Standard_EXPORT TDF_Attribute();
390
391
392
393 private:
394
395   
396   //! Set the "Valid" status with <aStatus>.
397     void Validate (const Standard_Boolean aStatus);
398   
399   //! Resumes the attribute (undos Forget action).
400   Standard_EXPORT void Resume();
401   
402   //! Set the "backuped" status with <aStatus>.
403     void Backup (const Standard_Boolean aStatus);
404   
405   //! Removes the last backup attribute, if it exists.
406   Standard_EXPORT void RemoveBackup();
407
408   TDF_LabelNodePtr myLabelNode;
409   Standard_Integer myTransaction;
410   Standard_Integer mySavedTransaction;
411   Standard_Integer myFlags;
412   Handle(TDF_Attribute) myNext;
413   Handle(TDF_Attribute) myBackup;
414
415
416 };
417
418
419 #include <TDF_Attribute.lxx>
420
421
422
423
424
425 #endif // _TDF_Attribute_HeaderFile