1 OCAF: Usage Tutorial {#samples__ocaf}
6 At the beginning of your development, you first define an application class by inheriting from the Application abstract class.
7 You only have to create and determine the resources of the application
8 for specifying the format of your documents (you generally use the standard one) and their file extension.
10 Then, you design the application data model by organizing attributes you choose among those provided with OCAF.
11 You can specialize these attributes using the User attribute. For example, if you need a reflection coefficient,
12 you aggregate a User attribute identified as a reflection coefficient
13 with a Real attribute containing the value of the coefficient (as such, you don't define a new class).
15 If you need application specific data not provided with OCAF, for example,
16 to incorporate a finite element model in the data structure,
17 you define a new attribute class containing the mesh,
18 and you include its persistent homologue in a new file format.
20 Once you have implemented the commands which create and modify the data structure
21 according to your specification, OCAF provides you, without any additional programming:
23 * Persistent reference to any data, including geometric elements â€" several documents can be linked with such reference;
24 * Document-View association;
25 * Ready-to-use functions such as :
27 * Save and open application data.
29 Finally, you develop the application's graphical user interface using the toolkit of your choice, for example:
30 * KDE Qt or GNOME GTK+ on Linux;
31 * Microsoft Foundation Classes (MFC) on Windows Motif on Sun;
32 * Other commercial products such as Ilog Views.
34 You can also implement the user interface in the Java language using
35 the Swing-based Java Application Desktop component (JAD) provided with OCAF.
37 ## An example of OCAF usage
39 To create a useful OCAF-based application, it is necessary to redefine two deferred methods: <i> Formats</i> and <i> ResourcesName</i>
41 In the <i> Formats </i> method, add the format of the documents, which need to be read by the application and may have been built in other applications.
46 void myApplication::Formats(TColStd_SequenceOfExtendedString& Formats)
48 Formats.Append(TCollection_ExtendedString ("OCAF-myApplication"));
52 In the <i> ResourcesName</i> method, you only define the name of the resource file. This
53 file contains several definitions for the saving and opening mechanisms associated
54 with each format and calling of the plug-in file.
57 Standard_CString myApplication::ResourcesName()
59 return Standard_CString ("Resources");
63 To obtain the saving and opening mechanisms, it is necessary to set two environment variables: <i> CSF_PluginDefaults</i>, which defines the path of the plug-in file, and <i> CSF_ResourcesDefault</i>, which defines the resource file:
66 SetEnvironmentVariable ( "CSF_ResourcesDefaults",myDirectory);
67 SetEnvironmentVariable ( "CSF_PluginDefaults",myDirectory);
70 The plugin and the resource files of the application will be located in <i> myDirector</i>.
71 The name of the plugin file must be <i>Plugin</i>.
75 The resource file describes the documents (type and extension) and
76 the type of data that the application can manipulate
77 by identifying the storage and retrieval drivers appropriate for this data.
79 Each driver is unique and identified by a GUID generated, for example, with the <i> uuidgen </i> tool in Windows.
81 Five drivers are required to use all standard attributes provided within OCAF:
83 * the schema driver (ad696002-5b34-11d1-b5ba-00a0c9064368)
84 * the document storage driver (ad696000-5b34-11d1-b5ba-00a0c9064368)
85 * the document retrieval driver (ad696001-5b34-11d1-b5ba-00a0c9064368)
86 * the attribute storage driver (47b0b826-d931-11d1-b5da-00a0c9064368)
87 * the attribute retrieval driver (47b0b827-d931-11d1-b5da-00a0c9064368)
89 These drivers are provided as plug-ins and are located in the <i> PappStdPlugin</i> library.
92 For example, this is a resource file, which declares a new model document OCAF-MyApplication:
95 formatlist:OCAF-MyApplication
96 OCAF-MyApplication.Description: MyApplication Document Version 1.0
97 OCAF-MyApplication.FileExtension: sta
98 OCAF-MyApplication.StoragePlugin: ad696000-5b34-11d1-b5ba-00a0c9064368
99 OCAF-MyApplication.RetrievalPlugin: ad696001-5b34-11d1-b5ba-00a0c9064368
100 OCAF-MyApplicationSchema: ad696002-5b34-11d1-b5ba-00a0c9064368
101 OCAF-MyApplication.AttributeStoragePlugin: 47b0b826-d931-11d1-b5da-00a0c9064368
102 OCAF-MyApplication.AttributeRetrievalPlugin: 47b0b827-d931-11d1-b5da-00a0c9064368
107 The plugin file describes the list of required plug-ins to run the application and the
108 libraries in which plug-ins are located.
110 You need at least the <i> FWOSPlugin</i> and the plug-in drivers to run an OCAF application.
112 The syntax of each item is <i> Identification.Location Library_Name, </i> where:
113 * Identification is GUID.
114 * Location defines the location of the Identification (where its definition is found).
115 * Library_Name is the name (and path to) the library, where the plug-in is located.
117 For example, this is a Plugin file:
120 a148e300-5740-11d1-a904-080036aaa103.Location: FWOSPlugin
121 ! base document drivers plugin
122 ad696000-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
123 ad696001-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
124 ad696002-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
125 47b0b826-d931-11d1-b5da-00a0c9064368.Location: PAppStdPlugin
126 47b0b827-d931-11d1-b5da-00a0c9064368.Location: PAppStdPlugin
129 ## Implementation of Attribute Transformation in a HXX file
132 \#include <TDF_Attribute.hxx>
134 \#include <gp_Ax3.hxx>
135 \#include <gp_Pnt.hxx>
136 \#include <gp_Vec.hxx>
137 \#include <gp_Trsf.hxx>
139 //! This attribute implements a transformation data container
140 class MyPackage_Transformation : public TDF_Attribute
143 //!@ name Static methods
145 //! The method returns a unique GUID of this attribute.
146 //! By means of this GUID this attribute may be identified
147 //! among other attributes attached to the same label.
148 Standard_EXPORT static const Standard_GUID& GetID ();
150 //! Finds or creates the attribute attached to <theLabel>.
151 //! The found or created attribute is returned.
152 Standard_EXPORT static Handle(MyPackage_Transformation) Set (const TDF_Label theLabel);
154 //!@ name Methods for access to the attribute data
156 //! The method returns the transformation.
157 Standard_EXPORT gp_Trsf Get () const;
159 //!@ name Methods for setting the data of transformation
161 //! The method defines a rotation type of transformation.
162 Standard_EXPORT void SetRotation (const gp_Ax1& theAxis, Standard_Real theAngle);
164 //! The method defines a translation type of transformation.
165 Standard_EXPORT void SetTranslation (const gp_Vec& theVector);
167 //! The method defines a point mirror type of transformation (point symmetry).
168 Standard_EXPORT void SetMirror (const gp_Pnt& thePoint);
170 //! The method defines an axis mirror type of transformation (axial symmetry).
171 Standard_EXPORT void SetMirror (const gp_Ax1& theAxis);
173 //! The method defines a point mirror type of transformation (planar symmetry).
174 Standard_EXPORT void SetMirror (const gp_Ax2& thePlane);
176 //! The method defines a scale type of transformation.
177 Standard_EXPORT void SetScale (const gp_Pnt& thePoint, Standard_Real theScale);
179 //! The method defines a complex type of transformation from one coordinate system to another.
180 Standard_EXPORT void SetTransformation (const gp_Ax3& theCoordinateSystem1, const gp_Ax3& theCoordinateSystem2);
182 //!@ name Overridden methods from TDF_Attribute
184 //! The method returns a unique GUID of the attribute.
185 //! By means of this GUID this attribute may be identified among other attributes attached to the same label.
186 Standard_EXPORT const Standard_GUID& ID () const;
188 //! The method is called on Undo / Redo.
189 //! It copies the content of theAttribute into this attribute (copies the fields).
190 Standard_EXPORT void Restore (const Handle(TDF_Attribute)& theAttribute);
192 //! It creates a new instance of this attribute.
193 //! It is called on Copy / Paste, Undo / Redo.
194 Standard_EXPORT Handle(TDF_Attribute) NewEmpty () const;
196 //! The method is called on Copy / Paste.
197 //! It copies the content of this attribute into theAttribute (copies the fields).
198 Standard_EXPORT void Paste (const Handle(TDF_Attribute)& theAttribute, const Handle(TDF_RelocationTable)& theRelocationTable);
200 //! Prints the content of this attribute into the stream.
201 Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS);
203 //!@ name Constructor
205 //! The C++ constructor of this attribute class.
206 //! Usually it is never called outside this class.
207 Standard_EXPORT MyPackage_Transformation();
212 // Axes (Ax1, Ax2, Ax3)
219 Standard_Real myAngle;
220 Standard_Real myScale;
224 gp_Pnt mySecondPoint;
228 ## Implementation of Attribute Transformation in a CPP file
231 \#include <MyPackage_Transformation.hxx>
233 //=======================================================================
235 //purpose : The method returns a unique GUID of this attribute.
236 // By means of this GUID this attribute may be identified
237 // among other attributes attached to the same label.
238 //=======================================================================
239 const Standard_GUID& MyPackage_Transformation::GetID()
241 static Standard_GUID ID("4443368E-C808-4468-984D-B26906BA8573");
245 //=======================================================================
247 //purpose : Finds or creates the attribute attached to <theLabel>.
248 // The found or created attribute is returned.
249 //=======================================================================
250 Handle(MyPackage_Transformation) MyPackage_Transformation::Set(const TDF_Label& theLabel)
252 Handle(MyPackage_Transformation) T;
253 if (!theLabel.FindAttribute(MyPackage_Transformation::GetID(), T))
255 T = new MyPackage_Transformation();
256 theLabel.AddAttribute(T);
261 //=======================================================================
263 //purpose : The method returns the transformation.
264 //=======================================================================
265 gp_Trsf MyPackage_Transformation::Get() const
267 gp_Trsf transformation;
276 transformation.SetRotation(myAx1, myAngle);
281 transformation.SetTranslation(myFirstPoint, mySecondPoint);
286 transformation.SetMirror(myFirstPoint);
291 transformation.SetMirror(myAx1);
296 transformation.SetMirror(myAx2);
301 transformation.SetScale(myFirstPoint, myScale);
304 case gp_CompoundTrsf:
306 transformation.SetTransformation(myFirstAx3, mySecondAx3);
314 return transformation;
317 //=======================================================================
318 //function : SetRotation
319 //purpose : The method defines a rotation type of transformation.
320 //=======================================================================
321 void MyPackage_Transformation::SetRotation(const gp_Ax1& theAxis, const Standard_Real theAngle)
324 myType = gp_Rotation;
329 //=======================================================================
330 //function : SetTranslation
331 //purpose : The method defines a translation type of transformation.
332 //=======================================================================
333 void MyPackage_Transformation::SetTranslation(const gp_Vec& theVector)
336 myType = gp_Translation;
337 myFirstPoint.SetCoord(0, 0, 0);
338 mySecondPoint.SetCoord(theVector.X(), theVector.Y(), theVector.Z());
341 //=======================================================================
342 //function : SetMirror
343 //purpose : The method defines a point mirror type of transformation
345 //=======================================================================
346 void MyPackage_Transformation::SetMirror(const gp_Pnt& thePoint)
349 myType = gp_PntMirror;
350 myFirstPoint = thePoint;
353 //=======================================================================
354 //function : SetMirror
355 //purpose : The method defines an axis mirror type of transformation
357 //=======================================================================
358 void MyPackage_Transformation::SetMirror(const gp_Ax1& theAxis)
361 myType = gp_Ax1Mirror;
365 //=======================================================================
366 //function : SetMirror
367 //purpose : The method defines a point mirror type of transformation
368 // (planar symmetry).
369 //=======================================================================
370 void MyPackage_Transformation::SetMirror(const gp_Ax2& thePlane)
373 myType = gp_Ax2Mirror;
377 //=======================================================================
378 //function : SetScale
379 //purpose : The method defines a scale type of transformation.
380 //=======================================================================
381 void MyPackage_Transformation::SetScale(const gp_Pnt& thePoint, const Standard_Real theScale)
385 myFirstPoint = thePoint;
389 //=======================================================================
390 //function : SetTransformation
391 //purpose : The method defines a complex type of transformation
392 // from one coordinate system to another.
393 //=======================================================================
394 void MyPackage_Transformation::SetTransformation(const gp_Ax3& theCoordinateSystem1,
395 const gp_Ax3& theCoordinateSystem2)
398 myFirstAx3 = theCoordinateSystem1;
399 mySecondAx3 = theCoordinateSystem2;
402 //=======================================================================
404 //purpose : The method returns a unique GUID of the attribute.
405 // By means of this GUID this attribute may be identified
406 // among other attributes attached to the same label.
407 //=======================================================================
408 const Standard_GUID& MyPackage_Transformation::ID() const
413 //=======================================================================
415 //purpose : The method is called on Undo / Redo.
416 // It copies the content of <theAttribute>
417 // into this attribute (copies the fields).
418 //=======================================================================
419 void MyPackage_Transformation::Restore(const Handle(TDF_Attribute)& theAttribute)
421 Handle(MyPackage_Transformation) theTransformation = Handle(MyPackage_Transformation)::DownCast(theAttribute);
422 myType = theTransformation->myType;
423 myAx1 = theTransformation->myAx1;
424 myAx2 = theTransformation->myAx2;
425 myFirstAx3 = theTransformation->myFirstAx3;
426 mySecondAx3 = theTransformation->mySecondAx3;
427 myAngle = theTransformation->myAngle;
428 myScale = theTransformation->myScale;
429 myFirstPoint = theTransformation->myFirstPoint;
430 mySecondPoint = theTransformation->mySecondPoint;
433 //=======================================================================
434 //function : NewEmpty
435 //purpose : It creates a new instance of this attribute.
436 // It is called on Copy / Paste, Undo / Redo.
437 //=======================================================================
438 Handle(TDF_Attribute) MyPackage_Transformation::NewEmpty() const
440 return new MyPackage_Transformation();
443 //=======================================================================
445 //purpose : The method is called on Copy / Paste.
446 // It copies the content of this attribute into
447 // <theAttribute> (copies the fields).
448 //=======================================================================
449 void MyPackage_Transformation::Paste(const Handle(TDF_Attribute)& theAttribute,
450 const Handle(TDF_RelocationTable)& ) const
452 Handle(MyPackage_Transformation) theTransformation = Handle(MyPackage_Transformation)::DownCast(theAttribute);
453 theTransformation->myType = myType;
454 theTransformation->myAx1 = myAx1;
455 theTransformation->myAx2 = myAx2;
456 theTransformation->myFirstAx3 = myFirstAx3;
457 theTransformation->mySecondAx3 = mySecondAx3;
458 theTransformation->myAngle = myAngle;
459 theTransformation->myScale = myScale;
460 theTransformation->myFirstPoint = myFirstPoint;
461 theTransformation->mySecondPoint = mySecondPoint;
464 //=======================================================================
466 //purpose : Prints the content of this attribute into the stream.
467 //=======================================================================
468 Standard_OStream& MyPackage_Transformation::Dump(Standard_OStream& anOS) const
470 anOS = "Transformation: ";
475 anOS = "gp_Identity";
480 anOS = "gp_Rotation";
485 anOS = "gp_Translation";
490 anOS = "gp_PntMirror";
495 anOS = "gp_Ax1Mirror";
500 anOS = "gp_Ax2Mirror";
508 case gp_CompoundTrsf:
510 anOS = "gp_CompoundTrsf";
522 //=======================================================================
523 //function : MyPackage_Transformation
524 //purpose : A constructor.
525 //=======================================================================
526 MyPackage_Transformation::MyPackage_Transformation():myType(gp_Identity){
531 ## Implementation of typical actions with standard OCAF attributes.
533 There are four sample files provided in the directory 'OpenCasCade/ros/samples/ocafsamples'. They present typical actions with OCAF services (mainly for newcomers).
534 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.
536 ### TDataStd_Sample.cxx
537 This sample contains templates for typical actions with the following standard OCAF attributes:
538 - Starting with data framework;
539 - TDataStd_Integer attribute management;
540 - TDataStd_RealArray attribute management;
541 - TDataStd_Comment attribute management;
542 - TDataStd_Name attribute management;
543 - TDataStd_UAttribute attribute management;
544 - TDF_Reference attribute management;
545 - TDataXtd_Point attribute management;
546 - TDataXtd_Plane attribute management;
547 - TDataXtd_Axis attribute management;
548 - TDataXtd_Geometry attribute management;
549 - TDataXtd_Constraint attribute management;
550 - TDataStd_Directory attribute management;
551 - TDataStd_TreeNode attribute management.
553 ### TDocStd_Sample.cxx
554 This sample contains template for the following typical actions:
555 - creating application;
556 - creating the new document (document contains a framework);
557 - retrieving the document from a label of its framework;
558 - filling a document with data;
559 - saving a document in the file;
560 - closing a document;
561 - opening the document stored in the file;
562 - copying content of a document to another document with possibility to update the copy in the future.
564 ### TPrsStd_Sample.cxx
565 This sample contains template for the following typical actions:
566 - starting with data framework;
567 - setting the TPrsStd_AISViewer in the framework;
568 - initialization of aViewer;
569 - finding TPrsStd_AISViewer attribute in the DataFramework;
570 - getting AIS_InteractiveContext from TPrsStd_AISViewer;
571 - adding driver to the map of drivers;
572 - getting driver from the map of drivers;
573 - setting TNaming_NamedShape to \<ShapeLabel\>;
574 - setting the new TPrsStd_AISPresentation to \<ShapeLabel\>;
577 - updating and displaying presentation of the attribute to be displayed;
578 - setting a color to the displayed attribute;
579 - getting transparency of the displayed attribute;
581 - updating presentation of the attribute in viewer.
583 ### TNaming_Sample.cxx
584 This sample contains template for typical actions with OCAF Topological Naming services.
585 The following scenario is used:
586 - data framework initialization;
587 - creating Box1 and pushing it as PRIMITIVE in DF;
588 - creating Box2 and pushing it as PRIMITIVE in DF;
589 - moving Box2 (applying a transformation);
590 - pushing the selected edges of the top face of Box1 in DF;
591 - creating a Fillet (using the selected edges) and pushing the result as a modification of Box1;
592 - creating a Cut (Box1, Box2) as a modification of Box1 and push it in DF;
593 - recovering the result from DF.