To append and return a new child label, you use *TDF_TagSource::NewChild*. In the example below, the argument *level2*, which is passed to *NewChild,* is a *TDF_Label*.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~{.cpp}
TDF_Label child1 = TDF_TagSource::NewChild (level2);
TDF_Label child2 = TDF_TagSource::NewChild (level2);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsubsection occt_ocaf_3_3_2 Creation of a child label by user delivery from a tag
To retrieve a child label from a tag which you have specified yourself, you need to use *TDF_Label::FindChild* and *TDF_Label::Tag* as in the example below. Here, the integer 3 designates the tag of the label you are interested in, and the Boolean false is the value for the argument *create*. When this argument is set to *false*, no new child label is created.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~{.cpp}
TDF_Label achild = root.FindChild(3,Standard_False);
if (!achild.IsNull()) {
Standard_Integer tag = achild.Tag();
}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsection occt_ocaf_3_4 Label
To create a new child label in the data framework using explicit delivery of tags, use *TDF_Label::FindChild*.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
//creating a label with tag 10 at Root
TDF_Label lab1 = aDF->Root().FindChild(10);
TDF_Label lab2 = lab1.FindChild(7);
TDF_Label lab3 = lab1.FindChild(2);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
You could also use the same syntax but add the Boolean *true* as a value of the argument **create**. This ensures that a new child label will be created if none is found. Note that in the previous syntax, this was also the case since **create** is *true* by default.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
TDF_Label level1 = root.FindChild(3,Standard_True);
TDF_Label level2 = level1.FindChild(1,Standard_True);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsubsection occt_ocaf_3_4_3 Retrieving child labels
You can retrieve child labels of your current label by iteration on the first level in the scope of this label.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
TDF_Label current;
//
for (TDF_ChildIterator it1 (current,Standard_False); it1.More(); it1.Next()) {
// do something on a child (level 1)
//
}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
You can also retrieve all child labels in every descendant generation of your current label by iteration on all levels in the scope of this label.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
for (TDF_ChildIterator itall (current,Standard_True); itall.More(); itall.Next()) {
achild = itall.Value();
//
// do something on a child (all levels)
//
}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
Using *TDF_Tool::Entry* with *TDF_ChildIterator* you can retrieve the entries of your current label’s child labels as well.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
void DumpChildren(const TDF_Label& aLabel)
{
TDF_ChildIterator it;
cout << as.ToCString() << endl;
}
}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsubsection occt_ocaf_3_4_4 Retrieving the father label
Retrieving the father label of a current label.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
TDF_Label father = achild.Father();
isroot = father.IsRoot();
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsection occt_ocaf_3_5 Attribute
To retrieve an attribute from a label, you use *TDF_Label::FindAttribute*. In the example below, the GUID for integer attributes, and *INT*, a handle to an attribute are passed as arguments to *FindAttribute* for the current label.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
if(current.FindAttribute(TDataStd_Integer::GetID(),INT))
{
// the attribute is found
{
// the attribute is not found
}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsubsection occt_ocaf_3_5_2 Identifying an attribute using a GUID
You can create a new instance of an attribute and retrieve its GUID. In the example below, a new integer attribute is created, and its GUID is passed to the variable *guid* by the method ID inherited from *TDF_Attribute*.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
Handle(TDataStd_Integer) INT = new TDataStd_Integer();
Standard_GUID guid = INT->ID();
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsubsection occt_ocaf_3_5_3 Attaching an attribute to a label
*TDF_Attribute::Label* for *INT* then returns the label *attach* to which *INT* is attached.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
current.Add (INT); // INT is now attached to current
current.Add (INT); // causes failure
TDF_Label attach = INT->Label();
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
Note. There is an exception from this rule for some sub-set of Standard attributes. See for details chapter 6.Standard Attributes.
*TDF_Attribute::HasAttribute* tests whether there is an attached attribute, and *TDF_Tool::NbAttributes* returns the number of attributes attached to the label in question, e.g. *current*.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
// Testing of attribute attachment
//
if (current.IsA(TDataStd_Integer::GetID())) {
Standard_Integer nbatt = current.NbAttributes();
// the label has nbatt attributes attached
}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsubsection occt_ocaf_3_5_5 Removing an attribute from a label
To remove an attribute from a label, you use *TDF_Label::Forget* with the GUID of the deleted attribute. To remove all attributes of a label, *TDF_Label::ForgetAll*.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
current.Forget(TDataStd_Integer::GetID());
// integer attribute is now not attached to current label
current.ForgetAll();
// current has now 0 attributes attached
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsubsection occt_ocaf_3_5_6 Specific attribute creation
If the set of existing and ready to use attributes implementing standard data types does not cover the needs of a specific data presentation task, the user can build his own data type and the corresponding new specific attribute implementing this new data type.
To create an application, use the following syntax.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
Handle(TDocStd_Application) app = new TDocStd_Application ();
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsubsection occt_ocaf_4_2_2 Creating a new document
To the application which you declared in the previous example (4.2.1), you must add the document *doc* as an argument of *TDocStd_Application::NewDocument*.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
Handle(TDocStd_Document) doc;
app->NewDocument("NewDocumentFormat", doc);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
Here "NewDocumentFormat" is identifier of the format of your document.
OCCT defines several standard formats, distinguishing by a set of supported OCAF attributes, and method of encoding (e.g. binary data or XML), described below.
To retrieve the application containing your document, you use the syntax below.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
app = Handle(TDocStd_Application)::DownCast (doc->Application());
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsection occt_ocaf_4_3 The Document
The document contains your data framework, and allows you to retrieve this framework, recover its main label, save it in a file, and open or close this file.
To access the main label in the data framework, you use *TDocStd_Document::Main* as in the example below. The main label is the first child of the root label in the data framework, and has the entry 0:1.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
TDF_Label label = doc->Main();
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsubsection occt_ocaf_4_3_2 Retrieving the document from a label in its framework
To retrieve the document from a label in its data framework, you use *TDocStd_Document::Get* as in the example below. The argument *label* passed to this method is an instantiation of *TDF_Label*.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
doc = TDocStd_Document::Get(label);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsubsection occt_ocaf_4_3_format Defining storage format
In order to use OCAF persistence to save and read your documents to / from the file, you need to define one or several formats in your application.
For that, use method TDocStd_Application::DefineFormat(), for instance:
-~~~~~
+~~~~{.cpp}
app->DefineFormat ("NewDocumentFormat", "New format for OCAF documents", "ndf",
new NewDocumentFormat_RetrievalDriver(),
new NewDocumentFormat_StorageDriver());
-~~~~~
+~~~~
This example defines format "NewDocumentFormat" with a default file extension "ndf", and instantiates drivers for reading and storing documents from and to that format.
Either of the drivers can be null, in this case the corresponding action will not be supported for that format.
For convenience, these toolkits provide static methods *DefineFormat()* accepting handle to application.
These methods allow defining corresponding formats easily, e.g.:
-~~~~~
+~~~~{.cpp}
BinDrivers::DefineFormat (app); // define format "BinOcaf"
-~~~~~
+~~~~
Use these toolkits as an example for implementation of persistence drivers for custom attributes, or new persistence formats.
Then create that resource file and define the parameters of your format:
-~~~~~
+~~~~
ndf.FileFormat: NewDocumentFormat
NewDocumentFormat.Description: New Document Format Version 1.0
NewDocumentFormat.FileExtension: ndf
NewDocumentFormat.StoragePlugin: bb5aa176-c65c-4c84-862e-6b7c1fe16921
NewDocumentFormat.RetrievalPlugin: 76fb4c04-ea9a-46aa-88a2-25f6a228d902
-~~~~~
+~~~~
The GUIDs should be unique and correspond to the GUIDs supported by relevant plugin.
You can use an existing plugins (see the table above) or create your own.
Finally, make a copy of the resource file "Plugin" from *$CASROOT/src/StdResource* and, if necessary, add the definition of your plugin in it, for instance:
-~~~~~
+~~~~
bb5aa176-c65c-4c84-862e-6b7c1fe16921.Location: TKNewFormat
76fb4c04-ea9a-46aa-88a2-25f6a228d902.Location: TKNewFormat
-~~~~~
+~~~~
In order to have these resource files loaded during the program execution, it is necessary to set two environment variables: *CSF_PluginDefaults* and *CSF_NewFormatDefaults*.
For example, set the files in the directory *MyApplicationPath/MyResources*:
-~~~~~
+~~~~
setenv CSF_PluginDefaults MyApplicationPath/MyResources
setenv CSF_NewFormatDefaults MyApplicationPath/MyResources
-~~~~~
+~~~~
@subsubsection occt_ocaf_4_3_3 Saving a document
To save the document, make sure that its parameter *StorageFormat()* corresponds to one of the formats defined in the application, and use method *TDocStd_Application::SaveAs*, for instance:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
app->SaveAs(doc, "/tmp/example.caf");
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsubsection occt_ocaf_4_3_4 Opening the document from a file
To open the document from a file where it has been previously saved, you can use *TDocStd_Application::Open* as in the example below. The arguments are the path of the file and the document saved in this file.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~
app->Open("/tmp/example.caf", doc);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsubsection occt_ocaf_4_3_5 Cutting, copying and pasting inside a document
* The data container (e.g. <i> Lab_source</i>)
* The destination of the copy (e.g. <i> Lab_ Target</i> )
-~~~~
+~~~~{.cpp}
Copy = copy (Lab_Source => Lab_Clipboard)
Cut = copy + Lab_Source.ForgetAll() // command clear the contents of LabelSource.
Paste = copy (Lab_Clipboard => Lab_target)
So we need a tool to copy all (or a part) of the content of a label and its sub-label,
to another place defined by a label.
-~~~~
+~~~~{.cpp}
TDF_CopyLabel aCopy;
TDF_IDFilter aFilter (Standard_False);
To copy a document with a possibility of updating it later, you use *TDocStd_XLinkTool::CopyWithLink*.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
Handle(TDocStd_Document) doc1;
Handle(TDocStd_Document) doc2;
TDocStd_XLinkTool XLinkTool;
XLinkTool.CopyWithLink(target,source);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
Now the target document has a copy of the source document. The copy also has a link in order to update the content of the copy if the original changes.
In the example below, something has changed in the source document. As a result, you need to update the copy in the target document. This copy is passed to *TDocStd_XLinkTool::UpdateLink* as the argument *target*.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
XLinkTool.UpdateLink(target);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
#### Without any link between the copy and the original
You can also create a copy of the document with no link between the original and the copy. The syntax to use this option is *TDocStd_XLinkTool::Copy*. The copied document is again represented by the argument *target*, and the original -- by *source.*
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
XLinkTool.Copy(target, source);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@section occt_ocaf_5 OCAF Shape Attributes
The class *TNaming_Builder* allows creating a named shape attribute. It has a label of a future attribute as an argument of the constructor. Respective methods are used for the evolution and setting of shape pairs. If for the same TNaming_Builder object a lot of pairs of shapes with the same evolution are given, then these pairs would be placed in the resulting named shape. After the creation of a new object of the TNaming_Builder class, an empty named shape is created at the given label.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
// a new empty named shape is created at "label"
TNaming_Builder builder(label);
// set a pair of shapes with evolution GENERATED
builder.Generated(oldshape2,newshape2);
// get the result - TNaming_NamedShape attribute
Handle(TNaming_NamedShape) ns = builder.NamedShape();
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsection occt_ocaf_5_5 Reading the contents of a named shape attribute
* The method <i>NamedShape(TopoDS_Shape,TDF_Label) </i> returns a named shape, which contains a given shape as a new shape. A given label is any label from the data framework -- it just gives access to it.
* *TNaming_Iterator* gives access to the named shape and hooks pairs.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
// create an iterator for a named shape
TNaming_Iterator iter(namedshape);
// iterate while some pairs are not iterated
// go to the next pair
iter.Next();
}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsection occt_ocaf_5_6 Topological naming
If you need to create a topological attribute for existing data, use the method *NamedShape*.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
class MyPkg_MyClass
{
public: Standard_Boolean SameEdge (const Handle(CafTest_Line)& L1, const Handle(CafTest_Line)& L2);
Handle(TNaming_NamedShape) NS2 = L2->NamedShape();
return BRepTools::Compare(NS1,NS2);
}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsection occt_ocaf_5_8 Example of topological naming usage
To find an attribute attached to a specific label, you use the GUID of the attribute type you are looking for. This information can be found using the method <i> GetID</i> and the method <i> Find</i> for the label as follows:
-~~~~
+~~~~{.cpp}
Standard_GUID anID = MyAttributeClass::GetID();
Standard_Boolean HasAttribute = aLabel.Find(anID,anAttribute);
~~~~
Let's consider it on the example of the TDataStd_Real attribute. The previous version of the attribute allowed to set the attribute using
static method Set in next way:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
static Handle(TDataStd_Real) Set (const TDF_Label& label, const Standard_Real value);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
This is a default form which is kept by the attribute. It uses the default GUID for the attribute identification - TDataStd_Real::GetID().
In case if you want to use the new feature (user defined Real attribute), for example to define several attributes which should keep a value
of the same type - Standard_Real, but to be associated with different user's notions (or objects) the new static method Set should be used.
In our example we will define two Real attributes which presents two customer's objects - Density and Volume and will be put on the same Label.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
#define DENSITY Standard_GUID("12e9454b-6dbc-11d4-b9c8-0060b0ee2810")
#define VOLUME Standard_GUID("161595c0-3628-4737-915a-c160ce94c6f7")
To find an user defined Real attribute just use a corresponding GUID:
Handle (TDataStd_Real) anAtt;
aLabel.FindAttribute (DENSITY, anAtt);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsection occt_ocaf_6_4_1 Creation Attributes with User Defined GUID.
You can create a new instance of an attribute with user define GUID and add it to label in two ways.
1. Using static method Set(). For example:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
TDF_Label aLabel = ...;
Standard_Integer aValue = ...;
Standard_GUID aGuid = TDataStd_Integer::GetID();
TDataStd_Integer::Set(aLabel, aGuid, aValue);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
2. Using the default constructor
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
Handle(TDataStd_Integer) anInt = new TDataStd_Integer();
anInt->SetID(aGuid);
aLabel.Add(anInt);
anInt->Set(aValue);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@section occt_ocaf_7 Visualization Attributes
To initialize the AIS viewer as in the example below, use method *Find*.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
// "access" is any label of the data framework
Handle(TPrsStd_AISViewer) viewer = TPrsStd_AISViewer::Find(access)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsection occt_ocaf_7_2_2 Defining a presentation attribute
To fill a driver table with standard drivers, first initialize the AIS viewer as in the example above, and then pass the return value of the method *InitStandardDrivers* to the driver table returned by the method *Get*. Then attach a *TNaming_NamedShape* to a label and set the named shape in the presentation attribute using the method *Set*. Then attach the presentation attribute to the named shape attribute, and the *AIS_InteractiveObject*, which the presentation attribute contains, will initialize its drivers for the named shape. This can be seen in the example below.
**Example**
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
DriverTable::Get() -> InitStandardDrivers();
// next, attach your named shape to a label
TPrsStd_AISPresentation::Set(NS};
// here, attach the AISPresentation to NS.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@section occt_ocaf_8 Function Services
This is an example of the code for iteration and execution of functions.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
// The scope of functions is defined.
Handle(TFunction_Scope) aScope = TFunction_Scope::Set (anyLabel);
}
}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
@subsection occt_ocaf_8a_6 Example 2: Cylinder function driver
This is an example of the code for a cylinder function driver. To make the things clearer, the methods <i>\::Arguments()</i> and <i>\::Results()</i> from the base class are also mentioned.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+~~~~{.cpp}
// A virtual method ::Arguments() returns a list of arguments of the function.
CylinderDriver::Arguments( TDF_LabelList& args )
return 0;
}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
The following example is a sample text from an XML file obtained by storing an OCAF document with two labels (0: and 0:2) and two attributes -- *TDataStd_Name* (on label 0:) and *TNaming_NamedShape* (on label 0:2). The \<shapes\> section contents are replaced by an ellipsis.
-~~~~
+~~~~{.cpp}
<?xml version="1.0" encoding="UTF-8"?>
<document format="XmlOcaf" xmlns="http://www.opencascade.org/OCAF/XML" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opencascade.org/OCAF/XML http://www.opencascade.org/OCAF/XML/XmlOcaf.xsd">
The other available format is *XmlOcaf*. The class **TObj_Model** declares and provides a default
implementation of two virtual methods:
-~~~~~{.cpp}
+~~~~{.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}
+~~~~{.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
All objects in the model are stored in the main partition and accessed by iterators.
To access all model objects use:
-~~~~~{.cpp}
+~~~~{.cpp}
virtual Handle(TObj_ObjectIterator) GetObjects () const;
-~~~~~
+~~~~
This method returns a recursive iterator on all objects stored in the model.
-~~~~~{.cpp}
+~~~~{.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}
+~~~~{.cpp}
Handle(TObj_Partition) GetMainPartition() const;
-~~~~~
+~~~~
To receive the iterator on objects of a specific type *AType* use the following call:
-~~~~~{.cpp}
+~~~~{.cpp}
GetMainPartition()->GetChildren(STANDARD_TYPE(AType) );
-~~~~~
+~~~~
The set of protected methods is provided for descendant classes to deal with partitions:
-~~~~~{.cpp}
+~~~~{.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).
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}
+~~~~{.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}
+~~~~{.cpp}
Handle(TObj_Object) FindObject (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary) const;
-~~~~~
+~~~~
@subsubsection occt_tobj_2_5 Own model data
*AfterRetrieval* of the *TObj_Object* class and skip the registration of the object name.
Use the following methods for the naming mechanism:
-~~~~~{.cpp}
+~~~~{.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}
+~~~~{.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}
+~~~~{.cpp}
void UnRegisterName (const Handle(TCollection_HExtendedString)& theName, const Handle(TObj_TNameContainer)& theDictionary ) const;
-~~~~~
+~~~~
Unregisters the name from the dictionary.
The names of *TObj* model objects are removed from the dictionary when the objects are deleted from the model.
-~~~~~{.cpp}
+~~~~{.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.
Class *TObj_Model* provides the API for transaction mechanism (supported by OCAF):
-~~~~~{.cpp}
+~~~~{.cpp}
Standard_Boolean HasOpenCommand() const;
-~~~~~
+~~~~
Returns True if a Command transaction is open
-~~~~~{.cpp}
+~~~~{.cpp}
void OpenCommand() const;
-~~~~~
+~~~~
Opens a new command transaction.
-~~~~~{.cpp}
+~~~~{.cpp}
void CommitCommand() const;
-~~~~~
+~~~~
Commits the Command transaction. Does nothing If there is no open Command transaction.
-~~~~~{.cpp}
+~~~~{.cpp}
void AbortCommand() const;
-~~~~~
+~~~~
Aborts the Command transaction. Does nothing if there is no open Command transaction.
-~~~~~{.cpp}
+~~~~{.cpp}
Standard_Boolean IsModified() const;
-~~~~~
+~~~~
Returns True if the model document has a modified status (has changes after the last save)
-~~~~~{.cpp}
+~~~~{.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*.
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}
+~~~~{.cpp}
virtual TCollection_ExtendedString GetFormat () const;
-~~~~~
+~~~~
Returns the string *TObjBin* or *TObjXml* indicating
the current persistent mechanism. The default value is *TObjBin*.
of the model format. The current version of the model
format is stored in the model file and can be checked upon retrieval.
-~~~~~{.cpp}
+~~~~{.cpp}
Standard_Integer GetFormatVersion() const;
-~~~~~
+~~~~
Returns the format version stored in the model file
-~~~~~{.cpp}
+~~~~{.cpp}
void SetFormatVersion(const Standard_Integer theVersion);
-~~~~~
+~~~~
Defines the format version used for save.
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}
+~~~~{.cpp}
virtual Standard_Boolean Update();
-~~~~~
+~~~~
This method is usually called after loading of the model.
The default implementation does nothing and returns **True**.
-~~~~~{.cpp}
+~~~~{.cpp}
virtual Standard_Boolean initNewModel( const Standard_Boolean IsNew);
-~~~~~
+~~~~
This method performs model initialization, check and updates (as described above).
-~~~~~{.cpp}
+~~~~{.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
To copy the model between OCAF documents use the following methods:
-~~~~~{.cpp}
+~~~~{.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}
+~~~~{.cpp}
virtual Handle(TObj_Model) NewEmpty() = 0;
-~~~~~
+~~~~
Redefines a pure virtual method to create a new empty instance of the model.
-~~~~~{.cpp}
+~~~~{.cpp}
void CopyReferences ( const Handle(TObj_Model)& theTarget, const Handle(TDF_RelocationTable)& theRelocTable);
-~~~~~
+~~~~
Copies the references from the current model to the target model.
The messenger is stored as the field of the model instance
and can be set and retrieved by the following methods:
-~~~~~{.cpp}
+~~~~{.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
An object can be received from the model by the following methods:
-~~~~~{.cpp}
+~~~~{.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}
+~~~~{.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).
*TObj_Object* class provides a set of auxiliary methods for descendants
to access the data stored in sub-labels by their tag numbers:
-~~~~~{.cpp}
+~~~~{.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
*TColStd_HArray1OfReal*, *TColStd_HArray1OfInteger*, *TColStd_HArray1OfExtendedString*).
For instance, methods provided for real numbers are:
-~~~~~{.cpp}
+~~~~{.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}
+~~~~{.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}
+~~~~{.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
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}
+~~~~{.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}
+~~~~{.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
This functionality is provided by the following methods:
-~~~~~{.cpp}
+~~~~{.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}
+~~~~{.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}
+~~~~{.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 most used methods for work with references are:
-~~~~~{.cpp}
+~~~~{.cpp}
virtual Standard_Boolean HasReference( const Handle(TObj_Object)& theObject) const;
-~~~~~
+~~~~
Returns True if the current object refers to the indicated object.
-~~~~~{.cpp}
+~~~~{.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}
+~~~~{.cpp}
virtual void RemoveAllReferences();
-~~~~~
+~~~~
Removes all references from the current object.
-~~~~~{.cpp}
+~~~~{.cpp}
virtual void RemoveReference( const Handle(TObj_Object)& theObject );
-~~~~~
+~~~~
Removes the reference to the indicated object.
-~~~~~{.cpp}
+~~~~{.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}
+~~~~{.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}
+~~~~{.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}
+~~~~{.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).
The most used methods for object removing are:
-~~~~~{.cpp}
+~~~~{.cpp}
virtual Standard_Boolean CanDetachObject (const TObj_DeletingMode theMode = TObj_FreeOnly );
-~~~~~
+~~~~
Returns **True** if the object can be deleted with the indicated deletion mode.
-~~~~~{.cpp}
+~~~~{.cpp}
virtual Standard_Boolean Detach ( const TObj_DeletingMode theMode = TObj_FreeOnly );
-~~~~~
+~~~~
Removes the object from the document if possible
(according to the indicated deletion mode).
*TObj_Object* provides a number of special virtual methods to support replications of objects. These methods should be redefined by descendants when necessary.
-~~~~~{.cpp}
+~~~~{.cpp}
virtual Handle(TObj_Object) Clone (const TDF_Label& theTargetLabel, Handle(TDF_RelocationTable) theRelocTable = 0);
-~~~~~
+~~~~
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:
-~~~~~{.cpp}
+~~~~{.cpp}
virtual Handle(TCollection_HExtendedString) GetNameForClone ( const Handle(TObj_Object)& ) const;
-~~~~~
+~~~~
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:
-~~~~~{.cpp}
+~~~~{.cpp}
virtual void CopyReferences (const const Handle(TObj_Object)& theTargetObject, const Handle(TDF_RelocationTable) theRelocTable);
-~~~~~
+~~~~
Adds to the copy of the original object its references.
-~~~~~{.cpp}
+~~~~{.cpp}
virtual void CopyChildren (TDF_Label& theTargetLabel, const Handle(TDF_RelocationTable) theRelocTable);
-~~~~~
+~~~~
Copies the children of an object to the target child label.
The user (developer) can define any new flags in descendant classes.
To set/get an object, the flags use the following methods:
-~~~~~{.cpp}
+~~~~{.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 );
-~~~~~
+~~~~
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:
-~~~~~{.cpp}
+~~~~{.cpp}
virtual Standard_Integer GetTypeFlags() const;
-~~~~~
+~~~~
The default implementation returns the flag **Visible**
defined in the enumeration *TypeFlags*. This flag is used to define visibility
The main partition object methods:
-~~~~~{.cpp}
+~~~~{.cpp}
TDF_Label NewLabel() const;
-~~~~~
+~~~~
Allocates and returns a new label for creation of a new child object.
-~~~~~{.cpp}
+~~~~{.cpp}
void SetNamePrefix ( const Handle(TCollection_HExtendedString)& thePrefix);
-~~~~~
+~~~~
Defines the prefix for automatic generation of names of the newly created objects.
-~~~~~{.cpp}
+~~~~{.cpp}
Handle(TCollection_HExtendedString) GetNamePrefix() const;
-~~~~~
+~~~~
Returns the current name prefix.
-~~~~~{.cpp}
+~~~~{.cpp}
Handle(TCollection_HExtendedString) GetNewName ( const Standard_Boolean theIsToChangeCount) const;
-~~~~~
+~~~~
Generates the new name and increases the internal counter of child objects if theIsToChangeCount is **True**.
-~~~~~{.cpp}
+~~~~{.cpp}
Standard_Integer GetLastIndex() const;
-~~~~~
+~~~~
Returns the last reserved child index.
-~~~~~{.cpp}
+~~~~{.cpp}
void SetLastIndex( const Standard_Integer theIndex );
-~~~~~
+~~~~
Sets the last reserved index.
* 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}
+~~~~{.cpp}
0:3:24:7:2:7
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~
* **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.
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}
+~~~~{.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.
projects / occt.git / blobdiff