3D PLM PPR Hub Open Gateway

What You Will Learn With This Use Case

This use case is intended to show you how to create a parameter manipulator and build an editor allowing you to modify interactively a parameter value by using a spinner. The spinner operates according to the manipulator specifications (range, bounds and increment/decrement value).

[Top]

The CAALifParamFrame Use Case

CAALifParamFrame is a use case of the CAALiteralFeatures.edu framework that illustrates KnowledgeInterfaces framework capabilities.

[Top]

What Does CAALifParamFrame Do?

CAALifParamFrame explains how to associate a manipulator with a length type parameter and create an editor whereby the parameter can be modified according to an increment/decrement amount and within a value range specified in the manipulator definition. The interactive tool which is used to increment or decrement the parameter value is a spinner. This spinner is an option of the editor object which is created.

In addition, this use case illustrates how to subscribe to a parameter "ChangeValue" notification. Each time the spinner is operated, the parameter value changes (except if either bound is reached) and an information box displays the new parameter value.

This use case can be worked through in three ways:

1. The parameter to be edited ("Length1") is constrained by a formula ("Length1 = Length2 * 2") which is deactivated. This is the use case which is provided by default.

To the end-user, the parameter is displayed as an editable data. No f(x) push-button is displayed opposite the editor value field.

2. The formula which constrains the parameter to be edited is activated (see [1] for more information on how to manage the activity of a knowledgeware relation) and you specify that the f(x) push button can be clicked to display a formula editor (this is done by passing the container root object as the first argument of the GetInPanelEdition method of the CATICkeParamFrame interface (see [2]).

To the end-user, the value field of the editor is grayed-out, the parameter value is not editable because it is constrained by a formula which is active. You can click f(x) but be aware that this use case does not provide any formula editor behind the f(x) icon. Clicking f(x) results in a crash.

3. The formula which constrains the parameter to be edited is activated and you make the f(x) push inactive by specifying a NULL_var handler in the first argument of the GetInPanelEdition method of the CATICkeParamFrame interface (see [2]).

To the end-user, the value field of the editor is grayed-out, the parameter value is not editable because it is constrained by a formula which is active. The f(x) push button is inactive.

[Top]

How to Launch CAALifParamFrame

To launch CAALifParamFrame, you will need to set up the build time environment, then compile CAALifGettingStarted along with its prerequisites, set up the run time environment, and then execute the use case [1].

Once you have displayed the parameter editor as it is delivered by default, you can use the down arrow of the spinner to decrement the "Length1" parameter value. Here is the information box you get:

Note that you cannot use the up arrow of the spinner to increment the parameter value as the upper bound of the manipulator has been set to 5mm. Likewise, if you keep on decrementing the parameter value, you won't be able to reach a value less than 0.5 mm.

[Top]

Where to Find the CAALifParamFrame Code

The CAALifParamFrame use case is made of three files : two source files named CAALifApplication.cpp and CAALifWindow.cpp, both located in the CAALifParamFrame.m module of the CAALiteralFeatures.edu framework:

where InstallRootDirectory is the directory where the CAA CD-ROM is installed, and one resource file named CAALifWindow.CATNls, located in :

[Top]

Step-by-Step

Here are the programming steps to create a parameter editor in a dialog window:

1. Creating an interactive application
   This step creates an interactive application so that the window which contains the objects to be created can be displayed and run as a standalone application.
2. Creating the knowledgeware features
   Two length parameters as well as a formula are created.
3. Creating the "Length1" manipulator
   The parameter to be associated with a manipulator and displayed in an editor is created.
4. Creating the "Length1" parameter editor
   A parameter editor with a spinner is created.

[Top]

Creating an Interactive Application

The interactive application is made of the class CAALifApplication that derives from CATInteractiveApplication. In addition to the constructor and destructor, this interactive application class redefines two methods of CATInteractiveApplication:

1. BeginApplication, called just after the application constructor. This method creates the different objects managed by the application, namely here the window to contain the parameters, the formula and the parameter editor. None of these objects can be created without a document. The preliminary declarations required to create a document and initialize the environment are also done by this method.
2. EndApplication, called when the application destruction is requested. This method is dedicated to deallocate objects or close files. Note that the application window declared as the application class data member is automatically deleted. The environment initialization is performed in the BeginApplication method as well as the parameter editor creation, and the EndApplication method removes the document created and closes the session.

...
void CAALifApplication::BeginApplication()
{
  ...
  CAALifWindow * pMainWindow ;
  pMainWindow = new CAALifWindow(this);
  ...
  pMainWindow->Build();

  pMainWindow->SetVisibility(CATDlgShow);
}

int CAALifApplication::EndApplication()
{              
  ...
  CAALifClose ();
  ... 
  return 0;
}
...
CAALifApplication ApplicationInstance("CAALifAppplicationInstance");
...

[Top]

Creating the Knowledgeware Features

All the objects manipulated in this use case are created in the CAALifWindow::Build method. Prior to creating a knowledgeware objects you must initialize the environment and retrieve the CATICkeParmFactory smart pointer from the document root container. See [2] for more information on how to initialize the environment.

1. Creating two length type parameters

   ... _spParam1 = spFact->CreateLength("Length1",0); ... CATICkeParm_var spParam2 = NULL_var; spParam2 = spFact->CreateLength("Length2", 2.5/1000); ...

   Let's remind you that the second argument of the CreateLength method must be expressed according to the International System of Units (SI), that is, in meters. The initial value of "Length2" is 2.5mm. See [3] for more information on how to create parameters.

2. Creating a formula constraining "Length1"

   ... CATCkeListOf(Parm) pParamList; pParamList.Append (_spParam1); pParamList.Append (spParam2); ... CATICkeRelation_var spFormula = spFact->CreateFormula ("Formula1", "", "", _spParam1, &pParamList, "a2*2", NULL_var, CATCke::False); ...

See [4] for information on formulas. The formula which is created specifies that "Length1=Length2 * 2". Right after the formula is created, the "Length1" value becomes 5 mm.

[Top]

Creating the "Length1" Manipulator

The manipulator which is created defines:

1. a minimum value of 0.5 in model units i.e. in mm. This lower bound can be included in the "Length1" range of possible values. See [5] for information on units.
2. a maximum value of 5.0 mm. This upper bound can be included in the "Length1" value range.
3. a increment/decrement amount (step) of 0.5 mm.

...
CATIParmManipulator_var spParmManip = NULL_var;
spParmManip = spFact->CreateParmManipulator();
...
spParmManip->SetAccurateRange (0.5,1,5,1);

  // Set the manipulator increment/decrement value
  //
spParmManip->SetStep (0.5);

  // Associate the manipulator with "Length1"
  //
_spParam1->SetManipulator (spParmManip);
   ...

After it is created, the manipulator is associated with the "Length1" parameter. See [6] for information on manipulators.

[Top]

Creating the "Length1" Parameter Editor

A parameter which is created by using any of the relations provided by the CATICkeParmFactory factory supports the CATICkeParamFrame interface. From this interface you can create a CATDlgFrame object by using the GetInPanelEdition method.

...
CATICkeParamFrame_var spParamFrame1 = _spParam1;
CATDlgFrame *pFrame1  =  NULL;
pFrame1 = spParamFrame1->GetInPanelEdition(NULL_var, this,
	                                  CATCkeLabel|CATCkeWithSpinner, "MySpinner");
...

What the displayed editor looks like depends on the values passed as the arguments.

1. the CATIParmPublisher object which is passed as the first argument allows you to plug an editor whenever the parameter is constrained by a relation. This object must be the root of the literals created in your document. If NULL_var is specified, you will get a push button opposite the parameter value field, but you won't be able to activate this button. This is what happens with this use case when the formula is activated.
2. the second argument refers to the window where the parameter editor is to be created
3. the third argument is made up of a list of style identifiers. Refer to the KnowledgeInterfaces framework interface documentation for more information. Note that specifying the CATCkeNoFormula identifier prevents from displaying the formula push button.
4. the fourth argument is the name of the returned frame (used in the resource file).

[Top]

In Short

This use case shows the objects and interfaces used when creating a parameter editor. There are two important points to remember about:

1. a parameter supports by default the CATICkeParmFrame interface.
2. through this interface, you can access to the creation of a parameter editor. The GetInPanelEdition method allows you to create a parameter editor with a specified style.
3. depending on whether the parameter is constrained and depending on the editor style, you may display or not a button opposite the editor value field.

[Top]

References

History

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