Mechanical Modeler

Creating a Command to Edit a User Feature

Implementing CATIEdit onto a User Feature
Use Case

Abstract

This article shows how to create a command to edit a User Feature of a given type by implementing the CATIEdit interface

What You Will Learn With This Use Case

This use case is intended to show you how to create a command to edit a User Feature of a given type in implementing the CATIEdit interface. This interface is implemented on a late type whose the name is the type of the User Feature. This article describes how to:

Before getting to the use case itself, it is important to already be familiar with the basic notions of User Features. See the referenced article [1] for a detailed overview.

This article has been updated in V5R13 to take the Ordered Geometrical Set into account. The following icon is in front of each piece of code newly added or modified. On the other hand, it does not have been functionally modified to take into account the solid and surfacic features set. 

[Top]

The CAAMcaUdfEdit Use Case

CAAMcaUdfEdit is a use case of the CAAMechanicalCommands.edu framework that illustrates MechanicalCommands and MechanicalModelerUI framework capabilities.

[Top]

What Does CAAMcaUdfEdit Do

In the CAAUdfLoft Part document you have the CAAUserFeatureSample User Feature reference [2]. This file, as all the files indicated in this article, is located in the InputData module of the CAAMechanicalCommands.edu framework. 

Fig.1: The CAAUdfLoft Part Document

Double click on the CAAUserFeatureSample feature: the "Userfeature Definition" Dialog box appears [Fig 2]. Select the "Type" tab and observe that the "Instance Type" field is empty.

Fig.2: User Feature Definition- No Type

The CAAUdfLoftWithType Part document contains the same User Feature reference, CAAUserFeatureSample, enriched with the "CAAUdfLoft" type. The following picture shows the "Userfeature Definition" Dialog box [Fig 3] when this feature is edited.  

Fig.3: User Feature Definition, the CAAUdfLoft Type

Notice that:

To set a type to an User Feature reference there are two means:

In the CAAUdfModelWithTypeInst Part document you will find an instance of the CAAUserFeatureSample feature with the CAAUdfLoft type. This instance is named CAAUserFeatureToEdit. 

Fig.4: The CAAUdfModelWithTypeInst Part Document

When you double click on the CAAUserFeatureToEdit feature, in place of the default edit command, the following dialog box appears:

Fig.5: Dialog Box to Edit a CAAUdfLoft User Feature

This dialog box is the CAAMcaUdfLoftEditCreateCmd class which contains

Refer to the use case "Creating a User Feature Reference" [2] for details about the inputs and the roles of the "CAAUserFeatureSample" User Feature.

To replace the default command we have implemented the CATIEdit interface [3] on the CAAUdfLoft late type. This interface contains the method, Activate, which returns a pointer to the command that edits the object. This command is the CAAMcaUdfLoftEditCreateCmd command which derives from CATPrtPanelStateCmd (MechanicalModelerUI framework). It is recommended to derive from this class to benefit from Mechanical Modeler behaviors (update, input validation ...)

The CAAMcaUdfLoftEditCreateCmd command is a CATStateCommand which has two state charts:


The "CAAUdfLoft" dialog box [Fig 5] is instantiated. The end user can:

This UML [4] diagram shows the transitions triggered at each end user interaction:

[Top]

How to Launch CAAMcaUdfEdit

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

First scenario, to set a type to an User Feature reference:

Launch CATIA. When the application is ready:

Second scenario, to see the new edit command:

Launch CATIA. When the application is ready:

Third scenario, to see the default edit command:

Launch CATIA. When the application is ready:

Where CAAUdfLoft.CATPart, CAAUdfModelWithTypeInst.CATPart, and CAAUdfModelWithInstances.CATPart are included in the directory CAAMechanicalCommands.edu/InputData

[Top]

Where to Find the CAAMcaUdfEdit Code

The CAAMcaUdfEdit use case is made of several classes located in the CAAMcaUdfEdit.m module of the CAAMechanicalCommands.edu framework:

Windows InstallRootDirectory\CAAMechanicalCommands.edu\CAAMcaUdfEdit.m\
Unix InstallRootDirectory/CAAMechanicalCommands.edu/CAAMcaUdfEdit.m/

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

[Top]

Step-by-Step

There are three logical steps in the CAAMcaUdfEdit use case:

  1. Implementing the CATIEdit Interface
  2. Creating the Command to Edit a User Feature
  3. Creating the Input Dialog Box

[Top]

Implementing the CATIEdit Interface

The implementation class is CAAEMcaEditUdfLoft. This section describes:

  1. The header file
  2. The source file
  3. The interface dictionary
  1. The CAAEMcaEditUdfLoft header file.
    2. #include "CATExtIEdit.h" 

class CAAEMcaEditUdfLoft : public CATExtIEdit
{
  CATDeclareClass;
  public :
    CAAEMcaEditUdfLoft();
    virtual ~CAAEMcaEditUdfLoft();

    virtual CATCommand  * Activate(CATPathElement * iPath);

 private :
    CAAEMcaEditUdfLoft(const CAAEMcaEditUdfLoft &iObjectToCopy);
    CAAEMcaEditUdfLoft & operator = (const CAAEMcaEditUdfLoft &iObjectToCopy);
};

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

  2. The CAAEMcaEditUdfLoft source file.
  3. The interface dictionary

    4. In the interface dictionary dedicated to the CAAMechanicalCommands.edu framework, it is necessary to add the following line to indicate that the CAAUdfLoft component implements the CATIEdit interface in the CAAMcaUdfEdit.m module.

    CAAUdfLoft CATIEdit libCAAMcaUdfEdit

    [Top]

Creating the Command to Edit a User Feature

The command CAAMcaUdfLoftEditCreateCmd is a command which can edit and create a CAAUdfLoft User Feature. In this section we have only extracted the code to make an edition. The "Instantiating Interactively a User Feature" [6] use case details the complementary code which are in this article preceded by the comment "Create Code": 

From V5R13, to ensure the insertion of CAAUdfLoft user features into an ordered set, the CAAMcaUdfLoftEditCreateCmd command must now:

This section describes:

  1. The header class
  2. The source class
  3. The Nls resources
  1. The CAAMcaUdfLoftEditCreateCmd header file.
    2. #include "CATPrtPanelStateCmd.h" // To derive from

class CAAMcaUdfLoftDlg ;         // Dialog box to edit the user feature
class CATFeatureImportAgent ;    // To select features
class CATIUdfInstantiate ;       // Interface to instantiate a user feature 
class CATDocument ;              // Used by the RetrieveTheUFRef method
class CATDlgNotify ;             // Dialog box to display the error message
class CATPathElement ;           // Input selected

class CAAMcaUdfLoftEditCreateCmd: public CATPrtPanelStateCmd
{

  CmdDeclareResource( CAAMcaUdfLoftEditCreateCmd, CATPrtPanelStateCmd )

  public:

    CAAMcaUdfLoftEditCreateCmd(CATISpecObject *iObjectToEdit);
    ...
    virtual ~CAAMcaUdfLoftEditCreateCmd();

  private:

    CAAMcaUdfLoftEditCreateCmd(const CAAMcaUdfLoftEditCreateCmd &iObjectToCopy);

    CAAMcaUdfLoftEditCreateCmd & operator = (const CAAMcaUdfLoftEditCreateCmd &iObjectToCopy);
  
    ...

    The CAAMcaUdfLoftEditCreateCmd command derives from the CATPrtPanelStateCmd command that enables to benefit from MechanicalModeler behaviors: update, inputs validation ... The copy constructor and the "=" operator are set as private to prevent the compiler from automatically creating them as public. Notice that the default constructor is not set as private because it is set as public in creation mode.

    The CmdDeclareResource macro states that the resources of the CAAMcaUdfLoftEditCreateCmd command are located in the CAAMcaUdfLoftEditCreateCmd.CATNls file. If resources were assigned to the CATPrtPanelStateCmd class, they would be concatenated with the resources for CAAMcaUdfLoftEditCreateCmd.

        ...
    HRESULT InitCommand();
    HRESULT CheckUserFeatureType(CATISpecObject * iUserFeature);
    ...

    In the InitCommand method we have grouped together the common code to call in the constructors, for edition and for creation. For our command, this code creates only the dialog box to display the input even though the parameter as not proceeded.

    The CheckUserFeatureType method checks that the feature to edit has the CAAUdfLoft type.

    Some methods are overriden from CATPrtPanelStateCmd or from its parent class: CATMMUIPanelStateCmd: GiveMyPanel, OkAction and PreviewAction. We will see that in case of the two first methods, it is mandatory to override them; in the case of the third, is is necessary here since the dialog box includes a Preview button.

        ...
    virtual CATDlgDialog*		GiveMyPanel();

    virtual CATBoolean		OkAction(void * iUsefuldata);  

    virtual CATBoolean		PreviewAction(void * iUsefuldata); 
    ...

    Below is a CATStateCommand with its BuildGraph method, its condition method CheckInput and its action methods: SelectPoint and CloseErrorDialogBox.

        ...
    virtual void    	         BuildGraph(); 
    ...
    virtual CATBoolean              CheckInput(void * iUsefuldata);

    virtual CATBoolean		SelectPoint(void * iUsefuldata);
    
    virtual CATBoolean		CloseErrorDialogBox(void * iUsefuldata);
    ...

    V5R13 novelty. To manage the current feature, the following methods have been added:

        ...
    virtual CATBoolean CancelAction(void * iUsefuldata); 
    ...
    CATStatusChangeRC  Activate   (CATCommand * iCmd,CATNotification * iNotif);

    CATStatusChangeRC  Deactivate (CATCommand * iCmd,CATNotification * iNotif);
    
    virtual CATBoolean InitAction(void * iUsefuldata);
    
    virtual CATBoolean BeforeBuildGraph();
    
    virtual CATBoolean IsUFInsideOrderedBody();
    ...

    The first part of the data members concerns the error management

      ...
  private:
    
    CATString               _ErrorKey ;
    
    CATDlgNotify          * _pErrorDialogBox;

    CATDialogAgent        * _pAgentErrorDialogBox ; 

    ...

    When an error occurs in the constructor, a dialog box, _pErrorDialogBoxis, is launched and which displays the error.

    _ErrorKey contains the type of the error. This string enables the creation of a keyword used to search the NLS message to display in the _pErrorDialogBox dialog box. _pAgentErrorDialogBox is an agent to trigger the transition between the first state and the Cancel state when the end user clicks OK or Close [Fig. 6].

    The next part concerns the input acquisition.

        ...
    CAAMcaUdfLoftDlg      * _pInputDialogBox;

    CATFeatureImportAgent * _pFeatureAgent ;

    CATPathElement        * _pFirstPoint ;
    CATPathElement        * _pSecondPoint ;
    CATPathElement        * _pSelectedPath ;
};

    The dialog box to display the input is _pInputDialogBox.

    _pFeatureAgent is the agent used to select the input in the specification tree or in 3D.

    _pFirstPoint and _pSecondPoint contain pointers on the initial inputs, or on the selected inputs during the life of the command. These two pointers enable to modify the edited User Feature in the OkAction when the end user clicks OK, or in the PreviewAction when he clicks on the Preview Button. _pSelectedPath is a storage path valuated in the CheckInput condition method and used in the SelectPoint action method to valuate _pFirstPoint or _pSecondPoint.

    V5R13 novelty. The last data member is the current feature when the command is launched. _spSpecObjOnPreviousCurrentFeat is kept to be restored at the end of the command (excepted in case of successful creation into an ordered set, because the new feature must stay the current one). 

        ...
    CATISpecObject_var      _spSpecObjOnPreviousCurrentFeat ;
};

    Notice that the feature to edit is not a data member of this class. This feature is set in the _MyFeature data member of the CATMMUIPanelStateCmd class. After the affectation, we retrieve this smart pointer thanks to the GiveMyFeature method, always defined in the grand-parent class.

  2. The CAAMcaUdfLoftEditCreateCmd source file.
  3. The NLS resources.

    4. The CAAMcaUdfLoftEditCreateCmd.CATNls file is located in the CAAMechanicalCommands.edu/Cnext/resources/msgcatalog directory. It contains:

[Top]

Creating the Input Dialog Box

This dialog box is a CAAMcaUdfLoftDlg class.This section describes:

  1. The header file
  2. The source file
  3. The NLS resources
  1. The CAAMcaUdfLoftDlg header file.
    2. #include "CATDlgDialog.h"   
class  CATDlgSelectorList;  
class  CATDlgLabel;         

class CAAMcaUdfLoftDlg: public CATDlgDialog
{

  DeclareResource(CAAMcaUdfLoftDlg,CATDlgDialog) ;

  public :

    CAAMcaUdfLoftDlg(CATDialog *iParent);
    virtual ~CAAMcaUdfLoftDlg(); 
	
    void Build();

    void InitPointName(CATUnicodeString iName1 , CATUnicodeString iName2 );
    void SetRole(int iPointNumber , CATUnicodeString iName );
    
    void SetPointName(int iPointNumber , CATUnicodeString iName );
    int  GetActiveEditorNumber();

  private : 

    CAAMcaUdfLoftDlg ();
    CAAMcaUdfLoftDlg(const CAAMcaUdfLoftDlg &iObjectToCopy);
    CAAMcaUdfLoftDlg & operator = (const CAAMcaUdfLoftDlg &iObjectToCopy);
	
    virtual void EditorSelect (CATCommand *, CATNotification* , CATCommandClientData data);

  private : 

      int _ActiveEditor ;

      CATDlgSelectorList * _pEditorOfThePoint1 ;
      CATDlgSelectorList * _pEditorOfThePoint2;

      CATDlgLabel        * _pLabelOfThePoint1 ;
      CATDlgLabel        * _pLabelOfThePoint2 ;

};

    The CAAMcaUdfLoftDlg class derives from the CATDlgDialog class and contains the following methods:

    To display the name of the input, we have chosen a CATDlgSelectorList dialog object even though a CATDlgEditor with the CATDlgEdtReadOnly style could have been used as well. But the selected lines of the CATDlgSelectorList are highlighted, it is not the case of the CATDlgEditor class. The highlight is the visual means for the end user to know which input will be valuated with its selection. Notice that in this command the CATDlgSelectorList are highlighted each one in his turn.

  2. The CAAMcaUdfLoftDlg source file.

    3. Among the recommended styles for a CATDlgDialog we have chosen a dialog box with three buttons at the bottom: OK, Cancel and Preview. The Preview button is not mandatory.

  3. NLS resources.

    4. The CAAMcaUdfLoftDlg.CATNls file is located in the CAAMechanicalCommands.edu/Cnext/resources/msgcatalog directory. It contains:

[Top]

In Short

This use case has demonstrated how to provide a new command to edit a User Feature of a given type by implementing the CATIEdit interface. This command is a CATStateCommand which derives from the CATPrtPanelStateCmd class in order to benefit from the MechanicalModeler behaviors.

[Top]

References

[1] Power Copy and User Feature Overview
[2] Creating a User Feature Reference
[3] Editing Object
[4] Describing State Dialog Commands Using UML
[5] Building and Launching a CAA V5 Use Case
[6] Instantiating Interactively a User Feature
[8] Editing Combined Curves
[9] The CAA Command Model
[Top]

History

Version: 1 [Feb 2002] Document created
Version: 2 [Nov 2003] Document updated to take into account the Ordered Geometrical Set
Version: 3 [Jan 2005] CATImplementBOA usage instead TIE_CATIEdit
[Top]

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