ba06f8bb |
1 | TObj Package {#occt_user_guides__tobj} |
72b7576f |
2 | ================== |
e5bd0d98 |
3 | |
4 | @tableofcontents |
5 | |
dba69de2 |
6 | @section occt_tobj_1 Introduction |
72b7576f |
7 | |
8 | This document describes the package TObj, which is an add-on |
9 | to the Open CASCADE Application Framework (OCAF). |
dba69de2 |
10 | |
72b7576f |
11 | This package provides a set of classes and auxiliary tools facilitating |
12 | the creation of object-oriented data models on top of low-level OCAF data structures. |
13 | This 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 | |
20 | This document describes basic principles of logical and physical organization |
21 | of 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 | |
25 | The main purpose of the *TObj* data model is rapid development |
26 | of the object-oriented data models for applications, using the existing |
27 | functionality provided by OCAF (Undo/Redo and persistence) |
28 | without the necessity to re-develop such functionality from scratch. |
dba69de2 |
29 | |
72b7576f |
30 | As opposed to using bare OCAF (at the level of labels and attributes), |
31 | TObj facilitates dealing with higher level abstracts, which are closer |
32 | to the application domain. It works best when the application data are naturally |
33 | organized in hierarchical structures, and is especially useful for complex data |
34 | models with dependencies between objects belonging to different parts of the model. |
dba69de2 |
35 | |
72b7576f |
36 | It should be noted that *TObj* is efficient for representing data structures containing |
37 | a limited number of objects at each level of the data structure (typically less than 1000). |
dba69de2 |
38 | A 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 |
39 | can be combined with the usage of *TObj* to represent the high-level structure of the model. |
40 | |
4ee1bdf4 |
41 | @section occt_tobj_2 TObj Model |
72b7576f |
42 | |
4ee1bdf4 |
43 | @subsection occt_tobj_2_1 TObj Model structure |
72b7576f |
44 | |
45 | In the *TObj* data model the data are separated from the interfaces that manage them. |
72b7576f |
46 | |
dba69de2 |
47 | It 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 |
49 | Logically 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 | |
54 | As the *TObj* Data Model is based on OCAF (Open CASCADE Application Framework) technology, |
55 | it stores its data in the underlying OCAF document. The OCAF document consists of a tree of |
56 | items called *labels*. Each label has some data attached to it in the form of *attributes*, |
57 | and may contain an arbitrary number of sub-labels. Each sub-label is identified by its sequential |
58 | number called the *tag*. The complete sequence of tag numbers of the label |
59 | and its parents starting from the document root constitutes the complete *entry* |
60 | of the label, which uniquely identifies its position in the document. |
61 | |
62 | Generally the structure of the OCAF tree of the *TObj* data |
63 | model 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 |
68 | All data of the model are stored in the root label (0:1) of the OCAF document. |
dba69de2 |
69 | An attribute *TObj_TModel* is located in this root label. It |
72b7576f |
70 | stores the object of type *TObj_Model*. This object serves as a main interface tool |
71 | to access all data and functionalities of the data model. |
72 | |
73 | In simple cases all data needed by the application may be |
74 | contained in a single data model. Moreover, *TObj* gives the possibility to |
75 | distribute the data between several interconnected data models. This can be |
76 | especially useful for the applications dealing with great amounts of data. because |
77 | only the data required for the current operation is loaded in the memory at one time. |
78 | It is presumed that the models have a hierarchical (tree-like) structure, |
79 | where the objects of the child models can refer to the objects of the parent |
80 | models, not vice-versa. Provided that the correct order of loading and closing |
81 | of 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 | |
85 | The 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 | |
99 | The persistent representation of any OCAF model is contained in an XML or a binary file, |
100 | which is defined by the format string returned by the method *GetFormat*. |
101 | The default implementation works with a binary OCAF document format (*BinOcaf*). |
102 | The other available format is *XmlOcaf*. The class **TObj_Model** declares and provides a default |
103 | implementation 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 | |
110 | which retrieve and store the model from or |
111 | in the OCAF file. The descendants |
112 | should 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 | |
118 | This method is called by *Load* after creation of a new model |
119 | or after its loading from the file; its purpose is to perform |
120 | the necessary initialization of the model (such as creation of necessary top-level |
121 | partitions, model update due to version changes etc.). Note that if |
122 | the specified file does not exist, method *Load* will create |
123 | a new document and call *initNewModel* with the argument **True**. |
124 | If the file has been normally loaded, the argument **False** is passed. |
125 | Thus, a new empty *TObj* model is created by calling *Load* with an empty |
126 | string or the path to a nonexistent file as argument. |
127 | |
128 | The 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. |
130 | If no errors have been detected during initialization (model retrieval or creation), |
131 | the virtual method *AfterRetrieval* is invoked for all objects of the model. |
132 | This method initializes or updates the objects immediately after the model initialization. |
133 | It could be useful when some object data should be imported from an OCAF attribute into transient |
134 | fields which could be changed outside of the OCAF transaction mechanism. |
135 | Such fields can be stored into OCAF attributes for saving into persistent storage during the save operation. |
136 | |
137 | To avoid memory leaks, the *TObj_Model* class destructor invokes *Close* method |
138 | which clears the OCAF document and removes all data from memory before the model is destroyed. |
dba69de2 |
139 | |
72b7576f |
140 | For XML and binary persistence of the *TObj* data model the corresponding drivers are implemented |
141 | in *BinLDrivers*, *BinMObj* and *XmlLDrivers*, *XmlMObj* packages. |
142 | These packages contain retrieval and storage drivers for the model, model objects and custom attributes |
143 | from the *TObj* package. The schemas support persistence for the standard OCAF and *TObj* attributes. |
144 | This is sufficient for the implementation of simple data models, but |
145 | in some cases it can be reasonable to add specific OCAF attributes to |
146 | facilitate the storage of the data specific to the application. |
147 | In 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 | |
151 | All objects in the model are stored in the main partition and accessed by iterators. |
152 | To access all model objects use: |
153 | |
dba69de2 |
154 | ~~~~~{.cpp} |
72b7576f |
155 | virtual Handle(TObj_ObjectIterator) GetObjects () const; |
dba69de2 |
156 | ~~~~~ |
72b7576f |
157 | |
158 | This 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 | |
164 | This method returns an iterator on child objects of the main partition. |
165 | Use the following method to get the main partition: |
166 | |
dba69de2 |
167 | ~~~~~{.cpp} |
72b7576f |
168 | Handle(TObj_Partition) GetMainPartition() const; |
dba69de2 |
169 | ~~~~~ |
72b7576f |
170 | |
171 | To 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 | |
177 | The 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 | |
183 | This method returns (creating if necessary) a partition in the specified label of the document. |
184 | The partition can be created as hidden (*TObj_HiddenPartition* class). |
185 | A hidden partition can be useful to distinguish the data that |
186 | should not be visible to the user when browsing the model in the application. |
187 | |
188 | The following two methods allow getting (creating) a partition |
189 | in 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 | |
197 | If the default object naming and the name register mechanism |
198 | is 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 | |
206 | The model object can store its own data in the Data label |
207 | of its main partition, however, there is no standard API for |
208 | setting and getting these data types. The descendants can add |
209 | their own data using standard OCAF methods. The enumeration DataTag is defined |
210 | in *TObj_Model* to avoid conflict of data labels used by this class |
211 | and its descendants, similarly to objects (see below). |
212 | |
dba69de2 |
213 | @subsection occt_tobj_2_6 Object naming |
72b7576f |
214 | |
215 | The basic implementation of *TObj_Model* provides the default |
216 | naming mechanism: all objects must have unique names, |
217 | which are registered automatically in the data model dictionary. |
218 | The dictionary is a *TObj_TNameContainer* |
219 | attribute whose instance is located in the model root label. |
220 | If necessary, the developer can add several dictionaries into |
221 | the specific partitions, providing the name registration in the |
222 | correct name dictionary and restoring the name map after document is loaded from file. |
223 | To 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. |
225 | Use 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 | |
231 | Returns **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 | |
237 | Registers the object name with the indicated label where the object |
238 | is located in the OCAF document. Note that the default implementation |
239 | of 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 | |
246 | Unregisters the name from the dictionary. Ther names of *TObj* model |
247 | objects 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 | |
253 | Returns a default instance of the model dictionary (located at the model root label). |
254 | The default implementation works only with one dictionary. |
255 | If there are a necessity to have more than one dictionary for the model objects, |
256 | it is recommended to redefine the corresponding virtual method of TObj_Object |
257 | that returns the dictionary where names of objects should be registered. |
258 | |
dba69de2 |
259 | @subsection occt_tobj_2_7 API for transaction mechanism |
72b7576f |
260 | |
261 | Class *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 | |
267 | Returns True if a Command transaction is open |
268 | |
ad211ad3 |
269 | ~~~~~{.cpp} |
72b7576f |
270 | void OpenCommand() const; |
ad211ad3 |
271 | ~~~~~ |
72b7576f |
272 | |
273 | Opens a new command transaction. |
274 | |
ad211ad3 |
275 | ~~~~~{.cpp} |
72b7576f |
276 | void CommitCommand() const; |
ad211ad3 |
277 | ~~~~~ |
72b7576f |
278 | |
279 | Commits 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 | |
285 | Aborts 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 | |
291 | Returns 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 | |
297 | Changes the modified status by force. For synchronization of transactions |
298 | within several *TObj_Model* documents use class *TDocStd_MultiTransactionManager*. |
299 | |
dba69de2 |
300 | @subsection occt_tobj_28 Model format and version |
72b7576f |
301 | |
302 | Class *TObj_Model* provides the descendant classes with a means to control |
303 | the 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 | |
309 | Returns the string *TObjBin* or *TObjXml* indicating |
310 | the current persistent mechanism. The default value is *TObjBin*. |
311 | Due to the evolution of functionality of the developed application, |
312 | the contents and the structure of its data model vary from version to version. |
313 | *TObj* package provides a basic mechanism supporting backward versions compatibility, |
314 | which means that newer versions of the application will be able to read |
315 | Data Model files created by previous versions (but not vice-versa) with a minimum loss of data. |
316 | For each type of Data Model, all known versions of the data format |
317 | should be enumerated in increasing order, incremented with every change |
318 | of the model format. The current version of the model |
319 | format 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 | |
325 | Returns the format version stored in the model file |
326 | |
ad211ad3 |
327 | ~~~~~{.cpp} |
72b7576f |
328 | void SetFormatVersion(const Standard_Integer theVersion); |
ad211ad3 |
329 | ~~~~~ |
72b7576f |
330 | |
331 | Defines the format version used for save. |
332 | |
333 | Upon loading a model, the method *initNewModel()*, called immediately |
334 | after opening a model from disk (on the level of the OCAF document), |
335 | provides a specific code that checks the format version stored in that model. |
336 | If it is older than the current version of the application, the data update can be performed. |
337 | Each model can have its own specific conversion code |
338 | that performs the necessary data conversion to make them compliant with the current version. |
339 | |
340 | When the conversion ends the user is advised of that by the messenger interface |
341 | provided by the model (see messaging chapter for more details), |
342 | and 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. |
344 | The program updating the model after version change can be implemented as static |
345 | methods directly in C++ files of the corresponding Data Model classes, |
346 | not exposing it to the other parts of the application. |
347 | These codes can use direct access to the model and objects data (attributes) |
348 | not using objects interfaces, because the data model API and object classes |
349 | could have already been changed. |
350 | |
351 | Note that this mechanism has been designed to maintain version compatibility |
352 | for the changes of data stored in the model, not for the changes of |
353 | low-level format of data files (such as the storage format of a specific OCAF attribute). |
354 | If 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 | |
358 | The following methods are used for model update to ensure its consistency |
359 | with 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 | |
365 | This method is usually called after loading of the model. |
366 | The 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 | |
372 | This 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 | |
378 | This method is called from the previous method to update back references |
379 | of 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 | |
384 | To copy the model between OCAF documents use the following methods: |
385 | |
ad211ad3 |
386 | ~~~~~{.cpp} |
4ee1bdf4 |
387 | virtual Standard_Boolean Paste (Handle(TObj_Model) theModel, Handle(TDF_RelocationTable) theRelocTable = 0 ); |
ad211ad3 |
388 | ~~~~~ |
72b7576f |
389 | |
390 | Pastes the current model to the new model. The relocation table |
391 | ensures correct copying of the sub-data shared by several parts of the model. |
392 | It stores a map of processed original objects of relevant types in their copies. |
393 | |
ad211ad3 |
394 | ~~~~~{.cpp} |
4ee1bdf4 |
395 | virtual Handle(TObj_Model) NewEmpty() = 0; |
ad211ad3 |
396 | ~~~~~ |
72b7576f |
397 | |
398 | Redefines a pure virtual method to create a new empty instance of the model. |
399 | |
ad211ad3 |
400 | ~~~~~{.cpp} |
4ee1bdf4 |
401 | void CopyReferences ( const Handle(TObj_Model)& theTarget, const Handle(TDF_RelocationTable)& theRelocTable); |
ad211ad3 |
402 | ~~~~~ |
72b7576f |
403 | |
404 | Copies the references from the current model to the target model. |
405 | |
dba69de2 |
406 | @subsection occt_tobj_2_11 Messaging |
72b7576f |
407 | |
408 | The messaging is organised using Open CASCADE Messenger from the package Message. |
409 | The messenger is stored as the field of the model instance |
410 | and 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 | |
417 | A developer should create his own instance of the Messenger |
418 | bound to the application user interface, and attribute it to the model |
419 | for future usage. In particular the messenger is used for reporting |
420 | errors and warnings in the persistence mechanism. |
421 | Each message has a unique string identifier (key). |
422 | All message keys are stored in a special resource file TObj.msg. |
423 | This file should be loaded at the start of the application |
424 | by call to the appropriate method of the class *Message_MsgFile*. |
425 | |
dba69de2 |
426 | @section occt_tobj_3 Model object |
72b7576f |
427 | |
428 | Class *TObj_Object* provides basic interface and default implementation |
429 | of important features of *TObj* model objects. This implementation defines |
430 | basic approaches that are recommended for all descendants, |
431 | and 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 | |
438 | In the *TObj* data model, the data are separated from the interfaces that manage them. |
439 | The data belonging to a model object are stored in its root label and sub-labels |
440 | in the form of standard OCAF attributes. This allows using standard OCAF mechanisms |
441 | for work with these data, and eases the implementation of the persistence mechanism. |
dba69de2 |
442 | |
72b7576f |
443 | The 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, |
445 | and typically does not bring its own data. The interface classes are organized in a hierarchy |
446 | corresponding to the natural hierarchy of the model objects according to the application. |
dba69de2 |
447 | |
72b7576f |
448 | In the text below the term 'object' is used to denote either the instance |
449 | of the interface class or the object itself (both interface and data stored in OCAF). |
dba69de2 |
450 | |
72b7576f |
451 | The special type of attribute *TObj_TObject* is used for storing instances of objects interfaces |
452 | in the OCAF tree. *TObj_TObject* is a simple container for the object of type *TObj_Object*. |
dba69de2 |
453 | All objects (interfaces) of the data model inherit this class. |
72b7576f |
454 | |
4ee1bdf4 |
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 | |
461 | The *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* |
4ee1bdf4 |
468 | * References to other objects stored in the label returned by the method *GetReferenceLabel* |
dba69de2 |
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 | |
480 | An 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 |
486 | Returns *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 | |
492 | Returns the father object of the indicated type |
493 | for 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 | |
497 | As far as the data objects are separated from the interfaces and stored in the OCAF tree, |
498 | the functionality to support inheritance is required. Each object has its own data |
499 | and references stored in the labels in the OCAF tree. All data are stored in the sub-tree |
500 | of the main object label. If it is necessary to inherit a class from the base class, |
501 | the descendant class should use different labels for data and references than its ancestor. |
dba69de2 |
502 | |
72b7576f |
503 | Therefore each *TObj* class can reserve the range of tags in each of |
504 | *Data*, *References*, and *Child* sub-labels. |
505 | The reserved range is declared by the enumeration defined |
506 | in the class scope (called DataTag, RefTag, and ChildTag, respectively). |
507 | The item *First* of the enumeration of each type is defined via the *Last* item |
508 | of the corresponding enumeration of the parent class, thus ensuring that the tag numbers |
509 | do not overlap. The item *Last* of the enumeration defines the last tag reserved by this class. |
510 | Other items of the enumeration define the tags used for storing particular data items of the object. |
511 | See the declaration of the TObj_Partition class for the example. |
512 | |
513 | *TObj_Object* class provides a set of auxiliary methods for descendants |
514 | to 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 | |
521 | Returns the label in *Data* or *References* sub-labels at a given tag number (theRank1). |
522 | The second argument, theRank2, allows accessing the next level of hierarchy |
523 | (theRank2-th sub-label of theRank1-th data label). |
524 | This is useful when the data to be stored are represented by multiple OCAF attributes |
525 | of the same type (e.g. sequences of homogeneous data or references). |
dba69de2 |
526 | |
72b7576f |
527 | The get/set methods allow easily accessing the data located in the specified data label |
528 | for the most widely used data types (*Standard_Real*, *Standard_Integer*, *TCollection_HExtendedString*, |
529 | *TColStd_HArray1OfReal*, *TColStd_HArray1OfInteger*, *TColStd_HArray1OfExtendedString*). |
530 | For 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 | |
537 | Similar 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 | |
544 | The 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 | |
550 | Note that while references to other objects should be defined by descendant classes |
551 | individually according to the type of object, *TObj_Object* provides methods |
552 | to 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 | |
556 | The persistence of the *TObj* Data Model is implemented with the help |
557 | of standard OCAF mechanisms (a schema defining necessary plugins, drivers, etc.). |
558 | This implies the possibility to store/retrieve all data that are stored |
559 | as standard OCAF attributes., The corresponding handlers are added |
560 | to the drivers for *TObj*-specific attributes. |
dba69de2 |
561 | |
72b7576f |
562 | The special tool is provided for classes inheriting from *TObj_Object* |
563 | to add the new types of persistence without regeneration of the OCAF schema. |
564 | The 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 | |
569 | Two macros defined in the file TObj_Persistence.hxx have to be included in the definition |
570 | of 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 | |
576 | Should 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, |
578 | and declares an auxiliary (private) class inheriting *TObj_Persistence* |
579 | that 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 | |
585 | Should be included in .cxx file of each object class that should be saved and restored. |
586 | This is not needed for abstract types of objects. This macro implements the functions |
587 | declared by the previous macro and creates a static member |
588 | that automatically registers that type for persistence. |
589 | |
590 | When the attribute *TObj_TObject* that contains the interface object is saved, |
591 | its persistence handler stores the runtime type of the object class. |
592 | When the type is restored the handler dynamically recognizes the type |
593 | and creates the corresponding object using mechanisms provided by *TObj_Persistence*. |
594 | |
dba69de2 |
595 | @subsection occt_tobj_35 Names of objects |
72b7576f |
596 | |
dba69de2 |
597 | All *TObj* model objects have names by which the user can refer to the object. |
72b7576f |
598 | Upon creation, each object receives a default name, constructed |
599 | from the prefix corresponding to the object type (more precisely, the prefix is defined |
600 | by the partition to which the object belongs), and the index of the object in the current partition. |
601 | The user has the possibility to change this name. The uniqueness of the name in the model is ensured |
602 | by the naming mechanism (if the name is already used, it cannot be attributed to another object). |
603 | This default implementation of *TObj* package works with a single instance of the name container (dictionary) |
604 | for name registration of objects and it is enough in most simple projects. |
605 | If 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 |
608 | This functionality is provided by the following methods: |
609 | |
ad211ad3 |
610 | ~~~~~{.cpp} |
72b7576f |
611 | virtual Handle(TObj_TNameContainer) GetDictionary() const; |
ad211ad3 |
612 | ~~~~~ |
72b7576f |
613 | |
614 | Returns the name container where the name of object should be registered. |
615 | The 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 | |
623 | Returns 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 | |
631 | Attributes a new name to the object and returns **True** if the name has been attributed successfully. |
632 | Returns False if the name has been already attributed to another object. |
633 | The last two methods are short-cuts to the first one. |
634 | |
dba69de2 |
635 | @subsection occt_tobj_36 References between objects |
72b7576f |
636 | |
637 | Class *TObj_Object* allows creating references to other objects in the model. |
638 | Such references describe relations among objects which are not adequately reflected |
639 | by the hierarchical objects structure in the model (parent-child relationship). |
dba69de2 |
640 | |
72b7576f |
641 | The references are stored internally using the attribute TObj_TReference. |
642 | This attribute is located in the sub-label of the referring object (called *master*) |
643 | and keeps reference to the main label of the referred object. |
644 | At 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 | |
651 | The back references are stored not in the OCAF document but as a transient field |
652 | of the object; they are created when the model is restored from file, |
653 | and updated automatically when the references are manipulated. |
654 | The class *TObj_TReference* allows storing references between objects |
655 | from different *TObj* models, facilitating the construction of complex relations between objects. |
dba69de2 |
656 | |
72b7576f |
657 | The 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 | |
663 | Returns 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 | |
669 | Returns an iterator on the object references. The optional argument *theType* |
670 | restricts 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 | |
676 | Removes all references from the current object. |
677 | |
ad211ad3 |
678 | ~~~~~{.cpp} |
72b7576f |
679 | virtual void RemoveReference( const Handle(TObj_Object)& theObject ); |
ad211ad3 |
680 | ~~~~~ |
72b7576f |
681 | |
682 | Removes 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 | |
688 | Returns an iterator on the object back references. |
689 | The 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 | |
695 | Replaces the reference to theOldObject by the reference to *theNewObject*. |
696 | The 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 | |
702 | Replaces all references to a descendant label of *theFromRoot* |
703 | by the references to an equivalent label under *theToRoot*. |
704 | Returns **False** if the resulting reference does not point at a *TObj_Object*. |
705 | Updates 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 | |
711 | Returns **True** if the reference can be removed and the master object |
712 | will remain valid (*weak* reference). |
713 | Returns **False** if the master object cannot be valid without the referred object (*strong* reference). |
714 | This affects the behaviour of objects removal from the model – if the reference cannot be removed, |
715 | either the referred object will not be removed, or both the referred |
716 | and 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 | |
720 | It is recommended that all objects inheriting from *TObj_Object* |
721 | should implement the same approach to creation and deletion. |
dba69de2 |
722 | |
72b7576f |
723 | The object of the *TObj* data model cannot be created independently |
724 | of the model instance, as far as it stores the object data in OCAF data structures. |
725 | Therefore an object class cannot be created directly as its constructor is protected. |
dba69de2 |
726 | |
72b7576f |
727 | Instead, each object should provide a static method *Create*(), which accepts the model, |
728 | with the label, which stores the object and other type-dependent parameters |
729 | necessary 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 |
732 | The method *Detach*() is provided for deletion of objects from OCAF model. |
733 | Object data are deleted from the corresponding OCAF label; however, |
734 | the handle on object remains valid. The only operation available after object deletion |
dba69de2 |
735 | is the method *IsAlive*() checking whether the object has been deleted or not, |
72b7576f |
736 | which returns False if the object has been deleted. |
737 | |
738 | When the object is deleted from the data model, the method checks |
739 | whether there are any alive references to the object. |
740 | Iterating on references the object asks each referring (master) object |
741 | whether the reference can be removed. If the master object can be unlinked, |
742 | the reference is removed, otherwise the master object will be removed too |
743 | or the referred object will be kept alive. This check is performed by the method *Detach* , |
744 | but 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 | |
750 | The 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 | |
756 | Returns **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 | |
762 | Removes the object from the document if possible |
763 | (according to the indicated deletion mode). |
764 | Unlinks references from removed objects. |
765 | Returns **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 | |
775 | Copies the object to theTargetLabel. The new object will have all references of its original. |
776 | Returns a handle to the new object (null handle if fail). The data are copied directly, |
777 | but the name is changed by adding the postfix *_copy*. |
778 | To 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 | |
784 | Returns the name for a new object copy. It could be useful to return the same object name |
785 | if the copy will be in the other model or in the other partition with its own dictionary. |
786 | The 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 | |
792 | Adds 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 | |
798 | Copies the children of an object to the target child label. |
799 | |
dba69de2 |
800 | @subsection occt_tobj_3_9 Object flags |
72b7576f |
801 | |
dba69de2 |
802 | Each instance of *TObj_Object* stores a set of bit flags, |
72b7576f |
803 | which 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 | |
812 | The user (developer) can define any new flags in descendant classes. |
813 | To 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 | |
822 | In addition, the generic virtual interface stores the logical properties |
823 | of the object class in the form of a set of bit flags. |
824 | Type flags can be received by the method: |
825 | |
ad211ad3 |
826 | ~~~~~{.cpp} |
72b7576f |
827 | virtual Standard_Integer GetTypeFlags() const; |
ad211ad3 |
828 | ~~~~~ |
72b7576f |
829 | |
830 | The default implementation returns the flag **Visible** |
dba69de2 |
831 | defined in the enumeration *TypeFlags*. This flag is used to define visibility |
832 | of the object for the user browsing the model (see class *TObj_HiddenPartition*). |
72b7576f |
833 | Other flags can be added by the applications. |
834 | |
dba69de2 |
835 | @subsection occt_tobj_310 Partitions |
72b7576f |
836 | |
837 | The special kind of objects defined by the class *TObj_Partition* |
838 | (and its descendant *TObj_HiddenPartition*) is provided for partitioning |
839 | the model into a hierarchical structure. This object represents the container |
840 | of other objects. Each *TObj* model contains the main partition that is placed |
841 | in the same OCAF label as the model object, and serves as a root of the object's tree. |
842 | A hidden partition is a simple partition with a predefined hidden flag. |
dba69de2 |
843 | |
72b7576f |
844 | The main partition object methods: |
845 | |
ad211ad3 |
846 | ~~~~~{.cpp} |
72b7576f |
847 | TDF_Label NewLabel() const; |
ad211ad3 |
848 | ~~~~~ |
72b7576f |
849 | |
850 | Allocates 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 | |
856 | Defines 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 | |
862 | Returns the current name prefix. |
863 | |
ad211ad3 |
864 | ~~~~~{.cpp} |
72b7576f |
865 | Handle(TCollection_HExtendedString) GetNewName ( const Standard_Boolean theIsToChangeCount) const; |
ad211ad3 |
866 | ~~~~~ |
72b7576f |
867 | |
868 | Generates 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 | |
874 | Returns the last reserved child index. |
875 | |
ad211ad3 |
876 | ~~~~~{.cpp} |
72b7576f |
877 | void SetLastIndex( const Standard_Integer theIndex ); |
ad211ad3 |
878 | ~~~~~ |
72b7576f |
879 | |
880 | Sets the last reserved index. |
881 | |
dba69de2 |
882 | @section occt_tobj_4 Auxiliary classes |
72b7576f |
883 | |
884 | Apart 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 | |
899 | The 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 | |
907 | The *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 | |