0031939: Coding - correction of spelling errors in comments [part 3]
[occt.git] / dox / samples / ocaf.md
1 OCAF Usage {#samples__ocaf}
2 ========
3
4 ## Getting  Started
5
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.  
9    
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).  
14    
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.  
19    
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:  
22    
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 :
26     * Undo-redo;  
27     * Save and open application data.  
28  
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.
33  
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.  
36   
37 ## An example of OCAF usage
38
39 To create a useful OCAF-based application, it is necessary to redefine two deferred methods: <i> Formats</i> and <i> ResourcesName</i>
40
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.
42
43 For example:
44
45 ~~~~
46     void myApplication::Formats(TColStd_SequenceOfExtendedString& Formats)
47     {
48       Formats.Append(TCollection_ExtendedString ("OCAF-myApplication"));
49     }
50 ~~~~
51
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.
55
56 ~~~~
57     Standard_CString myApplication::ResourcesName()
58     {
59       return Standard_CString ("Resources");
60     }
61 ~~~~
62
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:
64
65 ~~~~
66     SetEnvironmentVariable ( "CSF_ResourcesDefaults",myDirectory);
67     SetEnvironmentVariable ( "CSF_PluginDefaults",myDirectory);
68 ~~~~
69
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>.
72
73 ### Resource File
74
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.
78
79 Each driver is unique and identified by a GUID generated, for example, with the <i> uuidgen </i> tool in Windows.
80
81 Five drivers are required to use all standard attributes provided within OCAF:
82
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)
88
89 These drivers are provided as plug-ins and are located in the <i> PappStdPlugin</i> library.
90
91
92 For example, this is a resource file, which declares a new model document OCAF-MyApplication:
93
94 ~~~~
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
103 ~~~~
104    
105 ### Plugin File
106
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.
109
110 You need at least the <i> FWOSPlugin</i> and the plug-in drivers to run an OCAF application.
111
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.
116
117 For example, this is a Plugin file:
118
119 ~~~~
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
127 ~~~~
128  
129 ## Implementation of Attribute Transformation in a HXX file
130
131 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
132 \#include <TDF_Attribute.hxx>
133
134 \#include <gp_Ax3.hxx>
135 \#include <gp_Pnt.hxx>
136 \#include <gp_Vec.hxx>
137 \#include <gp_Trsf.hxx>
138
139 //! This attribute implements a transformation data container
140 class MyPackage_Transformation : public TDF_Attribute
141 {
142 public:
143   //!@ name Static methods 
144
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 ();
149
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);
153
154   //!@ name Methods for access to the attribute data 
155       
156   //! The method returns the transformation. 
157   Standard_EXPORT gp_Trsf Get () const; 
158
159   //!@ name Methods for setting the data of transformation 
160
161   //! The method defines a rotation type of transformation. 
162   Standard_EXPORT void SetRotation (const gp_Ax1& theAxis, Standard_Real theAngle); 
163
164   //! The method defines a translation type of transformation. 
165   Standard_EXPORT void SetTranslation (const gp_Vec& theVector); 
166
167   //! The method defines a point mirror type of transformation (point symmetry). 
168   Standard_EXPORT void SetMirror (const gp_Pnt& thePoint); 
169
170   //! The method defines an axis mirror type of transformation (axial symmetry). 
171   Standard_EXPORT void SetMirror (const gp_Ax1& theAxis); 
172
173   //! The method defines a point mirror type of transformation (planar symmetry). 
174   Standard_EXPORT void SetMirror (const gp_Ax2& thePlane); 
175
176   //! The method defines a scale type of transformation. 
177   Standard_EXPORT void SetScale (const gp_Pnt& thePoint, Standard_Real theScale); 
178
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); 
181
182   //!@ name Overridden methods from TDF_Attribute 
183       
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; 
187
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); 
191
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;
195
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); 
199
200   //! Prints the content of this attribute into the stream. 
201   Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS);
202
203   //!@ name Constructor 
204
205   //! The C++ constructor of this attribute class.
206   //! Usually it is never called outside this class. 
207   Standard_EXPORT MyPackage_Transformation();
208
209 private:
210   gp_TrsfForm myType;
211
212   // Axes (Ax1, Ax2, Ax3) 
213   gp_Ax1 myAx1;
214   gp_Ax2 myAx2;
215   gp_Ax3 myFirstAx3;
216   gp_Ax3 mySecondAx3;
217
218   // Scalar values 
219   Standard_Real myAngle;
220   Standard_Real myScale;
221
222   // Points 
223   gp_Pnt myFirstPoint;
224   gp_Pnt mySecondPoint;
225 }; 
226 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
227
228 ## Implementation of Attribute Transformation in a CPP file
229
230 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
231 \#include <MyPackage_Transformation.hxx> 
232
233 //======================================================================= 
234 //function : GetID 
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()   
240
241   static Standard_GUID ID("4443368E-C808-4468-984D-B26906BA8573"); 
242   return ID; 
243
244
245 //======================================================================= 
246 //function : Set 
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)   
251
252   Handle(MyPackage_Transformation) T; 
253   if (!theLabel.FindAttribute(MyPackage_Transformation::GetID(), T))   
254   { 
255     T = new MyPackage_Transformation();   
256     theLabel.AddAttribute(T); 
257   } 
258   return T; 
259
260
261 //======================================================================= 
262 //function : Get 
263 //purpose  : The method returns the transformation. 
264 //======================================================================= 
265 gp_Trsf MyPackage_Transformation::Get() const 
266
267   gp_Trsf transformation; 
268   switch (myType) 
269   { 
270     case gp_Identity: 
271     { 
272       break; 
273     } 
274     case gp_Rotation: 
275     { 
276       transformation.SetRotation(myAx1, myAngle); 
277       break; 
278     } 
279     case gp_Translation: 
280     { 
281       transformation.SetTranslation(myFirstPoint, mySecondPoint); 
282       break; 
283     } 
284     case gp_PntMirror: 
285     { 
286       transformation.SetMirror(myFirstPoint); 
287       break; 
288     } 
289     case gp_Ax1Mirror: 
290     { 
291       transformation.SetMirror(myAx1); 
292       break; 
293     } 
294     case gp_Ax2Mirror: 
295     { 
296       transformation.SetMirror(myAx2); 
297       break; 
298     } 
299     case gp_Scale: 
300     { 
301       transformation.SetScale(myFirstPoint, myScale); 
302       break; 
303     } 
304     case gp_CompoundTrsf: 
305     { 
306       transformation.SetTransformation(myFirstAx3, mySecondAx3); 
307       break; 
308     } 
309     case gp_Other: 
310     { 
311       break; 
312     } 
313   } 
314   return transformation; 
315
316
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) 
322
323   Backup(); 
324   myType = gp_Rotation; 
325   myAx1 = theAxis; 
326   myAngle = theAngle; 
327
328
329 //======================================================================= 
330 //function : SetTranslation 
331 //purpose  : The method defines a translation type of transformation. 
332 //======================================================================= 
333 void MyPackage_Transformation::SetTranslation(const gp_Vec& theVector) 
334
335   Backup(); 
336   myType = gp_Translation; 
337   myFirstPoint.SetCoord(0, 0, 0); 
338   mySecondPoint.SetCoord(theVector.X(), theVector.Y(), theVector.Z()); 
339
340
341 //======================================================================= 
342 //function : SetMirror 
343 //purpose  : The method defines a point mirror type of transformation 
344 //           (point symmetry). 
345 //======================================================================= 
346 void MyPackage_Transformation::SetMirror(const gp_Pnt& thePoint) 
347
348   Backup(); 
349   myType = gp_PntMirror; 
350   myFirstPoint = thePoint; 
351
352
353 //======================================================================= 
354 //function : SetMirror 
355 //purpose  : The method defines an axis mirror type of transformation 
356 //           (axial symmetry). 
357 //======================================================================= 
358 void MyPackage_Transformation::SetMirror(const gp_Ax1& theAxis) 
359
360   Backup(); 
361   myType = gp_Ax1Mirror; 
362   myAx1 = theAxis; 
363
364
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) 
371
372   Backup(); 
373   myType = gp_Ax2Mirror; 
374   myAx2 = thePlane; 
375
376
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) 
382
383   Backup(); 
384   myType = gp_Scale; 
385   myFirstPoint = thePoint; 
386   myScale = theScale; 
387
388
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) 
396
397   Backup(); 
398   myFirstAx3 = theCoordinateSystem1; 
399   mySecondAx3 = theCoordinateSystem2; 
400
401
402 //======================================================================= 
403 //function : ID 
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   
409 {   
410   return GetID();   
411
412
413 //======================================================================= 
414 //function : Restore 
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)   
420
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; 
431
432
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 
439 {    
440   return new MyPackage_Transformation();   
441
442
443 //======================================================================= 
444 //function : Paste 
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 
451
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; 
462
463
464 //======================================================================= 
465 //function : Dump 
466 //purpose  : Prints the content of this attribute into the stream. 
467 //======================================================================= 
468 Standard_OStream& MyPackage_Transformation::Dump(Standard_OStream& anOS) const 
469 {    
470   anOS = "Transformation: "; 
471   switch (myType) 
472   { 
473     case gp_Identity: 
474     { 
475       anOS = "gp_Identity"; 
476       break; 
477     } 
478     case gp_Rotation: 
479     { 
480       anOS = "gp_Rotation"; 
481       break; 
482     } 
483     case gp_Translation: 
484     { 
485       anOS = "gp_Translation"; 
486       break; 
487     } 
488     case gp_PntMirror: 
489     { 
490       anOS = "gp_PntMirror"; 
491       break; 
492     } 
493     case gp_Ax1Mirror: 
494     { 
495       anOS = "gp_Ax1Mirror"; 
496       break; 
497     } 
498     case gp_Ax2Mirror: 
499     { 
500       anOS = "gp_Ax2Mirror"; 
501       break; 
502     } 
503     case gp_Scale: 
504     { 
505       anOS = "gp_Scale"; 
506       break; 
507     } 
508     case gp_CompoundTrsf: 
509     { 
510       anOS = "gp_CompoundTrsf"; 
511       break; 
512     } 
513     case gp_Other: 
514     { 
515       anOS = "gp_Other"; 
516       break; 
517     } 
518   } 
519   return anOS; 
520
521
522 //=======================================================================
523 //function : MyPackage_Transformation 
524 //purpose  : A constructor. 
525 //=======================================================================
526 MyPackage_Transformation::MyPackage_Transformation():myType(gp_Identity){ 
527
528 }
529 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
530
531 ##  Implementation of typical actions with standard OCAF attributes.
532
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.
535
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.
552   
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.
563  
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\>;
575 - displaying;
576 - erasing;
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;
580 -  modify attribute;
581 - updating presentation of the attribute in viewer.
582
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.
594