42cf5bc1 |
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> |
25e59720 |
24 | #include <Standard_Transient.hxx> |
42cf5bc1 |
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; |
25e59720 |
46 | DEFINE_STANDARD_HANDLE(TDF_Attribute, Standard_Transient) |
42cf5bc1 |
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. |
25e59720 |
135 | class TDF_Attribute : public Standard_Transient |
42cf5bc1 |
136 | { |
137 | |
138 | public: |
139 | |
140 | |
141 | //! Returns the ID of the attribute. |
142 | Standard_EXPORT virtual const Standard_GUID& ID() const = 0; |
5a1271c8 |
143 | |
144 | //! Sets specific ID of the attribute (supports several attributes |
145 | //! of one type at the same label feature). |
0f57ab75 |
146 | virtual void SetID (const Standard_GUID& /*theGuid*/) {} |
5a1271c8 |
147 | |
148 | //! Sets default ID defined in nested class (to be used for attributes having User ID feature). |
0f57ab75 |
149 | virtual void SetID() {} |
5a1271c8 |
150 | |
42cf5bc1 |
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 | |
aa00364d |
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 | |
42cf5bc1 |
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 | |
bc73b006 |
375 | //! Dumps the content of me into the stream |
376 | Standard_EXPORT virtual void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const; |
377 | |
42cf5bc1 |
378 | |
379 | friend class TDF_Data; |
380 | friend class TDF_Label; |
381 | friend class TDF_LabelNode; |
382 | friend class TDF_AttributeIterator; |
383 | friend class TDF_DeltaOnForget; |
384 | |
385 | |
25e59720 |
386 | DEFINE_STANDARD_RTTIEXT(TDF_Attribute,Standard_Transient) |
42cf5bc1 |
387 | |
388 | protected: |
389 | |
390 | |
391 | //! Initializes fields. |
392 | Standard_EXPORT TDF_Attribute(); |
393 | |
394 | |
395 | |
396 | private: |
397 | |
398 | |
399 | //! Set the "Valid" status with <aStatus>. |
400 | void Validate (const Standard_Boolean aStatus); |
401 | |
402 | //! Resumes the attribute (undos Forget action). |
403 | Standard_EXPORT void Resume(); |
404 | |
405 | //! Set the "backuped" status with <aStatus>. |
406 | void Backup (const Standard_Boolean aStatus); |
407 | |
408 | //! Removes the last backup attribute, if it exists. |
409 | Standard_EXPORT void RemoveBackup(); |
410 | |
411 | TDF_LabelNodePtr myLabelNode; |
412 | Standard_Integer myTransaction; |
413 | Standard_Integer mySavedTransaction; |
414 | Standard_Integer myFlags; |
415 | Handle(TDF_Attribute) myNext; |
416 | Handle(TDF_Attribute) myBackup; |
417 | |
418 | |
419 | }; |
420 | |
421 | |
422 | #include <TDF_Attribute.lxx> |
423 | |
424 | |
425 | |
426 | |
427 | |
428 | #endif // _TDF_Attribute_HeaderFile |