3D PLM Enterprise Architecture

User Interface - Frame

Creating a Setting Controller

Encapsulating the access to the setting file
Use Case

Abstract

This article shows how to create a setting controller.

What You Will Learn With This Use Case

This use case is intended to show how to create a setting controller component in order to encapsulate and ensure a unique access to a setting file. The setting controller enables several applications to access the parameters stored in a setting file, without having to know about the internal storage details. Setting controller ensures a consistent access to a setting file for different applications, the Tools/Options command being the most important of these applications.

This article describes a concrete use case of a setting controller. For more explanations, refer to the technical article [1] on the topic.

[Top]

The CAACafCtrlToolsOptions Use Case

CAACafCtrlToolsOptions is a use case of the CAACATIAApplicationFrm.edu framework that illustrates the CATIAApplicationFrame framework capabilities.

[Top]

What Does CAACafCtrlToolsOptions Do

CAACafCtrlToolsOptions creates the setting controller for a setting file. The options are used in our CAAGeometry document.

This setting controller is used by the Elements property page accessible with the Tools/Options command. The use case "Creating a Property Page for Application Properties" [2] describes how to create this property page.

This property page displays three parameters which are inside the following frames:

  1. The "Identifier" frame is used to modify and display the visibility of the element's identifiers. The elements are created through commands of the CAAV5 Geometrical Creation workbench. The element identifiers can be permanently:
  2. The "Max Points/Curve" frame is used to modify and display the maximum number of points used to discretize a curve.
  3. The "Implicit Points" frame is used to modify and display the visibility of implicit points. Those can be shown or hidden.

These three parameters are saved in the CAACafGeometryElt setting file and must always be accessible through the CAACafGeometryEltSettingCtrl setting controller. This controller is a component which implements the following interfaces:

[Top]

How to Launch CAACafCtrlToolsOptions

See the section entitled "How to Launch the CAAGeometry Use Case" in the "The CAAGeometry Sample" use case for a detailed description of how this use case should be launched.

[Top]

Where to Find the CAACafCtrlToolsOptions Code

The CAACafCtrlToolsOptions use case is made of classes and interfaces located in the CAACafCtrlToolsOptions.m module and in the ProtectedInterfaces directory of the CAACATIAApplicationFrm.edu framework:

Windows InstallRootDirectory\CAACATIAApplicationFrm.edu\CAACafCtrlToolsOptions.m\
Unix InstallRootDirectory/CAACATIAApplicationFrm.edu/CAACafCtrlToolsOptions.m/

where InstallRootDirectory is the directory where the CAA CD-ROM is installed.

These classes and interfaces are:

CAAICafGeometryEltSettingAtt Interface to access each parameter
TIE_CAAICafGeometryEltSettingAtt TIE to this interface
CAACafGeometryEltSettingCtrl Setting controller component main class
CAAECafGeometryEltSettingAtt Setting controller component extension class that implements CAAICafGeometryEltSettingAtt
CAAECafSettingManagmentForGeometryElt Setting controller component extension class that implements CATIIniSettingManagment
GetCAACafGeometryEltSettingCtrl Factory function to retrieve the setting controller

[Top]

Step-by-Step

To create a setting controller, there are five main steps:

  1. Creating the Interface to Access Each Parameter
  2. Creating the Setting Controller Component Main Class
  3. Implementing CAAICafGeometryEltSettingAtt
  4. Implementing CATIIniSettingManagment
  5. Creating the Factory for the Setting Controller

[Top]

Creating the Interface to Access Each Parameter

The CAAICafGeometryEltSettingAtt interface is dedicated to the access of the three parameters:

[Top]

Creating the Setting Controller Component Main Class

  1. Header file

    2. Here is the CAACafGeometryEltSettingCtrl header file:

    #include "CATBaseUnknown.h"  
#include "CATIniCleanerSettingCtrl.h" 

class  CAACafGeometryEltSettingCtrl : public CATBaseUnknown
{  
   CATDeclareClass;

   public:
 
   CAACafGeometryEltSettingCtrl();
   virtual ~CAACafGeometryEltSettingCtrl(); 

   static HRESULT GetSettingController(CAACafGeometryEltSettingCtrl ** oCtrl);

 private:
   CAACafGeometryEltSettingCtrl(const CAACafGeometryEltSettingCtrl &iObjectToCopy);
   CAACafGeometryEltSettingCtrl & operator = (const CAACafGeometryEltSettingCtrl &iObjectToCopy);

 private:
   static CATIniCleanerSettingCtrl _CleanerCtrl ;
};

    The CAACafGeometryEltSettingCtrl C++ class derives from CATBaseUnknown. The CATDeclareClass macro declares that the CAACafGeometryEltSettingCtrl class belongs to a component. The copy constructor and the "=" operator are set as private to prevent the compiler from automatically creating them as public.

    The CAACafGeometryEltSettingCtrl component class is created only once during a session. The GetSettingController method returns the unique pointer to this class. To manage the destruction of this pointer, an instance of the CATIniCleanerSettingCtrl class is used. The _CleanerCtrl static data member contains this unique pointer.

  2. Source file

    3. Here is the CAACafGeometryEltSettingCtrl source file:

    #include "CAACafGeometryEltSettingCtrl.h"
#include "CAAICafGeometryEltSettingAtt.h"
#include "CATIIniSettingManagment.h"
#include "CATErrorDef.h"
#include "CATBoolean.h"

CATIniCleanerSettingCtrl CAACafGeometryEltSettingCtrl::_CleanerCtrl ;

CATImplementClass(CAACafGeometryEltSettingCtrl, 
                     Implementation, 
                     CATBaseUnknown , 
                     CATNull);

CAACafGeometryEltSettingCtrl::CAACafGeometryEltSettingCtrl()
{
}

CAACafGeometryEltSettingCtrl::~CAACafGeometryEltSettingCtrl()
{
} 
...

    The _CleanerCtrl static data member is created.

    The CATImplementClass macro declares that the CAACafGeometryEltSettingCtrl class is a component main class thanks to the Implementation keyword, and it also OM-derives [4] from CATBaseUnknown.

    The constructor and destructor are empty.

    ...
HRESULT CAACafGeometryEltSettingCtrl::GetSettingController
                                      (CAACafGeometryEltSettingCtrl ** oCtrl)
{
 HRESULT rc = S_OK ;

        if ( NULL != oCtrl )
        {
           *oCtrl = NULL ;

           CATBaseUnknown * pCtrl = _CleanerCtrl.GetController();
           if ( NULL == pCtrl )
           {
               CAACafGeometryEltSettingCtrl * SettingController = NULL;
               SettingController = new CAACafGeometryEltSettingCtrl();
               if ( NULL == SettingController )
               {
                  rc = E_OUTOFMEMORY ;
               }else
               {
                  CATBoolean Init = FALSE ;

                  // The Initialization is mandatory
                  CAAICafGeometryEltSettingAtt * pISettingAtForCtrl = NULL ;
                  rc = SettingController->QueryInterface(IID_CAAICafGeometryEltSettingAtt,
                                                        (void**) &pISettingAtForCtrl );
                  if ( SUCCEEDED(rc) )
                  {
                     rc = pISettingAtForCtrl->Initialize();
                     if ( SUCCEEDED(rc) )
                     {
                        CATIIniSettingManagment * pIMgtAtForCtrl = NULL ;
                        rc = SettingController->QueryInterface(IID_CATIIniSettingManagment,
                                                               (void**) &pIMgtAtForCtrl );
                        if ( SUCCEEDED(rc) )
                        {
                           // For the first Roolback 
                           pIMgtAtForCtrl->Commit() ;                      

                           pIMgtAtForCtrl->Release();
                           pIMgtAtForCtrl = NULL; 

                           // The cleaner keeps the unique instance
                           _CleanerCtrl.SetController(SettingController);

                           *oCtrl = SettingController ;
                           Init = TRUE ;
                        }

                     }
                     pISettingAtForCtrl->Release();
                     pISettingAtForCtrl = NULL ;
                  }

                  if ( FALSE == Init ) 
                  {
                     SettingController->Release() ;
                     SettingController = NULL ; 
                  }
               }
           }else  
           {
              *oCtrl = (CAACafGeometryEltSettingCtrl *) pCtrl ;
           }
                
        }else rc = E_FAIL ;

        return rc ;
}

    The goal of this method is to return a pointer to the CAACafGeometryEltSettingCtrl class. This unique pointer is saved in the _CleanerCtrl data member.

    Before setting the new controller in _CleanerCtrl, using the SetController method, it is first necessary to execute the following methods:

[Top]

Implementing CAAICafGeometryEltSettingAtt

The implement class is the CAAECafGeometryEltSettingCtrl class.

  1. Header file

    2. Here is the CAAECafGeometryEltSettingCtrl header file:

    #include "CATBaseUnknown.h"
class CATSettingRepository ;

#include "CAAICafGeometryEltSettingAtt.h" 
class CAAECafGeometryEltSettingAtt: public CATBaseUnknown
{
  CATDeclareClass;

  public:

    CAAECafGeometryEltSettingAtt();
    virtual ~CAAECafGeometryEltSettingAtt();

    virtual  HRESULT   Initialize() ;

    virtual  HRESULT   GetIdentifierVisibility(CATString & oIdVisibility)   ;

    virtual  HRESULT   SetIdentifierVisibility(const CATString & iIdVisibility)  ;

    virtual  HRESULT   GetInfoIdentifierVisibility(CATSettingInfo * oInfo)  ;


    virtual  HRESULT   GetMaxPointCurve(int & oMaxPoint)       ;

    virtual  HRESULT   SetMaxPointCurve(const int iMaxPoint)  ;

    virtual  HRESULT   GetInfoMaxPointCurve(CATSettingInfo ** oInfoArray, int * oNbSettingInfo)  ;


    virtual  HRESULT   GetImplPointVisibility(CATString & oImplPointVisibility)        ;
    
    virtual  HRESULT   SetImplPointVisibility(const CATString & iImplPointVisibility)  ;

    virtual  HRESULT   GetInfoImplPointVisibility(CATSettingInfo * oInfo)  ;

  private:

    CAAECafGeometryEltSettingAtt(const CAAECafGeometryEltSettingAtt &iObjectToCopy);
    CAAECafGeometryEltSettingAtt & operator = (const CAAECafGeometryEltSettingAtt &iObjectToCopy);

  private:

    CATSettingRepository *   _pSettingRep     ;
};
#endif

    The CAAECafGeometryEltSettingAtt C++ class derives from CATBaseUnknown. The CATDeclareClass macro declares that the CAAECafGeometryEltSettingAtt class belongs to a component. The copy constructor and the "=" operator are set as private to prevent the compiler from automatically creating as public.

    The public methods other than the constructor and the destructor, are methods defined in the CAAICafGeometryEltSettingAtt interface.

    In the private data section, _pSettingRep is a pointer to the CATSettingRepository [5] used to access the attributes of the setting file.

     

  2. Source file

    3. Here is the CAAECafGeometryEltSettingCtrl source file:

  3. Interface dictionary

    4. In the interface dictionary dedicated to the CAACATIAApplicationFrm.edu framework, it is necessary to add the following line to indicate that the CAACafGeometryEltSettingCtrl component implements the CAAICafGeometryEltSettingAtt interface in the CAACafCtrlToolsOptions module.

    CAACafGeometryEltSettingCtrl CAAICafGeometryEltSettingAtt libCAACafCtrlToolsOptions

[Top]

Implementing CATIIniSettingManagment

The CATIIniSettingManagment interface manages general methods of the setting repository. The implemention class is the CAAECafSettingManagmentForGeometryElt class.

  1. Header file

    2. Here is the CAAECafSettingManagmentForGeometryElt header file:

    #include "CATIIniSettingManagment.h" 
#include "CATEIniSettingManagment.h" 

class CAAECafSettingManagmentForGeometryElt: public CATEIniSettingManagment
{
  CATDeclareClass;

  public:

    CAAECafSettingManagmentForGeometryElt();

    virtual ~CAAECafSettingManagmentForGeometryElt();

  private:

    CAAECafSettingManagmentForGeometryElt(const CAAECafSettingManagmentForGeometryElt &iObjectToCopy);
    CAAECafSettingManagmentForGeometryElt & operator = (const CAAECafSettingManagmentForGeometryElt &iObjectToCopy);

};

    The CAAECafSettingManagmentForGeometryElt C++ class derives from CATEIniSettingManagment. This adapter class is defined in the InteractiveInterfaces framework. The CATDeclareClass macro declares that the CAAECafSettingManagmentForGeometryElt class belongs to a component. The copy constructor and the " =" operator are set as private to prevent the compiler from automatically creating as public.

  2. Source file
    3.

    Here is the CAAECafSettingManagmentForGeometryElt source file:

    #include "CAAECafSettingManagmentForGeometryElt.h"

#include "TIE_CATIIniSettingManagment.h"
TIE_CATIIniSettingManagment(CAAECafSettingManagmentForGeometryElt);

CATImplementClass(CAAECafSettingManagmentForGeometryElt,
                  DataExtension,
                  CATBaseUnknown,
                  CAACafGeometryEltSettingCtrl);

CAAECafSettingManagmentForGeometryElt::CAAECafSettingManagmentForGeometryElt():
                   CATEIniSettingManagment("CAACafGeometryElt")
{
}

CAAECafSettingManagmentForGeometryElt::~CAAECafSettingManagmentForGeometryElt()
{
}

    The CAAECafSettingManagmentForGeometryElt class states that it implements the CATIIniSettingManagment interface thanks to the TIE_CATIIniSettingManagment macro. This extension class is dedicated to the controller component. The CATImplementClass macro declares that the CAAECafSettingManagmentForGeometryElt class is a data extension class, thanks to the DataExtension keyword and that it extends the component whose main class is CAACafGeometryEltSettingCtrl. The third parameter must always be set to CATBaseUnknown; it makes no sense here as it.

    The constructor calls the constructor of the CATEIniSettingManagment adaptor using the name of the setting file, CAACafGeometryElt, the same name as in the CAAECafGeometryEltSettingAtt constructor. Refer to the Constructor-Destructor section in previous step.

    The destructor is empty.
  3. Interface dictionary

    4. In the interface dictionary dedicated to the CAACATIAApplicationFrm.edu framework, it is necessary to add the following line in order to declare that the CAACafGeometryEltSettingCtrl component implements the CATIIniSettingManagment interface in the CAACafCtrlToolsOptions module.

    CAACafGeometryEltSettingCtrl CATIIniSettingManagment libCAACafCtrlToolsOptions

[Top]

Creating the Factory for the Setting Controller

The CAACafGeometryEltSettingCtrl header class is located in a LocalInterfaces directory, so that the only way to retrieve a pointer on it, is to use the public global function. This function returns a pointer to an interface implemented by the setting controller component.

  1. Header file

    2. Here is the GetCAACafGeometryEltSettingCtrl header file:

    #include "IUnknown.h"  
#include "CAACafCtrlToolsOptions.h" 

HRESULT ExportedByCAACafCtrlToolsOptions
        GetCAACafGeometryEltSettingCtrl(const IID & iInterfaceIdentifier ,
                                        void ** oInterfacePointer) ;

    The GetCAACafGeometryEltSettingCtrl global function is exported by the CAACafCtrlToolsOptions module.
  2. Source file

    3. Here is the GetCAACafGeometryEltSettingCtrl source file:

    #include "GetCAACafGeometryEltSettingCtrl.h" 
#include "CAACafGeometryEltSettingCtrl.h"    
#include "CATErrorDef.h" 

HRESULT GetCAACafGeometryEltSettingCtrl(const IID & iInterfaceIdentifier,
                                       void     ** oInterfacePointer)
{
   HRESULT rc = S_OK ;

   if ( NULL != oInterfacePointer )
   {
       CAACafGeometryEltSettingCtrl * pCtrl = NULL ;
       rc = ::CAACafGeometryEltSettingCtrl::GetSettingController(&pCtrl);
       if ( SUCCEEDED(rc) && ( NULL != pCtrl) )
       {
         rc = pCtrl->QueryInterface(iInterfaceIdentifier,oInterfacePointer);
  
         pCtrl->Release();
         pCtrl= NULL ;
       } 
       else
       {
           rc = E_FAIL ;
       }
   }else rc = E_FAIL ;

   return rc ;
}

    The GetSettingController method of the CAACafGeometryEltSettingCtrl class is called to the retrieve the unique pointer of the CAACafGeometryEltSettingCtrl class. Then, a QueryInterface on the input interface is called, to retrieve the requested interface pointer.

[Top]

In Short

This use case has demonstrated how to create a setting controller through the creation of:

[Top]

References

[1] The Setting Controller
[3] Creating a Property Page for Application Properties
[4] About Globally Unique IDentifiers
[5] Object Modeler Component and Implementation Inheritances
[6] Setting Repositories and Attributes
[Top]

History

Version: 1 [Jan 2002] Document created
[Top]

Copyright © 2002, Dassault Systèmes. All rights reserved.