0024331: CMake scripts improvements
[occt.git] / dox / user_guides / tobj / tobj.md
CommitLineData
72b7576f 1TObj Package {#user_guides__tobj}
2==================
e5bd0d98 3
4@tableofcontents
5
dba69de2 6@section occt_tobj_1 Introduction
72b7576f 7
8This document describes the package TObj, which is an add-on
9to the Open CASCADE Application Framework (OCAF).
dba69de2 10
72b7576f 11This package provides a set of classes and auxiliary tools facilitating
12the creation of object-oriented data models on top of low-level OCAF data structures.
13This includes:
14
15 * Definition of classes representing data objects. Data objects store their data using primitive OCAF attributes, taking advantage of OCAF mechanisms for Undo/Redo and persistence. At the same time they provide a higher level abstraction over the pure OCAF document structure (labels / attributes).
16 * Organization of the data model as a hierarchical (tree-like) structure of objects.
17 * Support of cross-references between objects within one model or among different models. In case of cross-model references the models should depend hierarchically.
18 * Persistence mechanism for storing *TObj* objects in OCAF files, which allows storing and retrieving objects of derived types without re-generating the schema.
19
20This document describes basic principles of logical and physical organization
21of TObj-based data models and typical approaches to implementation of classes representing model objects.
22
dba69de2 23@subsection occt_tobj_1_1 Applicability
72b7576f 24
25The main purpose of the *TObj* data model is rapid development
26of the object-oriented data models for applications, using the existing
27functionality provided by OCAF (Undo/Redo and persistence)
28without the necessity to re-develop such functionality from scratch.
dba69de2 29
72b7576f 30As opposed to using bare OCAF (at the level of labels and attributes),
31TObj facilitates dealing with higher level abstracts, which are closer
32to the application domain. It works best when the application data are naturally
33organized in hierarchical structures, and is especially useful for complex data
34models with dependencies between objects belonging to different parts of the model.
dba69de2 35
72b7576f 36It should be noted that *TObj* is efficient for representing data structures containing
37a limited number of objects at each level of the data structure (typically less than 1000).
dba69de2 38A greater number of objects causes performance problems due to list-based organization of OCAF documents. Therefore, other methods of storage, such as arrays, are advisable for data models or their sub-parts containing a great number of uniform objects. However, these methods
72b7576f 39can be combined with the usage of *TObj* to represent the high-level structure of the model.
40
dba69de2 41@section occt_tobj_2 *TObj* Model
72b7576f 42
dba69de2 43@subsection occt_tobj_2_1 *TObj* Model structure
72b7576f 44
45In the *TObj* data model the data are separated from the interfaces that manage them.
72b7576f 46
dba69de2 47It should be emphasized that *TObj* package defines only the interfaces and the basic structure of the model and objects, while the actual contents and structure of the model of a particular application are defined by its specific classes inherited from *TObj* classes. The implementation can add its own features or even change the default behaviour and the data layout, though this is not recommended.
72b7576f 48
dba69de2 49Logically the *TObj* data model is represented as a tree of model objects, with upper-level objects typically being collections of other objects (called *partitions*, represented by the class *TObj_Partition*). The root object of the model is called the *Main partition* and is maintained by the model itself. This partition contains a list of sub-objects called its *children* each sub-object may contain its own children (according to its type), etc.
50
51@image html /user_guides/tobj/images/tobj_image003.png "TObj Data Model"
52@image latex /user_guides/tobj/images/tobj_image003.png "TObj Data Model"
72b7576f 53
54As the *TObj* Data Model is based on OCAF (Open CASCADE Application Framework) technology,
55it stores its data in the underlying OCAF document. The OCAF document consists of a tree of
56items called *labels*. Each label has some data attached to it in the form of *attributes*,
57and may contain an arbitrary number of sub-labels. Each sub-label is identified by its sequential
58number called the *tag*. The complete sequence of tag numbers of the label
59and its parents starting from the document root constitutes the complete *entry*
60of the label, which uniquely identifies its position in the document.
61
62Generally the structure of the OCAF tree of the *TObj* data
63model corresponds to the logical structure of the model and can be presented as in the following picture:
64
e5bd0d98 65@image html /user_guides/tobj/images/tobj_image004.png "TObj Data Model mapped on OCAF document"
66@image latex /user_guides/tobj/images/tobj_image004.png "TObj Data Model mapped on OCAF document"
72b7576f 67
72b7576f 68All data of the model are stored in the root label (0:1) of the OCAF document.
dba69de2 69An attribute *TObj_TModel* is located in this root label. It
72b7576f 70stores the object of type *TObj_Model*. This object serves as a main interface tool
71to access all data and functionalities of the data model.
72
73In simple cases all data needed by the application may be
74contained in a single data model. Moreover, *TObj* gives the possibility to
75distribute the data between several interconnected data models. This can be
76especially useful for the applications dealing with great amounts of data. because
77only the data required for the current operation is loaded in the memory at one time.
78It is presumed that the models have a hierarchical (tree-like) structure,
79where the objects of the child models can refer to the objects of the parent
80models, not vice-versa. Provided that the correct order of loading and closing
81of the models is ensured, the *TObj* classes will maintain references between the objects automatically.
82
dba69de2 83@subsection occt_tobj_2_2 Data Model basic features
72b7576f 84
85The class *TObj_Model* describing the data model provides the following functionalities:
86
87 * Loading and saving of the model from or in a file (methods *Load* and *Save*)
88 * Closing and removal of the model from memory (method *Close*)
89 * Definition of the full file name of the persistence storage for this model (method *GetFile*)
90 * Tools to organize data objects in partitions and iterate on objects (methods *GetObjects*, *GetMainPartition*, *GetChildren*, *getPartition*, *getElementPartition*)
91 * Mechanism to give unique names to model objects
92 * Copy (*clone*) of the model (methods *NewEmpty* and *Paste*)
93 * Support of earlier model formats for proper conversion of a model loaded from a file written by a previous version of the application (methods *GetFormatVersion* and *SetFormatVersion*)
94 * Interface to check and update the model if necessary (method *Update*)
95 * Support of several data models in one application. For this feature use OCAF multi-transaction manager, unique names and GUIDs of the data model (methods *GetModelName*, *GetGUID*)
96
dba69de2 97@subsection occt_tobj_2_3 Model Persistence
72b7576f 98
99The persistent representation of any OCAF model is contained in an XML or a binary file,
100which is defined by the format string returned by the method *GetFormat*.
101The default implementation works with a binary OCAF document format (*BinOcaf*).
102The other available format is *XmlOcaf*. The class **TObj_Model** declares and provides a default
103implementation of two virtual methods:
104
dba69de2 105~~~~~{.cpp}
72b7576f 106 virtual Standard_Boolean Load (const char* theFile);
107 virtual Standard_Boolean SaveAs (const char* theFile);
dba69de2 108~~~~~
72b7576f 109
110which retrieve and store the model from or
111in the OCAF file. The descendants
112should define the following protected method to support Load and Save operations:
113
dba69de2 114~~~~~{.cpp}
72b7576f 115 virtual Standard_Boolean initNewModel (const Standard_Boolean IsNew);
dba69de2 116~~~~~
72b7576f 117
118This method is called by *Load* after creation of a new model
119or after its loading from the file; its purpose is to perform
120the necessary initialization of the model (such as creation of necessary top-level
121partitions, model update due to version changes etc.). Note that if
122the specified file does not exist, method *Load* will create
123a new document and call *initNewModel* with the argument **True**.
124If the file has been normally loaded, the argument **False** is passed.
125Thus, a new empty *TObj* model is created by calling *Load* with an empty
126string or the path to a nonexistent file as argument.
127
128The method *Load* returns **True** if the model has been retrieved successfully
129(or created a new), or **False** if the model could not be loaded.
130If no errors have been detected during initialization (model retrieval or creation),
131the virtual method *AfterRetrieval* is invoked for all objects of the model.
132This method initializes or updates the objects immediately after the model initialization.
133It could be useful when some object data should be imported from an OCAF attribute into transient
134fields which could be changed outside of the OCAF transaction mechanism.
135Such fields can be stored into OCAF attributes for saving into persistent storage during the save operation.
136
137To avoid memory leaks, the *TObj_Model* class destructor invokes *Close* method
138which clears the OCAF document and removes all data from memory before the model is destroyed.
dba69de2 139
72b7576f 140For XML and binary persistence of the *TObj* data model the corresponding drivers are implemented
141in *BinLDrivers*, *BinMObj* and *XmlLDrivers*, *XmlMObj* packages.
142These packages contain retrieval and storage drivers for the model, model objects and custom attributes
143from the *TObj* package. The schemas support persistence for the standard OCAF and *TObj* attributes.
144This is sufficient for the implementation of simple data models, but
145in some cases it can be reasonable to add specific OCAF attributes to
146facilitate the storage of the data specific to the application.
147In this case the schema should be extended using the standard OCAF mechanism.
148
dba69de2 149@subsection occt_tobj_2_4 Access to the objects in the model
72b7576f 150
151All objects in the model are stored in the main partition and accessed by iterators.
152To access all model objects use:
153
dba69de2 154~~~~~{.cpp}
72b7576f 155 virtual Handle(TObj_ObjectIterator) GetObjects () const;
dba69de2 156~~~~~
72b7576f 157
158This method returns a recursive iterator on all objects stored in the model.
159
dba69de2 160~~~~~{.cpp}
72b7576f 161 virtual Handle(TObj_ObjectIterator) GetChildren () const;
dba69de2 162~~~~~
72b7576f 163
164This method returns an iterator on child objects of the main partition.
165Use the following method to get the main partition:
166
dba69de2 167~~~~~{.cpp}
72b7576f 168 Handle(TObj_Partition) GetMainPartition() const;
dba69de2 169~~~~~
72b7576f 170
171To receive the iterator on objects of a specific type *AType* use the following call:
172
dba69de2 173~~~~~{.cpp}
72b7576f 174 GetMainPartition()->GetChildren(STANDARD_TYPE(AType) );
dba69de2 175~~~~~
72b7576f 176
177The set of protected methods is provided for descendant classes to deal with partitions:
178
dba69de2 179~~~~~{.cpp}
180 virtual Handle(TObj_Partition) getPartition (const TDF_Label, const Standard_Boolean theHidden) const;
181~~~~~
72b7576f 182
183This method returns (creating if necessary) a partition in the specified label of the document.
184The partition can be created as hidden (*TObj_HiddenPartition* class).
185A hidden partition can be useful to distinguish the data that
186should not be visible to the user when browsing the model in the application.
187
188The following two methods allow getting (creating) a partition
189in the sub-label of the specified label in the document
190(the label of the main partition for the second method) and with the given name:
191
dba69de2 192~~~~~{.cpp}
193 virtual Handle(TObj_Partition) getPartition (const TDF_Label, const Standard_Integer theIndex, const TCollection_ExtendedString& theName, const Standard_Boolean theHidden) const;
194 virtual Handle(TObj_Partition) getPartition (const Standard_Integer theIndex, const TCollection_ExtendedString& theName, const Standard_Boolean theHidden) const;
195~~~~~
72b7576f 196
197If the default object naming and the name register mechanism
198is turned on, the object can be found in the model by its unique name:
199
dba69de2 200~~~~~{.cpp}
72b7576f 201 Handle(TObj_Object) FindObject (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary) const;
dba69de2 202~~~~~
72b7576f 203
dba69de2 204@subsection occt_tobj_2_5 Own model data
72b7576f 205
206The model object can store its own data in the Data label
207of its main partition, however, there is no standard API for
208setting and getting these data types. The descendants can add
209their own data using standard OCAF methods. The enumeration DataTag is defined
210in *TObj_Model* to avoid conflict of data labels used by this class
211and its descendants, similarly to objects (see below).
212
dba69de2 213@subsection occt_tobj_2_6 Object naming
72b7576f 214
215The basic implementation of *TObj_Model* provides the default
216naming mechanism: all objects must have unique names,
217which are registered automatically in the data model dictionary.
218The dictionary is a *TObj_TNameContainer*
219attribute whose instance is located in the model root label.
220If necessary, the developer can add several dictionaries into
221the specific partitions, providing the name registration in the
222correct name dictionary and restoring the name map after document is loaded from file.
223To ignore name registering it is necessary to redefine the methods *SetName*,
224*AfterRetrieval* of the *TObj_Object* class and skip the registration of the object name.
225Use the following methods for the naming mechanism:
226
dba69de2 227~~~~~{.cpp}
72b7576f 228 Standard_Boolean IsRegisteredName (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary ) const;
dba69de2 229~~~~~
72b7576f 230
231Returns **True** if the object name is already registered in the indicated (or model) dictionary.
232
dba69de2 233~~~~~{.cpp}
72b7576f 234 void RegisterName (const Handle(TCollection_HExtendedString)& theName, const TDF_Label& theLabel, const Handle(TObj_TNameContainer)& theDictionary ) const;
dba69de2 235~~~~~
72b7576f 236
237Registers the object name with the indicated label where the object
238is located in the OCAF document. Note that the default implementation
239of the method *SetName* of the object registers the new name automatically
240(if the name is not yet registered for any other object)
241
dba69de2 242~~~~~{.cpp}
72b7576f 243 void UnRegisterName (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary ) const;
dba69de2 244~~~~~
72b7576f 245
246Unregisters the name from the dictionary. Ther names of *TObj* model
247objects are removed from the dictionary when the objects are deleted from the model.
248
dba69de2 249~~~~~{.cpp}
ad211ad3 250 Handle(TObj_TNameContainer) GetDictionary() const;
251~~~~~
72b7576f 252
253Returns a default instance of the model dictionary (located at the model root label).
254The default implementation works only with one dictionary.
255If there are a necessity to have more than one dictionary for the model objects,
256it is recommended to redefine the corresponding virtual method of TObj_Object
257that returns the dictionary where names of objects should be registered.
258
dba69de2 259@subsection occt_tobj_2_7 API for transaction mechanism
72b7576f 260
261Class *TObj_Model* provides the API for transaction mechanism (supported by OCAF):
262
ad211ad3 263~~~~~{.cpp}
72b7576f 264 Standard_Boolean HasOpenCommand() const;
ad211ad3 265~~~~~
72b7576f 266
267Returns True if a Command transaction is open
268
ad211ad3 269~~~~~{.cpp}
72b7576f 270 void OpenCommand() const;
ad211ad3 271~~~~~
72b7576f 272
273Opens a new command transaction.
274
ad211ad3 275~~~~~{.cpp}
72b7576f 276 void CommitCommand() const;
ad211ad3 277~~~~~
72b7576f 278
279Commits the Command transaction. Does nothing If there is no open Command transaction.
280
ad211ad3 281~~~~~{.cpp}
72b7576f 282 void AbortCommand() const;
ad211ad3 283~~~~~
72b7576f 284
285Aborts the Command transaction. Does nothing if there is no open Command transaction.
286
ad211ad3 287~~~~~{.cpp}
72b7576f 288 Standard_Boolean IsModified() const;
ad211ad3 289~~~~~
72b7576f 290
291Returns True if the model document has a modified status (has changes after the last save)
292
ad211ad3 293~~~~~{.cpp}
72b7576f 294 void SetModified( const Standard_Boolean );
ad211ad3 295~~~~~
72b7576f 296
297Changes the modified status by force. For synchronization of transactions
298within several *TObj_Model* documents use class *TDocStd_MultiTransactionManager*.
299
dba69de2 300@subsection occt_tobj_28 Model format and version
72b7576f 301
302Class *TObj_Model* provides the descendant classes with a means to control
303the format of the persistent file by choosing the schema used to store or retrieve operations.
304
ad211ad3 305~~~~~{.cpp}
72b7576f 306 virtual TCollection_ExtendedString GetFormat () const;
ad211ad3 307~~~~~
72b7576f 308
309Returns the string *TObjBin* or *TObjXml* indicating
310the current persistent mechanism. The default value is *TObjBin*.
311Due to the evolution of functionality of the developed application,
312the contents and the structure of its data model vary from version to version.
313*TObj* package provides a basic mechanism supporting backward versions compatibility,
314which means that newer versions of the application will be able to read
315Data Model files created by previous versions (but not vice-versa) with a minimum loss of data.
316For each type of Data Model, all known versions of the data format
317should be enumerated in increasing order, incremented with every change
318of the model format. The current version of the model
319format is stored in the model file and can be checked upon retrieval.
320
ad211ad3 321~~~~~{.cpp}
72b7576f 322 Standard_Integer GetFormatVersion() const;
ad211ad3 323~~~~~
72b7576f 324
325Returns the format version stored in the model file
326
ad211ad3 327~~~~~{.cpp}
72b7576f 328 void SetFormatVersion(const Standard_Integer theVersion);
ad211ad3 329~~~~~
72b7576f 330
331Defines the format version used for save.
332
333Upon loading a model, the method *initNewModel()*, called immediately
334after opening a model from disk (on the level of the OCAF document),
335provides a specific code that checks the format version stored in that model.
336If it is older than the current version of the application, the data update can be performed.
337Each model can have its own specific conversion code
338that performs the necessary data conversion to make them compliant with the current version.
339
340When the conversion ends the user is advised of that by the messenger interface
341provided by the model (see messaging chapter for more details),
342and the model version is updated. If the version of data model is not supported
343(it is newer than the current or too old), the load operation should fail.
344The program updating the model after version change can be implemented as static
345methods directly in C++ files of the corresponding Data Model classes,
346not exposing it to the other parts of the application.
347These codes can use direct access to the model and objects data (attributes)
348not using objects interfaces, because the data model API and object classes
349could have already been changed.
350
351Note that this mechanism has been designed to maintain version compatibility
352for the changes of data stored in the model, not for the changes of
353low-level format of data files (such as the storage format of a specific OCAF attribute).
354If the format of data files changes, a specific treatment on a case-by-case basis will be required.
355
dba69de2 356@subsection occt_tobj_2_9 Model update
72b7576f 357
358The following methods are used for model update to ensure its consistency
359with respect to the other models in case of cross-model dependencies:
360
ad211ad3 361~~~~~{.cpp}
72b7576f 362 virtual Standard_Boolean Update();
ad211ad3 363~~~~~
72b7576f 364
365This method is usually called after loading of the model.
366The default implementation does nothing and returns **True**.
367
ad211ad3 368~~~~~{.cpp}
72b7576f 369 virtual Standard_Boolean initNewModel( const Standard_Boolean IsNew);
ad211ad3 370~~~~~
72b7576f 371
372This method performs model initialization, check and updates (as described above).
373
ad211ad3 374~~~~~{.cpp}
72b7576f 375 virtual void updateBackReferences( const Handle(TObj_Object)& theObj);
ad211ad3 376~~~~~
72b7576f 377
378This method is called from the previous method to update back references
379of the indicated object after the retrieval of the model from file
380(see data model - object relationship chapter for more details)
381
dba69de2 382@subsection occt_tobj_2_10 Model copying
72b7576f 383
384To copy the model between OCAF documents use the following methods:
385
ad211ad3 386~~~~~{.cpp}
72b7576f 387 virtual Standard_Boolean Paste (Handle(*TObj_Model*) theModel, Handle(TDF_RelocationTable) theRelocTable = 0 );
ad211ad3 388~~~~~
72b7576f 389
390Pastes the current model to the new model. The relocation table
391ensures correct copying of the sub-data shared by several parts of the model.
392It stores a map of processed original objects of relevant types in their copies.
393
ad211ad3 394~~~~~{.cpp}
72b7576f 395 virtual Handle(*TObj_Model*) NewEmpty() = 0;
ad211ad3 396~~~~~
72b7576f 397
398Redefines a pure virtual method to create a new empty instance of the model.
399
ad211ad3 400~~~~~{.cpp}
72b7576f 401 void CopyReferences ( const Handle(*TObj_Model*)& theTarget, const Handle(TDF_RelocationTable)& theRelocTable);
ad211ad3 402~~~~~
72b7576f 403
404Copies the references from the current model to the target model.
405
dba69de2 406@subsection occt_tobj_2_11 Messaging
72b7576f 407
408The messaging is organised using Open CASCADE Messenger from the package Message.
409The messenger is stored as the field of the model instance
410and can be set and retrieved by the following methods:
411
ad211ad3 412~~~~~{.cpp}
72b7576f 413 void SetMessenger( const Handle(Message_Messenger)& );
414 Handle(Message_Messenger) Messenger() const;
ad211ad3 415~~~~~
72b7576f 416
417A developer should create his own instance of the Messenger
418bound to the application user interface, and attribute it to the model
419for future usage. In particular the messenger is used for reporting
420errors and warnings in the persistence mechanism.
421Each message has a unique string identifier (key).
422All message keys are stored in a special resource file TObj.msg.
423This file should be loaded at the start of the application
424by call to the appropriate method of the class *Message_MsgFile*.
425
dba69de2 426@section occt_tobj_3 Model object
72b7576f 427
428Class *TObj_Object* provides basic interface and default implementation
429of important features of *TObj* model objects. This implementation defines
430basic approaches that are recommended for all descendants,
431and provides tools to facilitate their usage.
432
dba69de2 433@image html /user_guides/tobj/images/tobj_image005.png "TObj objects hierarchy"
434@image latex /user_guides/tobj/images/tobj_image005.png "TObj objects hierarchy"
72b7576f 435
dba69de2 436@subsection occt_tobj_3_1 Separation of data and interface
72b7576f 437
438In the *TObj* data model, the data are separated from the interfaces that manage them.
439The data belonging to a model object are stored in its root label and sub-labels
440in the form of standard OCAF attributes. This allows using standard OCAF mechanisms
441for work with these data, and eases the implementation of the persistence mechanism.
dba69de2 442
72b7576f 443The instance of the interface which serves as an API for managing object data
444(e.g. represents the model object) is stored in the root label of the object,
445and typically does not bring its own data. The interface classes are organized in a hierarchy
446corresponding to the natural hierarchy of the model objects according to the application.
dba69de2 447
72b7576f 448In the text below the term 'object' is used to denote either the instance
449of the interface class or the object itself (both interface and data stored in OCAF).
dba69de2 450
72b7576f 451The special type of attribute *TObj_TObject* is used for storing instances of objects interfaces
452in the OCAF tree. *TObj_TObject* is a simple container for the object of type *TObj_Object*.
dba69de2 453All objects (interfaces) of the data model inherit this class.
72b7576f 454
dba69de2 455@image html /user_guides/tobj/images/tobj_image006.png "*TObj* object stored on OCAF label"
456@image latex /user_guides/tobj/images/tobj_image006.png "*TObj* object stored on OCAF label"
72b7576f 457
72b7576f 458
dba69de2 459@subsection occt_tobj_3_2 Basic features
72b7576f 460
461The *TObj_Object* class provides some basic features that can be inherited (or, if necessary, redefined) by the descendants:
462
463 * Gives access to the model to which the object belongs (method *GetModel*) and to the OCAF label in which the object is stored (method *GetLabel*).
464 * Supports references (and back references) to other objects in the same or in another model (methods *getReference*, *setReference*, *addReference*, *GetReferences*, *GetBackReferences*, *AddBackReference*, *RemoveBackReference*, *ReplaceReference*)
465 * Provides the ability to contain child objects, as it is actual for partition objects (methods *GetChildren*, *GetFatherObject*)
466 * Organizes its data in the OCAF structure by separating the sub-labels of the main label intended for various kinds of data and providing tools to organize these data (see <a href="../../../../Documents%20and%20Settings/TEMP/obj-inher">below</a>). The kinds of data stored separately are:
dba69de2 467 * Child objects stored in the label returned by the method *GetChildLabel*
468 * References to other objects stored in the label returned by the method* GetReferenceLabel*
469 * Other data, both common to all objects and specific for each subtype of the model object, are stored in the label returned by the method *GetDataLabel*
72b7576f 470 * Provides unique names of all objects in the model (methods *GetDictionary*, *GetName*, *SetName*)
471 * Provides unified means to maintain persistence (implemented in descendants with the help of macros *DECLARE_TOBJOCAF_PERSISTENCE* and *IMPLEMENT_TOBJOCAF_PERSISTENCE*)
dba69de2 472 * Allows an object to remove itself from the OCAF document and check the depending objects can be deleted according to the back references (method *Detach*)
72b7576f 473 * Implements methods for identification and versioning of objects
474 * Manages the object interaction with OCAF Undo/Redo mechanism (method *IsAlive*, *AfterRetrieval*, *BeforeStoring*)
475 * Allows make a clone (methods *Clone*, *CopyReferences*, *CopyChildren*, *copyData*)
476 * Contains additional word of bit flags (methods *GetFlags*, *SetFlags*, *TestFlags*, *ClearFlags*)
477 * Defines the interface to sort the objects by rank (methods *GetOrder*, *SetOrder*)
478 * Provides a number of auxiliary methods for descendants to set/get the standard attribute values, such as int, double, string, arrays etc.
479
480An object can be received from the model by the following methods:
481
ad211ad3 482~~~~~{.cpp}
72b7576f 483 static Standard_Boolean GetObj ( const TDF_Label& theLabel, Handle(TObj_Object)& theResObject, const Standard_Boolean isSuper = Standard_False );
ad211ad3 484~~~~~
72b7576f 485
dba69de2 486Returns *True* if the object has been found in the indicated label (or in the upper level label if *isSuper* is *True*).
72b7576f 487
ad211ad3 488~~~~~{.cpp}
72b7576f 489 Handle(TObj_Object) GetFatherObject ( const Handle(Standard_Type)& theType = NULL ) const;
ad211ad3 490~~~~~
72b7576f 491
492Returns the father object of the indicated type
493for the current object (the direct father object if the type is NULL).
494
dba69de2 495@subsection occt_tobj_3_3 Data layout and inheritance
72b7576f 496
497As far as the data objects are separated from the interfaces and stored in the OCAF tree,
498the functionality to support inheritance is required. Each object has its own data
499and references stored in the labels in the OCAF tree. All data are stored in the sub-tree
500of the main object label. If it is necessary to inherit a class from the base class,
501the descendant class should use different labels for data and references than its ancestor.
dba69de2 502
72b7576f 503Therefore each *TObj* class can reserve the range of tags in each of
504*Data*, *References*, and *Child* sub-labels.
505The reserved range is declared by the enumeration defined
506in the class scope (called DataTag, RefTag, and ChildTag, respectively).
507The item *First* of the enumeration of each type is defined via the *Last* item
508of the corresponding enumeration of the parent class, thus ensuring that the tag numbers
509do not overlap. The item *Last* of the enumeration defines the last tag reserved by this class.
510Other items of the enumeration define the tags used for storing particular data items of the object.
511See the declaration of the TObj_Partition class for the example.
512
513*TObj_Object* class provides a set of auxiliary methods for descendants
514to access the data stored in sub-labels by their tag numbers:
515
ad211ad3 516~~~~~{.cpp}
72b7576f 517 TDF_Label getDataLabel (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const;
518 TDF_Label getReferenceLabel (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const;
ad211ad3 519~~~~~
72b7576f 520
521Returns the label in *Data* or *References* sub-labels at a given tag number (theRank1).
522The second argument, theRank2, allows accessing the next level of hierarchy
523(theRank2-th sub-label of theRank1-th data label).
524This is useful when the data to be stored are represented by multiple OCAF attributes
525of the same type (e.g. sequences of homogeneous data or references).
dba69de2 526
72b7576f 527The get/set methods allow easily accessing the data located in the specified data label
528for the most widely used data types (*Standard_Real*, *Standard_Integer*, *TCollection_HExtendedString*,
529 *TColStd_HArray1OfReal*, *TColStd_HArray1OfInteger*, *TColStd_HArray1OfExtendedString*).
530For instance, methods provided for real numbers are:
531
ad211ad3 532~~~~~{.cpp}
72b7576f 533 Standard_Real getReal (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const;
534 Standard_Boolean setReal (const Standard_Real theValue, const Standard_Integer theRank1, const Standard_Integer theRank2 = 0, const Standard_Real theTolerance = 0.) const;
ad211ad3 535~~~~~
72b7576f 536
537Similar methods are provided to access references to other objects:
538
ad211ad3 539~~~~~{.cpp}
72b7576f 540 Handle(TObj_Object) getReference (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const;
541 Standard_Boolean setReference (const Handle(TObj_Object) &theObject, const Standard_Integer theRank1, const Standard_Integer theRank2 = 0);
ad211ad3 542~~~~~
72b7576f 543
544The method *addReference* gives an easy way to store a sequence of homogeneous references in one label.
545
ad211ad3 546~~~~~{.cpp}
72b7576f 547 TDF_Label addReference (const Standard_Integer theRank1, const Handle(TObj_Object) &theObject);
ad211ad3 548~~~~~
72b7576f 549
550Note that while references to other objects should be defined by descendant classes
551individually according to the type of object, *TObj_Object* provides methods
552to manipulate (check, remove, iterate) the existing references in the uniform way, as described below.
553
dba69de2 554@subsection occt_tobj_3_4 Persistence
72b7576f 555
556The persistence of the *TObj* Data Model is implemented with the help
557of standard OCAF mechanisms (a schema defining necessary plugins, drivers, etc.).
558This implies the possibility to store/retrieve all data that are stored
559as standard OCAF attributes., The corresponding handlers are added
560to the drivers for *TObj*-specific attributes.
dba69de2 561
72b7576f 562The special tool is provided for classes inheriting from *TObj_Object*
563to add the new types of persistence without regeneration of the OCAF schema.
564The class *TObj_Persistence* provides basic means for that:
565
566 * automatic run-time registration of object types
567 * creation of a new object of the specified type (one of the registered types)
568
569Two macros defined in the file TObj_Persistence.hxx have to be included in the definition
570of each model object class inheriting TObj_Object to activate the persistence mechanism:
571
ad211ad3 572~~~~~{.cpp}
72b7576f 573 DECLARE_TOBJOCAF_PERSISTENCE (classname, ancestorname)
ad211ad3 574~~~~~
72b7576f 575
576Should be included in the private section of declaration of each class inheriting
577*TObj_Object* (hxx file). This macro adds an additional constructor to the object class,
578and declares an auxiliary (private) class inheriting *TObj_Persistence*
579that provides a tool to create a new object of the proper type.
580
ad211ad3 581~~~~~{.cpp}
72b7576f 582 IMPLEMENT_TOBJOCAF_PERSISTENCE (classname)
ad211ad3 583~~~~~
72b7576f 584
585Should be included in .cxx file of each object class that should be saved and restored.
586This is not needed for abstract types of objects. This macro implements the functions
587declared by the previous macro and creates a static member
588that automatically registers that type for persistence.
589
590When the attribute *TObj_TObject* that contains the interface object is saved,
591its persistence handler stores the runtime type of the object class.
592When the type is restored the handler dynamically recognizes the type
593and creates the corresponding object using mechanisms provided by *TObj_Persistence*.
594
dba69de2 595@subsection occt_tobj_35 Names of objects
72b7576f 596
dba69de2 597All *TObj* model objects have names by which the user can refer to the object.
72b7576f 598Upon creation, each object receives a default name, constructed
599from the prefix corresponding to the object type (more precisely, the prefix is defined
600by the partition to which the object belongs), and the index of the object in the current partition.
601The user has the possibility to change this name. The uniqueness of the name in the model is ensured
602by the naming mechanism (if the name is already used, it cannot be attributed to another object).
603This default implementation of *TObj* package works with a single instance of the name container (dictionary)
604for name registration of objects and it is enough in most simple projects.
605If necessary, it is easy to redefine a couple of object methods
dba69de2 606(for instance *GetDictionary*()) and to take care of construction and initialization of containers.
607
72b7576f 608This functionality is provided by the following methods:
609
ad211ad3 610~~~~~{.cpp}
72b7576f 611 virtual Handle(TObj_TNameContainer) GetDictionary() const;
ad211ad3 612~~~~~
72b7576f 613
614Returns the name container where the name of object should be registered.
615The default implementation returns the model name container.
616
ad211ad3 617~~~~~{.cpp}
72b7576f 618 Handle(TCollection_HExtendedString) GetName() const;
619 Standard_Boolean GetName( TCollection_ExtendedString& theName ) const;
620 Standard_Boolean GetName( TCollection_AsciiString& theName ) const;
ad211ad3 621~~~~~
72b7576f 622
623Returns the object name. The methods with in / out argument return False if the object name is not defined.
624
ad211ad3 625~~~~~{.cpp}
72b7576f 626 virtual Standard_Boolean SetName ( const Handle(TCollection_HExtendedString)& theName ) const;
dba69de2 627 Standard_Boolean SetName ( const Handle(TCollection_HAsciiString)& theName ) const;
628 Standard_Boolean SetName ( const Standard_CString theName ) const;
ad211ad3 629~~~~~
72b7576f 630
631Attributes a new name to the object and returns **True** if the name has been attributed successfully.
632Returns False if the name has been already attributed to another object.
633The last two methods are short-cuts to the first one.
634
dba69de2 635@subsection occt_tobj_36 References between objects
72b7576f 636
637Class *TObj_Object* allows creating references to other objects in the model.
638Such references describe relations among objects which are not adequately reflected
639by the hierarchical objects structure in the model (parent-child relationship).
dba69de2 640
72b7576f 641The references are stored internally using the attribute TObj_TReference.
642This attribute is located in the sub-label of the referring object (called *master*)
643and keeps reference to the main label of the referred object.
644At the same time the referred object can maintain the back reference to the master object.
645
dba69de2 646@image html /user_guides/tobj/images/tobj_image007.png "Objects relationship"
647@image latex /user_guides/tobj/images/tobj_image007.png "Objects relationship"
648
72b7576f 649
72b7576f 650
651The back references are stored not in the OCAF document but as a transient field
652of the object; they are created when the model is restored from file,
653and updated automatically when the references are manipulated.
654The class *TObj_TReference* allows storing references between objects
655from different *TObj* models, facilitating the construction of complex relations between objects.
dba69de2 656
72b7576f 657The most used methods for work with references are:
658
ad211ad3 659~~~~~{.cpp}
72b7576f 660 virtual Standard_Boolean HasReference( const Handle(TObj_Object)& theObject) const;
ad211ad3 661~~~~~
72b7576f 662
663Returns True if the current object refers to the indicated object.
664
ad211ad3 665~~~~~{.cpp}
72b7576f 666 virtual Handle(TObj_ObjectIterator) GetReferences ( const Handle(Standard_Type)& theType = NULL ) const;
ad211ad3 667~~~~~
72b7576f 668
669Returns an iterator on the object references. The optional argument *theType*
670restricts the types of referred objects, or does not if it is NULL.
671
ad211ad3 672~~~~~{.cpp}
72b7576f 673 virtual void RemoveAllReferences();
ad211ad3 674~~~~~
72b7576f 675
676Removes all references from the current object.
677
ad211ad3 678~~~~~{.cpp}
72b7576f 679 virtual void RemoveReference( const Handle(TObj_Object)& theObject );
ad211ad3 680~~~~~
72b7576f 681
682Removes the reference to the indicated object.
683
ad211ad3 684~~~~~{.cpp}
72b7576f 685 virtual Handle(TObj_ObjectIterator) GetBackReferences ( const Handle(Standard_Type)& theType = NULL ) const;
ad211ad3 686~~~~~
72b7576f 687
688Returns an iterator on the object back references.
689The argument theType restricts the types of master objects, or does not if it is NULL.
690
ad211ad3 691~~~~~{.cpp}
dba69de2 692 virtual void ReplaceReference ( const Handle(TObj_Object)& theOldObject, const Handle(TObj_Object)& theNewObject );
ad211ad3 693~~~~~
72b7576f 694
695Replaces the reference to theOldObject by the reference to *theNewObject*.
696The handle theNewObject may be NULL to remove the reference.
697
ad211ad3 698~~~~~{.cpp}
dba69de2 699 virtual Standard_Boolean RelocateReferences ( const TDF_Label& theFromRoot, const TDF_Label& theToRoot, const Standard_Boolean theUpdateackRefs = Standard_True );
ad211ad3 700~~~~~
72b7576f 701
702Replaces all references to a descendant label of *theFromRoot*
703by the references to an equivalent label under *theToRoot*.
704Returns **False** if the resulting reference does not point at a *TObj_Object*.
705Updates back references if theUpdateackRefs is **True**.
706
ad211ad3 707~~~~~{.cpp}
72b7576f 708 virtual Standard_Boolean CanRemoveReference ( const Handle(TObj_Object)& theObj) const;
ad211ad3 709~~~~~
72b7576f 710
711Returns **True** if the reference can be removed and the master object
712will remain valid (*weak* reference).
713Returns **False** if the master object cannot be valid without the referred object (*strong* reference).
714This affects the behaviour of objects removal from the model – if the reference cannot be removed,
715either the referred object will not be removed, or both the referred
716and the master objects will be removed (depends on the deletion mode in the method **Detach**)
717
dba69de2 718@subsection occt_tobj_3_7 Creation and deletion of objects
72b7576f 719
720It is recommended that all objects inheriting from *TObj_Object*
721 should implement the same approach to creation and deletion.
dba69de2 722
72b7576f 723The object of the *TObj* data model cannot be created independently
724of the model instance, as far as it stores the object data in OCAF data structures.
725Therefore an object class cannot be created directly as its constructor is protected.
dba69de2 726
72b7576f 727Instead, each object should provide a static method *Create*(), which accepts the model,
728with the label, which stores the object and other type-dependent parameters
729necessary for proper definition of the object. This method creates a new object with its data
730(a set of OCAF attributes) in the specified label, and returns a handle to the object's interface.
dba69de2 731
72b7576f 732The method *Detach*() is provided for deletion of objects from OCAF model.
733Object data are deleted from the corresponding OCAF label; however,
734the handle on object remains valid. The only operation available after object deletion
dba69de2 735is the method *IsAlive*() checking whether the object has been deleted or not,
72b7576f 736which returns False if the object has been deleted.
737
738When the object is deleted from the data model, the method checks
739whether there are any alive references to the object.
740Iterating on references the object asks each referring (master) object
741whether the reference can be removed. If the master object can be unlinked,
742the reference is removed, otherwise the master object will be removed too
743or the referred object will be kept alive. This check is performed by the method *Detach* ,
744but the behavior depends on the deletion mode *TObj_DeletingMode*:
745
746 * **TObj_FreeOnly** – the object will be destroyed only if it is free, i.e. there are no references to it from other objects
747 * **TObj_KeepDepending** – the object will be destroyed if there are no strong references to it from master objects (all references can be unlinked)
748 * **TObj_Force** – the object and all depending master objects that have strong references to it will be destroyed.
749
750The most used methods for object removing are:
751
ad211ad3 752~~~~~{.cpp}
72b7576f 753 virtual Standard_Boolean CanDetachObject (const TObj_DeletingMode theMode = TObj_FreeOnly );
ad211ad3 754~~~~~
72b7576f 755
756Returns **True** if the object can be deleted with the indicated deletion mode.
757
ad211ad3 758~~~~~{.cpp}
72b7576f 759 virtual Standard_Boolean Detach ( const TObj_DeletingMode theMode = TObj_FreeOnly );
ad211ad3 760~~~~~
72b7576f 761
762Removes the object from the document if possible
763(according to the indicated deletion mode).
764Unlinks references from removed objects.
765Returns **True** if the objects have been successfully deleted.
766
dba69de2 767@subsection occt_tobj_3_8 Transformation and replication of object data
72b7576f 768
dba69de2 769*TObj_Object* provides a number of special virtual methods to support replications of objects. These methods should be redefined by descendants when necessary.
72b7576f 770
ad211ad3 771~~~~~{.cpp}
72b7576f 772 virtual Handle(TObj_Object) Clone (const TDF_Label& theTargetLabel, Handle(TDF_RelocationTable) theRelocTable = 0);
ad211ad3 773~~~~~
72b7576f 774
775Copies the object to theTargetLabel. The new object will have all references of its original.
776Returns a handle to the new object (null handle if fail). The data are copied directly,
777but the name is changed by adding the postfix *_copy*.
778To assign different names to the copies redefine the method:
779
ad211ad3 780~~~~~{.cpp}
72b7576f 781 virtual Handle(TCollection_HExtendedString) GetNameForClone ( const Handle(TObj_Object)& ) const;
ad211ad3 782~~~~~
72b7576f 783
784Returns the name for a new object copy. It could be useful to return the same object name
785if the copy will be in the other model or in the other partition with its own dictionary.
786The method *Clone* uses the following public methods for object data replications:
787
ad211ad3 788~~~~~{.cpp}
72b7576f 789 virtual void CopyReferences (const const Handle(TObj_Object)& theTargetObject, const Handle(TDF_RelocationTable) theRelocTable);
ad211ad3 790~~~~~
72b7576f 791
792Adds to the copy of the original object its references.
793
ad211ad3 794~~~~~{.cpp}
72b7576f 795 virtual void CopyChildren (TDF_Label& theTargetLabel, const Handle(TDF_RelocationTable) theRelocTable);
ad211ad3 796~~~~~
72b7576f 797
798Copies the children of an object to the target child label.
799
dba69de2 800@subsection occt_tobj_3_9 Object flags
72b7576f 801
dba69de2 802Each instance of *TObj_Object* stores a set of bit flags,
72b7576f 803which facilitate the storage of auxiliary logical information assigned to the objects
dba69de2 804(object state). Several typical state flags are defined in the enumeration *ObjectState*:
72b7576f 805
806 * ObjectState_Hidden – the object is marked as hidden
807 * ObjectState_Saved – the object has (or should have) the corresponding saved file on disk
808 * ObjectState_Imported – the object is imported from somewhere
809 * ObjectState_ImportedByFile – the object has been imported from file and should be updated to have correct relations with other objects
810 * ObjectState_Ordered – the partition contains objects that can be ordered.
811
812The user (developer) can define any new flags in descendant classes.
813To set/get an object, the flags use the following methods:
814
ad211ad3 815~~~~~{.cpp}
72b7576f 816 Standard_Integer GetFlags() const;
817 void SetFlags( const Standard_Integer theMask );
818 Stadnard_Boolean TestFlags( const Standard_Integer theMask ) const;
819 void ClearFlags( const Standard_Integer theMask = 0 );
ad211ad3 820~~~~~
72b7576f 821
822In addition, the generic virtual interface stores the logical properties
823of the object class in the form of a set of bit flags.
824Type flags can be received by the method:
825
ad211ad3 826~~~~~{.cpp}
72b7576f 827 virtual Standard_Integer GetTypeFlags() const;
ad211ad3 828~~~~~
72b7576f 829
830The default implementation returns the flag **Visible**
dba69de2 831defined in the enumeration *TypeFlags*. This flag is used to define visibility
832of the object for the user browsing the model (see class *TObj_HiddenPartition*).
72b7576f 833Other flags can be added by the applications.
834
dba69de2 835@subsection occt_tobj_310 Partitions
72b7576f 836
837The special kind of objects defined by the class *TObj_Partition*
838(and its descendant *TObj_HiddenPartition*) is provided for partitioning
839the model into a hierarchical structure. This object represents the container
840of other objects. Each *TObj* model contains the main partition that is placed
841in the same OCAF label as the model object, and serves as a root of the object's tree.
842A hidden partition is a simple partition with a predefined hidden flag.
dba69de2 843
72b7576f 844The main partition object methods:
845
ad211ad3 846~~~~~{.cpp}
72b7576f 847 TDF_Label NewLabel() const;
ad211ad3 848~~~~~
72b7576f 849
850Allocates and returns a new label for creation of a new child object.
851
ad211ad3 852~~~~~{.cpp}
dba69de2 853 void SetNamePrefix ( const Handle(TCollection_HExtendedString)& thePrefix);
ad211ad3 854~~~~~
72b7576f 855
856Defines the prefix for automatic generation of names of the newly created objects.
857
ad211ad3 858~~~~~{.cpp}
72b7576f 859 Handle(TCollection_HExtendedString) GetNamePrefix() const;
ad211ad3 860~~~~~
72b7576f 861
862Returns the current name prefix.
863
ad211ad3 864~~~~~{.cpp}
72b7576f 865 Handle(TCollection_HExtendedString) GetNewName ( const Standard_Boolean theIsToChangeCount) const;
ad211ad3 866~~~~~
72b7576f 867
868Generates the new name and increases the internal counter of child objects if theIsToChangeCount is **True**.
869
ad211ad3 870~~~~~{.cpp}
72b7576f 871 Standard_Integer GetLastIndex() const;
ad211ad3 872~~~~~
72b7576f 873
874Returns the last reserved child index.
875
ad211ad3 876~~~~~{.cpp}
72b7576f 877 void SetLastIndex( const Standard_Integer theIndex );
ad211ad3 878~~~~~
72b7576f 879
880Sets the last reserved index.
881
dba69de2 882@section occt_tobj_4 Auxiliary classes
72b7576f 883
884Apart from the model and the object, package *TObj* provides a set of auxiliary classes:
885
dba69de2 886 * *TObj_Application* - defines OCAF application supporting existence and operation with *TObj* documents.
887 * *TObj_Assistant* – class provides an interface to the static data to be used during save and load operations on models. In particular, in case of cross-model dependencies it allows passing information on the parent model to the OCAF loader to correctly resolve the references when loading a dependent model.
888 * *TObj_TReference* - OCAF attribute describes the references between objects in the *TObj* model(s). This attribute stores the label of the referred model object, and provides transparent cross-model references. At runtime, these references are simple Handles; in persistence mode, the cross-model references are automatically detected and processed by the persistence mechanism of *TObj_TReference* attribute.
889 * Other classes starting with *TObj_T...* - define OCAF attributes used to store TObj-specific classes and some types of data on OCAF labels.
890 * Iterators – a set of classes implementing *TObj_ObjectIterator* interface, used for iterations on *TObj* objects:
891 * *TObj_ObjectIterator* – a basic abstract class for other *TObj* iterators. Iterates on *TObj_Object* instances.
892 * *TObj_LabelIterator* – iterates on object labels in the *TObj* model document
893 * *TObj_ModelIterator* – iterates on all objects in the model. Works with sequences of other iterators.
894 * *TObj_OcafObjectIterator* – Iterates on *TObj* data model objects. Can iterate on objects of a specific type.
895 * *TObj_ReferenceIterator* – iterates on object references.
896 * *TObj_SequenceIterator* – iterates on a sequence of *TObj* objects.
897 * *TObj_CheckModel* - a tool that checks the internal consistency of the model. The basic implementation checks only the consistency of references between objects.
72b7576f 898
899The structure of *TObj* iterators hierarchy is presented below:
900
dba69de2 901@image html /user_guides/tobj/images/tobj_image008.png "Hierarchy of iterators"
902@image latex /user_guides/tobj/images/tobj_image008.png "Hierarchy of iterators"
72b7576f 903
72b7576f 904
dba69de2 905@section occt_tobj_5 Packaging
72b7576f 906
907The *TObj* sources are distributed in the following packages:
908
dba69de2 909 * *TObj* - defines basic classes that implement *TObj* interfaces for OCAF-based modelers.
910 * *BinLDrivers, XmlLDrivers* – binary and XML driver of *TObj* package
911 * *BinLPlugin, XmlLPlugin* – plugin for binary and XML persistence
912 * *BinMObj, XmlMObj* – binary and XML drivers to store and retrieve specific *TObj* data to or from OCAF document
913 * *TKBinL, TKXmlL* – toolkits of binary and XML persistence
72b7576f 914
915