3D PLM Enterprise Architecture

Introduction

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 controllers ensure a consistent access to settings information for applications, the Tools/Options command being the most important of these applications.

Fig.1: Links Between Objects

As you can see from the above figure, the setting controller is the interface between one application and the setting repository [1], the latter being the memory representation of the setting file. The controller is a component that implements two interfaces:

• CATIIniSettingManagment

This interface, defined in the InteractiveInterfaces framework, manages the general methods of the setting repository: Commit, Save, Rollback and ResetToAdminValues.

• IParameterAccess

This interface, whose signature depends on the setting file, enables the access to the parameters.

Applications using a setting controller are commands. If your command modifies parameters it must be exclusive (CATCommandModeExclusive) like any command which modifies data model.

[Top]

How to Define the Interface Dedicated to the Parameters

Setting Attributes versus Parameters

The setting repository contains setting attributes accessible thanks to the ReadSetting and WriteSetting methods. Using these methods ties the code to the formats and locations of the attributes. To enable attribute format and location modifications while ensuring client code compatibility, it is advised to encapsulate the attribute access using an interface which increases the semantic in having parameter access.

For each parameter, you need to provide:

• A Getxxx method to access to the xxx parameter

This method calls one or several ReadSetting methods. This depends on the number of setting attributes that the xxx the parameter represents

• A Setxxx method to modify the xxx parameter

This method calls one or several WriteSetting methods. This depends on the number of setting attributes that the xxx the parameter represents

Method to Initialize the Setting Controller

To ensure a good use of the setting repository, it is necessary to load or to create in memory all the setting attributes of the setting file. This operation must be done just before the first use of the setting controller, in other words just after its creation. It is the role of the Initialize method. Refer to the section "The Life Cycle of the Setting Object", for the use of this method.

The Initialize method consists in calling all Getxxx methods, which contain the call to the appropriate ReadSetting method of the CATSettingRepository class.

When you enrich your setting file with new parameters, you have to modify the Initialize method, so that it calls the new Getxxx methods.

Methods to Manage the State of the Locks

In a Property Page of the Tools/Options command, the administrator has the possibility to "lock" parameters [1].

Fig.2: Locks in a Property Page

In the above figure, the administrator has locked the "Identifier" parameter to the "Show" option and the "Implicit Points" parameter to the "Hide" option. The end user is still free to modify the value of the maximum points used to discretize a curve, but cannot modify the two other parameters.

The dialog object acting as a lock is an instance of the CATDlgLock class whose constructor takes one or a list of CATSettingInfo instances in input. Each instance of CATSettingInfo, retrieved thanks to the GetInfo method of the CATSettingRepository class, represents an attribute for a setting repository. If the lock controls only one attribute, the CATDlgLock constructor needs one instance of CATSettingInfo. Moreover, if the lock controls several attributes the constructor needs several instances of CATSettingInfo. Refer to the use case "Creating a Property Page for Application Properties" [2] for an example on how to use CATDlgLock and CATSettingInfo classes.

For each xxx parameter, you need to provide:

• HRESULT GetInfoxxx(CATSettingInfo ** oInfoArray, int iNbSettingInfo) = 0;

This method calls one or several GetInfo methods. This depends on the number of setting attributes that represent the parameter.

Remark: If the parameter is represented by one attribute, and if you are sure this will not change over time, you can simplify the signature of the method: GetInfoxxx(CATSettingInfo * oInfo)

[Top]

How to Implement a Setting Controller

This section describes the classes and the interface needed to create a Setting Controller in order to take into account a naming rule. Refer to the use case "Creating a Setting Controller" [3] for a concrete example.

The setting file is named XXXyyyZZZ.CATSetting, where:

• XXX is the trigram of your company
• yyy is the trigram of the framework where the setting controller will be created
• ZZZ is dedicated to your setting file

Fig.3: Setting Controller Component

As you can see in the above figure, the controller is a component named XXXyyyZZZSettingCtrl which implements:

• CATIIniSettingManagment through the XXXEyyySettingManagmentForZZZ extension class
• XXXIyyyZZZSettingAtt through the XXXEyyyZZZSettingAtt extension class.

Here are the classes and interfaces needed to be created in your framework:

• In the ProtectedInterfaces directory:
  • XXXIyyyZZZSettingAtt.h
• In a LocalInterfaces directory of a module:
  • XXXyyyZZZSettingCtrl.h
  • XXXEyyyZZZSettingAtt.h
  • XXXEyyySettingManagmentForZZZ.h
• In a src directory of the same module:
  • TIE_XXXIyyyZZZSettingAtt.h
  • XXXIyyyZZZSettingAtt.cpp
  • XXXyyyZZZSettingCtrl.cpp
  • XXXEyyyZZZSettingAtt.cpp
  • XXXEyyySettingManagmentForZZZ.cpp

[Top]

The Life Cycle of the Setting Controller

In most cases, to access and modify a parameter, the setting controller reads and writes data from and to the setting repository. But to enhance performances, the setting controller can save values without making an automatic synchronization with the setting repository. To ensure the validity of the data, the setting controller must be unique during the session. This methodology must be used, even if your setting controller modifies directly the setting repository since it allows a possible evolution of your code.

The main component class of the setting controller, named XXXyyyZZZSettingCtrl in the previous section, contains:

• a public static method, GetSettingController

This method creates a XXXyyyZZZSettingCtrl class only if it does not already exist, otherwise the pointer comes from the next static data.

In this method, immediately after the first and unique class creation, you must initialize the setting repository by calling:

• the Initialize method of the XXXIyyyZZZSettingAtt interface
• the Commit method of the CATIIniSettingManagement interface, to save the values that would be used in case a rollback is invoked.

• a static data member to keep a pointer on the XXXyyyZZZSettingCtrl class

This data member is not a XXXyyyZZZSettingCtrl pointer, it is a CATIniCleanerSettingCtrl instance. This class, defined in the InteractiveInterfaces framework, contains the XXXyyyZZZSettingCtrl pointer. This encapsulation is the means to delete the unique setting controller pointer at the end of the session. A static instance is already deleted, a pointer is not. So the destructor of the CATIniCleanerSettingCtrl releases the XXXyyyZZZSettingCtrl pointer.

[Top]

Factory for the Setting Controller

For completeness when creating an instance of any component, you should implement and use the CATICreateInstance interface (System framework). But since your component is unique during the session, you must create a global factory function which is a special factory. This public function enables the retrieval of an interface pointer on the setting controller. This global function is called GetXXXyyyZZZSettingCtrl.

[Top]

In Short

A setting controller enables the encapsulation for the access to the setting attributes, and ensures a consistent access through its uniqueness.

A setting controller is a component which implements:

• A XXXIyyyZZZSettingAtt interface, whose signature depends on the setting file, that grants the access to the parameters without having to know about the internal storage (the name of the setting file, the format and the location of the attributes). This interface contains
• The Initialize method
• For each parameter, a Getxxx and Setxxx pair of methods, and one GetInfoxxx method
• CATIniSettingManagement interface, defined in the InteractiveInterfaces framework, that manages general methods on the setting repository: Commit, Save, ResetToAdminValues and Rollback.

A setting controller is accessible through a global function which returns an interface pointer to the component.

[Top]

References

History

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