3D PLM Enterprise Architecture |
User Interface - Frame |
Creating a Property Page for Object PropertiesCustomizing Edit->Properties |
| Use Case | ||
AbstractThis article shows how to add a property page to the property sheet for one or several property interfaces that objects implement. |
This use case is intended to show how to create a property page for a given property of objects in your document [1].
[Top]
CAACafEditTextureProp is a use case of the CAACATIAApplicationFrm.edu framework that illustrates the CATIAApplicationFrame framework capabilities.
[Top]
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]
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]
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]
To create a property page, there are four main steps:
[Top]
This factory interface is named CAAICafTexturePropertyPageEdtFactory. To create this interface, create:
This is shown below.
#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.
#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.
#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]
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:
CAT_EDITOR_DECLARE_FACTORY macroCAT_EDITOR_DEFINE_FACTORY macro
#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.
#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.
CATEditorManager CAAICafTexturePropertyPageEdtFactory libCAACafEditTextureProp |
CAACafTexturePropertyPageEdt CAAICafTexturePropertyPageEdtFactory |
At run time, the pathname of the directory that contains these files is concatenated at run time in the CATDictionaryPath environment variable.
[Top]
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:
ExtractFromSelection returns the list of objects found in the
Current Set of Objects (CSO) that implement the CAAISysTextureProperties
interfaceGetEditorTitle returns the property page titleSetEditorSize lets you request which size you need to
accommodate your property page, among the possible values: small, medium, or
largeBuildEditor instantiates the associated dialog classSetPropertyValue sets the values and options in the property
page dialog from the elementCommitModification applies to the selected elements the
modifications made to values and options in the property page dialogCancelModification is empty, but exists and could be used to
delete temporary objects that could possibly be allocated in previous
methodsCloseWindowFromEditor is called whenever the end user selects
another property page.The methods ExtractFromSelection, GetEditorTitle, SetEditorSize,
BuildEditor, and SetPropertyValue are executed in this
order when instantiating the property page.
When the end user clicks:
CommitModification method is executed and the window
is closedCommitModification method is executed, but the
window is not closedCancelModification method is executed and the
window is closedSetPropertyValue, 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.
_pTextureFrame
dialog frame to include in the property page to NULL.
// Local Framework
#include "CAACafTexturePropertyPageEdt.h"
#include "CAACafTexturePropertyPageDlg.h"
// CAASystem.edu Framework
#include "CAAISysTextureProperties.h"
// Visualization Framework
#include "CATPathElement.h"
// System Framework
#include "CATLISTV_CATBaseUnknown.h"
#include "CATMsgCatalog.h"
#include "CATUnicodeString.h"
// CATIAApplicationFrame Framework
#include "CATEditorPage.h"
#include "TIE_CATIEditProperties.h"
TIE_CATIEditProperties(CAACafTexturePropertyPageEdt);
CATImplementClass(CAACafTexturePropertyPageEdt, Implementation, CATBaseUnknown , CATNull);
CAACafTexturePropertyPageEdt::CAACafTexturePropertyPageEdt()
:CATEditor(),_pTextureFrame(NULL)
{}
CAACafTexturePropertyPageEdt::~CAACafTexturePropertyPageEdt()
{
_pTextureFrame = NULL;
}
|
ExtractFromSelection is called with the list of
objects in the CSO as second argument. This should be a list of CATPathElement
instances.
void CAACafTexturePropertyPageEdt::ExtractFromSelection(CATLISTV(CATBaseUnknown_var)& oExtract,
const CATLISTV(CATBaseUnknown_var) * iSelection)
{
oExtract.RemoveAll();
if (iSelection && iSelection->Size())
{
CAAISysTextureProperties * pISysTexProperties = NULL;
HRESULT resu;
for (int i=1 ; i<= iSelection->Size(); i++ )
{
if ( (*iSelection)[i] != NULL_var )
{
CATBaseUnknown_var ukn = (*iSelection)[i];
CATBaseUnknown * pukn = ukn;
if ( pukn )
{
CATPathElement path = (CATPathElement &) *pukn;
if ( path.GetSize() )
{
CATBaseUnknown * leaf = path[path.GetSize()-1];
resu = leaf->QueryInterface(IID_CAAISysTextureProperties,
(void**)&pISysTexProperties);
// object extracted implements CAAISysTextureProperties
if ( SUCCEEDED(resu) )
{
oExtract.Append((*iSelection)[i]);
pISysTexProperties->Release();
pISysTexProperties = NULL;
}
}
}
}
}
}
}
|
The list is scanned, and any object that implements the CAAISysTextureProperties
interface is added to the oExtract list returned as the first
argument.
GetEditorTitle assigns the property page title.
CATUnicodeString CAACafTexturePropertyPageEdt::GetEditorTitle()
{
CATUnicodeString Title;
Title = CATMsgCatalog::BuildMessage("CAACafTexturePropertyPageDlg",
"TexturePageTitle",
NULL, 0, "Texture");
return Title;
}
|
It creates a thet title as a CATUnicodeString instance using the
static BuildMessage of CATMsgCatalog. This method takes
the following arguments:
CAACafTexturePropertyPageDlg is the message catalog name
found in the CAACafTexturePropertyPageDlg.CATNls message fileTexturePageTitle is the message key using which the
property page editor title should be retrievedNULL because there is no
parameters customizing the messageTexture is the default title to be used if the message
catalog is not found.SetEditorSize sets the property page size.
void CAACafTexturePropertyPageEdt::SetEditorSize(int & oSize )
{
oSize = 1;
}
|
This size can be set to small (1), medium (2), or large (3) for this property page. The dialog window is displayed using the largest value found among the property pages to be displayed.
BuildEditor instantiates and builds the dialog object
for the property page.
void CAACafTexturePropertyPageEdt::BuildEditor(CATEditorPage * iEditor)
{
_pTextureFrame = new CAACafTexturePropertyPageDlg(iEditor);
_pTextureFrame->Build();
}
|
This dialog object is described in Creating the Property Page Dialog.
SetPropertyValue requests from the dialog object to
set the values and options of its controls from the properties of the
extracted objects.
void CAACafTexturePropertyPageEdt::SetPropertyValue(CATLISTV(CATBaseUnknown_var)& iExtract,
ModeReadWrite iMode)
{
_pTextureFrame->SetPropertyValue(iExtract, iMode);
}
|
iMode is always set to Write
CommitModification saves the modified values in each
extracted object.
void CAACafTexturePropertyPageEdt::CommitModification(CATLISTV(CATBaseUnknown_var)& iExtract)
{
_pTextureFrame->CommitModification(iExtract);
}
|
It is called whenever the end user clicks OK or Apply.
CancelModification cancels the modifications brought
to the parameter values in the property page.
void CAACafTexturePropertyPageEdt::CancelModification(CATLISTV(CATBaseUnknown_var)& extract)
{
_pTextureFrame->CancelModification(extract);
}
|
It is called whenever the end user clicks Cancel. When the end user clicks Cancel, the objects are not yet modified.
CloseWindowFromEditor is called whenever the end user
selects a new property page, but not when the dialog box is closed.
void CAACafTexturePropertyPageEdt::CloseWindowFromEditor()
{}
|
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]
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.
// Local Framework
#include "CAACafTexturePropertyPageDlg.h"
#include "CAAISysTextureProperties.h"
// Dialog Framework
#include "CATDlgCheckButton.h"
// Visualization Framework
#include "CATPathElement.h"
CAACafTexturePropertyPageDlg::CAACafTexturePropertyPageDlg (CATDialog * parent)
: CATDlgFrame(parent, "TexturePageFrame", CATDlgFraNoFrame|CATDlgFraNoTitle),
_pMetal(NULL), _pRough(NULL)
{}
CAACafTexturePropertyPageDlg ::~CAACafTexturePropertyPageDlg ()
{
_pMetal = NULL;
_pRough = NULL;
}
|
Build creates the controls.
void CAACafTexturePropertyPageDlg ::Build()
{
_pMetal = new CATDlgCheckButton(this,"Metal");
_pRough = new CATDlgCheckButton(this,"Rough");
}
|
SetPropertyValue sets the values and options of its
controls, and saves these values, from the properties of the first extracted
object. Here it checks or unchecks the appropriate check buttons
accordingly.
void CAACafTexturePropertyPageDlg::SetPropertyValue(CATLISTV(CATBaseUnknown_var) & iExtract,ModeReadWrite mode)
{
_pMetal->SetState(CATDlgCheck);
_pRough->SetState(CATDlgCheck);
int IsMetalic = 1 ;
int IsRough = 1 ;
if ( iExtract.Size() > 0 )
{
// the first element selected
CATBaseUnknown_var elt = (iExtract)[1];
CATBaseUnknown *pPath = elt;
if ( pPath )
{
CATPathElement &path = (CATPathElement &)*pPath;
if (path.GetSize())
{
// the leaf of the first element
CATBaseUnknown * currentp = path[path.GetSize()-1];
// Information are on the CAAISysTextureProperties interface
// of the first object
CAAISysTextureProperties * pISysTexProperties = NULL ;
HRESULT resu = currentp->QueryInterface(IID_CAAISysTextureProperties,
(void**)&pISysTexProperties) ;
// Get values of this first element to initialize the Dialog's object
if ( SUCCEEDED(resu) )
{
pISysTexProperties->GetMetal(IsMetalic);
if ( !IsMetalic ) _pMetal->SetState(CATDlgUncheck);
pISysTexProperties->GetRough(IsRough);
if ( !IsRough ) _pRough->SetState(CATDlgUncheck);
pISysTexProperties->Release();
}
}
}
}
SetSensitivity(CATDlgEnable);
}
|
CommitModification applies the modified property
values to the extracted objects.
void CAACafTexturePropertyPageDlg::CommitModification(CATLISTV(CATBaseUnknown_var) & iExtract)
{
HRESULT resu ;
CAAISysTextureProperties * pISysTexProperties = NULL ;
for ( int i=1 ; i <= iExtract.Size() ; i++ )
{
// current element to modify
CATBaseUnknown_var elt = (iExtract)[i];
CATBaseUnknown *pPath = elt;
CATPathElement &path = (CATPathElement &)*pPath;
if (path.GetSize() )
{
CATBaseUnknown * currentp = path[path.GetSize()-1];
resu = currentp->QueryInterface(IID_CAAISysTextureProperties,
(void**)&pISysTexProperties) ;
// Modification of the model with the current values
if ( SUCCEEDED(resu) )
{
if ( _pMetal->GetState() == CATDlgCheck )
pISysTexProperties->SetMetal(1);
else
pISysTexProperties->SetMetal(0);
if ( _pRough->GetState() == CATDlgCheck )
pISysTexProperties->SetRough(1);
else
pISysTexProperties->SetRough(0);
pISysTexProperties->Release();
pISysTexProperties = NULL ;
}
}
}
}
|
CancelModification closes the dialog window without
applying the modified values.
void CAACafTexturePropertyPageDlg::CancelModification(CATLISTV(CATBaseUnknown_var) & iExtract)
{}
|
CloseWindowFromEditor is called whenever the end user
selects another property page when this is the current one.
void CAACafTexturePropertyPageDlg::CloseWindowFromEditor()
{}
|
[Top]
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]
| [1] | Edit Properties |
| [2] | About Globally Unique IDentifiers |
[Top]
| Version: 1 [Jan 2000] | Document created |
|
[Top] |
|
Copyright © 2000, Dassault Systèmes. All rights reserved.