3D PLM Enterprise Architecture

User Interface - Frame

Creating a Property Page for Object Properties

Customizing Edit->Properties
Use Case

Abstract

This article shows how to add a property page to the property sheet for one or several property interfaces that objects implement.

What You Will Learn With This Use Case

This use case is intended to show how to create a property page for a given property of objects in your document [1].

[Top]

The CAACafEditTextureProp Command Use Case

CAACafEditTextureProp is a use case of the CAACATIAApplicationFrm.edu framework that illustrates the CATIAApplicationFrame framework capabilities.

[Top]

What Does CAACafEditTextureProp Command Do

CAACafEditTextureProp creates the Texture Properties property page with the two check buttons that set or unset the Metal Aspect and Rough properties to objects. The values of these properties are read from the object when the property page is built. The dialog box is as follows:

[Top]

How to Launch CAACafEditTextureProp

See the section entitled "How to Launch the CAAGeometry Use Case" in the "The CAAGeometry Sample" use case for a detailed description of how this use case should be launched. 

But just before launching the execution, edit the CAACATIApplicationFrm.edu.dico interface dictionary file located in the dictionary directory of the CAACATIApplicationFrm.edu framework:

Windows InstallRootDirectory\CAACATIAApplicationFrm.edu\CNext\code\dictionary\
UNIX InstallRootDirectory/CAACATIAApplicationFrm.edu/CNext/code/dictionary/

In this file, remove the "#" character before the two following lines, and then run mkCreateRuntimeView.

# 2 lines to decomment to see pages in the Property Dialog Box
# CAACafTexturePropertyPageEdt CATIEditProperties  libCAACafEditTextureProp
# CAACafColorPropertyPageEdt   CATIEditProperties  libCAACafEditColorProp

The second line deals with the Color tab page created by the non-described CAACafEditColorProp use case located in the CAACafEditColorProp.m module. Then, in the window where you run the mkrun command, do not type the module name on the command line, but type CNEXT instead. When the application is ready, do the following:

[Top]

Where to Find the CAACafEditTextureProp Code

The CAACafEditTextureProp use case is made of classes and interfaces located in the CAACafEditTextureProp.m module and in the ProtectedInterfaces directory of the CAACATIAApplicationFrm.edu framework:

Windows InstallRootDirectory\CAACATIAApplicationFrm.edu\CAACafEditTextureProp.m\
Unix InstallRootDirectory/CAACATIAApplicationFrm.edu/CAACafEditTextureProp.m/

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

These classes and interfaces are:

CAACafTexturePropertyPageEdt Property page editor class
CAACafTexturePropertyPageEdtFactory Factory class for the property page editor class
CAAICafTexturePropertyPageEdtFactory Factory interface implemented by CAACafElementPropertyPageEdtFactory
TIE_CAAICafTexturePropertyPageEdtFactory TIE class for the factory interface
CAACafTexturePropertyPageDlg Dialog box class associated with the property page editor

[Top]

Step-by-Step

To create a property page, there are four main steps:

  1. Create the property page editor factory interface
  2. Create the property page editor factory
  3. Create the property page editor
  4. Create the property page dialog

[Top]

Creating the Property Page Editor Factory Interface

This factory interface is named CAAICafTexturePropertyPageEdtFactory. To create this interface, create:

  1. The header file
  2. The source file
  3. The TIE tsrc file.

This is shown below.

  1. Header file: CAAICafTexturePropertyPageEdtFactory.h is as follows. 
    #include <CATIGenericFactory.h>.

extern IID IID_CAAICafTexturePropertyPageEdtFactory;

class CAAICafTexturePropertyPageEdtFactory : public CATIGenericFactory
{
  CATDeclareInterface;
  public :
};

    A factory interface is an interface, that is, an abstract class that derives from CATIGenericFactory. As any interface, it has an IID declared as IID_ followed by the interface name, and includes the CATDeclareInterface macro that declares that this abstract class is an interface. No additional method than those inherited from CATIGenericFactory is necessary. Don" t forget the public keyword required by the tie compiler.

  2. Source file: CAAICafTexturePropertyPageEdtFactory.cpp is as follows. 
    #include "CAAICafTexturePropertyPageEdtFactory.h"

IID IID_CAAICafTexturePropertyPageEdtFactory = { 
    0x0cf4c1bc,
    0xd409,
    0x11d3,
    {0xb7, 0xf5, 0x00, 0x08, 0xc7, 0x4f, 0xe8, 0xdd}
    };

CATImplementInterface(CAAICafTexturePropertyPageEdtFactory, CATIGenericFactory);

    This file includes a GUID [2] as follows. The GUID is shown in bold typeface. The CATDeclareInterface in the header file and the CATImplementInterface macros make an interface from this C++ class. The second parameter of CATImplementInterface declares that CAAICafTexturePropertyPageEdtFactory OM-derives from CATIGenericFactory.

  3. TIE file: to enable components to implement this interface, create a file named TIE_CAAICafTexturePropertyPageEdtFactory.tsrc in the src directory, and containing: 
    #include "CAAICafTexturePropertyPageEdtFactory.h"

    The building tool mkmk will generate the TIE for this interface, that is the TIE_CAAICafTexturePropertyPageEdtFactory.h file for you in the ProtectedGenerated directory.

[Top]

Creating the Property Page Editor Factory

Macros help to create the class. These macros create a class whose name is made of the property page editor class name to which the string Factory is appended. This is the reason why the header file is named CAACafTexturePropertyPageEdtFactory.h and the source file is named CAACafTexturePropertyPageEdtFactory.cpp.

To create this class, create:

  1. The header file, using the CAT_EDITOR_DECLARE_FACTORY macro
  2. The source file, using the CAT_EDITOR_DEFINE_FACTORY macro
  3. Update the interface dictionary and the factory dictionary.
  1. Header file: CAACafTexturePropertyPageEdtFactory.h is as follows. 
    #include <CATEditorFactory.h>
#include <CAACafTexturePropertyPageEdt.h>

#define ExportedByNOTHING

CAT_EDITOR_DECLARE_FACTORY(NOTHING, CAACafTexturePropertyPageEdt, CAACafTexturePropertyPageEdt);

    It is important to set the same string where NOTHING is used in this example. ExportedByNOTHING sets a non existing shared library or DLL to the class. Setting a valid one is useless, since the created class in an extension of CATEditorManager, and its instantiation is made when CATEditorManager is asked for CAAICafTexturePropertyPageEdtFactory. In this case, the appropriate shared library or DLL is retrieved using the interface dictionary. The second parameter is the name of the property page editor class. This name is used to create the factory class name by appending Factory. The third parameter is a type assigned to the class to instantiate that could be retrieved using the CATIGenericFactory::Support method. It is unused here, but must be set, and is thus also set to the name of the class to instantiate.

  2. Source file: CAACafTexturePropertyPageEdtFactory.cpp is as follows. 
    #include <CAACafTexturePropertyPageEdtFactory.h>

CAT_EDITOR_DEFINE_FACTORY(CAACafTexturePropertyPageEdt, CAACafTexturePropertyPageEdt);
 
#include <TIE_CAAICafTexturePropertyPageEdtFactory.h>
TIE_CAAICafTexturePropertyPageEdtFactory(CAACafTexturePropertyPageEdtFactory);

    The CAT_EDITOR_DECLARE_FACTORY and CAT_EDITOR_DEFINE_FACTORY macros create the property page editor factory implementation class as a data extension of the CATEditorManager class. Then the TIE macro declares that this extension class implements the CAAICafTexturePropertyPageEdtFactory interface.

  3. Dictionary files: you should now update

    At run time, the pathname of the directory that contains these files is concatenated at run time in the CATDictionaryPath environment variable.

[Top]

Creating the Property Page Editor

You'll now create the class for the property page. This class derives from the CATEditor class, implements the CATIEditProperties interface and overrides methods that are either pure virtual or empty in their CATEditor implementation. You should provide their body to make them play the following role:

The methods ExtractFromSelection, GetEditorTitle, SetEditorSize, BuildEditor, and SetPropertyValue are executed in this order when instantiating the property page.

When the end user clicks:

SetPropertyValue, CommitModification, and CancelModification call in turn the methods with the same name of the associated dialog class.

The property page editor class header file is shown below.

#include "CATEditor.h"                 // Needed to derive from CATEditor
#include "CATLISTV_CATBaseUnknown.h"   // Needed by ExtractFromSelection,...

class CAACafTexturePropertyPageDlg;    // Dialog Page
class CATEditorPage;                   // Tabpage frame parent

class CAACafTexturePropertyPageEdt : public CATEditor
{
  CATDeclareClass;
  public:
    CAACafTexturePropertyPageEdt();
    virtual ~CAACafTexturePropertyPageEdt(); 
    virtual void ExtractFromSelection(CATLISTV(CATBaseUnknown_var) & oExtract, 
                               const  CATLISTV(CATBaseUnknown_var) * iSelection=NULL);
    virtual CATUnicodeString  GetEditorTitle();
    virtual void SetEditorSize(int & oSize);
    virtual void BuildEditor(CATEditorPage *); 
    virtual void SetPropertyValue(CATLISTV(CATBaseUnknown_var)& iExtract, 
                                  ModeReadWrite iMode);
    virtual void CommitModification(CATLISTV(CATBaseUnknown_var)& iExtract);
    virtual void CancelModification(CATLISTV(CATBaseUnknown_var)& iExtract);
    virtual void CloseWindowFromEditor();
  
 private:
    CAACafTexturePropertyPageDlg * _pTextureFrame ;
};

We'll examine each method individually.

Update the interface dictionary, that is a file named, for example, CAACATIAApplicationFrm.edu.dico, whose directory's pathname is concatenated at run time in the CATDictionaryPath environment variable, and containing the following declaration to state that the CAACafTexturePropertyPageEdt class implements the CATIEditProperties interface, and whose code is located in the libCATAfrEduEditProp shared library or DLL. The update is in bold typeface:

CATEditorManager CAAICafTexturePropertyPageEdtFactory libCATAfrEduEditProp
CAACafTexturePropertyPageEdt CATIEditProperties       libCATAfrEduEditProp

[Top]

Creating the Property Page Dialog

This dialog class represents the contents of the tab page. Its header file is as follows.

#include "CATDlgFrame.h"  // Needed to derive from  CATDlgFrame  
#include <CATEditor.h>

class CATDlgCheckButton;

class CAACafTexturePropertyPageDlg : public CATDlgFrame
{
  public :
    DeclareResource(CAACafTexturePropertyPageDlg, CATDlgFrame);

    CAACafTexturePropertyPageDlg (CATDialog * ipParent);
    virtual ~CAACafTexturePropertyPageDlg ();

    void Build();
    void SetPropertyValue(CATLISTV(CATBaseUnknown_var) & iExtract,ModeReadWrite iMode);
    void CommitModification(CATLISTV(CATBaseUnknown_var) & iExtract);
    void CancelModification(CATLISTV(CATBaseUnknown_var) & iExtract);
    void CloseWindowFromEditor();

  private :
    CAACafTexturePropertyPageDlg ();
    CAACafTexturePropertyPageDlg(const CAACafTexturePropertyPageDlg &iObjectToCopy);

  private :
    CATDlgCheckButton * _pMetal;
    CATDlgCheckButton * _pRough;
};

A property page dialog must derive from CATDlgFrame. The DeclareResource macro declares that the messages and resources are to be searched for in the CAACafTexturePropertyPageDlg.CATNls and CAACafTexturePropertyPageDlg.CATRsc files respectively. These files are delivered in the CNext\resources\msgcatalog directory of CAACATIAApplicationFrame.edu framework. The class has a constructor with a single argument to get its parent, and a destructor. The constructor only initializes the data members, while the Build method creates and arranges the controls, and sets the callbacks onto these controls. The other methods are the companion methods of those of CATEditor overriden in CAACafTexturePropertyPageEdt. A default constructor and a copy constructor are set as private, and are not implemented in the source file. This prevents the compiler from creating them as public without you know.

We'll examine each method individually.

[Top]

In Short

Creating a property page for the Edit->Properties menu implies to create an property page editor factory interface that derives from CATIGenericFactory, the property page editor factory that instantiates the property page editor, and to supply the associated property page dialog class gathering the controls to access the parameters and values of the object's properties you let the end user access and modify.

To be extracted from the Current Set of Objects (CSO), the objects should implement the property interface(s) to which this property page is dedicated.

[Top]

References

[1] Edit Properties
[2] About Globally Unique IDentifiers

[Top]

History

Version: 1 [Jan 2000] Document created

[Top]

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