3D PLM PPR Hub Open Gateway

Product Modeler

Customizing Product's Icons

Implementing the
CATICustoIconProduct Interface

Use Case

Abstract

This article presents the CAAPstProductIcon use case which illustrates how Product's icons can be customized using the CATICustoIconProduct interface.

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

What You Will Learn With This Use Case

Using the CATICustoIconProduct interface and feature extension, product's icons and masks can be customized. This use case will focus solely on the CATICustoIconProduct interface implementation. Please refer to the Feature Modeler documentation ([2]) for more information.

[Top]

The CAAPstProductIcon Use Case

CAAPstProductIcon is a use case of the CAAProductStructure.edu framework that illustrates the ProductStructure framework capabilities.

[Top]

What Does CAAPstProductIcon Do

The goal of CAAPstProductIcon is to demonstrate how default Product's icons and masks can be overridden. The code is composed of two parts:

One part is responsible for feature extension initialization
The other is the implementation of CATICustoIconProduct

Below is the Product document that will be loaded in the use case where icons are customized. It can be found in

InstallRoot/CAAProductStructure.edu/CNext/resources/graphic/CAAPstProductIconDoc.CATProduct

Fig. 1: Product document with customized icons

If the Product's icons had not been customized, the same document will look like the following:

Fig. 2: Product document with regular icons

[Top]

How to Launch CAAPstProductIcon

To launch CAAPstProductIcon:

Set the current directory to InstallRoot/CAAProductStructure.edu
Set up the build time environment (see reference [1]) and build the following modules:
- CAAPstProductIconInit.m
- CAAPstProductIconImpl.m
Install the run time environment by executing the command mkCreateRuntimeView
Launch CATIA
Open the document InstallRoot/CAAProductStructure.edu/CNext/resources/graphic/CAAPstProductIconDoc.CATProduct

[Top]

Where to Find the CAAPstProductIcon Code

CAAPstProductIcon code is located in the CAAPstProductIconInit.m and CAAPstProductIconImpl.m modules of the CAAProductStructure.edu framework.

[Top]

Step-by-Step

There are two separate parts in CAAPstProductIcon:

Initializing Product's Feature Extensions
Implementing the CATICustoIconProduct Interface

We will now detail each of those sections:

[Top]

Initializing Product's Feature Extensions

Our CAAPstProductIconDoc document not only contains Products but also a feature extension named "CAAPstProductIconExt". The CAAPstProductIconInit::Init method that does the work is called when the CAAPstProductIconDoc.CATProduct document is opened.

It is because we have indicated in the CAAProductStructure.edu.dico dictionary (located in InstallRoot/CAAProductStructure.edu/CNext/dictionary) that the CAAPstProductIconInit module implements the CATInit interface for document initialization:

CAAPstProductIconCont       CATInit                     libCAAPstProductIconInit

CAAPstProductIconInit::Init first retrieves the root product

void CAAPstProductIconInit::Init (CATBoolean iDestroyExistingData)   
{
...
	CATILinkableObject *piLinkableOnCont = NULL;
	HRESULT rc = QueryInterface(IID_CATILinkableObject,
                                     (void**) &piLinkableOnCont);
...
	CATDocument *pDoc = piLinkableOnCont->GetDocument();
...
	//
	// Activate the extension on the root product and the first sub-prodoct
	//
	CATIDocRoots* piDocRootsOnDoc = NULL;
	rc = pDoc->QueryInterface(IID_CATIDocRoots,
                                   (void**) &piDocRootsOnDoc);
...
	CATListValCATBaseUnknown_var *pRoots = piDocRootsOnDoc->GiveDocRoots();
...
	CATIProduct_var spRootProduct = NULL_var;
	// Get CATIProduct handle on the root product.
	CATIProduct *piProductOnRoot = NULL;
	rc = spRootProduct->QueryInterface(IID_CATIProduct,
                                            (void**) &piProductOnRoot);
...

It then activates the CAAPstProductIconExt extension on it.

...
	// Activate the extension on the root product
	CATIExtendable *piExtendableOnRoot = NULL;
	rc = piProductOnRoot->QueryInterface(IID_CATIExtendable,
                                              (void**) &piExtendableOnRoot);
...
	const char *extensionName = "CAAPstProductIconExt";
	const char *applicationId = "PstProductIconContainer";
	rc = piExtendableOnRoot->ActivateExtension (extensionName,
                                                     applicationId,
                                                     TRUE);             
...

Next, it gets to the first sub-product to activate the same extension:

                    
...
	// Activate the extension on the first sub-product
	CATListValCATBaseUnknown_var *pChildren = piProductOnRoot->GetAllChildren();
...
	CATIExtendable_var spExtendableOnSub = (*pChildren)[1];
...
	rc = spExtendableOnSub->ActivateExtension (extensionName,
                                                    applicationId,
                                                    TRUE);
...

[Top]

Implementing the CATICustoIconProduct Interface

Now that both our products have the CAAPstProductIconExt extension activated, we must indicate that it provides an implementation of the CATICustoIconProduct interface. Again this is done using the CAAProductStructure.edu.dico dictionary:

CAAPstProductIconExt   	    CATICustoIconProduct	libCAAPstProductIconImpl

The CATICustoIconProduct interface comprises eight methods:

GetIconForProduct to return the icon name for an external product
GetIconForComponent to return the icon name for an internal product
IsPossibleToAdd...Mask to indicate whether additional masks can be overlaid on the icon or not.

GetIconForProduct and GetIconForComponent methods:

Each method returns the name of an icon that should be located at run-time in the OS/resource/graphic/icon/normal directory
The two icons used in our implementation are I_CAAPstProductIcon and I_CAAPstComponentIcon. They can be found in the InstallRoot/CAAProductStructure.edu/CNext/resource/graphic/icon/normal.

HRESULT CAAPstProductIconImpl::GetIconForProduct(CATUnicodeString& oIcon)
{
	oIcon = "I_CAAPstProductIcon";
	return S_OK;
}
...
HRESULT CAAPstProductIconImpl::GetIconForComponent(CATUnicodeString& oIcon)
{
	oIcon = "I_CAAPstComponentIcon";
	return S_OK;
}

IsPossibleToAdd...Mask methods:

In our implementation, all masks can be applied. It is up to the application to determine which masks are appropriate.

/**
 * Indicates whether or not the Document mask can be overlaid
 */
HRESULT CAAPstProductIconImpl::IsPossibleToAddDocMask()
{
	return S_OK;
}

/**
 * Indicates whether or not the Representation mask can be overlaid
 */
HRESULT CAAPstProductIconImpl::IsPossibleToAddRepMask()
{
	return S_OK;
}

/**
 * Indicates whether or not the Central mask can be overlaid
 */
HRESULT CAAPstProductIconImpl::IsPossibleToAddCentralMask()
{
	return S_OK;
}

/**
 * Indicates whether or not the Gear mask can be overlaid
 */
HRESULT CAAPstProductIconImpl::IsPossibleToAddGearsMask()
{
	return S_OK;
}

/**
 * Indicates whether or not the Contextual Design mask can be overlaid
 */
HRESULT CAAPstProductIconImpl::IsPossibleToAddContextDesignMask()
{
	return S_OK;
}

/**
 * Indicates whether or not the Flexible mask can be overlaid
 */
HRESULT CAAPstProductIconImpl::IsPossibleToAddFlexibleDesignMask()
{
	return S_OK;
}

[Top]

In Short

This use case has demonstrated how Product's icons can be customized by:

Implementing the CATInit interface to initialize extensions when documents are opened
Implementing the CATICustoIconProduct to return icon data

[Top]

References

[1]	Building and Launching a CAA V5 Use Case
[2]	Feature Modeler Overview
[Top]

History

Version: 1 [Aug 2004]	Document created
[Top]