Catalog Modeler

Integrating a New Type of Component

Implementing CATICatalogEnable, CATICatalogInstantiation, and CATICatalogSynchronize
Use Case

Abstract

This use case shows how to integrate a new type of component in a catalog document.


What You Will Learn With This Use case

The catalog document natively integrates the following components:

The aim of this article is to show how to integrate your own type of component in implementing three interfaces on it:

[Top]

The CAAMmrCatalogCombCrv Use Case

CAAMmrCatalogCombCrv is a use case of the CAAMechanicalModeler.edu framework that illustrates ComponentsCatalogsInterfaces framework capabilities.

[Top]

What Does CAAMmrCatalogCombCrv Do

This use case works with the CombinedCurve feature which is explained in the use case entitled "Creating a New Geometrical Feature: the Combined Curve" [6]. The next picture shows "CombineCrv" an instance of this feature. "CombineCrv" is the alias (CATIAlias interface of the ObjectModelerBase framework) name of the feature. It means that we have used the Edit Properties command to change its display name.  

Fig.1: The CAACombinedCurve.CATPart  Document 

In implementing  CATICatalogEnable, CATICatalogInstantiation and CATICatalogSynchronize  on the CombinedCurve feature, it is possible to integrate instances into a catalog document.

An example of one catalog which contains a links towards "CombineCrv" the CombinedCurve feature. The implementation of the CATICatalogSynchronize enables to value the "Name" and the "Inputs number" keywords [Fig.2] and the name of the description [Fig.3]. 

Fig.2: The CAACombinedCurve.catalog Document- Keywords Tab Page
Fig.3: The CAACombinedCurve.catalog Document- RerefenceTab Page

The CAACombinedCurve.catalog and the CAACombinedCurve.CATPart files are located in the directory CAAMechanicalModeler.edu/InputData

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

[Top]

How to Launch CAAMmrCatalogCombCrv

To launch CAAMmrCatalogCombCrv , you will need to set up the build time environment, then compile the CAAMmrCatalogCombCrv module along with its prerequisites, set up the run time environment, and then launch CATIA [7]. 

(*) The file is located in the directory CAAMechanicalModeler.edu/InputData

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

[Top]

Where to Find the CAAMmrCatalogCombCrv Code

The CAAMmrCatalogCombCrv use case is made of three classes located in the CAAMmrCatalogCombCrv .m module of the CAAMechanicalModeler.edu framework:

Name of the classes Function
CAAEMmrCatalogEnableForCombCrv Data extension of the CATICatalogEnable interface
CAAEMmrCatalogInstantiationForCombCrv Data extension of the CATICatalogInstantiation interface
CAAEMmrCatalogSynchronizeForCombCrv Data extension of the CATICatalogSynchronize interface

depending on operating system you find them :

Windows InstallRootDirectory\CAAMechanicalModeler.edu\CAAMmrCatalogCombCrv.m\
Unix InstallRootDirectory/CAAMechanicalModeler.edu/CAAMmrCatalogCombCrv.m/

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

[Top]

Step-by-Step

In the CAAMmrCatalogCombCrv use case you have four mains steps

  1. Implementing CATICatalogEnable
  2. Implementing CATICatalogInstantiation
  3. Implementing CATICatalogSynchronize
  4. Modifying the Interface Dictionary

[Top]

Implementing CATICatalogEnable

The implementation class is CAAEMmrCatalogEnableForCombCrv. This section describes:

  1. The header file
  2. The source file
  1. The header file
  2. // System Framework
    #include "CATBaseUnknown.h"  // To derive from 
    
    class CAAEMmrCatalogEnableForCombCrv: public CATBaseUnknown
    {
        CATDeclareClass;
        
    public:
        
        CAAEMmrCatalogEnableForCombCrv ();
        virtual ~CAAEMmrCatalogEnableForCombCrv ();
            
    private:
     
        CAAEMmrCatalogEnableForCombCrv (CAAEMmrCatalogEnableForCombCrv & iObjectToCopy);
        CAAEMmrCatalogEnableForCombCrv& operator=(CAAEMmrCatalogEnableForCombCrv & iObjectToCopy);    
    };

    The CAAEMmrCatalogEnableForCombCrv C++ class derives from CATBaseUnknown. The CATDeclareClass macro declares that the CAAEMmrCatalogEnableForCombCrv class belongs to a component. The copy constructor and the "=" operator are set as private to prevent the compiler from automatically creating as public.

  3. The source file
  4. #include "CAAEMmrCatalogEnableForCombCrv.h"
    
    CATImplementClass ( CAAEMmrCatalogEnableForCombCrv ,
                        DataExtension           ,
                        CATBaseUnknown          ,
                        CombinedCurve            );
    
    CAAEMmrCatalogEnableForCombCrv::CAAEMmrCatalogEnableForCombCrv()
    {     
    }
    
    CAAEMmrCatalogEnableForCombCrv::~CAAEMmrCatalogEnableForCombCrv()
    {
    }
    
    
    #include "TIE_CATICatalogEnable.h" 
    TIE_CATICatalogEnable( CAAEMmrCatalogEnableForCombCrv);
    

    The main points of this source file are:

Implementing CATICatalogInstantiation

The implementation class is CAAEMmrCatalogInstantiationForCombCrv. This section describes:

  1. The header file
  2. The source file
The last step consists in to launch the command. In this example the CATCreateExternalObject global function is used to launch the command by its name. This solution enables to execute a command whose the header is not accessible. It is the case for the "CAAMmrCombCrvPanelStCmd" command not exported by the CAAMmrCombinedCurveUI.m module of the CAAMechanicalModeler.edu framework. Otherwise you can always instantiate the command by the new method.

The deletion of the command, CAAMmrCombCrvPanelStCmd, is done by the command itself.

The output argument, NotDone, is set to 1 is the interactive command is launched otherwise it is set to 0.

Implementing CATICatalogSynchronize

  1. The header file
  2. The source file
  1. The header file
  2. // System Framework
    #include "CATBaseUnknown.h"  // To derive from 
    
    class CATPixelImage;
    class CATUnicodeString;
    #include "CATICkeType.h"
    
    class CAAEMmrCatalogSynchronizeForCombCrv: public CATBaseUnknown
    {
        CATDeclareClass;
        
    public:
    
       virtual ~CAAEMmrCatalogSynchronizeForCombCrv ();
     
       virtual HRESULT GetAlias(CATUnicodeString& oAlias) ;
    
       virtual HRESULT GetEmbeddedPreview(CATPixelImage** oImage) ;
    
       virtual HRESULT GetKeywordValue(const CATUnicodeString& iKeywordName,
                                       int& oKeyWordValue) ;
     
       virtual HRESULT GetKeywordValue(const CATUnicodeString& iKeywordName,
                                       const CATICkeType* iKeywordType,
                                       double& oKeyWordValue) ;
    
       virtual HRESULT GetKeywordValue(const CATUnicodeString& iKeywordName,
                                       CATCke::Boolean & oKeyWordValue) ;
     
    
       virtual HRESULT GetKeywordValue(const CATUnicodeString& iKeywordName,
                                       CATUnicodeString& oKeyWordValue) ;
        
    private:
    
        CAAEMmrCatalogSynchronizeForCombCrv (CAAEMmrCatalogSynchronizeForCombCrv & iObjectToCopy);
        CAAEMmrCatalogSynchronizeForCombCrv& operator=(CAAEMmrCatalogSynchronizeForCombCrv & iObjectToCopy);
        
    };

    The CAAEMmrCatalogSynchronizeForCombCrv C++ class derives from CATBaseUnknown. The CATDeclareClass macro declares that the CAAEMmrCatalogSynchronizeForCombCrv class belongs to a component. The copy constructor and the "=" operator are set as private to prevent the compiler from automatically creating as public.

  3. The source file
  4. // Local FrameWork
    #include "CAAEMmrCatalogSynchronizeForCombCrv.h"
    
    // ObjectModelerBase Framework
    #include "CATIAlias.h"
    
    // System Framework
    #include "CATUnicodeString.h"
    
    #include "TIE_CATICatalogSynchronize.h" 
    TIE_CATICatalogSynchronize( CAAEMmrCatalogSynchronizeForCombCrv);
    
    CATImplementClass ( CAAEMmrCatalogSynchronizeForCombCrv ,
                        DataExtension           ,
                        CATBaseUnknown          ,
                        CombinedCurve            );
    
    CAAEMmrCatalogSynchronizeForCombCrv::CAAEMmrCatalogSynchronizeForCombCrv()
    {
    }
    
    CAAEMmrCatalogSynchronizeForCombCrv::~CAAEMmrCatalogSynchronizeForCombCrv()
    {
    }
     ...

    GetAlias

    This method returns the name of the description. It is the value returned by the GetName method of the CATICatalogDescription interface. In the [Fig.3] notices the value and the following code: the string "CAA" is added to the name of the feature. It is an example to see the role of this method, but in most cases the alias of the feature is used.

    The value returned by this method is also the value of the "Name" keyword. see [Fig.2]. In others word, the value returned by the GetValue method of the CATICatalogDescription interface for the "Name" keyword is those of this method.

     ...
    HRESULT CAAEMmrCatalogSynchronizeForCombCrv::GetAlias(CATUnicodeString& oAlias) 
    {
      CATIAlias_var alias(this);
      if (alias!=NULL_var)
      {
          oAlias = "CAA" ;
          oAlias += alias->GetAlias();
      }
      return S_OK;
    }

    GetEmbeddedPreview

    This method enables to associate a specific image to the description. This method is called only if the description has an embedded preview. It means that this method is without effect if the description has an image from a file. The use case "Creating a Catalog With Part Document" [1] explains how to set an preview image by a file. 

    ...
    HRESULT CAAEMmrCatalogSynchronizeForCombCrv::GetEmbeddedPreview(CATPixelImage** oImage) 
    {
        return E_FAIL ;
    }
    ...

    GetKeywordValue

    There are four methods which depends on the type of the keyword : integer, CATUnicodeString, CATICkeType and CATCke::Boolean. For the four, the principle is the same: to value keywords. One of these four methods is called for each keyword of the catalog in taken account of its type.

    There is a specific keyword: the "Name" keyword. If your GetAlias method doesn't return E_FAIL, the value of this keyword is the value returned by GetAlias method. So in general, It is not necessary to write specific code in the GetKeywordValue method for this CATUnicodeString keyword.

    For this example, we have chosen to valuate the Inputs number (integer) keywords. 

     ...
    HRESULT CAAEMmrCatalogSynchronizeForCombCrv::GetKeywordValue(const CATUnicodeString& iKeywordName,
                                       int& oKeyWordValue) 
    {
        HRESULT rc = S_OK ;
        CATUnicodeString Key = "Inputs number" ;
        if ( Key == iKeywordName )
        {
            oKeyWordValue = 4 ;
        }else rc = E_FAIL ;
    
        return rc ;
    }
    

    Notice on the [Fig.2] the value of the keyword Inputs number . To create a Combined Curve, 4 elements are necessary: two curves and two directions, it is the reason of the 4 value.

    For the others methods, each returns E_FAIL. 

     ...
    HRESULT CAAEMmrCatalogSynchronizeForCombCrv::GetKeywordValue(const CATUnicodeString& iKeywordName,
                                       const CATICkeType* iKeywordType,
                                       double& oKeyWordValue)
    {
        return E_FAIL ;
    }
    
    HRESULT CAAEMmrCatalogSynchronizeForCombCrv::GetKeywordValue(const CATUnicodeString& iKeywordName,
                                       CATCke::Boolean & oKeyWordValue) 
    {
        return E_FAIL ;
    }
     ...
    HRESULT CAAEMmrCatalogSynchronizeForCombCrv::GetKeywordValue(const CATUnicodeString& iKeywordName,
                                       CATUnicodeString& oKeyWordValue)
    {
        return E_FAIL ;
    }

Modifying the Interface Dictionary

In the interface dictionary dedicated to the CAAMechanicalModeler.edu framework, it is necessary to add the following lines to indicate that the CombinedCurve component implements the three interfaces in the CAAMmrCatalogCombCrv.m module.

 ...
CombinedCurve               CATICatalogEnable               libCAAMmrCatalogCombCrv
CombinedCurve               CATICatalogInstantiation        libCAAMmrCatalogCombCrv
CombinedCurve               CATICatalogSynchronize          libCAAMmrCatalogCombCrv
 ...

 

[Top]


In Short

This use case illustrates how to implement the three following interfaces to integrate a new type of component in a catalog document:

[Top]


References

[1] Creating a Catalog With Part Document
[2] User Feature and Power Copy in Catalog
[3] Catalog Overview
[4] Creating a Catalog
[5] Instantiating a Component
[6] Creating a New Geometrical Feature: the Combined Curve
[7] Building and Launching a CAA V5 Use Case
[8] Application Frame Overview
[Top]

History

Version: 1 [Jul 2002] Document created
[Top]

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