@section occt_ocaf_1 Introduction
This manual explains how to use the Open CASCADE Application Framework (OCAF).
-It provides basic documentation on using OCAF. For advanced information on OCAF
-and its applications, see our <a href="https://www.opencascade.com/content/tutorial-learning">E-learning & Training</a> offerings.
+It provides basic documentation on using OCAF.
@subsection occt_ocaf_1_1 Purpose of OCAF
Let’s study the implementation of the same data type in both ways by the example of transformation represented by *gp_Trsf* class. The class *gp_Trsf* defines the transformation according to the type (*gp_TrsfForm*) and a set of parameters of the particular type of transformation (two points or a vector for translation, an axis and an angle for rotation, and so on).
-1. The first way: creation of a new attribute. The implementation of the transformation by creation of a new attribute is represented in the @ref occt_ocaf_11 "Samples".
+1. The first way: creation of a new attribute. The implementation of the transformation by creation of a new attribute is represented in the @ref samples__ocaf "Samples".
2. The second way: creation of a new data type by means of combination of standard attributes. Depending on the type of transformation it may be kept in data framework by different standard attributes. For example, a translation is defined by two points. Therefore the data tree for translation looks like this:
* Type of transformation <i>(gp_Translation)</i> as *TDataStd_Integer*;
* Add (in the new *DocumentStorageDriver*) the *targetNamespace* accompanied with its prefix, using method *XmlDrivers_DocumentStorageDriver::AddNamespace*. The same is done for all namespaces objects which are used by the new persistence, with the exception of the "ocaf" namespace.
* Pass (in every OCAF attribute driver) the namespace prefix of the *targetNamespace* to the constructor of *XmlMDF_ADriver*.
-@section occt_ocaf_10 GLOSSARY
+@section occt_tobj TObj Package
-* **Application** -- a document container holding all documents containing all application data.
-* **Application data** -- the data produced by an application, as opposed to data referring to it.
-* **Associativity of data** -- the ability to propagate modifications made to one document to other documents, which refer to such document. Modification propagation is:
- * unidirectional, that is, from the referenced to the referencing document(s), or
- * bi-directional, from the referencing to the referenced document and vice-versa.
-* **Attribute** -- a container for application data. An attribute is attached to a label in the hierarchy of the data framework.
-* **Child** -- a label created from another label, which by definition, is the father label.
-* **Compound document** -- a set of interdependent documents, linked to each other by means of external references. These references provide the associativity of data.
-* **Data framework** -- a tree-like data structure which in OCAF, is a tree of labels with data attached to them in the form of attributes. This tree of labels is accessible through the services of the *TDocStd_Document* class.
-* **Document** -- a container for a data framework which grants access to the data, and is, in its turn, contained by an application. A document also allows you to:
- * Manage modifications, providing Undo and Redo functions
- * Manage command transactions
- * Update external links
- * Manage save and restore options
- * Store the names of software extensions.
-* **Driver** -- an abstract class, which defines the communications protocol with a system.
-* **Entry** -- an ASCII character string containing the tag list of a label. For example:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-0:3:24:7:2:7
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+@subsection occt_tobj_1 Introduction
-* **External links** -- references from one data structure to another data structure in another document.
-To store these references properly, a label must also contain an external link attribute.
-* **Father** -- a label, from which other labels have been created. The other labels are, by definition, the children of this label.
-* **Framework** -- a group of co-operating classes which enable a design to be re-used for a given category of problem. The framework guides the architecture of the application by breaking it up into abstract classes, each of which has different responsibilities and collaborates in a predefined way. Application developer creates a specialized framework by:
- * defining new classes which inherit from these abstract classes
- * composing framework class instances
- * implementing the services required by the framework.
+This document describes the package TObj, which is an add-on
+to the Open CASCADE Application Framework (OCAF).
-In C++, the application behavior is implemented in virtual functions redefined in these derived classes. This is known as overriding.
+This package provides a set of classes and auxiliary tools facilitating
+the creation of object-oriented data models on top of low-level OCAF data structures.
+This includes:
-* **GUID** -- Global Universal ID. A string of 37 characters intended to uniquely identify an object. For example:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-2a96b602-ec8b-11d0-bee7-080009dc3333
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ * 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).
+ * Organization of the data model as a hierarchical (tree-like) structure of objects.
+ * Support of cross-references between objects within one model or among different models. In case of cross-model references the models should depend hierarchically.
+ * Persistence mechanism for storing *TObj* objects in OCAF files, which allows storing and retrieving objects of derived types without writing additional code to support persistence.
-* **Label** -- a point in the data framework, which allows data to be attached to it by means of attributes. It has a name in the form of an entry, which identifies its place in the data framework.
-* **Modified label** -- containing attributes whose data has been modified.
-* **Reference key** -- an invariant reference, which may refer to any type of data used in an application. In its transient form, it is a label in the data framework, and the data is attached to it in the form of attributes. In its persistent form, it is an entry of the label. It allows an application to recover any entity in the current session or in a previous session.
-* **Resource file** -- a file containing a list of each document’s schema name and the storage and retrieval plug-ins for that document.
-* **Root** -- the starting point of the data framework. This point is the top label in the framework. It is represented by the [0] entry and is created at the same time with the document you are working on.
-* **Scope** -- the set of all the attributes and labels which depend on a given label.
-* **Tag list** -- a list of integers, which identify the place of a label in the data framework. This list is displayed in an entry.
-* **Topological naming** -- systematic referencing of topological entities so that these entities can still be identified after the models they belong to have gone through several steps in modeling. In other words, topological naming allows you to track entities through the steps in the modeling process. This referencing is needed when a model is edited and regenerated, and can be seen as a mapping of labels and name attributes of the entities in the old version of a model to those of the corresponding entities in its new version. Note that if the topology of a model changes during the modeling, this mapping may not fully coincide. A Boolean operation, for example, may split edges.
-* **Topological tracking** -- following a topological entity in a model through the steps taken to edit and regenerate that model.
-* **Valid label** -- in a data framework, this is a label, which is already recomputed in the scope of regeneration sequence and includes the label containing a feature which is to be recalculated. Consider the case of a box to which you first add a fillet, then a protrusion feature. For recalculation purposes, only valid labels of each construction stage are used. In recalculating a fillet, they are only those of the box and the fillet, not the protrusion feature which was added afterwards.
+This document describes basic principles of logical and physical organization
+of TObj-based data models and typical approaches to implementation of classes representing model objects.
-@section occt_ocaf_11 Samples
+@subsubsection occt_tobj_1_1 Applicability
-@subsection occt_ocaf_11_a Getting Started
+The main purpose of the *TObj* data model is rapid development
+of the object-oriented data models for applications, using the existing
+functionality provided by OCAF (Undo/Redo and persistence)
+without the necessity to redevelop such functionality from scratch.
- At the beginning of your development, you first define an application class by inheriting from the Application abstract class.
- You only have to create and determine the resources of the application
- for specifying the format of your documents (you generally use the standard one) and their file extension.
-
- Then, you design the application data model by organizing attributes you choose among those provided with OCAF.
- You can specialize these attributes using the User attribute. For example, if you need a reflection coefficient,
- you aggregate a User attribute identified as a reflection coefficient
- with a Real attribute containing the value of the coefficient (as such, you don't define a new class).
-
- If you need application specific data not provided with OCAF, for example,
- to incorporate a finite element model in the data structure,
- you define a new attribute class containing the mesh,
- and you include its persistent homologue in a new file format.
-
- Once you have implemented the commands which create and modify the data structure
- according to your specification, OCAF provides you, without any additional programming:
-
- * Persistent reference to any data, including geometric elements — several documents can be linked with such reference;
- * Document-View association;
- * Ready-to-use functions such as :
- * Undo-redo;
- * Save and open application data.
-
- Finally, you develop the application's graphical user interface using the toolkit of your choice, for example:
- * KDE Qt or GNOME GTK+ on Linux;
- * Microsoft Foundation Classes (MFC) on Windows Motif on Sun;
- * Other commercial products such as Ilog Views.
+As opposed to using bare OCAF (at the level of labels and attributes),
+TObj facilitates dealing with higher level abstracts, which are closer
+to the application domain. It works best when the application data are naturally
+organized in hierarchical structures, and is especially useful for complex data
+models with dependencies between objects belonging to different parts of the model.
+
+It should be noted that *TObj* is efficient for representing data structures containing
+a limited number of objects at each level of the data structure (typically less than 1000).
+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
+can be combined with the usage of *TObj* to represent the high-level structure of the model.
+
+@subsection occt_tobj_2 TObj Model
+
+@subsubsection occt_tobj_2_1 TObj Model structure
+
+In the *TObj* data model the data are separated from the interfaces that manage them.
+
+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.
+
+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.
+
+@figure{/user_guides/ocaf/images/tobj_image003.png,"TObj Data Model",240}
+
+As the *TObj* Data Model is based on OCAF (Open CASCADE Application Framework) technology,
+it stores its data in the underlying OCAF document. The OCAF document consists of a tree of
+items called *labels*. Each label has some data attached to it in the form of *attributes*,
+and may contain an arbitrary number of sub-labels. Each sub-label is identified by its sequential
+number called the *tag*. The complete sequence of tag numbers of the label
+and its parents starting from the document root constitutes the complete *entry*
+of the label, which uniquely identifies its position in the document.
+
+Generally the structure of the OCAF tree of the *TObj* data
+model corresponds to the logical structure of the model and can be presented as in the following picture:
+
+@figure{/user_guides/ocaf/images/tobj_image004.png,"TObj Data Model mapped on OCAF document",360}
+
+All data of the model are stored in the root label (0:1) of the OCAF document.
+An attribute *TObj_TModel* is located in this root label. It
+stores the object of type *TObj_Model*. This object serves as a main interface tool
+to access all data and functionalities of the data model.
+
+In simple cases all data needed by the application may be
+contained in a single data model. Moreover, *TObj* gives the possibility to
+distribute the data between several interconnected data models. This can be
+especially useful for the applications dealing with great amounts of data. because
+only the data required for the current operation is loaded in the memory at one time.
+It is presumed that the models have a hierarchical (tree-like) structure,
+where the objects of the child models can refer to the objects of the parent
+models, not vice-versa. Provided that the correct order of loading and closing
+of the models is ensured, the *TObj* classes will maintain references between the objects automatically.
+
+@subsubsection occt_tobj_2_2 Data Model basic features
+
+The class *TObj_Model* describing the data model provides the following functionalities:
+
+ * Loading and saving of the model from or in a file (methods *Load* and *Save*)
+ * Closing and removal of the model from memory (method *Close*)
+ * Definition of the full file name of the persistence storage for this model (method *GetFile*)
+ * Tools to organize data objects in partitions and iterate on objects (methods *GetObjects*, *GetMainPartition*, *GetChildren*, *getPartition*, *getElementPartition*)
+ * Mechanism to give unique names to model objects
+ * Copy (*clone*) of the model (methods *NewEmpty* and *Paste*)
+ * 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*)
+ * Interface to check and update the model if necessary (method *Update*)
+ * 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*)
+
+@subsubsection occt_tobj_2_3 Model Persistence
+
+The persistent representation of any OCAF model is contained in an XML or a binary file,
+which is defined by the format string returned by the method *GetFormat*.
+The default implementation works with a binary OCAF document format (*BinOcaf*).
+The other available format is *XmlOcaf*. The class **TObj_Model** declares and provides a default
+implementation of two virtual methods:
+
+~~~~~{.cpp}
+ virtual Standard_Boolean Load (const char* theFile);
+ virtual Standard_Boolean SaveAs (const char* theFile);
+~~~~~
+
+which retrieve and store the model from or
+in the OCAF file. The descendants
+should define the following protected method to support Load and Save operations:
+
+~~~~~{.cpp}
+ virtual Standard_Boolean initNewModel (const Standard_Boolean IsNew);
+~~~~~
+
+This method is called by *Load* after creation of a new model
+or after its loading from the file; its purpose is to perform
+the necessary initialization of the model (such as creation of necessary top-level
+partitions, model update due to version changes etc.). Note that if
+the specified file does not exist, method *Load* will create
+a new document and call *initNewModel* with the argument **True**.
+If the file has been normally loaded, the argument **False** is passed.
+Thus, a new empty *TObj* model is created by calling *Load* with an empty
+string or the path to a nonexistent file as argument.
+
+The method *Load* returns **True** if the model has been retrieved successfully
+(or created a new), or **False** if the model could not be loaded.
+If no errors have been detected during initialization (model retrieval or creation),
+the virtual method *AfterRetrieval* is invoked for all objects of the model.
+This method initializes or updates the objects immediately after the model initialization.
+It could be useful when some object data should be imported from an OCAF attribute into transient
+fields which could be changed outside of the OCAF transaction mechanism.
+Such fields can be stored into OCAF attributes for saving into persistent storage during the save operation.
+
+To avoid memory leaks, the *TObj_Model* class destructor invokes *Close* method
+which clears the OCAF document and removes all data from memory before the model is destroyed.
+
+For XML and binary persistence of the *TObj* data model the corresponding drivers are implemented
+in *BinLDrivers*, *BinMObj* and *XmlLDrivers*, *XmlMObj* packages.
+These packages contain retrieval and storage drivers for the model, model objects and custom attributes
+from the *TObj* package. The schemas support persistence for the standard OCAF and *TObj* attributes.
+This is sufficient for the implementation of simple data models, but
+in some cases it can be reasonable to add specific OCAF attributes to
+facilitate the storage of the data specific to the application.
+In this case the schema should be extended using the standard OCAF mechanism.
+
+@subsubsection occt_tobj_2_4 Access to the objects in the model
+
+All objects in the model are stored in the main partition and accessed by iterators.
+To access all model objects use:
+
+~~~~~{.cpp}
+ virtual Handle(TObj_ObjectIterator) GetObjects () const;
+~~~~~
+
+This method returns a recursive iterator on all objects stored in the model.
+
+~~~~~{.cpp}
+ virtual Handle(TObj_ObjectIterator) GetChildren () const;
+~~~~~
+
+This method returns an iterator on child objects of the main partition.
+Use the following method to get the main partition:
+
+~~~~~{.cpp}
+ Handle(TObj_Partition) GetMainPartition() const;
+~~~~~
+
+To receive the iterator on objects of a specific type *AType* use the following call:
+
+~~~~~{.cpp}
+ GetMainPartition()->GetChildren(STANDARD_TYPE(AType) );
+~~~~~
+
+The set of protected methods is provided for descendant classes to deal with partitions:
+
+~~~~~{.cpp}
+ virtual Handle(TObj_Partition) getPartition (const TDF_Label, const Standard_Boolean theHidden) const;
+~~~~~
+
+This method returns (creating if necessary) a partition in the specified label of the document.
+The partition can be created as hidden (*TObj_HiddenPartition* class).
+A hidden partition can be useful to distinguish the data that
+should not be visible to the user when browsing the model in the application.
+
+The following two methods allow getting (creating) a partition
+in the sub-label of the specified label in the document
+(the label of the main partition for the second method) and with the given name:
+
+~~~~~{.cpp}
+ virtual Handle(TObj_Partition) getPartition (const TDF_Label, const Standard_Integer theIndex, const TCollection_ExtendedString& theName, const Standard_Boolean theHidden) const;
+ virtual Handle(TObj_Partition) getPartition (const Standard_Integer theIndex, const TCollection_ExtendedString& theName, const Standard_Boolean theHidden) const;
+~~~~~
+
+If the default object naming and the name register mechanism
+is turned on, the object can be found in the model by its unique name:
+
+~~~~~{.cpp}
+ Handle(TObj_Object) FindObject (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary) const;
+~~~~~
+
+@subsubsection occt_tobj_2_5 Own model data
+
+The model object can store its own data in the Data label
+of its main partition, however, there is no standard API for
+setting and getting these data types. The descendants can add
+their own data using standard OCAF methods. The enumeration DataTag is defined
+in *TObj_Model* to avoid conflict of data labels used by this class
+and its descendants, similarly to objects (see below).
+
+@subsubsection occt_tobj_2_6 Object naming
+
+The basic implementation of *TObj_Model* provides the default
+naming mechanism: all objects must have unique names,
+which are registered automatically in the data model dictionary.
+The dictionary is a *TObj_TNameContainer*
+attribute whose instance is located in the model root label.
+If necessary, the developer can add several dictionaries into
+the specific partitions, providing the name registration in the
+correct name dictionary and restoring the name map after document is loaded from file.
+To ignore name registering it is necessary to redefine the methods *SetName*,
+*AfterRetrieval* of the *TObj_Object* class and skip the registration of the object name.
+Use the following methods for the naming mechanism:
+
+~~~~~{.cpp}
+ Standard_Boolean IsRegisteredName (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary ) const;
+~~~~~
+
+Returns **True** if the object name is already registered in the indicated (or model) dictionary.
+
+~~~~~{.cpp}
+ void RegisterName (const Handle(TCollection_HExtendedString)& theName, const TDF_Label& theLabel, const Handle(TObj_TNameContainer)& theDictionary ) const;
+~~~~~
+
+Registers the object name with the indicated label where the object
+is located in the OCAF document. Note that the default implementation
+of the method *SetName* of the object registers the new name automatically
+(if the name is not yet registered for any other object)
+
+~~~~~{.cpp}
+ void UnRegisterName (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary ) const;
+~~~~~
+
+Unregisters the name from the dictionary. Ther names of *TObj* model
+objects are removed from the dictionary when the objects are deleted from the model.
+
+~~~~~{.cpp}
+ Handle(TObj_TNameContainer) GetDictionary() const;
+~~~~~
+
+Returns a default instance of the model dictionary (located at the model root label).
+The default implementation works only with one dictionary.
+If there are a necessity to have more than one dictionary for the model objects,
+it is recommended to redefine the corresponding virtual method of TObj_Object
+that returns the dictionary where names of objects should be registered.
+
+@subsubsection occt_tobj_2_7 API for transaction mechanism
+
+Class *TObj_Model* provides the API for transaction mechanism (supported by OCAF):
+
+~~~~~{.cpp}
+ Standard_Boolean HasOpenCommand() const;
+~~~~~
+
+Returns True if a Command transaction is open
+
+~~~~~{.cpp}
+ void OpenCommand() const;
+~~~~~
+
+Opens a new command transaction.
+
+~~~~~{.cpp}
+ void CommitCommand() const;
+~~~~~
+
+Commits the Command transaction. Does nothing If there is no open Command transaction.
+
+~~~~~{.cpp}
+ void AbortCommand() const;
+~~~~~
+
+Aborts the Command transaction. Does nothing if there is no open Command transaction.
+
+~~~~~{.cpp}
+ Standard_Boolean IsModified() const;
+~~~~~
+
+Returns True if the model document has a modified status (has changes after the last save)
+
+~~~~~{.cpp}
+ void SetModified( const Standard_Boolean );
+~~~~~
+
+Changes the modified status by force. For synchronization of transactions
+within several *TObj_Model* documents use class *TDocStd_MultiTransactionManager*.
+
+@subsubsection occt_tobj_28 Model format and version
+
+Class *TObj_Model* provides the descendant classes with a means to control
+the format of the persistent file by choosing the schema used to store or retrieve operations.
+
+~~~~~{.cpp}
+ virtual TCollection_ExtendedString GetFormat () const;
+~~~~~
+
+Returns the string *TObjBin* or *TObjXml* indicating
+the current persistent mechanism. The default value is *TObjBin*.
+Due to the evolution of functionality of the developed application,
+the contents and the structure of its data model vary from version to version.
+*TObj* package provides a basic mechanism supporting backward versions compatibility,
+which means that newer versions of the application will be able to read
+Data Model files created by previous versions (but not vice-versa) with a minimum loss of data.
+For each type of Data Model, all known versions of the data format
+should be enumerated in increasing order, incremented with every change
+of the model format. The current version of the model
+format is stored in the model file and can be checked upon retrieval.
+
+~~~~~{.cpp}
+ Standard_Integer GetFormatVersion() const;
+~~~~~
+
+Returns the format version stored in the model file
+
+~~~~~{.cpp}
+ void SetFormatVersion(const Standard_Integer theVersion);
+~~~~~
+
+Defines the format version used for save.
+
+Upon loading a model, the method *initNewModel()*, called immediately
+after opening a model from disk (on the level of the OCAF document),
+provides a specific code that checks the format version stored in that model.
+If it is older than the current version of the application, the data update can be performed.
+Each model can have its own specific conversion code
+that performs the necessary data conversion to make them compliant with the current version.
+
+When the conversion ends the user is advised of that by the messenger interface
+provided by the model (see messaging chapter for more details),
+and the model version is updated. If the version of data model is not supported
+(it is newer than the current or too old), the load operation should fail.
+The program updating the model after version change can be implemented as static
+methods directly in C++ files of the corresponding Data Model classes,
+not exposing it to the other parts of the application.
+These codes can use direct access to the model and objects data (attributes)
+not using objects interfaces, because the data model API and object classes
+could have already been changed.
+
+Note that this mechanism has been designed to maintain version compatibility
+for the changes of data stored in the model, not for the changes of
+low-level format of data files (such as the storage format of a specific OCAF attribute).
+If the format of data files changes, a specific treatment on a case-by-case basis will be required.
+
+@subsubsection occt_tobj_2_9 Model update
+
+The following methods are used for model update to ensure its consistency
+with respect to the other models in case of cross-model dependencies:
+
+~~~~~{.cpp}
+ virtual Standard_Boolean Update();
+~~~~~
+
+This method is usually called after loading of the model.
+The default implementation does nothing and returns **True**.
+
+~~~~~{.cpp}
+ virtual Standard_Boolean initNewModel( const Standard_Boolean IsNew);
+~~~~~
+
+This method performs model initialization, check and updates (as described above).
+
+~~~~~{.cpp}
+ virtual void updateBackReferences( const Handle(TObj_Object)& theObj);
+~~~~~
+
+This method is called from the previous method to update back references
+of the indicated object after the retrieval of the model from file
+(see data model - object relationship chapter for more details)
+
+@subsubsection occt_tobj_2_10 Model copying
+
+To copy the model between OCAF documents use the following methods:
+
+~~~~~{.cpp}
+ virtual Standard_Boolean Paste (Handle(TObj_Model) theModel, Handle(TDF_RelocationTable) theRelocTable = 0 );
+~~~~~
+
+Pastes the current model to the new model. The relocation table
+ensures correct copying of the sub-data shared by several parts of the model.
+It stores a map of processed original objects of relevant types in their copies.
+
+~~~~~{.cpp}
+ virtual Handle(TObj_Model) NewEmpty() = 0;
+~~~~~
+
+Redefines a pure virtual method to create a new empty instance of the model.
+
+~~~~~{.cpp}
+ void CopyReferences ( const Handle(TObj_Model)& theTarget, const Handle(TDF_RelocationTable)& theRelocTable);
+~~~~~
+
+Copies the references from the current model to the target model.
+
+@subsubsection occt_tobj_2_11 Messaging
+
+The messaging is organised using Open CASCADE Messenger from the package Message.
+The messenger is stored as the field of the model instance
+and can be set and retrieved by the following methods:
+
+~~~~~{.cpp}
+ void SetMessenger( const Handle(Message_Messenger)& );
+ Handle(Message_Messenger) Messenger() const;
+~~~~~
+
+A developer should create his own instance of the Messenger
+bound to the application user interface, and attribute it to the model
+for future usage. In particular the messenger is used for reporting
+errors and warnings in the persistence mechanism.
+Each message has a unique string identifier (key).
+All message keys are stored in a special resource file TObj.msg.
+This file should be loaded at the start of the application
+by call to the appropriate method of the class *Message_MsgFile*.
+
+@subsection occt_tobj_3 Model object
+
+Class *TObj_Object* provides basic interface and default implementation
+of important features of *TObj* model objects. This implementation defines
+basic approaches that are recommended for all descendants,
+and provides tools to facilitate their usage.
+
+@figure{/user_guides/ocaf/images/tobj_image005.png,"TObj objects hierarchy",170}
+
+@subsubsection occt_tobj_3_1 Separation of data and interface
+
+In the *TObj* data model, the data are separated from the interfaces that manage them.
+The data belonging to a model object are stored in its root label and sub-labels
+in the form of standard OCAF attributes. This allows using standard OCAF mechanisms
+for work with these data, and eases the implementation of the persistence mechanism.
+
+The instance of the interface which serves as an API for managing object data
+(e.g. represents the model object) is stored in the root label of the object,
+and typically does not bring its own data. The interface classes are organized in a hierarchy
+corresponding to the natural hierarchy of the model objects according to the application.
+
+In the text below the term 'object' is used to denote either the instance
+of the interface class or the object itself (both interface and data stored in OCAF).
+
+The special type of attribute *TObj_TObject* is used for storing instances of objects interfaces
+in the OCAF tree. *TObj_TObject* is a simple container for the object of type *TObj_Object*.
+All objects (interfaces) of the data model inherit this class.
+
+@figure{/user_guides/ocaf/images/tobj_image006.png,"TObj object stored on OCAF label",360}
+
+
+@subsubsection occt_tobj_3_2 Basic features
+
+The *TObj_Object* class provides some basic features that can be inherited (or, if necessary, redefined) by the descendants:
+
+ * 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*).
+ * Supports references (and back references) to other objects in the same or in another model (methods *getReference*, *setReference*, *addReference*, *GetReferences*, *GetBackReferences*, *AddBackReference*, *RemoveBackReference*, *ReplaceReference*)
+ * Provides the ability to contain child objects, as it is actual for partition objects (methods *GetChildren*, *GetFatherObject*)
+ * 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:
+ * Child objects stored in the label returned by the method *GetChildLabel*
+ * References to other objects stored in the label returned by the method *GetReferenceLabel*
+ * 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*
+ * Provides unique names of all objects in the model (methods *GetDictionary*, *GetName*, *SetName*)
+ * Provides unified means to maintain persistence (implemented in descendants with the help of macros *DECLARE_TOBJOCAF_PERSISTENCE* and *IMPLEMENT_TOBJOCAF_PERSISTENCE*)
+ * 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*)
+ * Implements methods for identification and versioning of objects
+ * Manages the object interaction with OCAF Undo/Redo mechanism (method *IsAlive*, *AfterRetrieval*, *BeforeStoring*)
+ * Allows make a clone (methods *Clone*, *CopyReferences*, *CopyChildren*, *copyData*)
+ * Contains additional word of bit flags (methods *GetFlags*, *SetFlags*, *TestFlags*, *ClearFlags*)
+ * Defines the interface to sort the objects by rank (methods *GetOrder*, *SetOrder*)
+ * Provides a number of auxiliary methods for descendants to set/get the standard attribute values, such as int, double, string, arrays etc.
+
+An object can be received from the model by the following methods:
+
+~~~~~{.cpp}
+ static Standard_Boolean GetObj ( const TDF_Label& theLabel, Handle(TObj_Object)& theResObject, const Standard_Boolean isSuper = Standard_False );
+~~~~~
+
+Returns *True* if the object has been found in the indicated label (or in the upper level label if *isSuper* is *True*).
+
+~~~~~{.cpp}
+ Handle(TObj_Object) GetFatherObject ( const Handle(Standard_Type)& theType = NULL ) const;
+~~~~~
+
+Returns the father object of the indicated type
+for the current object (the direct father object if the type is NULL).
+
+@subsubsection occt_tobj_3_3 Data layout and inheritance
+
+As far as the data objects are separated from the interfaces and stored in the OCAF tree,
+the functionality to support inheritance is required. Each object has its own data
+and references stored in the labels in the OCAF tree. All data are stored in the sub-tree
+of the main object label. If it is necessary to inherit a class from the base class,
+the descendant class should use different labels for data and references than its ancestor.
+
+Therefore each *TObj* class can reserve the range of tags in each of
+*Data*, *References*, and *Child* sub-labels.
+The reserved range is declared by the enumeration defined
+in the class scope (called DataTag, RefTag, and ChildTag, respectively).
+The item *First* of the enumeration of each type is defined via the *Last* item
+of the corresponding enumeration of the parent class, thus ensuring that the tag numbers
+do not overlap. The item *Last* of the enumeration defines the last tag reserved by this class.
+Other items of the enumeration define the tags used for storing particular data items of the object.
+See the declaration of the TObj_Partition class for the example.
+
+*TObj_Object* class provides a set of auxiliary methods for descendants
+to access the data stored in sub-labels by their tag numbers:
+
+~~~~~{.cpp}
+ TDF_Label getDataLabel (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const;
+ TDF_Label getReferenceLabel (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const;
+~~~~~
+
+Returns the label in *Data* or *References* sub-labels at a given tag number (theRank1).
+The second argument, theRank2, allows accessing the next level of hierarchy
+(theRank2-th sub-label of theRank1-th data label).
+This is useful when the data to be stored are represented by multiple OCAF attributes
+of the same type (e.g. sequences of homogeneous data or references).
+
+The get/set methods allow easily accessing the data located in the specified data label
+for the most widely used data types (*Standard_Real*, *Standard_Integer*, *TCollection_HExtendedString*,
+ *TColStd_HArray1OfReal*, *TColStd_HArray1OfInteger*, *TColStd_HArray1OfExtendedString*).
+For instance, methods provided for real numbers are:
+
+~~~~~{.cpp}
+ Standard_Real getReal (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const;
+ Standard_Boolean setReal (const Standard_Real theValue, const Standard_Integer theRank1, const Standard_Integer theRank2 = 0, const Standard_Real theTolerance = 0.) const;
+~~~~~
+
+Similar methods are provided to access references to other objects:
+
+~~~~~{.cpp}
+ Handle(TObj_Object) getReference (const Standard_Integer theRank1, const Standard_Integer theRank2 = 0) const;
+ Standard_Boolean setReference (const Handle(TObj_Object) &theObject, const Standard_Integer theRank1, const Standard_Integer theRank2 = 0);
+~~~~~
+
+The method *addReference* gives an easy way to store a sequence of homogeneous references in one label.
+
+~~~~~{.cpp}
+ TDF_Label addReference (const Standard_Integer theRank1, const Handle(TObj_Object) &theObject);
+~~~~~
+
+Note that while references to other objects should be defined by descendant classes
+individually according to the type of object, *TObj_Object* provides methods
+to manipulate (check, remove, iterate) the existing references in the uniform way, as described below.
+
+@subsubsection occt_tobj_3_4 Persistence
+
+The persistence of the *TObj* Data Model is implemented with the help
+of standard OCAF mechanisms (a schema defining necessary plugins, drivers, etc.).
+This implies the possibility to store/retrieve all data that are stored
+as standard OCAF attributes., The corresponding handlers are added
+to the drivers for *TObj*-specific attributes.
+
+The special tool is provided for classes inheriting from *TObj_Object*
+to add the new types of persistence without regeneration of the OCAF schema.
+The class *TObj_Persistence* provides basic means for that:
+
+ * automatic run-time registration of object types
+ * creation of a new object of the specified type (one of the registered types)
+
+Two macros defined in the file TObj_Persistence.hxx have to be included in the definition
+of each model object class inheriting TObj_Object to activate the persistence mechanism:
+
+~~~~~{.cpp}
+ DECLARE_TOBJOCAF_PERSISTENCE (classname, ancestorname)
+~~~~~
+
+Should be included in the private section of declaration of each class inheriting
+*TObj_Object* (hxx file). This macro adds an additional constructor to the object class,
+and declares an auxiliary (private) class inheriting *TObj_Persistence*
+that provides a tool to create a new object of the proper type.
+
+~~~~~{.cpp}
+ IMPLEMENT_TOBJOCAF_PERSISTENCE (classname)
+~~~~~
+
+Should be included in .cxx file of each object class that should be saved and restored.
+This is not needed for abstract types of objects. This macro implements the functions
+declared by the previous macro and creates a static member
+that automatically registers that type for persistence.
+
+When the attribute *TObj_TObject* that contains the interface object is saved,
+its persistence handler stores the runtime type of the object class.
+When the type is restored the handler dynamically recognizes the type
+and creates the corresponding object using mechanisms provided by *TObj_Persistence*.
+
+@subsubsection occt_tobj_3_5 Names of objects
+
+All *TObj* model objects have names by which the user can refer to the object.
+Upon creation, each object receives a default name, constructed
+from the prefix corresponding to the object type (more precisely, the prefix is defined
+by the partition to which the object belongs), and the index of the object in the current partition.
+The user has the possibility to change this name. The uniqueness of the name in the model is ensured
+by the naming mechanism (if the name is already used, it cannot be attributed to another object).
+This default implementation of *TObj* package works with a single instance of the name container (dictionary)
+for name registration of objects and it is enough in most simple projects.
+If necessary, it is easy to redefine a couple of object methods
+(for instance *GetDictionary*()) and to take care of construction and initialization of containers.
+
+This functionality is provided by the following methods:
+
+~~~~~{.cpp}
+ virtual Handle(TObj_TNameContainer) GetDictionary() const;
+~~~~~
+
+Returns the name container where the name of object should be registered.
+The default implementation returns the model name container.
+
+~~~~~{.cpp}
+ Handle(TCollection_HExtendedString) GetName() const;
+ Standard_Boolean GetName( TCollection_ExtendedString& theName ) const;
+ Standard_Boolean GetName( TCollection_AsciiString& theName ) const;
+~~~~~
+
+Returns the object name. The methods with in / out argument return False if the object name is not defined.
+
+~~~~~{.cpp}
+ virtual Standard_Boolean SetName ( const Handle(TCollection_HExtendedString)& theName ) const;
+ Standard_Boolean SetName ( const Handle(TCollection_HAsciiString)& theName ) const;
+ Standard_Boolean SetName ( const Standard_CString theName ) const;
+~~~~~
+
+Attributes a new name to the object and returns **True** if the name has been attributed successfully.
+Returns False if the name has been already attributed to another object.
+The last two methods are short-cuts to the first one.
+
+@subsubsection occt_tobj_3_6 References between objects
+
+Class *TObj_Object* allows creating references to other objects in the model.
+Such references describe relations among objects which are not adequately reflected
+by the hierarchical objects structure in the model (parent-child relationship).
+
+The references are stored internally using the attribute TObj_TReference.
+This attribute is located in the sub-label of the referring object (called *master*)
+and keeps reference to the main label of the referred object.
+At the same time the referred object can maintain the back reference to the master object.
+
+@figure{/user_guides/ocaf/images/tobj_image007.png,"Objects relationship",360}
+
+
+
+The back references are stored not in the OCAF document but as a transient field
+of the object; they are created when the model is restored from file,
+and updated automatically when the references are manipulated.
+The class *TObj_TReference* allows storing references between objects
+from different *TObj* models, facilitating the construction of complex relations between objects.
+
+The most used methods for work with references are:
+
+~~~~~{.cpp}
+ virtual Standard_Boolean HasReference( const Handle(TObj_Object)& theObject) const;
+~~~~~
+
+Returns True if the current object refers to the indicated object.
+
+~~~~~{.cpp}
+ virtual Handle(TObj_ObjectIterator) GetReferences ( const Handle(Standard_Type)& theType = NULL ) const;
+~~~~~
+
+Returns an iterator on the object references. The optional argument *theType*
+restricts the types of referred objects, or does not if it is NULL.
+
+~~~~~{.cpp}
+ virtual void RemoveAllReferences();
+~~~~~
+
+Removes all references from the current object.
+
+~~~~~{.cpp}
+ virtual void RemoveReference( const Handle(TObj_Object)& theObject );
+~~~~~
+
+Removes the reference to the indicated object.
+
+~~~~~{.cpp}
+ virtual Handle(TObj_ObjectIterator) GetBackReferences ( const Handle(Standard_Type)& theType = NULL ) const;
+~~~~~
+
+Returns an iterator on the object back references.
+The argument theType restricts the types of master objects, or does not if it is NULL.
+
+~~~~~{.cpp}
+ virtual void ReplaceReference ( const Handle(TObj_Object)& theOldObject, const Handle(TObj_Object)& theNewObject );
+~~~~~
+
+Replaces the reference to theOldObject by the reference to *theNewObject*.
+The handle theNewObject may be NULL to remove the reference.
+
+~~~~~{.cpp}
+ virtual Standard_Boolean RelocateReferences ( const TDF_Label& theFromRoot, const TDF_Label& theToRoot, const Standard_Boolean theUpdateackRefs = Standard_True );
+~~~~~
+
+Replaces all references to a descendant label of *theFromRoot*
+by the references to an equivalent label under *theToRoot*.
+Returns **False** if the resulting reference does not point at a *TObj_Object*.
+Updates back references if theUpdateackRefs is **True**.
+
+~~~~~{.cpp}
+ virtual Standard_Boolean CanRemoveReference ( const Handle(TObj_Object)& theObj) const;
+~~~~~
+
+Returns **True** if the reference can be removed and the master object
+will remain valid (*weak* reference).
+Returns **False** if the master object cannot be valid without the referred object (*strong* reference).
+This affects the behaviour of objects removal from the model -- if the reference cannot be removed,
+either the referred object will not be removed, or both the referred
+and the master objects will be removed (depends on the deletion mode in the method **Detach**)
+
+@subsubsection occt_tobj_3_7 Creation and deletion of objects
+
+It is recommended that all objects inheriting from *TObj_Object*
+ should implement the same approach to creation and deletion.
- You can also implement the user interface in the Java language using
- the Swing-based Java Application Desktop component (JAD) provided with OCAF.
-
-@subsection occt_ocaf_11_1 Implementation of Attribute Transformation in a HXX file
+The object of the *TObj* data model cannot be created independently
+of the model instance, as far as it stores the object data in OCAF data structures.
+Therefore an object class cannot be created directly as its constructor is protected.
+
+Instead, each object should provide a static method *Create*(), which accepts the model,
+with the label, which stores the object and other type-dependent parameters
+necessary for proper definition of the object. This method creates a new object with its data
+(a set of OCAF attributes) in the specified label, and returns a handle to the object's interface.
+
+The method *Detach*() is provided for deletion of objects from OCAF model.
+Object data are deleted from the corresponding OCAF label; however,
+the handle on object remains valid. The only operation available after object deletion
+is the method *IsAlive*() checking whether the object has been deleted or not,
+which returns False if the object has been deleted.
+
+When the object is deleted from the data model, the method checks
+whether there are any alive references to the object.
+Iterating on references the object asks each referring (master) object
+whether the reference can be removed. If the master object can be unlinked,
+the reference is removed, otherwise the master object will be removed too
+or the referred object will be kept alive. This check is performed by the method *Detach* ,
+but the behavior depends on the deletion mode *TObj_DeletingMode*:
+
+ * **TObj_FreeOnly** -- the object will be destroyed only if it is free, i.e. there are no references to it from other objects
+ * **TObj_KeepDepending** -- the object will be destroyed if there are no strong references to it from master objects (all references can be unlinked)
+ * **TObj_Force** -- the object and all depending master objects that have strong references to it will be destroyed.
+
+The most used methods for object removing are:
+
+~~~~~{.cpp}
+ virtual Standard_Boolean CanDetachObject (const TObj_DeletingMode theMode = TObj_FreeOnly );
+~~~~~
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-#include <TDF_Attribute.hxx>
+Returns **True** if the object can be deleted with the indicated deletion mode.
-#include <gp_Ax3.hxx>
-#include <gp_Pnt.hxx>
-#include <gp_Vec.hxx>
-#include <gp_Trsf.hxx>
+~~~~~{.cpp}
+ virtual Standard_Boolean Detach ( const TObj_DeletingMode theMode = TObj_FreeOnly );
+~~~~~
-// This attribute implements a transformation data container
-class MyPackage_Transformation : public TDF_Attribute
-{
-public:
- //!@ name Static methods
+Removes the object from the document if possible
+(according to the indicated deletion mode).
+Unlinks references from removed objects.
+Returns **True** if the objects have been successfully deleted.
- //! The method returns a unique GUID of this attribute.
- //! By means of this GUID this attribute may be identified
- //! among other attributes attached to the same label.
- Standard_EXPORT static const Standard_GUID& GetID ();
+@subsubsection occt_tobj_3_8 Transformation and replication of object data
- //! Finds or creates the attribute attached to <theLabel>.
- //! The found or created attribute is returned.
- Standard_EXPORT static Handle(MyPackage_Transformation) Set (const TDF_Label theLabel);
+*TObj_Object* provides a number of special virtual methods to support replications of objects. These methods should be redefined by descendants when necessary.
- //!@ name Methods for access to the attribute data
-
- //! The method returns the transformation.
- Standard_EXPORT gp_Trsf Get () const;
+~~~~~{.cpp}
+ virtual Handle(TObj_Object) Clone (const TDF_Label& theTargetLabel, Handle(TDF_RelocationTable) theRelocTable = 0);
+~~~~~
- //!@ name Methods for setting the data of transformation
+Copies the object to theTargetLabel. The new object will have all references of its original.
+Returns a handle to the new object (null handle if fail). The data are copied directly,
+but the name is changed by adding the postfix *_copy*.
+To assign different names to the copies redefine the method:
- //! The method defines a rotation type of transformation.
- Standard_EXPORT void SetRotation (const gp_Ax1& theAxis, Standard_Real theAngle);
+~~~~~{.cpp}
+ virtual Handle(TCollection_HExtendedString) GetNameForClone ( const Handle(TObj_Object)& ) const;
+~~~~~
- //! The method defines a translation type of transformation.
- Standard_EXPORT void SetTranslation (const gp_Vec& theVector);
+Returns the name for a new object copy. It could be useful to return the same object name
+if the copy will be in the other model or in the other partition with its own dictionary.
+The method *Clone* uses the following public methods for object data replications:
- //! The method defines a point mirror type of transformation (point symmetry).
- Standard_EXPORT void SetMirror (const gp_Pnt& thePoint);
+~~~~~{.cpp}
+ virtual void CopyReferences (const const Handle(TObj_Object)& theTargetObject, const Handle(TDF_RelocationTable) theRelocTable);
+~~~~~
- //! The method defines an axis mirror type of transformation (axial symmetry).
- Standard_EXPORT void SetMirror (const gp_Ax1& theAxis);
+Adds to the copy of the original object its references.
- //! The method defines a point mirror type of transformation (planar symmetry).
- Standard_EXPORT void SetMirror (const gp_Ax2& thePlane);
+~~~~~{.cpp}
+ virtual void CopyChildren (TDF_Label& theTargetLabel, const Handle(TDF_RelocationTable) theRelocTable);
+~~~~~
- //! The method defines a scale type of transformation.
- Standard_EXPORT void SetScale (const gp_Pnt& thePoint, Standard_Real theScale);
+Copies the children of an object to the target child label.
- //! The method defines a complex type of transformation from one co-ordinate system to another.
- Standard_EXPORT void SetTransformation (const gp_Ax3& theCoordinateSystem1, const gp_Ax3& theCoordinateSystem2);
+@subsubsection occt_tobj_3_9 Object flags
- //!@ name Overridden methods from TDF_Attribute
-
- //! The method returns a unique GUID of the attribute.
- //! By means of this GUID this attribute may be identified among other attributes attached to the same label.
- Standard_EXPORT const Standard_GUID& ID () const;
+Each instance of *TObj_Object* stores a set of bit flags,
+which facilitate the storage of auxiliary logical information assigned to the objects
+(object state). Several typical state flags are defined in the enumeration *ObjectState*:
- //! The method is called on Undo / Redo.
- //! It copies the content of theAttribute into this attribute (copies the fields).
- Standard_EXPORT void Restore (const Handle(TDF_Attribute)& theAttribute);
+ * *ObjectState_Hidden* -- the object is marked as hidden
+ * *ObjectState_Saved* -- the object has (or should have) the corresponding saved file on disk
+ * *ObjectState_Imported* -- the object is imported from somewhere
+ * *ObjectState_ImportedByFile* -- the object has been imported from file and should be updated to have correct relations with other objects
+ * *ObjectState_Ordered* -- the partition contains objects that can be ordered.
- //! It creates a new instance of this attribute.
- //! It is called on Copy / Paste, Undo / Redo.
- Standard_EXPORT Handle(TDF_Attribute) NewEmpty () const;
+The user (developer) can define any new flags in descendant classes.
+To set/get an object, the flags use the following methods:
- //! The method is called on Copy / Paste.
- //! It copies the content of this attribute into theAttribute (copies the fields).
- Standard_EXPORT void Paste (const Handle(TDF_Attribute)& theAttribute, const Handle(TDF_RelocationTable)& theRelocationTable);
+~~~~~{.cpp}
+ Standard_Integer GetFlags() const;
+ void SetFlags( const Standard_Integer theMask );
+ Stadnard_Boolean TestFlags( const Standard_Integer theMask ) const;
+ void ClearFlags( const Standard_Integer theMask = 0 );
+~~~~~
- //! Prints the content of this attribute into the stream.
- Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS);
+In addition, the generic virtual interface stores the logical properties
+of the object class in the form of a set of bit flags.
+Type flags can be received by the method:
- //!@ name Constructor
+~~~~~{.cpp}
+ virtual Standard_Integer GetTypeFlags() const;
+~~~~~
- //! The C++ constructor of this atribute class.
- //! Usually it is never called outside this class.
- Standard_EXPORT MyPackage_Transformation();
+The default implementation returns the flag **Visible**
+defined in the enumeration *TypeFlags*. This flag is used to define visibility
+of the object for the user browsing the model (see class *TObj_HiddenPartition*).
+Other flags can be added by the applications.
-private:
- gp_TrsfForm myType;
+@subsubsection occt_tobj_310 Partitions
- // Axes (Ax1, Ax2, Ax3)
- gp_Ax1 myAx1;
- gp_Ax2 myAx2;
- gp_Ax3 myFirstAx3;
- gp_Ax3 mySecondAx3;
+The special kind of objects defined by the class *TObj_Partition*
+(and its descendant *TObj_HiddenPartition*) is provided for partitioning
+the model into a hierarchical structure. This object represents the container
+of other objects. Each *TObj* model contains the main partition that is placed
+in the same OCAF label as the model object, and serves as a root of the object's tree.
+A hidden partition is a simple partition with a predefined hidden flag.
- // Scalar values
- Standard_Real myAngle;
- Standard_Real myScale;
+The main partition object methods:
- // Points
- gp_Pnt myFirstPoint;
- gp_Pnt mySecondPoint;
-};
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~{.cpp}
+ TDF_Label NewLabel() const;
+~~~~~
-@subsection occt_ocaf_11_2 Implementation of Attribute Transformation in a CPP file
+Allocates and returns a new label for creation of a new child object.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-#include <MyPackage_Transformation.hxx>
-
-//=======================================================================
-//function : GetID
-//purpose : The method returns a unique GUID of this attribute.
-// By means of this GUID this attribute may be identified
-// among other attributes attached to the same label.
-//=======================================================================
-const Standard_GUID& MyPackage_Transformation::GetID()
-{
- static Standard_GUID ID("4443368E-C808-4468-984D-B26906BA8573");
- return ID;
-}
+~~~~~{.cpp}
+ void SetNamePrefix ( const Handle(TCollection_HExtendedString)& thePrefix);
+~~~~~
-//=======================================================================
-//function : Set
-//purpose : Finds or creates the attribute attached to <theLabel>.
-// The found or created attribute is returned.
-//=======================================================================
-Handle(MyPackage_Transformation) MyPackage_Transformation::Set(const TDF_Label& theLabel)
-{
- Handle(MyPackage_Transformation) T;
- if (!theLabel.FindAttribute(MyPackage_Transformation::GetID(), T))
- {
- T = new MyPackage_Transformation();
- theLabel.AddAttribute(T);
- }
- return T;
-}
+Defines the prefix for automatic generation of names of the newly created objects.
-//=======================================================================
-//function : Get
-//purpose : The method returns the transformation.
-//=======================================================================
-gp_Trsf MyPackage_Transformation::Get() const
-{
- gp_Trsf transformation;
- switch (myType)
- {
- case gp_Identity:
- {
- break;
- }
- case gp_Rotation:
- {
- transformation.SetRotation(myAx1, myAngle);
- break;
- }
- case gp_Translation:
- {
- transformation.SetTranslation(myFirstPoint, mySecondPoint);
- break;
- }
- case gp_PntMirror:
- {
- transformation.SetMirror(myFirstPoint);
- break;
- }
- case gp_Ax1Mirror:
- {
- transformation.SetMirror(myAx1);
- break;
- }
- case gp_Ax2Mirror:
- {
- transformation.SetMirror(myAx2);
- break;
- }
- case gp_Scale:
- {
- transformation.SetScale(myFirstPoint, myScale);
- break;
- }
- case gp_CompoundTrsf:
- {
- transformation.SetTransformation(myFirstAx3, mySecondAx3);
- break;
- }
- case gp_Other:
- {
- break;
- }
- }
- return transformation;
-}
+~~~~~{.cpp}
+ Handle(TCollection_HExtendedString) GetNamePrefix() const;
+~~~~~
-//=======================================================================
-//function : SetRotation
-//purpose : The method defines a rotation type of transformation.
-//=======================================================================
-void MyPackage_Transformation::SetRotation(const gp_Ax1& theAxis, const Standard_Real theAngle)
-{
- Backup();
- myType = gp_Rotation;
- myAx1 = theAxis;
- myAngle = theAngle;
-}
+Returns the current name prefix.
-//=======================================================================
-//function : SetTranslation
-//purpose : The method defines a translation type of transformation.
-//=======================================================================
-void MyPackage_Transformation::SetTranslation(const gp_Vec& theVector)
-{
- Backup();
- myType = gp_Translation;
- myFirstPoint.SetCoord(0, 0, 0);
- mySecondPoint.SetCoord(theVector.X(), theVector.Y(), theVector.Z());
-}
+~~~~~{.cpp}
+ Handle(TCollection_HExtendedString) GetNewName ( const Standard_Boolean theIsToChangeCount) const;
+~~~~~
-//=======================================================================
-//function : SetMirror
-//purpose : The method defines a point mirror type of transformation
-// (point symmetry).
-//=======================================================================
-void MyPackage_Transformation::SetMirror(const gp_Pnt& thePoint)
-{
- Backup();
- myType = gp_PntMirror;
- myFirstPoint = thePoint;
-}
+Generates the new name and increases the internal counter of child objects if theIsToChangeCount is **True**.
-//=======================================================================
-//function : SetMirror
-//purpose : The method defines an axis mirror type of transformation
-// (axial symmetry).
-//=======================================================================
-void MyPackage_Transformation::SetMirror(const gp_Ax1& theAxis)
-{
- Backup();
- myType = gp_Ax1Mirror;
- myAx1 = theAxis;
-}
+~~~~~{.cpp}
+ Standard_Integer GetLastIndex() const;
+~~~~~
-//=======================================================================
-//function : SetMirror
-//purpose : The method defines a point mirror type of transformation
-// (planar symmetry).
-//=======================================================================
-void MyPackage_Transformation::SetMirror(const gp_Ax2& thePlane)
-{
- Backup();
- myType = gp_Ax2Mirror;
- myAx2 = thePlane;
-}
+Returns the last reserved child index.
-//=======================================================================
-//function : SetScale
-//purpose : The method defines a scale type of transformation.
-//=======================================================================
-void MyPackage_Transformation::SetScale(const gp_Pnt& thePoint, const Standard_Real theScale)
-{
- Backup();
- myType = gp_Scale;
- myFirstPoint = thePoint;
- myScale = theScale;
-}
+~~~~~{.cpp}
+ void SetLastIndex( const Standard_Integer theIndex );
+~~~~~
-//=======================================================================
-//function : SetTransformation
-//purpose : The method defines a complex type of transformation
-// from one co-ordinate system to another.
-//=======================================================================
-void MyPackage_Transformation::SetTransformation(const gp_Ax3& theCoordinateSystem1,
- const gp_Ax3& theCoordinateSystem2)
-{
- Backup();
- myFirstAx3 = theCoordinateSystem1;
- mySecondAx3 = theCoordinateSystem2;
-}
+Sets the last reserved index.
-//=======================================================================
-//function : ID
-//purpose : The method returns a unique GUID of the attribute.
-// By means of this GUID this attribute may be identified
-// among other attributes attached to the same label.
-//=======================================================================
-const Standard_GUID& MyPackage_Transformation::ID() const
-{
- return GetID();
-}
+@subsection occt_tobj_4 Auxiliary classes
-//=======================================================================
-//function : Restore
-//purpose : The method is called on Undo / Redo.
-// It copies the content of <theAttribute>
-// into this attribute (copies the fields).
-//=======================================================================
-void MyPackage_Transformation::Restore(const Handle(TDF_Attribute)& theAttribute)
-{
- Handle(MyPackage_Transformation) theTransformation = Handle(MyPackage_Transformation)::DownCast(theAttribute);
- myType = theTransformation->myType;
- myAx1 = theTransformation->myAx1;
- myAx2 = theTransformation->myAx2;
- myFirstAx3 = theTransformation->myFirstAx3;
- mySecondAx3 = theTransformation->mySecondAx3;
- myAngle = theTransformation->myAngle;
- myScale = theTransformation->myScale;
- myFirstPoint = theTransformation->myFirstPoint;
- mySecondPoint = theTransformation->mySecondPoint;
-}
+Apart from the model and the object, package *TObj* provides a set of auxiliary classes:
-//=======================================================================
-//function : NewEmpty
-//purpose : It creates a new instance of this attribute.
-// It is called on Copy / Paste, Undo / Redo.
-//=======================================================================
-Handle(TDF_Attribute) MyPackage_Transformation::NewEmpty() const
-{
- return new MyPackage_Transformation();
-}
+ * *TObj_Application* -- defines OCAF application supporting existence and operation with *TObj* documents.
+ * *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.
+ * *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.
+ * Other classes starting with *TObj_T...* -- define OCAF attributes used to store TObj-specific classes and some types of data on OCAF labels.
+ * Iterators -- a set of classes implementing *TObj_ObjectIterator* interface, used for iterations on *TObj* objects:
+ * *TObj_ObjectIterator* -- a basic abstract class for other *TObj* iterators. Iterates on *TObj_Object* instances.
+ * *TObj_LabelIterator* -- iterates on object labels in the *TObj* model document
+ * *TObj_ModelIterator* -- iterates on all objects in the model. Works with sequences of other iterators.
+ * *TObj_OcafObjectIterator* -- Iterates on *TObj* data model objects. Can iterate on objects of a specific type.
+ * *TObj_ReferenceIterator* -- iterates on object references.
+ * *TObj_SequenceIterator* -- iterates on a sequence of *TObj* objects.
+ * *TObj_CheckModel* -- a tool that checks the internal consistency of the model. The basic implementation checks only the consistency of references between objects.
-//=======================================================================
-//function : Paste
-//purpose : The method is called on Copy / Paste.
-// It copies the content of this attribute into
-// <theAttribute> (copies the fields).
-//=======================================================================
-void MyPackage_Transformation::Paste(const Handle(TDF_Attribute)& theAttribute,
- const Handle(TDF_RelocationTable)& ) const
-{
- Handle(MyPackage_Transformation) theTransformation = Handle(MyPackage_Transformation)::DownCast(theAttribute);
- theTransformation->myType = myType;
- theTransformation->myAx1 = myAx1;
- theTransformation->myAx2 = myAx2;
- theTransformation->myFirstAx3 = myFirstAx3;
- theTransformation->mySecondAx3 = mySecondAx3;
- theTransformation->myAngle = myAngle;
- theTransformation->myScale = myScale;
- theTransformation->myFirstPoint = myFirstPoint;
- theTransformation->mySecondPoint = mySecondPoint;
-}
+The structure of *TObj* iterators hierarchy is presented below:
-//=======================================================================
-//function : Dump
-//purpose : Prints the content of this attribute into the stream.
-//=======================================================================
-Standard_OStream& MyPackage_Transformation::Dump(Standard_OStream& anOS) const
-{
- anOS = "Transformation: ";
- switch (myType)
- {
- case gp_Identity:
- {
- anOS = "gp_Identity";
- break;
- }
- case gp_Rotation:
- {
- anOS = "gp_Rotation";
- break;
- }
- case gp_Translation:
- {
- anOS = "gp_Translation";
- break;
- }
- case gp_PntMirror:
- {
- anOS = "gp_PntMirror";
- break;
- }
- case gp_Ax1Mirror:
- {
- anOS = "gp_Ax1Mirror";
- break;
- }
- case gp_Ax2Mirror:
- {
- anOS = "gp_Ax2Mirror";
- break;
- }
- case gp_Scale:
- {
- anOS = "gp_Scale";
- break;
- }
- case gp_CompoundTrsf:
- {
- anOS = "gp_CompoundTrsf";
- break;
- }
- case gp_Other:
- {
- anOS = "gp_Other";
- break;
- }
- }
- return anOS;
-}
+@figure{/user_guides/ocaf/images/tobj_image008.png,"Hierarchy of iterators",420}
+
+
+@subsection occt_tobj_5 Packaging
+
+The *TObj* sources are distributed in the following packages:
-//=======================================================================
-//function : MyPackage_Transformation
-//purpose : A constructor.
-//=======================================================================
-MyPackage_Transformation::MyPackage_Transformation():myType(gp_Identity){
+ * *TObj* -- defines basic classes that implement *TObj* interfaces for OCAF-based modelers.
+ * *BinLDrivers, XmlLDrivers* -- binary and XML driver of *TObj* package
+ * *BinLPlugin, XmlLPlugin* -- plug-in for binary and XML persistence
+ * *BinMObj, XmlMObj* -- binary and XML drivers to store and retrieve specific *TObj* data to or from OCAF document
+ * *TKBinL, TKXmlL* -- toolkits of binary and XML persistence
-}
+
+@section occt_ocaf_10 GLOSSARY
+
+* **Application** -- a document container holding all documents containing all application data.
+* **Application data** -- the data produced by an application, as opposed to data referring to it.
+* **Associativity of data** -- the ability to propagate modifications made to one document to other documents, which refer to such document. Modification propagation is:
+ * unidirectional, that is, from the referenced to the referencing document(s), or
+ * bi-directional, from the referencing to the referenced document and vice-versa.
+* **Attribute** -- a container for application data. An attribute is attached to a label in the hierarchy of the data framework.
+* **Child** -- a label created from another label, which by definition, is the father label.
+* **Compound document** -- a set of interdependent documents, linked to each other by means of external references. These references provide the associativity of data.
+* **Data framework** -- a tree-like data structure which in OCAF, is a tree of labels with data attached to them in the form of attributes. This tree of labels is accessible through the services of the *TDocStd_Document* class.
+* **Document** -- a container for a data framework which grants access to the data, and is, in its turn, contained by an application. A document also allows you to:
+ * Manage modifications, providing Undo and Redo functions
+ * Manage command transactions
+ * Update external links
+ * Manage save and restore options
+ * Store the names of software extensions.
+* **Driver** -- an abstract class, which defines the communications protocol with a system.
+* **Entry** -- an ASCII character string containing the tag list of a label. For example:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+0:3:24:7:2:7
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-@subsection occt_ocaf_11_3 Implementation of typical actions with standard OCAF attributes.
-
-There are four sample files provided in the directory 'OpenCasCade/ros/samples/ocafsamples'. They present typical actions with OCAF services (mainly for newcomers).
-The method *Sample()* of each file is not dedicated for execution 'as is', it is rather a set of logical actions using some OCAF services.
-
-### TDataStd_Sample.cxx
-This sample contains templates for typical actions with the following standard OCAF attributes:
-- Starting with data framework;
-- TDataStd_Integer attribute management;
-- TDataStd_RealArray attribute management;
-- TDataStd_Comment attribute management;
-- TDataStd_Name attribute management;
-- TDataStd_UAttribute attribute management;
-- TDF_Reference attribute management;
-- TDataXtd_Point attribute management;
-- TDataXtd_Plane attribute management;
-- TDataXtd_Axis attribute management;
-- TDataXtd_Geometry attribute management;
-- TDataXtd_Constraint attribute management;
-- TDataStd_Directory attribute management;
-- TDataStd_TreeNode attribute management.
-
-### TDocStd_Sample.cxx
-This sample contains template for the following typical actions:
-- creating application;
-- creating the new document (document contains a framework);
-- retrieving the document from a label of its framework;
-- filling a document with data;
-- saving a document in the file;
-- closing a document;
-- opening the document stored in the file;
-- copying content of a document to another document with possibility to update the copy in the future.
-
-### TPrsStd_Sample.cxx
-This sample contains template for the following typical actions:
-- starting with data framework;
-- setting the TPrsStd_AISViewer in the framework;
-- initialization of aViewer;
-- finding TPrsStd_AISViewer attribute in the DataFramework;
-- getting AIS_InteractiveContext from TPrsStd_AISViewer;
-- adding driver to the map of drivers;
-- getting driver from the map of drivers;
-- setting TNaming_NamedShape to \<ShapeLabel\>;
-- setting the new TPrsStd_AISPresentation to \<ShapeLabel\>;
-- displaying;
-- erasing;
-- updating and displaying presentation of the attribute to be displayed;
-- setting a color to the displayed attribute;
-- getting transparency of the displayed attribute;
-- modify attribute;
-- updating presentation of the attribute in viewer.
-
-### TNaming_Sample.cxx
-This sample contains template for typical actions with OCAF Topological Naming services.
-The following scenario is used:
-- data framework initialization;
-- creating Box1 and pushing it as PRIMITIVE in DF;
-- creating Box2 and pushing it as PRIMITIVE in DF;
-- moving Box2 (applying a transformation);
-- pushing the selected edges of the top face of Box1 in DF;
-- creating a Fillet (using the selected edges) and pushing the result as a modification of Box1;
-- creating a Cut (Box1, Box2) as a modification of Box1 and push it in DF;
-- recovering the result from DF.
+* **External links** -- references from one data structure to another data structure in another document.
+To store these references properly, a label must also contain an external link attribute.
+* **Father** -- a label, from which other labels have been created. The other labels are, by definition, the children of this label.
+* **Framework** -- a group of co-operating classes which enable a design to be re-used for a given category of problem. The framework guides the architecture of the application by breaking it up into abstract classes, each of which has different responsibilities and collaborates in a predefined way. Application developer creates a specialized framework by:
+ * defining new classes which inherit from these abstract classes
+ * composing framework class instances
+ * implementing the services required by the framework.
+In C++, the application behavior is implemented in virtual functions redefined in these derived classes. This is known as overriding.
+
+* **GUID** -- Global Universal ID. A string of 37 characters intended to uniquely identify an object. For example:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+2a96b602-ec8b-11d0-bee7-080009dc3333
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* **Label** -- a point in the data framework, which allows data to be attached to it by means of attributes. It has a name in the form of an entry, which identifies its place in the data framework.
+* **Modified label** -- containing attributes whose data has been modified.
+* **Reference key** -- an invariant reference, which may refer to any type of data used in an application. In its transient form, it is a label in the data framework, and the data is attached to it in the form of attributes. In its persistent form, it is an entry of the label. It allows an application to recover any entity in the current session or in a previous session.
+* **Resource file** -- a file containing a list of each document’s schema name and the storage and retrieval plug-ins for that document.
+* **Root** -- the starting point of the data framework. This point is the top label in the framework. It is represented by the [0] entry and is created at the same time with the document you are working on.
+* **Scope** -- the set of all the attributes and labels which depend on a given label.
+* **Tag list** -- a list of integers, which identify the place of a label in the data framework. This list is displayed in an entry.
+* **Topological naming** -- systematic referencing of topological entities so that these entities can still be identified after the models they belong to have gone through several steps in modeling. In other words, topological naming allows you to track entities through the steps in the modeling process. This referencing is needed when a model is edited and regenerated, and can be seen as a mapping of labels and name attributes of the entities in the old version of a model to those of the corresponding entities in its new version. Note that if the topology of a model changes during the modeling, this mapping may not fully coincide. A Boolean operation, for example, may split edges.
+* **Topological tracking** -- following a topological entity in a model through the steps taken to edit and regenerate that model.
+* **Valid label** -- in a data framework, this is a label, which is already recomputed in the scope of regeneration sequence and includes the label containing a feature which is to be recalculated. Consider the case of a box to which you first add a fillet, then a protrusion feature. For recalculation purposes, only valid labels of each construction stage are used. In recalculating a fillet, they are only those of the box and the fillet, not the protrusion feature which was added afterwards.
projects / occt.git / blobdiff