3D PLM PPR Hub Open Gateway

Knowledge Modeler

Publishing Literals

Displaying knowledgeware objects in f(x)

Use Case

Abstract

This article discusses the CAALifPublish use case.
This use case explains how to display parameters and relations in the f(x) dialog box and benefit from the capabilities provided by the f(x) dialog.

What You Will Learn With This Use Case
The CAALifPublish Use Case

What Does CAALifPublish Do
How to Launch CAALifPublish
Where to Find the CAALifPublish Code

Step-by-Step
In Short
References

What You Will Learn With This Use Case

This use case is intended to show you how to create a length and an angle type parameters as the children of a given feature and make them display in f(x) when the parent feature is selected either in the specification tree or in the geometry area.

Throughout this article, the word 'published' qualifies a feature whose parameters and relations are designed to be displayed in f(x) as well as the displayed parameters and relations.

The example which is developed in this use case can be extended to other types of parameters and to relations as the principles illustrated in the use case are quite general.

[Top]

The CAALifPublish Use Case

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

[Top]

What Does CAALifPublish Do

CAALifPublish explains how to proceed to publish knowledgeware objects, that is display them in f(x). It illustrates the different coding steps required to display parameters in the "Formulas" dialog box:

it illustrates how to provide an implementation of CATIParmPublisher
and, through a basic example, it shows how to manage the published parameters by using the methods provided by the CATIParmPublisher implementation.

[Top]

How to Launch CAALifPublish

To launch CAALifPublish, you will need to set up the build time environment, then compile CAALifPublishMain along with its prerequisites, set up the run time environment, and then execute the use case which main program is CAALifPublishMain [1].

[Top]

Where to Find the CAALifPublish Code

The CAALifPublish use case is made up of:

The CAALifMyPublisher.cpp source file located in the CAALifBasis module which defines an implementation of CATIParmPublisher.
A main source file named CAALifPublishMain.cpp located in the CAALifPublish module which initializes the environment and creates features intended to publish parameters and relations.

Windows	`InstallRootDirectory\CAALiteralFeatures.edu\CAALifPublish.m\`
Unix	`InstallRootDirectory/CAALiteralFeatures.edu/CAALifPublish.m/`

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

[Top]

Step-by-Step

Here are the main steps followed in this use case to create parameters to be displayed in the f(x) dialog box:

Prolog
This step creates a session, a Part document, and retrieves from the document's root container a pointer to the factory to be used to create the parameters as well as the formula.
Creating the Feature to be Published
The "CAAMyPublisher1" feature is created. It is the initial feature intended to be published.
Implementing CATIParmPublisher
The CATIParmPublisher interface is implemented on "CAAMyPublisher1".
Adding a new Parameter of Angle Type to the Feature to be Published
The Append method redefined in the CATIParmPublisher implementation is used to add a parameter to the feature. The number of items in the list of children is checked.
Adding a Relation of Formula Type to the Feature to be Published
A formula is appended to the feature. The number of relations in the list of children is checked.
Removing Children
The RemoveChild method redefined in the CATIParmPublisher implementation is used. The number of items in the new list of children is checked.
Epilog
This step closes the document and the session.

[Top]

Prolog

Before going any further in literal programming, you must initialize your environment. This is done in the main source file.

int main (int argc, char** argv)
{
 CAALifServices services;
  // Initialize the session
  int rc = 0;
  rc = services.CAALifInitSession ();
  if( rc != CAALifOk )
    return rc;

  // Retrieve the parameter factory 
  CATIContainer* container = NULL;		
  rc = services.CAALifCreateInstanceContainer( &container );
  if( rc != CAALifOk )
    return rc;

  CATICkeParmFactory_var spFact = container;
...

This task consists in:

Creating a session
This is done by the CAALifInitSession method of the CAALifServices class defined in the CAALifBasis.m module.
Creating a document and retrieving its root container through a literal factory interface.
This is done by the CAALifCreateInstanceContainer method of the CAALifServices class that is also defined in the CAALifBasis.m module and that returns a CATIContainer interface smart pointer, cast into a CATICkeParmFactory smart pointer. There are two important points about this interface:
1. It is implemented by any root container
2. It provides you with all the literal and relation creation methods.

[Top]

Creating the Feature to be Published

For the purpose of this example, a StartUp with the "CAAMyPublish" type and the "CAAMyPublisher1" name is created. It is added a component named "myparam". The value of "myparam" is set by the "Height" parameter. Here is an excerpt of the CAALifPublish0.cpp file:

 ...
 CATISpecObject_var spSu = CreateStartUp("CAAMyPublisher1",
                                         "CAAMyPublisher",
                                         CATISpecObject::ClassName(),
                                         spFact);  
 ...
 CATISpecAttribute_var
     spMyParam = spSu->AddAttribute("myparam",tk_component);
 ...
 CATICkeParm_var spLength = spFact->CreateLength ("Height",2.3);
 spMyParam->SetSpecObject(spLength);
 ...

From now on, the feature we have on hand will be added two new objects (one parameter of angle type and one formula type relation).

To be able to publish these objects in f(x), the "CAAMyPublisher1" feature must implement the CATIParmPublisher interface. In your implementation, you must redefine the GetDirectChildren, GetAllChildren, Append and RemoveChild methods by deriving this CATCkeDescendants adapter.

[Top]

Implementing CATIParmPublisher

Implementing CATIParmPublisher consists in defining how a feature recognizes its children, how a parameter is added to or remove from the list of children.

To display the parameters and relations belonging to a document, you must at least implement CATIParmPublisher on the document root feature. Implementing CATIParmPublisher on other features below the root feature depends on whether your application needs to filter the parameters of objects below the root.

The KnowledgeInterfaces framework provides you with the CATCkeDescendants adapter. You redefine the GetDirectChildren, GetAllChildren, Append and RemoveChild methods by deriving this adapter.

You can implement the CATIParmPublisher methods in several ways. Nevertheless, it is is recommended to gather all the objects (parameters and relations) to be published in a tk_list(tk_component) attribute added to the parent feature. Implementing the GetDirectChildren and Append methods will be made easy thanks to the use of the services provided by the ObjectSpecsModeler framework to manipulate tl_list(tk_component) attributes.

Adding a tk_list(tk_component) attribute to the parent feature

This is done in the CAAMyPublish0.cpp source file.

...
CATISpecAttribute_var
  spAttcomp = spSu->AddAttribute("components",tk_list(tk_component));
...

Writing the CATIParmPublisher Implementation

In the example below, CAALifMyPublisher is the type of the feature to be published. This type is extended in the CAALifMyPublisher.cpp file. The extension redefines the GetDirectChildren, GetAllChildren, Append and RemoveChild methods of the CATCkeDescendants adapter.

In short

The GetDirectChildren is redefined so that:
- The "myparam" attribute is retrieved and added to the list of children if it supports the interface specified as the first argument
- The "components" attributes is retrieved. All its components are accessed by using the ListSpecObjects method of the CATISpecAttrAccess interface. The retrieved components are then appended one-by-one to the list to be populated by using the Append method.
The Append method uses the SetSpecObject method of the CATISpecAttrAccess interface which allows you to add one-by-one objects to a tk_list(tk_component) attribute.

...
#include "TIE_CATIParmPublisher.h"
TIE_CATIParmPublisher(CAALifMyPublisher);

CATImplementClass(CAALifMyPublisher,DataExtension,
                                    CATBaseUnknown,CAAMyPublisher);
void CAALifMyPublisher::GetDirectChildren (CATClassId iIntfName,
				CATListValCATISpecObject_var &oLst)  
{
  ...
  CATISpecAttrKey_var spSpecKey = spSpecAccess->GetAttrKey("myparam");
  ...
  CATISpecObject_var spMySpecParam = spSpecAccess->GetSpecObject(spSpecKey);
  ...
  oLst.Append(spMySpecParam);
  ...
  
  spSpecKey =  spSpecAccess->GetAttrKey("components");
  ...
  {
    ... 
    {
      CATListValCATInterfaceObject_var* 
      plis = spSpecAccess->ListSpecObjects(spSpecKey,iIntfName);
      ...
      CATISpecObject_var spec = (*plis)[i];
      if (spec != NULL_var) oLst.Append (spec);
	...
    }
  }
...

Retrieving the Initial List of Children

Prior to manipulating the published feature, the "myspec0" instance is created. This feature has exactly the same data structure as its StartUp.

The list of CATICkeParm which is retrieved from the created instance contains only one item, the "Height" parameter.

The list of CATICkeRelation which is retrieved from the created instance is empty.

...
CATISpecObject_var spSpec0 = spSu->Instanciate ("myspec0");
...
CATListValCATISpecObject_var spLst;
spPub->GetDirectChildren (CATICkeParm::ClassName(),spLst);
cout<<"The number of parameters is (1 expected): "<< spLst.Size()<< endl;
...
spPub->GetDirectChildren (CATICkeRelation::ClassName(),spLst);
...

[Top]

Adding a New Parameter of Angle Type to the Feature to be Published

The angle type parameter is created thanks to the CreateAngle method of the CATICkeParmFactory interface, that takes the angle name as a parameter in addition to the initial angle value.

...
CATICkeParm_var spPp2 = spFact->CreateAngle ("a",0);
...

The angle type parameter is added to "myspec0" by using the Append method of the CATIParmPublisher interface which is implemented in the CAALifMyPublisher class.

Back to the Append method implementation. Let's take a look at the implementation code. To append a new parameter to a feature, we use the SetSpecObject method of the CATISpecAttrKey interface which allows to populate a tk_list(tk_component) attribute by adding a new object to the attribute each time you do a SetSpectObject. Appending a new parameter to CAAMyFeature1 is the same as adding a new component to the "components" attribute.

...
void CAALifMyPublisher::Append(const CATISpecObject_var & iKBwareObject) 
{
  CATISpecAttrAccess_var spSak (this);
  CATISpecAttrKey_var spKey = spSak->GetAttrKey("components");
  if (NULL_var != spKey) 
  { 
    spSak->SetSpecObject(spKey,iKBwareObject);
    spKey->Release();
  }
}
...

Retrieving the New List of Children

The list of children whether it is retrieved by GetDirectChildren or GetAllChildren returns two objects("myparam" and "a").

[Top]

Adding a Relation of Formula Type to the Feature to be Published

The formula is created thanks to the CreateFormula method of the CATICkeParmFactory interface.

...
CATCkeListOf(Parm) spLi;
CATICkeRelation_var
    spRel = spFact->CreateFormula("","","",spPp2,&spLi,
	                                        "3deg",
					      NULL_var,
					CATCke::False);
spPub->Append(spRel);
...

The formula created is: a = 3deg. For more information on how to create formulas, see [2] and [3].

The relation is then appended to its parent feature by using the redefined Append method of CATIParmPublisher.

Retrieving the list of children of relation type

The list of relation to be published under the CAAMyPublisher1 feature. i.e. the list of objects supporting the CATICkeRelation interface is retrieved by using the redefined GetDirectChildren method as below:

...
spPub->GetDirectChildren (CATICkeRelation::ClassName(),spLst);
cout << " The number of direct children supporting" ;
cout << " CATICkeRelation is (1 expected) " ;
cout <<  spLst.Size() << endl;

The returned list is made up of one item.

[Top]

Removing Children

The angle type parameter and the formula are removed by using the redefined RemoveChild method of the CATIParmPublisher interface which is implemented in the CAALifMyPublisher class.

...
spPub->RemoveChild(spPp2);
spPub->RemoveChild(spRel);

Now let's take a look at the RemoveChild implementation. To remove a parameter from the list of published objects, we simply use the RemoveSpecObject method of the CATISpecAttrAccess interface.

...
void
  CAALifMyPublisher::RemoveChild(const CATISpecObject_var & iKBwareObject) 
{
CATISpecAttrAccess_var spSak (this); 
CATISpecAttrKey_var spKey = spSak->GetAttrKey("components");
if (NULL_var != spKey) 
  { 
   spSak->RemoveSpecObject(spKey,iKBwareObject);
   spKey->Release();
  }
}

The list of direct children now contains one item ("myparam") and the list of children supporting CATICkeRelation, that is the list of published relations is now empty as the formula has been removed.

[Top]

Epilog

int main (int argc, char** argv)
{
  ...
  rc = services.CAALifCloseSession();
  return rc;
};

The CAALifCloseSession method of the CAALifServices class defined in the CAALifBasis.m module removes the Part document and deletes the session.

[Top]

In Short

This use case shows how to publish the attributes of a feature and illustrates how to implement the CATIParmPublisher on any feature to be published.

The recommended implementation requires a tk_list(tk_component) added to the feature to be published.

[Top]

References

[1]	Building and Launching CAA V5 Samples
[2]	Getting Started with Literal Programming
[3]	Creating and Manipulating Formulas
[Top]

History

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