Creating a Property Page for Application Properties

3D PLM Enterprise Architecture	User Interface - Frame	Creating a Property Page for Application Properties Customizing the Tools Options dialog box
Use Case

Abstract

This article shows how to add a property page to a property sheet for a given workshop or workbench displayed in the Tools Options dialog box.

What You Will Learn With This Use Case
The CAACafEltToolsOptions Case
Step-by-Step
In Short
References

What You Will Learn With This Use Case

This use case is intended to show how to create a property page for a given workshop or workbench [1]. It is important to refer to the technical article "Application Property Access" before reading this article [2].

Each property page contains options managed as setting attributes [3] which are stored on disk in a setting file and in a memory in a CATSettingRepositoty class instance. The Tools Options command, such as other commands, must not directly handle the setting repository but it's setting controller [4].

[Top]

The CAACafEltToolsOptions Use Case

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

[Top]

What Does CAACafEltToolsOptions Do

CAACafEltToolsOptions creates the Elements property page that contains three frames: Identifier, Max Points/Curve, and Implicit Points. This property page is associated with the "CAA V5: Geometrical Creation" workbench of the Infrastructure submenu of the Start menu [1]. The dialog box is as follows:

The left part of the dialog box is dedicated to workshop or workbench selection in a tree. The right part displays the property sheet for the selected workshop or workbench. It is automatically generated at run time using the available workshops and workbenches. The property sheet for the "CAA V5: Geometrical Creation" workbench is made of a single property page named "Elements". It includes three frames:

The "Identifier" frame manages the visibility of the identifiers of the elements for which the workbench supplies creation commands. The element identifiers can be permanently:
- Hidden
- Shown
- Shown only when elements are preselected, that is, when the mouse is located above them.
  This property can be set thanks to three radio buttons.
The "Max Points/Curve" frame manages the maximum number of points in a curve. This property can be set thanks to a slider whose value can range from 2 to 100
The "Implicit Points" frame manages whether implicit points should be shown or hidden. This property can be set thanks to two radio buttons.

These three options are saved in a setting file named CAACafGeometryEltSetting.CATSetting and managed by a setting controller. This controller is a component named CAACafGeometryEltSettingCtrl [5]. This component implements the following interfaces:

CATIIniSettingManagment
This interface, defined in the InteractiveInterfaces Framework, manages general methods of the setting repository: Commit, Save, etc.
CAAICafGeometryEltSettingAtt
This interface, dedicated to the current setting file, allows each application to get and set setting attributes without knowing the internal storage.

[Top]

How to Launch CAACafEltToolsOptions

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.

But just before launching the execution, edit the CAACATIAApplicationFrm.edu.dico interface dictionary file located in the dictionary directory of the CAACATIAApplicationFrm.edu framework:

Windows	`InstallRootDirectory\CAACATIAApplicationFrm.edu\CNext\code\dictionary\`
UNIX	`InstallRootDirectory/CAACATIAApplicationFrm.edu/CNext/code/dictionary/`

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

In this file, remove the "#" character before the two following lines, and then run mkCreateRuntimeView.

# CAACafElementPropertyPageEdt CATIUserSettings libCAACafEltToolsOptions
# CAACafViewPropertyPageEdt    CATIUserSettings libCAACafViewToolsOptions

The second line deals with the View property page created by the non-described CAACafViewToolsOptions use case located in the CAACafViewToolsOptions.m module.

Then, in the window where you run the mkrun command, do not type the module name on the command line, but type CNEXT instead. When the application is ready, do the following:

Point Tools and click Options
Click Infrastructure in the left part of the dialog box
In the list of workbenches displayed, click CAA V5: Geometrical Creation

[Top]

Where to Find the CAACafEltToolsOptions Code

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

Windows	`InstallRootDirectory\CAACATIAApplicationFrm.edu\CAACafEltToolsOptions.m\`
Unix	`InstallRootDirectory/CAACATIAApplicationFrm.edu/CAACafEltToolsOptions.m/`

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

These classes and interfaces are:

CAACafElementPropertyPageEdt	Property page editor class
CAACafElementPropertyPageEdtFactory	Factory class for the property page editor class
CAAICafElementPropertyPageEdtFactory	Factory interface implemented by CAACafElementPropertyPageEdtFactory
TIE_CAAICafElementPropertyPageEdtFactory	TIE class for the factory interface
CAACafElementPropertyPageDlg	Dialog box class associated with the property page

[Top]

Step-by-Step

To create a property page, there are seven main steps:

Creating the property page editor factory interface
Creating the property page editor factory
Creating the property page editor
Setting the resources for the property page editor
Creating the property page dialog
Setting the resources for the property page Dialog
Testing in administrator mode

[Top]

Creating the Property Page Editor Factory Interface

This factory interface is named CAAICafElementPropertyPageEdtFactory. To create this interface, create:

The header file
The source file
The TIE tsrc file.

This is shown below.

Header file: CAAICafElementPropertyPageEdtFactory.h is as follows

#include <CATIGenericFactory.h>

extern IID IID_CAAICafElementPropertyPageEdtFactory;

class CAAICafElementPropertyPageEdtFactory : public CATIGenericFactory
{
  CATDeclareInterface;
  public :
};

A factory interface is an interface, that is, an abstract class that derives from CATIGenericFactory. Like any interface, it has an IID declared as IID_ followed by the interface name, and includes the CATDeclareInterface macro that declares that this abstract class is an interface. No additional method than those of CATIGenericFactory is necessary. Don't forget the public keyword required by the TIE compiler.

Source file: CAAICafElementPropertyPageEdtFactory.cpp is as follows.

#include "CAAICafElementPropertyPageEdtFactory.h"

IID IID_CAAICafElementPropertyPageEdtFactory = {
    0x4ee83c16,
    0xd55d,
    0x11d3,
    {0xb7, 0xf5, 0x00, 0x08, 0xc7, 0x4f, 0xe8, 0xdd}
  };

CATImplementInterface(CAAICafElementPropertyPageEdtFactory, CATIGenericFactory);

This file includes a GUID [6], shown in bold typeface. The CATDeclareInterface in the header file and the CATImplementInterface macros make an interface from this C++ class. CATImplementInterface states that CAAICafElementPropertyPageEdtFactory OM-derives [7] from CATIGenericFactory.

TIE file: to enable components to implement this interface, create a file named TIE_CAAICafElementPropertyPageEdtFactory.tsrc in the src directory, and containing:
#include "CAAICafElementPropertyPageEdtFactory.h"
The Multi-Workspace Application Builder (mkmk) will generate the TIE for this interface, that is the TIE_CAAICafElementPropertyPageEdtFactory.h file for you in the ProtectedGenerated directory.

[Top]

Creating the Property Page Editor Factory

Macros help to create the class. These macros create a class whose name is made of the property page editor class name to which the string Factory is appended. This is the reason why the header file is named CAACafElementPropertyPageEdtFactory.h and the source file is named CAACafElementPropertyPageEdtFactory.cpp.

To create this class, create:

The header file, using the CAT_EDITOR_DECLARE_FACTORY macro
The source file, using the CAT_EDITOR_DEFINE_FACTORY2 macro
Update the interface dictionary and the factory dictionary.

The macros help you to create the class. These macros create a class whose name is made of the property page editor class name to which the string Factory is appended. This is the reason why this class is named CAACafElementPropertyPageEdtFactory.

Header file: CAACafElementPropertyPageEdtFactory.h is as follows.

#include <CATEditorFactory.h>
#include <CAACafElementPropertyPageEdt.h>

#define ExportedByNOTHING

CAT_EDITOR_DECLARE_FACTORY(NOTHING,
                           CAACafElementPropertyPageEdt,
                           CAACafElementPropertyPageEdt);

The CAT_EDITOR_DECLARE_FACTORY macro creates the factory class header file contents. It is important to set the same string wherever NOTHING is used in this example. ExportedByNOTHING sets a non existing shared library or DLL to the class. Setting a valid one is useless, since the created class in an extension of CATUserSettingManager, and its instantiation is made when CATUserSettingManager is asked for a pointer to CAAICafElementPropertyPageEdtFactory. In this case, the shared library or DLL is known using the interface dictionary. The second parameter is the name of the property page editor class. This name is used to create the factory class name by appending Factory, that is, CAACafElementPropertyPageEdtFactory in this example. The third parameter is a type assigned to the class to create that could be retrieved using the CATIGenericFactory::Support method, but that is unused here, and simply set as the property page editor class name.

Source file: CAACafElementPropertyPageEdtFactory.cpp is as follows.

#include <CAACafElementPropertyPageEdtFactory.h>

CAT_EDITOR_DEFINE_FACTORY2(CAACafElementPropertyPageEdt,
                           CAACafElementPropertyPageEdt);

#include <TIE_CAAICafElementPropertyPageEdtFactory.h>
TIE_CAAICafElementPropertyPageEdtFactory(CAACafElementPropertyPageEdtFactory);

The CAT_EDITOR_DEFINE_FACTORY2 macro creates the property page editor factory implementation class contents as a data extension of the CATUserSettingManager component. CATUserSettingManager manages all the property page editor factories for Tools Options. Then the TIE macro declares that this extension class implements the CAAICafElementPropertyPageEdtFactory interface.

Dictionary files: you should now update
- The interface dictionary, that is, a file whose name is the framework name suffixed by dico, such as CAACATIAApplicationFrm.edu.dico. You should create or update it in the framework CNext/code/dictionary directory. The interface dictionary contains the following declaration to state that the CATUserSettingsManager component implements the CAAICafElementPropertyPageEdtFactory interface, by means of the extension class created by the macros, whose code is located in the libCAACafEltToolsOptions shared library or DLL:
  CATUserSettingsManager CAAICafElementPropertyPageEdtFactory libCAACafEltToolsOptions
- The factory dictionary, that is, a file whose name is the framework name suffixed by fact, such as CAACATIAApplicationFrm.edu.fact. You should create or update it in the framework CNext/code/dictionary directory. The factory dictionary contains the following declaration to state that the CAAICafElementPropertyPageEdtFactory interface is an interface to a factory whose implementation creates an CAACafElementPropertyPageEdt class instance:
  CAACafElementPropertyPageEdt CAAICafElementPropertyPageEdtFactory
At run time, the pathname of the directory that contains these files is concatenated in the CATDictionaryPath environment variable.

[Top]

Creating the Property Page Editor

You'll now create the class for the property page editor. This class should implement the CATIUserSettings interface, derive from the CATEditor class, and override methods that are either pure virtual or empty in their CATEditor implementation. You should provide their body to make them play the following roles.

`BuildEditor`	Instantiates the associated dialog class
`SetUserSettingValue`	Sets the values in the property page from the setting controller
`ResetUserSettingValue`	Restores the values set by the administrator, or if any, restores the default values set in the code
`CancelModification`	Cancels the modifications made to values in the property page and restore the previous ones
`CommitModification`	Saves the modifications in the setting file.

The property page editor class header file is shown below.

#ifndef CAACafElementPropertyPageEdt_H
#define CAACafElementPropertyPageEdt_H

// CATIAApplicationFrame framework
#include "CATEditor.h"                // Needed to derive from CATEditor
class CATIIniSettingManagment ;       // Interface to handle the setting controller

// Local framework
class CAACafElementPropertyPageDlg;   // Property page dialog  

// System framework
class CATSettingRepository;

class CAACafElementPropertyPageEdt : public CATEditor
{
  CATDeclareClass;

  public :

    CAACafElementPropertyPageEdt();
    virtual ~CAACafElementPropertyPageEdt();

    void             BuildEditor           (CATEditorPage * iTabPage);
    void             SetUserSettingsValue  (CATSettingRepository * iUselessFileRep);
    void             ResetUserSettingsValue();
    void             CancelModification    (CATSettingRepository * iUselessFileRep);
    void             CommitModification    (CATSettingRepository * iUselessFileRep);

 private:

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

  private : 

    CAACafElementPropertyPageDlg  *  _pDialogPage;
    CATIIniSettingManagment       *  _pISettingManagmentForCtrl ;
};
#endif

The CAACafElementProperetyPageEdt class C++ derives from CATEditor. The CATDeclareClass macro declares that the class CAACafElementProperetyPageEdt belongs to a component. Note that the copy constructor and the assignment operator are set as private, and are not implemented in the source file. This prevents the compiler from creating them as public without you know. We'll examine the implementation of each method individually.

_pDialogPage is the pointer to property page dialog created in the BuildEditor method.

_pISettingManagmentForCtrl is a pointer of the CATIIniSettingManagment interface. In the constructor class, this interface pointer is initialized and in the ResetUserSettingsValue, CancelModification and CommitModification methods it is used. This interface manages the Save, Rollback, ResetToAdminValues, Commit on the setting repository encapsulated by the setting controller.

The property page editor class source file is shown below.

The beginning of the CAACafElementPropertyPageEdt.cpp file is as follows:

// Local Framework
#include "CAACafElementPropertyPageEdt.h"
#include "CAACafElementPropertyPageDlg.h"
#include "CAAICafGeometryEltSettingAtt.h"
#include "GetCAACafGeometryEltSettingCtrl.h"

// InteractiveInterfaces Framework
#include <CATIIniSettingManagment.h>
...

#include <TIE_CATIUserSettings.h>
TIE_CATIUserSettings(CAACafElementPropertyPageEdt);

CATImplementClass(CAACafElementPropertyPageEdt,
                  Implementation,
                  CATBaseUnknown,
                  CATNull);
...

The CAACafElementPropertyPageEdt class states that it implements the CATIUserSttings interface thanks to the TIE_CATIUserSettings macro. The CATImplementClass macro declares that the CAACafElementPropertyPageEdt class is an implementation, that is a component main class, thanks to the Implementation keyword, and that it OM-derives from CATBaseUnknown. The fourth parameter must always be set to CATNull, makes no sense, and is unused for implementations.

Update the interface dictionary, that is a file named, for example, CAACATIAApplicationFrm.edu.dico, whose directory's pathname is concatenated at run time in the CATDictionaryPath environment variable, and containing the following declaration to state that the CAACafElementPropertyPageEdt class implements the CATIUserSettings interface, and whose code is located in the libCAACafEltToolsOptions shared library or DLL. The update is shown in bold typeface:

CATUserSettingsManager CAAICafElementPropertyPageEdtFactory libCAACafEltToolsOptions
CAACafElementPropertyPageEdt   CATIUserSettings        libCAACafEltToolsOptions

The constructor retrieves a pointer to the CATIIniSettingManagment interface on the setting controller dedicated the setting file

...
CAACafElementPropertyPageEdt::CAACafElementPropertyPageEdt()
                            : CATEditor(), _pDialogPage(NULL)
  
{
  _pISettingManagmentForCtrl = NULL;
  HRESULT rc = ::GetCAACafGeometryEltSettingCtrl(IID_CATIIniSettingManagment,
	                                        (void**) &_pISettingManagmentForCtrl);
}
...

The GetCAACafGeometryEltSettingCtrl global function retrieves interface pointers on the CAACafGeometryElt setting file. The first argument is the IID of the interface to retrieve.

The destructor simply resets the dialog page pointer to NULL and releases the pointer on the CATIIniSettingManagment interface.

...
CAACafElementPropertyPageEdt::~CAACafElementPropertyPageEdt()
{
  _pDialogPage = NULL; 
  if ( NULL != _pISettingManagmentForCtrl )
  {
    _pISettingManagmentForCtrl->Release();
    _pISettingManagmentForCtrl = NULL;
  }
}
...

BuildEditor instantiates and builds the dialog object for the property page.

...
void CAACafElementPropertyPageEdt::BuildEditor(CATEditorPage * iDlgPageParent)
{
  if ( NULL != iDlgPageParent)
  {
    _pDialogPage = new CAACafElementPropertyPageDlg(iDlgPageParent);
    if ( NULL != _pDialogPage )
    { 
      _pDialogPage->Build();
    }
  }
}
...

This dialog object is described in Creating the Property Page Dialog.

SetUserSettingsValue requests the dialog object to set the values of the displayed parameters.

...
void CAACafElementPropertyPageEdt::SetUserSettingsValue(CATSettingRepository * iUselessFileRep)
{
  if ( NULL != _pDialogPage )
  { 
    _pDialogPage->ValueSettings();
  }
}
...

The ValueSettings method of the dialog class reads the setting attribute values from the setting controller to set those of the controls that represent the setting attributes in the property page.

ResetUserSettingsValue resets the values to the default ones.

...
void CAACafElementPropertyPageEdt::ResetUserSettingsValue()
{
  if ( NULL != _pISettingManagmentForCtrl )
  {
    _pISettingManagmentForCtrl->ResetToAdminValues();  
  }
}
...

This method is called whenever the end user clicks Reset, if the tab page is part of the reset scope. The ResetToAdminValues method uses the setting values from the file that an administrator could have set up. The SetUserSettingsValue method is called just after to update the displayed values.

CancelModification is called whenever the end user clicks Cancel to cancel the modifications brought to the parameter values.

...
void CAACafElementPropertyPageEdt::CancelModification(CATSettingRepository * iUselessFileRep)
{
  if ( NULL != _pISettingManagmentForCtrl )
  {
    _pISettingManagmentForCtrl->Rollback();
    _pISettingManagmentForCtrl->Commit();
 }
}
...

The setting repository object is used to restore the previous values saved, and is saved again to manage a possible future cancel, since the Rollback method deletes the saved setting object.

CommitModification is called whenever the end user clicks OK to save the modified values from the setting repository to the setting file.

...
void CAACafElementPropertyPageEdt::CommitModification(CATSettingRepository * iUselessFileRep)
{
  if ( NULL != _pISettingManagmentForCtrl )
  {
    _pISettingManagmentForCtrl ->SaveRepository();
  }
}
...

[Top]

Setting the Resources for the Property Page Editor

The resources for the property page editor are its title and the property sheet linked to your workshop or workbench into which your property page should be displayed.

The title of the property page, is in the CAACafElementPropertyPageEdt.CATNls file in the CNext\resources\msgcatalog directory of the CAACATIAApplicationFrm.edu framework.

TabPage.Title = "Elements" ;

where:

TabPage A required keyword for property pages

Title The keyword for titles

The property page is set in the property sheet of the "CAA V5 Geometrical Creation" workbench of the Infrastructure solution. This information is set in the CAACafElementPropertyPageEdt.CATRsc file in the CNext\resources\msgcatalog directory of the CAACATIAApplicationFrm.edu framework.

TabPage.SolutionName = "Infrastructure" ;
TabPage.WorkbenchName = "CAAAfrGeoCreationWkb" ;

where:

TabPage A required keyword for property pages

SolutionName The submenu of the Start menu where your workshop or workbench appears. This name is defined in the CATRsc file of your workshop or workbench within the keyword Category.

WorkbenchName The identifier of your workshop or workbench, set using the NewAccess macro in the CreateWorkshop or CreateWorkbench method [1]

In this same resource file you retrieve the URL for the contextual help:

TabPage.LongHelpId = "ToolsOptions.Infrastructure.CAAV5GeometricalCreation.Elements";

where:

`TabPage`	A required keyword for property pages
LongHelpId	A required keyword for URL
ToolsOptions	A mandatory string
Infrastructure	The name of the solution (in fact the category)
CAAV5GeometricalCreation	The identifier of your workshop or workbench, set using the `NewAccess` macro in the `CreateWorkshop` or `CreateWorkbench` method [1]
Elements	English name of the property page

[Top]

Creating the Property Page Dialog

This dialog class represents the contents of the property page, that is, the right part of the dialog box. The header file is as follows.

#ifndef CAACafElementPropertyPageDlg_H
#define CAACafElementPropertyPageDlg_H

#include "CATDlgFrame.h"          // Needed to derive from CATDlgFrame

// Dialog Framework
class CATDlgRadioButton;
class CATDlgSlider;

// System Framework
class CAAICafGeometryEltSettingAtt;

class CAACafElementPropertyPageDlg : public CATDlgFrame
{
  public :
    DeclareResource(CAACafElementPropertyPageDlg, CATDlgFrame);

    CAACafElementPropertyPageDlg(CATDialog * ipParent);
    virtual ~CAACafElementPropertyPageDlg();

    void Build();
    void ValueSettings();

  private :
    CAACafElementPropertyPageDlg ();
    CAACafElementPropertyPageDlg(const CAACafElementPropertyPageDlg &iObjectToCopy);
    CAACafElementPropertyPageDlg & operator = (const CAACafElementPropertyPageDlg &iObjectToCopy);
      
    void IdHideCB            (CATCommand         * iPublishingCommand,
                              CATNotification    * iNotification,
                              CATCommandClientData iUsefulData);
    void IdShowCB            (CATCommand         * iPublishingCommand,
                              CATNotification    * iNotification,
                              CATCommandClientData iUsefulData);
    void IdPreSelectShowCB   (CATCommand         * iPublishingCommand,
                              CATNotification    * iNotification,
                              
    void MaxPointCB          (CATCommand         * iPublishingCommand,
                              CATNotification    * iNotification,
                              CATCommandClientData iUsefulData);
                              
    void ImplPointHideCB     (CATCommand         * iPublishingCommand,
                              CATNotification    * iNotification,
                              CATCommandClientData iUsefulData);
    void ImplPointShowCB     (CATCommand         * iPublishingCommand,
                              CATNotification    * iNotification,
                              CATCommandClientData iUsefulData);
    
  private :
    CATDlgRadioButton    * _pIdHide;
    CATDlgRadioButton    * _pIdShow;
    CATDlgRadioButton    * _pIdPreSelectShow;
    
    CATDlgRadioButton    * _pImplPointShow;
    CATDlgRadioButton    * _pImplPointHide;    
    
    CATDlgSlider         * _pMaxPoint;
    
    CAAICafGeometryEltSettingAtt * _pISettingAttForCtrl;
};

A property page dialog must derive from CATDlgFrame. The DeclareResource macro declares that the messages and resources are to be searched for in the CAACafElementPropertyPageDlg.CATNls and CAACafElementPropertyPageDlg.CATRsc files respectively. These files are delivered in the CNext\resources\msgcatalog directory of CAACATIAApplicationFrm.edu framework. The class has a constructor with a single argument to get its parent, and a destructor. The constructor only initializes the data members, while the Build method creates and arranges the controls, and sets the callbacks onto these controls. The ValueSettings method reads the setting attribute values to set those of the controls that represent the setting attributes in the property page. A default constructor and a copy constructor are set as private, and are not implemented in the source file. This prevents the compiler from creating them as public without you know.

The controls declared as data member are used in callback methods: radio buttons, slider.

_pISettingAttForCtrlis a pointer of the CAAICafGeometryEltSettingAtt interface. In the constructor class, the pointer is initialized and in ValueSettings and in all the callback methods it is used. This interface reads/writes the attributes values on the setting repository encapsulated by the setting controller.

We'll examine each method or group of methods individually.

The constructor

// Local Framework
#include "CAACafElementPropertyPageDlg.h"
#include "CAAICafGeometryEltSettingAtt.h"

// Dialog Framework
#include "CATDlgInclude.h"
#include "CATDlgGridConstraints.h"
#include "CATDlgLock.h"

// System Framework 
#include "CATSettingInfo.h"

// CATIAApplicationFrame Framework 
#include "CATDlgToolsOptionsFrame.h"

CAACafElementPropertyPageDlg::CAACafElementPropertyPageDlg(CATDialog * parent)
                            : CATDlgFrame(parent, "GeometryElementTO",
                              CATDlgFraNoFrame|CATDlgGridLayout),
                              _pIdHide(NULL), _pIdShow(NULL), _pIdPreSelectShow(NULL),
                              _pImplPointShow(NULL),_pImplPointHide(NULL),
                              _pMaxPoint(NULL)
{
  _pISettingAttForCtrl = NULL;
  ::GetCAACafGeometryEltSettingCtrl(IID_CAAICafGeometryEltSettingAtt,
                                    (void**)&_pISettingAttForCtrl);
}
...

All the data member are initialized. The GetCAACafGeometryEltSettingCtrlglobal function retrieves interface pointers on the CAACafGeometryEltsetting file. The first argument is the IID of the interface to retrieve.

The destructor sets the control data member pointers to NULL since any dialog object is automatically deleted and releases the pointer on the CAAICafGeometryEltSettingAtt interface.

...
CAACafElementPropertyPageDlg::~CAACafElementPropertyPageDlg()
{
  _pIdHide = NULL ; 
  _pIdShow =NULL ; 
  _pIdPreSelectShow = NULL ;
  _pImplPointShow = NULL ; 
  _pImplPointHide =NULL ;
  _pMaxPoint = NULL;

  if ( NULL != _pISettingAttForCtrl )
  {
    _pISettingAttForCtrl->Release();
    _pISettingAttForCtrl = NULL ;
  }
}
...

Build does all the job of creating the controls, arranging them in independent frame, and setting the callbacks to react to the expected events.

...
void CAACafElementPropertyPageDlg::Build()
{
  if ( NULL == pISettingAttForCtrl )
  {
     return ;
  }
    
  // Frame 1
  See first frame 
  
  // Frame 2
  See second frame    
        
  // Frame 3
  See third and last frame     
}
...

Each frame is an instance of the CATDlgToolsOptionsFrame class whose the style is defined by the last argument.

The first frame is as follows:

The frame "Identifier" contains three radio button without an icon in front of it.

  ...

  CATString    TOFrameId1      = "Identifier" ;
  CATString    IconName1      = "" ;
  CATDlgStyle  TOFrameStyle1   = CATDlgToolsOptionsInvisibleIcon ;
  
  CATDlgToolsOptionsFrame * pToolsOptionsFrame1 = NULL ;
  pToolsOptionsFrame1 = new CATDlgToolsOptionsFrame(this,
                                                    TOFrameId1,
                                                    IconName1,
                                                    TOFrameStyle1);
  
  pToolsOptionsFrame1->SetGridConstraints(0,0,1,1,CATGRID_TOP);

  CATDlgFrame * pIdentifierFrame = NULL ;
  pIdentifierFrame = pToolsOptionsFrame1->GetOptionsFrame();

  ...

For the first frame, the style is CATDlgToolsOptionsInvisibleIcon It means that in the current property page, some frames have icons, so this style enables to save the global layout.

The pToolsOptionsFrame1 frame contains itself a frame, returned by the GetOptionsFrame method, which will be the parent of all the dialog object for the second frame. pIdentifierFrame is the parent frame of the following dialog object: three radio buttons and a lock.

  ...
     // Lock sets at the top of the three radio buttons
     CATSettingInfo InfoForLockForId ;
     _pISettingAttForCtrl->GetInfoIdentifierVisibility(&InfoForLockForId);    
           
     CATDlgLock * pIdentifierLock = NULL ;
     pIdentifierLock = new CATDlgLock(pIdentifierFrame,"IdentifierLock",InfoForLock);
     pIdentifierLock->SetGridConstraints(0,0,1,3,CATGRID_LEFT);

     // 3 Radio buttons 
     _pIdHide   = new CATDlgRadioButton(pIdentifierFrame, "IdHide");
     _pIdHide->SetGridConstraints(0,1,1,1,CATGRID_LEFT);
     pIdentifierLock->AddAssociatedDialog(_pIdHide);

     _pIdShow  = new CATDlgRadioButton(pIdentifierFrame, "IdShow");
     _pIdShow->SetGridConstraints(1,1,1,1,CATGRID_LEFT);
     pIdentifierLock->AddAssociatedDialog(_pIdShow);

     _pIdPreSelectShow = new CATDlgRadioButton(pIdentifierFrame, "IdPreSelectShow");
     _pIdPreSelectShow->SetGridConstraints(2,1,1,1,CATGRID_LEFT);
     pIdentifierLock->AddAssociatedDialog(_pIdPreSelectShow);
  ...

In the setting repository there is an CATSettingInfo class instance for each attribute. The GetInfoIdentifierVisibility method of the setting controller, retrieves it and passes it to the CATDlgLock dialog object.

After the radio button creation, you can associate the lock to each dialog object concerned by this lock.

The callbacks are set as usually for dialogs.

  ...
  AddAnalyseNotificationCB(_pIdHide,
                           _pIdHide->GetRadBModifyNotification(),
                           (CATCommandMethod)&CAACafElementPropertyPageDlg::IdHideCB,
                           NULL);

  AddAnalyseNotificationCB(_pIdShow,
                           _pIdShow->GetRadBModifyNotification(),
                           (CATCommandMethod)&CAACafElementPropertyPageDlg::IdShowCB,
                           NULL);

  AddAnalyseNotificationCB(_pIdPreSelectShow,
                           _pIdPreSelectShow->GetRadBModifyNotification(),
                           (CATCommandMethod)&CAACafElementPropertyPageDlg::IdPreSelectShowCB,
                           NULL);
  ...
}
...

The second frame is as follows.

The frame "Max Points/Curve" contains a slider with an icon in front of it.

  ...  
  CATString    TOFrameId2      = "MaxPointCurve";
  CATString    IconName2       = "I_CAAToolsOptionsEltMaxPointCurve";
  CATDlgStyle  TOFrameStyle2   = NULL; 
  
  CATDlgToolsOptionsFrame * pToolsOptionsFrame2 = NULL;
  pToolsOptionsFrame2 = new CATDlgToolsOptionsFrame(this,TOFrameId2,
                                                    IconName2,
                                                    TOFrameStyle2);
  
  pToolsOptionsFrame2->SetGridConstraints(1,0,1,1,CATGRID_TOP);
  
  CATDlgFrame             * pMaxPointCurveFrame = NULL;
  pMaxPointCurveFrame = pToolsOptionsFrame2->GetOptionsFrame();
  ...

Since having an icon and a frame companion below is the standard style for a frame in a property page, this style is the default and set to NULL.

The icon name is passed as a CATString instance. The icon name is not retrieved from a resource file as it is usually the case for a dialog. The string passed corresponds to the icon bmp image file name without the bmp extension (I_CAAToolsOptionsEltMaxPointCurve.bmp) located in the CNext\resources\graphic\icons\normal directory of the CAACATIAApplicationFrm.edu framework.

The pToolsOptionsFrame2 frame contains itself a frame, returned by the GetOptionsFrame method, which will be the parent of all the dialog object for the second frame. pMaxPointCurveFrame is the parent frame of the following dialog object: a slider and a lock.

... // Lock sets before the slider CATSettingInfo * pInfoList = NULL ; int nbInfo = 0; _pISettingAttForCtrl->GetInfoMaxPointCurve(&pInfoList,&nbInfo); CATDlgLock * pMaxPointLock = NULL ; pMaxPointLock = new CATDlgLock(pMaxPointCurveFrame,"MaxPointLock",pInfoList,nbInfo); pMaxPointLock->SetGridConstraints(0,0,1,1,CATGRID_LEFT); delete [] pInfoList ; pInfoList = NULL ; // Slider _pMaxPoint = new CATDlgSlider(pMaxPointCurveFrame, "MaxPoint"); _pMaxPoint->SetRange(2, 100, 100); _pMaxPoint->SetGridConstraints(0,1,1,1,CATGRID_CENTER);

// Associate the lock to one dialog object, the slider _pMaxPointLock->AddAssociatedDialog(_pMaxPoint); ...

The GetInfoMaxPointCurve method of the setting controller, retrieves a list of CATSettingInfo. You pass it to the CATDlgLock dialog object and after you can delete the list created in the GetInfoMaxPointCurve method.

After the slider creation, you can associate the lock to each dialog object concerned by this lock.

The callbacks are set as usually for dialogs.

  ...
  AddAnalyseNotificationCB(_pMaxPoint,
                      _pMaxPoint->GetSliderModifyNotification(),
                      (CATCommandMethod)&CAACafElementPropertyPageDlg::MaxPointCB,
                      NULL);
  ...
}
...

The callback methods access and modify the setting attribute values in the setting repository in using the setting controller.

The third and last frame is as follows:

The frame "Implicit Points" contains two radio button with an icon in front of it.

  ...  
  CATString    TOFrameId3      = "ImplicitePoint" ;
  CATString    IconName3      = "I_CAAToolsOptionsEltImplicitePoint" ;
  CATDlgStyle  TOFrameStyle3   = CATDlgToolsOptionsBottomFrame ; 
  
  CATDlgToolsOptionsFrame * pToolsOptionsFrame3 = NULL ;
  pToolsOptionsFrame3 = new CATDlgToolsOptionsFrame(this,
                                                    TOFrameId3,
                                                    IconName3,
                                                    TOFrameStyle3);
  ...

This frame is the last, so the CATDlgToolsOptionsBottomFrame style must be mixed with an another possible style. Here NULL | CATDlgToolsOptionsBottomFrame = CATDlgToolsOptionsBottomFrame . This style avoids to construct an invisible separator at the end of the page.

The frame is not completely described since it is identical to the second frame.

ValueSettings sets the values of the displayed parameters from the settings attribute values.

...
void CAACafElementPropertyPageDlg::ValueSettings()
{
  CATString ident; 
  _pISettingAttForCtrl->GetIdentifierVisibility(ident);

  if      (ident == "IdHide")           _pIdHide->SetState(CATDlgCheck, 0);
  else if (ident == "IdShow")           _pIdShow->SetState(CATDlgCheck, 0);
  else if (ident == "IdPreSelectShow")  _pIdPreSelectShow->SetState(CATDlgCheck, 0);  
  
  int maxpoint;
  _pISettingAttForCtrl->GetMaxPointCurve(maxpoint);

  float maxpointf = maxpoint ;
  _pMaxPoint->SetCurrentValue(maxpointf, 0);
  
  CATString implpoint; 
  _pISettingAttForCtrl->GetImplPointVisibility(implpoint);

  if      (implpoint == "ImplPointHide")  _pImplPointHide->SetState(CATDlgCheck, 0);
  else if (implpoint == "ImplPointShow")  _pImplPointShow->SetState(CATDlgCheck, 0);
}
...

It values the dialog object in using methods of the CAAICafGeometryEltSettingAtt interface.

IdHideCB is one of the callbacks that modify the setting attribute values when a control is activated.

...
void CAACafElementPropertyPageDlg::IdHideCB(
                              CATCommand         * iPublishingCommand,
                              CATNotification    * iNotification,
                              CATCommandClientData iUsefulData)
{
  if (_pIdHide->GetState() == CATDlgCheck)
  {
     _pISettingAttForCtrl->SetIdentifierVisibility("IdHide");
  }
...

If the Hide radio button is ckecked, the Identifier setting attribute value is set to IdHide using the SetIdentifierVisibility method. The other callback methods that access the setting attribute values are very similar and are not shown here.

Setting the Resources for the Property Page Dialog

In the CAACafElementPropertyPageDlg.CATNls, defined in the CNext/resources/msgcatalog, you set the NLS for each dialog object created in the property page dialog.

The title of the frame

IdFrame.HeaderFrame.Global.Title ="xxx";

where:

IdFrame Identifier of the frame, the second argument of the CATDlgToolsOptionsFrame method

HeaderFrame.Global.Title A required keyword

Identifier.HeaderFrame.Global.Title = "Identifier"; MaxPointCurve.HeaderFrame.Global.Title = "Max Points/Curve";

For each object inside a frame

IdFrame.IconAndOptionsFrame.OptionsFrame.IdWidget.Title = "xxx";

where:

IdFrame Identifier of the frame, the second argument of the CATDlgToolsOptionsFrame method

IconAndOptionsFrame.OptionsFrame A required keyword

IdWidget Identifier of the dialog object inside de frame

Title A required keyword

Identifier.IconAndOptionsFrame.OptionsFrame.IdHide.Title = "Hide"; Identifier.IconAndOptionsFrame.OptionsFrame.IdShow.Title = "Show"; Identifier.IconAndOptionsFrame.OptionsFrame.PreSelectShow.Title = "Preselect Show";

[Top]

Testing in Administrator Mode

To test your new property page, you must it run using the administrator mode. This mode can be accessed by setting the CATReferenceSettingPath environment variable. First test the case where you are an administrator in passing the -admin parameter to the CNEXT command and next when you benefit of the administrator files in relaunching CNEXT without argument.

With UNIX:

$ mkrun -c "/bin/ksh"
$ export CATReferenceSettingPath=MySettingPath
$ CNEXT -admin
$ CNEXT

With Windows:

mkrun -c "cmd"
set CATReferenceSettingPath=MySettingPath
CNEXT -admin
$ CNEXT

where MySettingPath is the pathname of your setting file directory. Caution: MySettingPath must already exist.

[Top]

In Short

Creating a property page for the Tools Options menu implies to create a property page editor factory, a property page editor class instantiated by this factory, and to supply a property page dialog class gathering the controls to access the parameters and values you let the end user access and modify.

The property page uses a setting controller that manages the access to the setting repositories and files to read and save these parameters and values.

[Top]

References

[1]	Creating a Workbench
[2]	Application Property Access
[3]	Setting Repositories and Attributes
[4]	The Setting Controller
[5]	Creating a Setting Controller
[6]	About Globally Unique IDentifiers
[7]	Object Modeler Component and Implementation Inheritances
[Top]

History

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

`TabPage`	A required keyword for property pages
`Title`	The keyword for titles

`TabPage`	A required keyword for property pages
`SolutionName`	The submenu of the Start menu where your workshop or workbench appears. This name is defined in the CATRsc file of your workshop or workbench within the keyword `Category`.
`WorkbenchName`	The identifier of your workshop or workbench, set using the `NewAccess` macro in the `CreateWorkshop` or `CreateWorkbench` method [1]

IdFrame	Identifier of the frame, the second argument of the CATDlgToolsOptionsFrame method
HeaderFrame.Global.Title	A required keyword

IdFrame	Identifier of the frame, the second argument of the CATDlgToolsOptionsFrame method
IconAndOptionsFrame.OptionsFrame	A required keyword
IdWidget	Identifier of the dialog object inside de frame
Title	A required keyword

3D PLM Enterprise Architecture

User Interface - Frame