1 // Created on: 2004-11-22
2 // Created by: Pavel TELKOV
3 // Copyright (c) 2004-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 // The original implementation Copyright: (C) RINA S.p.A
18 #ifndef TObj_Object_HeaderFile
19 #define TObj_Object_HeaderFile
21 #include <TObj_Common.hxx>
22 #include <TObj_DeletingMode.hxx>
23 #include <TObj_SequenceOfObject.hxx>
24 #include <Handle_TObj_Model.hxx>
25 #include <Handle_TObj_Object.hxx>
27 #include <TDF_Label.hxx>
30 class TObj_Persistence;
31 class Handle(TObj_ObjectIterator);
32 class Handle(TObj_TNameContainer);
34 class Handle(TCollection_HAsciiString);
35 class Handle(TCollection_HExtendedString);
36 class Handle(TColStd_HArray1OfReal);
37 class Handle(TColStd_HArray1OfInteger);
38 class Handle(TColStd_HArray1OfExtendedString);
40 //! Basis class for transient objects in OCAF-based models
42 class TObj_Object : public MMgt_TShared
45 enum TypeFlags //!< Flags that define type-specific behaviour of objects
47 Visible = 0x0001 //!< Is visible in DataViewer
50 //! enumeration describing various object state bit flags (see Set/GetFlags())
53 ObjectState_Hidden = 0x0001, //!< object is hidden in tree browser
54 ObjectState_Saved = 0x0002, //!< object has (or should have)
55 //!< corresponding saved file on disk
56 ObjectState_Imported = 0x0004, //!< object's data are just imported from somewhere
57 ObjectState_ImportedByFile = 0x0008, //!< a model imported by file may need a
58 //!< sophisticated update of external references
59 ObjectState_Ordered = 0x0010 //!< flag that partition contains ordered objects
64 //! enumeration for the ranks of label under Data section.
68 DataTag_Flags, //!< stores flags of object
69 DataTag_Order, //!< stores order of object
70 DataTag_Last = DataTag_First + 100 //!< Reserved for possible future use
73 //! enumeration for the ranks of label under Child section.
77 ChildTag_Last = ChildTag_First //!< No children
80 //! enumeration for the ranks of label under Reference section.
84 RefTag_Last = RefTag_First //!< No children
92 //! Constructor of a new object interface: requires label,
93 //! which should be one of the labels in model's data structure.
94 //! This creates a new object and attaches it to a given label.
95 //! The initialisation of the object's data and their integrity is
96 //! to be ensured by implementations and by persistence mechanism.
97 //! If the flag theSetName is true (default) the object is assign the default name
98 //! that is generated using the father partition object if any.
99 Standard_EXPORT TObj_Object (const TDF_Label& theLabel,
100 const Standard_Boolean theSetName = Standard_True);
102 //! The special constructor intended for implementation of persistence
103 //! mechanism. See class TObj_Persistence for more details.
104 //! The first argument is used only to avoid confusion with
105 //! other constructors.
106 Standard_EXPORT TObj_Object (const TObj_Persistence *,
107 const TDF_Label& theLabel)
108 : myLabel(theLabel) {}
110 //! This method is called from persistence to initialize the object fields,
111 //! so successors that have transient fields must initialize them in initFields(),
112 //! and call the same method of parent.
120 //! Returns the model to which the object belongs
121 virtual Standard_EXPORT Handle(TObj_Model) GetModel () const;
123 //! Returns iterator for the child objects.
124 //! This method provides tree-like view of the objects hierarchy.
125 //! The references to other objects are not considered as children.
126 //! theType narrows a variety of iterated objects
127 //! The default implementation search for children on 1 sublavel
128 //! of the children sub label
129 virtual Standard_EXPORT Handle(TObj_ObjectIterator) GetChildren
130 (const Handle(Standard_Type)& theType = NULL) const;
132 //! Returns the label under which children are stored
133 Standard_EXPORT TDF_Label GetChildLabel() const;
135 //! Returns the label for child with rank
136 Standard_EXPORT TDF_Label getChildLabel(const Standard_Integer theRank) const;
140 * Access to the OCAF-specific data
143 //! Returns the OCAF label on which object`s data are stored
144 Standard_EXPORT TDF_Label GetLabel() const;
146 //! Returns the label which is the root for data OCAF sub-tree
147 Standard_EXPORT TDF_Label GetDataLabel() const;
149 //! Returns the label which is the root for reference OCAF sub-tree
150 Standard_EXPORT TDF_Label GetReferenceLabel() const;
154 * Methods hanling name of the object
157 //! Returns the map of names of the objects
158 //! Default implementation returns global Dictionary of the model
159 virtual Standard_EXPORT Handle(TObj_TNameContainer) GetDictionary() const;
161 //! Returns the name of the object (empty string if object has no name)
162 virtual Standard_EXPORT Handle(TCollection_HExtendedString) GetName() const;
164 //! Returns the Standard_True is object has name and returns name to theName
165 Standard_EXPORT Standard_Boolean GetName
166 (TCollection_ExtendedString& theName) const;
168 //! Returns the Standard_True is object has name and returns name to theName
169 Standard_EXPORT Standard_Boolean GetName
170 (TCollection_AsciiString& theName) const;
172 //! Sets name of the object. Returns False if theName is not unique.
173 virtual Standard_EXPORT Standard_Boolean SetName
174 (const Handle(TCollection_HExtendedString)& theName) const;
176 //! Sets name of the object. Returns False if theName is not unique.
177 Standard_EXPORT Standard_Boolean SetName
178 (const Handle(TCollection_HAsciiString)& theName) const;
180 //! Sets name of the object. Returns False if theName is not unique.
181 Standard_EXPORT Standard_Boolean SetName (const Standard_CString name) const;
183 //! Returns name for copy
184 //! default implementation returns the same name
185 virtual Standard_EXPORT Handle(TCollection_HExtendedString) GetNameForClone
186 ( const Handle(TObj_Object)& ) const
187 { return GetName(); }
191 * Analysis of dependencies on other objects
194 //! Returns True if object has reference to indicated object
195 virtual Standard_EXPORT Standard_Boolean HasReference
196 (const Handle(TObj_Object)& theObject) const;
198 //! Returns an Iterator containing objects that compose the this one
199 //! theType narrows a variety of iterated objects
200 virtual Standard_EXPORT Handle(TObj_ObjectIterator) GetReferences
201 (const Handle(Standard_Type)& theType = NULL) const;
203 //! Remove all references to other objects, by removing all reference attributes
204 virtual Standard_EXPORT void RemoveAllReferences();
206 //! Returns iterator for the objects which depend on this one.
207 //! These reffering objects may belong to other models.
208 //! theType narrows a variety of iterated objects
209 virtual Standard_EXPORT Handle(TObj_ObjectIterator) GetBackReferences
210 (const Handle(Standard_Type)& theType = NULL) const;
212 //! Registers another object as being dependent on this one.
213 //! Stores back references under sublabel 2 (purely transient data,
214 //! not subject to persistency).
215 virtual Standard_EXPORT void AddBackReference
216 (const Handle(TObj_Object)& theObject);
218 //! Removes information on dependent object (back reference).
219 //! If theSingleOnly is true only the first back reference is removed in the
220 //! case of duplicate items.
221 virtual Standard_EXPORT void RemoveBackReference
222 (const Handle(TObj_Object)& theObject,
223 const Standard_Boolean theSingleOnly = Standard_True);
225 //! Removes all back reference by removing references from other to me.
226 virtual Standard_EXPORT Standard_Boolean RemoveBackReferences
227 (const TObj_DeletingMode theMode = TObj_FreeOnly);
229 //! The default implementation just clear the back references container
230 virtual Standard_EXPORT void ClearBackReferences();
232 //! Returns TRUE if obejct has 1 or more back references
233 Standard_EXPORT Standard_Boolean HasBackReferences() const;
235 //! Replace reference from old object to new object.
236 //! If it is not possible, may raise exception.
237 //! If new object is null then simple remove reference to old object.
238 virtual Standard_EXPORT void ReplaceReference
239 (const Handle(TObj_Object)& theOldObject,
240 const Handle(TObj_Object)& theNewObject);
242 //! Return True if this refers to the model theRoot belongs
243 //! to and a referred label is not a descendant of theRoot.
244 //! In this case theBadReference returns the currently referred label.
245 virtual Standard_EXPORT Standard_Boolean GetBadReference
246 (const TDF_Label& theRoot,
247 TDF_Label& theBadReference) const;
249 //! Make that each reference pointing to a descendant label of
250 //! theFromRoot to point to an equivalent label under theToRoot.
251 //! Return False if a resulting reference does not point to
254 //! a referred object label = 0:3:24:7:2:7
255 //! theFromRoot = 0:3:24
257 //! a new referred label = 0:2:7:2:7
258 virtual Standard_EXPORT Standard_Boolean RelocateReferences
259 (const TDF_Label& theFromRoot,
260 const TDF_Label& theToRoot,
261 const Standard_Boolean theUpdateBackRefs = Standard_True);
263 //! Returns True if the referred object theObject can be deleted
264 //! without deletion of this object.
265 //! Default implementation does nothing and returns False.
266 virtual Standard_EXPORT Standard_Boolean CanRemoveReference
267 (const Handle(TObj_Object)& theObject) const;
269 //! Removes reference to the object by replace reference to NULL object
270 virtual Standard_EXPORT void RemoveReference (const Handle(TObj_Object)& theObject);
272 //! Invokes from TObj_TReference::BeforeForget().
273 //! theLabel - label on that reference become removed
274 //! Default implementation is empty
275 virtual Standard_EXPORT void BeforeForgetReference( const TDF_Label& /*theLabel*/ )
280 * Methods for deleting the object
283 //! Checks if object can be detached with specified mode
284 virtual Standard_EXPORT Standard_Boolean CanDetach(const TObj_DeletingMode theMode = TObj_FreeOnly);
286 //! Deletes the object from the model.
287 //! The dependent objects are either deleted or modified when possible
288 //! (see description of TObj_DeletingMode enumeration for more details)
289 //! Returns True if deletion was successful.
290 //! Checks if object can be deleted.
291 //! Should be redefined for each specific kind of object
292 virtual Standard_EXPORT Standard_Boolean Detach
293 (const TObj_DeletingMode theMode = TObj_FreeOnly);
295 //! Deletes the object from the label. Checks if object can be deleted.
296 //! Finds object on the label and detaches it by calling previos method.
297 //! Returns true if there is no object on the label after detaching
298 static Standard_EXPORT Standard_Boolean Detach
299 (const TDF_Label& theLabel,
300 const TObj_DeletingMode theMode = TObj_FreeOnly);
305 * methods for object retrieval
308 //! Returns the Object attached to a given label.
309 //! Returns False if no object of type TObj_Object is stored on the
311 //! If isSuper is true tries to find on the super labels.
312 static Standard_EXPORT Standard_Boolean GetObj
313 (const TDF_Label& theLabel,
314 Handle(TObj_Object)& theResult,
315 const Standard_Boolean isSuper = Standard_False);
317 //! Returns the father object, which may be NULL
318 //! theType gives type of father object to search
319 Standard_EXPORT Handle(TObj_Object) GetFatherObject
320 (const Handle(Standard_Type)& theType = NULL) const;
324 * Methods for checking and Updating object
327 //! Checks that object alive in model
328 //! Default implementation checks that object has TObject attribute at own label.
329 virtual Standard_EXPORT Standard_Boolean IsAlive() const;
333 * Cloning related methods
336 //! Copy me to other label theTargetLabel
337 //! New object will not have all the reference that has me.
338 //! Coping object with data and childs, but change name by adding string "_copy"
339 //! As result return handle of new object (null handle is something wrong)
340 //! NOTE: BackReferences not coping.
341 //! After clonning all objects it is neccessary to call copy references
342 //! with the same relocation table
343 virtual Standard_EXPORT Handle(TObj_Object) Clone
344 (const TDF_Label& theTargetLabel,
345 Handle(TDF_RelocationTable) theRelocTable = 0);
347 //! Coping the references.
348 //! return Standard_False is Target object is different type
349 virtual Standard_EXPORT void CopyReferences
350 (const Handle(TObj_Object)& theTargetObject,
351 const Handle(TDF_RelocationTable)& theRelocTable);
353 //! Coping the children from source label to the target.
354 virtual Standard_EXPORT void CopyChildren
355 (TDF_Label& theTargetLabel,
356 const Handle(TDF_RelocationTable)& theRelocTable);
361 * Public methods to access order of object
364 //! returns order of object (or tag of their label if order is not initialised)
365 virtual Standard_EXPORT Standard_Integer GetOrder() const;
367 //! sets order of object
368 virtual Standard_EXPORT Standard_Boolean SetOrder( const Standard_Integer& theIndx );
372 * Protected Methods copy data of object to other object
375 //! Coping the data of me to Target object.
376 //! return Standard_False is Target object is different type
377 virtual Standard_EXPORT Standard_Boolean copyData
378 (const Handle(TObj_Object)& theTargetObject);
380 //! Coping the references from source label to the target.
381 Standard_EXPORT void copyReferences
382 (const TDF_Label& theSourceLabel,
383 TDF_Label& theTargetLabel,
384 const Handle(TDF_RelocationTable)& theRelocTable);
388 * Access to object flags
391 //! Returns flags (bitmask) that define properties of objects of that type
392 //! By default returns flag Visible
393 virtual Standard_EXPORT Standard_Integer GetTypeFlags() const;
395 //! Returns mask of seted flags
396 Standard_EXPORT Standard_Integer GetFlags() const;
398 //! Sets flags with defined mask.
399 Standard_EXPORT void SetFlags(const Standard_Integer theMask);
401 //! tests flags by the mask.
402 Standard_EXPORT Standard_Boolean TestFlags(const Standard_Integer theMask) const;
404 //! clears flags by the mask.
405 Standard_EXPORT void ClearFlags(const Standard_Integer theMask = ~0);
409 * Method for updating object afrer restoring
412 //! Preforms updating the links and dependances of the object which are not
413 //! stored in persistence. Should be redefined if necessary.
414 virtual Standard_EXPORT void AfterRetrieval();
416 //! Preforms storing the objects transient fields in OCAF document
417 //! which were outside transaction mechanism.
418 //! Default implementation doesnot nothing
419 virtual Standard_EXPORT void BeforeStoring();
423 * Internal tools for work with OCAF data
426 //! Returns the theRank2-th sub label of the theRank1-th sublabel of the
427 //! Data label of the object.
428 //! If theRank2 is 0 (default), sub label theRank1 of Data label is returned.
429 //! If requested label does not exist, it is created.
430 Standard_EXPORT TDF_Label getDataLabel
431 (const Standard_Integer theRank1,
432 const Standard_Integer theRank2 = 0) const;
434 //! Returns the theRank2-th sub label of the theRank1-th sublabel of the
435 //! Reference label of the object.
436 //! If theRank2 is 0 (default), sub label theRank1 of Reference label is returned.
437 //! If requested label does not exist, it is created.
438 Standard_EXPORT TDF_Label getReferenceLabel
439 (const Standard_Integer theRank1,
440 const Standard_Integer theRank2 = 0) const;
442 //! Returns True if there is an attribute having theGUID on the
443 //! theRank2-th sublabel of theRank1-th sublabel of the Data
444 //! label of the object.
445 //! If theRank2 is 0 (default), label theRank1 is supposed, not
447 Standard_EXPORT Standard_Boolean isDataAttribute
448 (const Standard_GUID& theGUID,
449 const Standard_Integer theRank1,
450 const Standard_Integer theRank2 = 0) const;
452 //! Returns the real value from theRank2-th sublabel of theRank1-th
453 //! sublabel of the Data label of the object.
454 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
455 //! Returns 0.0 if no real value is stored on that label.
456 Standard_EXPORT Standard_Real getReal
457 (const Standard_Integer theRank1,
458 const Standard_Integer theRank2 = 0) const;
460 //! Sets the real value for theRank2-th sublabel of theRank1-th
461 //! sublabel of the Data label of the object.
462 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
463 //! Returns True if new value is actually different from previous one
464 //! (with specified tolerance)
465 Standard_EXPORT Standard_Boolean setReal
466 (const Standard_Real theValue,
467 const Standard_Integer theRank1,
468 const Standard_Integer theRank2 = 0,
469 const Standard_Real theTolerance = 0.) const;
471 //! Returns the integer value from theRank2-th sublabel of theRank1-th
472 //! sublabel of the Data label of the object.
473 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
474 //! Returns 0 if no integer value is stored on that label.
475 Standard_EXPORT Standard_Integer getInteger
476 (const Standard_Integer theRank1,
477 const Standard_Integer theRank2 = 0) const;
479 //! Sets the integer value for theRank2-th sublabel of theRank1-th
480 //! sublabel of the Data label of the object.
481 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
482 //! Returns True if new value is actually different from previous one
483 Standard_EXPORT Standard_Boolean setInteger
484 (const Standard_Integer theValue,
485 const Standard_Integer theRank1,
486 const Standard_Integer theRank2 = 0) const;
488 //! Returns an existing or create a new real array on theRank2-th
489 //! sublabel of theRank1-th sublabel of the Data label of the object.
490 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
491 //! A newly created array has 1 and theLength bounds and is initialized
492 //! with theInitialValue
494 //! NOTE: do not create new array and returns NULL handle if no array on label
495 //! and theLength less than
497 //! WARNING: call setArray() after array contents modification
498 //! in order to assure Undo work
499 Standard_EXPORT Handle(TColStd_HArray1OfReal) getRealArray
500 (const Standard_Integer theLength,
501 const Standard_Integer theRank1,
502 const Standard_Integer theRank2 = 0,
503 const Standard_Real theInitialValue = 0.0) const;
505 //! Returns an existing or create a new integer array on theRank2-th
506 //! sublabel of theRank1-th sublabel of the Data label of the object.
507 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
508 //! A newly created array has 1 and theLength bounds and is initialized
509 //! with theInitialValue
511 //! NOTE: do not create new array and returns NULL handle if no array on label
512 //! and theLength less than
514 //! WARNING: call setArray() after array contents modification
515 //! in order to assure Undo work
516 Standard_EXPORT Handle(TColStd_HArray1OfInteger) getIntegerArray
517 (const Standard_Integer theLength,
518 const Standard_Integer theRank1,
519 const Standard_Integer theRank2 = 0,
520 const Standard_Integer theInitialValue = 0) const;
522 //! Returns an existing or create a new string array on theRank2-th
523 //! sublabel of theRank1-th sublabel of the Data label of the object.
524 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
525 //! A newly created array has 1 and theLength bounds
526 //! NOTE: new created array is NOT initialized.
528 //! NOTE: do not create new array and returns NULL handle if no array on label
529 //! and theLength less than
531 //! WARNING: call setArray() after array contents modification
532 //! in order to assure Undo work
533 Standard_EXPORT Handle(TColStd_HArray1OfExtendedString) getExtStringArray
534 (const Standard_Integer theLength,
535 const Standard_Integer theRank1,
536 const Standard_Integer theRank2 = 0) const;
538 //! Store theArray on theRank2-th sublabel of theRank1-th sublabel
539 //! of the Data label of the object.
540 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
541 //! If theArray is null then array attribute if any is removed.
542 Standard_EXPORT void setArray
543 (const Handle(TColStd_HArray1OfReal)& theArray,
544 const Standard_Integer theRank1,
545 const Standard_Integer theRank2 = 0);
547 //! Store theArray on theRank2-th sublabel of theRank1-th sublabel
548 //! of the Data label of the object.
549 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
550 //! If theArray is null then array attribute if any is removed.
551 Standard_EXPORT void setArray
552 (const Handle(TColStd_HArray1OfInteger)& theArray,
553 const Standard_Integer theRank1,
554 const Standard_Integer theRank2 = 0);
556 //! Store theArray on theRank2-th sublabel of theRank1-th sublabel
557 //! of the Data label of the object.
558 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
559 //! If theArray is null then array attribute if any is removed.
560 Standard_EXPORT void setArray
561 (const Handle(TColStd_HArray1OfExtendedString)& theArray,
562 const Standard_Integer theRank1,
563 const Standard_Integer theRank2 = 0);
565 //! Sets the string value for theRank2-th sublabel of theRank1-th
566 //! sublabel of the Data label of the object.
567 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
568 Standard_EXPORT void setExtString
569 (const Handle(TCollection_HExtendedString)& theValue,
570 const Standard_Integer theRank1,
571 const Standard_Integer theRank2 = 0) const;
573 //! Returns the string value from theRank2-th sublabel of theRank1-th
574 //! sublabel of the Data label of the object.
575 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
576 Standard_EXPORT Handle(TCollection_HExtendedString) getExtString
577 (const Standard_Integer theRank1,
578 const Standard_Integer theRank2 = 0) const;
580 //! Sets the ascii string value for theRank2-th sublabel of theRank1-th
581 //! sublabel of the Data label of the object.
582 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
583 Standard_EXPORT void setAsciiString
584 (const Handle(TCollection_HAsciiString)& theValue,
585 const Standard_Integer theRank1,
586 const Standard_Integer theRank2 = 0) const;
588 //! Returns the string value from theRank2-th sublabel of theRank1-th
589 //! sublabel of the Data label of the object.
590 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
591 Standard_EXPORT Handle(TCollection_HAsciiString) getAsciiString
592 (const Standard_Integer theRank1,
593 const Standard_Integer theRank2 = 0) const;
595 //! Returns the reference attribute from theRank2-th sublabel of theRank1-th
596 //! sublabel of the References label of the object.
597 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
598 Standard_EXPORT Handle(TObj_Object) getReference
599 (const Standard_Integer theRank1,
600 const Standard_Integer theRank2 = 0) const;
602 //! Sets the reference to theObject on theRank2-th sublabel of theRank1-th
603 //! sublabel of the References label of the object.
604 //! If theRank2 is 0 (default), label theRank1 is supposed (not its sublabel).
605 //! Returns True if new value is actually different from previous one
606 //! If Object is NULL, reference is deleted
607 Standard_EXPORT Standard_Boolean setReference
608 (const Handle(TObj_Object) &theObject,
609 const Standard_Integer theRank1,
610 const Standard_Integer theRank2 = 0);
612 //! Adds the reference to theObject on next free sublabel of theRank1-th
613 //! sublabel of the References label of the object and returns the Label.
614 Standard_EXPORT TDF_Label addReference
615 (const Standard_Integer theRank1,
616 const Handle(TObj_Object) &theObject);
622 TDF_Label myLabel; //!< Label on which object`s data are stored
624 Handle(TObj_HSequenceOfObject) myHSeqBackRef; //!< hsequence of back references.
626 friend class TObj_TObject;
630 DEFINE_STANDARD_RTTI(TObj_Object, MMgt_TShared)
633 //! Define handle in separate file