3D PLM Enterprise Architecture

User Interface - Frame

Creating Editors in Toolbar

How to create a command header class whose the representation is an editor in a toolbar?
Use Case

Abstract

This use case explains how to create a specialized command header. This command header has a customized graphic representation. In place of a check button into a toolbar, the graphic representation is two editors. 

What You Will Learn With This Use Case

This use case illustrates the creation of a customized command header. In a toolbar, its graphic representation is two editors in place of a check button, the default representation. You will learn how to:

It is a component which must derive from the CATAfrDialogCommandHeader class. 

It is a component which must derive from the CATAfrCommandHeaderRep class and which instantiates two CATDlgEditor instances.

The data used by the the graphic representation is the count of lines and points in the document. This data is dependent of the instance of a V5 document. 

You can also read 

To take full advantage of this article, you can first read "The Command Headers" technical article [3], and precisely the "Creating Customized Command Headers" section.  

[Top]

The CAAAfrEltCountHeader Use Case

CAAAfrEltCountHeader is a use case of the CAAApplicationFrame.edu framework that illustrates ApplicationFrame framework capabilities.

[Top]

What Does CAAAfrEltCountHeader Do

CAAAfrEltCountHeader creates a command header whose the graphic representation is two editors in a toolbar. The following picture shows the header in the "Tools Palette" toolbar [4]:

Fig.1 The EltCount header

There is a command header displaying the count of points and lines created in the CAAGeometry document [5]

The CAASysGeomCont component is the component controlling the data used by the graphic representation. It manages the list of elements in the CAAGeometry document through the CAAISysCollection interface.  

Fig.2 Component Controlling the Data Used by the Graphic Representation - UML Diagram

The CAASysGeomCont component plays the role of controller [3], when a line or a point is created (or deleted), the CAAISysCollection interface is used, and the CAAEAfrCollection class sends a notification, a CAASysCollectionModifNotif class instance. 

The EltCount header is an instance of a class, CAAAfrEltCountHeader ,deriving from the CATAfrDialogCommandHeader class, like any command header whose the graphic representation is customized. The following UML diagram describes in details the schema of classes:

Fig.3 EltCount Header - UML Diagram

CAAAfrEltCountHeader is a component which must implement the CATIAfrCommandHeaderRep interface to provide the customized graphic representation. This interface contains three methods:

Fig.4 Class Instantiating the Graphic Representation - UML Diagram

The CAAAfrEltCountRep class creates CATDlgEditor [6] class instances and sets a callback to be inform when lines or points are created or deleted. 

The EltCount header is instantiated in the Tools Palette for a workbench of the CAAGeometry document [4]. 

[Top]

How to Launch CAAAfrEltCountHeader

See the section entitled "How to Launch CAAAfrPaletteOptions" in the use case [4] for a detailed description of how this use case should be launched.

[Top]

Where to Find the CAAAfrEltCountHeader Code

The CAAAfrEltCountHeader use case is made of several classes mainly located in modules of the CAAApplicationFrame.edu framework:

Windows InstallRootDirectory\CAAApplicationFrame.edu\
Unix InstallRootDirectory/CAAApplicationFrame.edu/

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

[Top]

Step-by-Step

There are three logical steps in CAAAfrEltCountHeader:

  1. Creating the Component Providing Data
  2. Creating the Component Representing the Command Header 
  3. Creating the Class Instantiating the Graphic Representation

[Top]

Creating Component Providing Data

Count of lines and points are kept by the CAASysGeomCont component which implements the CAAISysCollection interface (Fig.2). When a point/Line is created/deleted in the current CAAGeometry document, a CAASysCollectionModifNotif notification is sent by the callback mechanism [7]. 

Here the CAAISysCollection interface such as you can see it in the PublicInterfaces directory of the CAASystem.edu framework. Refer to the Creating an Interface use case [8] for more details on its creation. 

...
class ExportedByCAASysGeoModelInf CAAISysCollection : public CATBaseUnknown
{
  CATDeclareInterface;

  public:
    virtual HRESULT GetNumberOfObjects(int * oCount) = 0;
    virtual HRESULT GetObject    (int iRank,
                                  CATBaseUnknown ** oObject) = 0;
    virtual HRESULT AddObject    (CATBaseUnknown * iObject) = 0;
    virtual HRESULT RemoveObject (CATBaseUnknown * iObject) = 0;
    virtual HRESULT Empty  () =0 ;
};
...

This interface is implemented by the CAASysGeomCont component thanks to the CAAEAfrCollection class extension. 

...
#include "TIE_CAAISysCollection.h"
TIE_CAAISysCollection(CAAEAfrCollection);

CATBeginImplementClass(CAAEAfrCollection,DataExtension,CATBaseUnknown,CAASysGeomCont);
CATAddClassExtension(CAASysSampCont) ;
CATEndImplementClass(CAAEAfrCollection);
...

The CAAEAfrCollection class states that it implements the CAAISysCollection interface thanks to the TIE_CAAISysCollection macro. This extension class is dedicated to this component, and the CATBeginImplementClass macro declares that the CAAEAfrCollection  class is data extension class, thanks to the DataExtension keyword, and that it extends the component whose main class is CAASysGeomCont. The third parameter must always be set to CATBaseUnknown, makes no sense, and is unused for extensions. 

The AddObject adds an element in the CAAGeometry document. _pListe is a data member of the CAAEAfrCollection class.

...
HRESULT CAAEAfrCollection::AddObject (CATBaseUnknown * iObject)
{
...
   _pListe->Append(iObject);
...

and sends a notification:

...
    CAASysCollectionModifNotif * pNotifModif = new CAASysCollectionModifNotif();

    ::GetDefaultCallbackManager(this)->DispatchCallbacks(pNotifModif,this);
      
    pNotifModif->Release() ;
    pNotifModif = NULL ;
...

The AddObject  method publishes the notification that states the list of element in the document is modifying. To do this, the global function GetDefaultCallbackManager retrieves the callback manager associated by default with the CAAEAfrCollection class instance, and this callback uses its DispatchCallbacks method to inform its subscribers or listeners that liste is modifying by means of the CAASysCollectionModifNotif notification created.

Refer to the callback use case [9] which explains in detail the callback mechanism, and how the CAASysCollectionModifNotif must be created. You will learn why the CAASysCollectionModifNotif class instance is deleted just after the DispatchCallbacks call. 

[Top]

Creating the Component Representing the Command Header 

The EltCount header is a component which must Object Modeler and C++ derive from CATAfrDialogCommandHeader and must implement the CATIAfrCommandHeaderRep interface (Fig.3). This paragraph is divided in two parts:

Component Creation

Here the CAAAfrEltCountHeader header file:

//ApplicationFrame framework
#include "CATAfrDialogCommandHeader.h"

class ExportedByCAAAfrCustomizedCommandHeader CAAAfrEltCountHeader : 
                                public CATAfrDialogCommandHeader
{
  CATDeclareHeaderResources;
  CATDeclareClass ;

  public:
    CAAAfrEltCountHeader(const CATString & iHeaderName);

    virtual ~CAAAfrEltCountHeader();
    CATCommandHeader * Clone() ;
      
  private:
    CAAAfrEltCountHeader(CATCommandHeader *iHeaderToCopy);
    CAAAfrEltCountHeader(const CAAAfrEltCountHeader &iObjectToCopy);
    CAAAfrEltCountHeader & operator = (const CAAAfrEltCountHeader &iObjectToCopy);
};

CAAAfrEltCountHeader derives from CATAfrDialogCommandHeader. It is mandatory for a command header whose the graphic representation is customized. The CATDeclareClass macro declares that it belongs to a CAA component. The CATDeclareHeaderResources macro inserts the methods to manage the command header resources. 

About the mandatory public methods:

About the mandatory private methods:

Here the CAAAfrEltCountHeader header file:

#include "CAAAfrEltCountHeader.h"

CATImplementClass(CAAAfrEltCountHeader, 
                  Implementation,
                  CATAfrDialogCommandHeader, 
                  CATNull);

CATImplementHeaderResources(CAAAfrEltCountHeader,  
			 CATAfrDialogCommandHeader,          
			 CAAAfrEltCountHeader);            

CAAAfrEltCountHeader::CAAAfrEltCountHeader(const CATString & iHeaderName) : 
    CATAfrDialogCommandHeader(iHeaderName){}

CAAAfrEltCountHeader::~CAAAfrEltCountHeader(){}

CATCommandHeader * CAAAfrEltCountHeader::Clone ()                                  
{ 
    return new CAAAfrEltCountHeader(this); 
}   

CAAAfrEltCountHeader::CAAAfrEltCountHeader(CATCommandHeader * iHeaderToCopy):
                          CATAfrDialogCommandHeader(iHeaderToCopy)
{}

CATIAfrCommandHeaderRep implementation

This interface of the ApplicationFrame framework must be implemented by all command header whose the graphic representation is customized. On Fig.3, you see that the CAAEAfrCommandHeaderRepForEltCount class is the implementation of this interface for the CAAAfrEltCountHeader component. 

Here the CAAEAfrCommandHeaderRepForEltCount header file

...
class CAAEAfrCommandHeaderRepForEltCount: public CATBaseUnknown
{
  CATDeclareClass;
public:
  
  CAAEAfrCommandHeaderRepForEltCount();
  virtual CAAEAfrCommandHeaderRepForEltCount();
  
  virtual HRESULT  CreateToolbarRep (const CATDialog * iParent,
                                            CATAfrCommandHeaderRep ** oHdrRep) ;
  virtual HRESULT  CreateMenuRep    (const CATDialog * iParent,
                                            CATAfrCommandHeaderRep ** oHdrRep) ;
  virtual HRESULT  CreateCtxMenuRep (const CATDialog * iParent,
                                            CATAfrCommandHeaderRep ** oHdrRep) ;
  
private:
  CAAEAfrCommandHeaderRepForEltCount(const CAAEAfrCommandHeaderRepForEltCount&iObjectToCopy);
  CAAEAfrCommandHeaderRepForEltCount& operator = (const CAAEAfrCommandHeaderRepForEltCount&iObjectToCopy);
};

The CATDeclareClass macro declares that CAAEAfrCommandHeaderRepForEltCount belongs to a component. CreateToolbarRep, CreateMenuRep, and CreateCtxMenuRep are methods of the CATIAfrCommandHeaderRep interface.

Here the CAAEAfrCommandHeaderRepForEltCount source file

...
#include <TIE_CATIAfrCommandHeaderRep.h>
TIE_CATIAfrCommandHeaderRep(CAAEAfrCommandHeaderRepForEltCount);

CATImplementClass(CAAEAfrCommandHeaderRepForEltCount, 
                  DataExtension,
                  CATBaseUnknown, 
                  CAAAfrEltCountHeader);
};
CAAEAfrCommandHeaderRepForEltCount::
           CAAEAfrCommandHeaderRepForEltCount():CATBaseUnknown(){}

CAAEAfrCommandHeaderRepForEltCount::~CAAEAfrCommandHeaderRepForEltCount(){}
...

The CAAEAfrCommandHeaderRepForEltCount class states that it implements the CATIAfrCommandHeaderRep interface thanks to the TIE_CATIAfrCommandHeaderRep macro. The CATImplementClass macro declares that the CAAEAfrCommandHeaderRepForEltCount class is a data extension, thanks to the DataExtension keyword, that extends CAAAfrEltCountHeader. The third argument must always be set as CATBaseUnknown or CATNull for any kind of extension.  The class constructor and the class destructor are empty.

...
HRESULT CAAEAfrCommandHeaderRepForEltCount::CreateToolbarRep
         (const CATDialog * iParent,CATAfrCommandHeaderRep ** oHdrRep)
{
   HRESULT rc = E_FAIL ;

   if ( oHdrRep != NULL )
   {
      CATString Name = "CAAAfrEltCountRepId" ;
      CAAAfrEltCountRep * pEltCountRep = new CAAAfrEltCountRep(iParent,Name);

      *oHdrRep = (CATAfrCommandHeaderRep *) pEltCountRep ;
      rc = S_OK ;
   }

   return rc ;
}
...

The CreateToolbarRep method provides the class instantiating the graphic representation of the EltCount header. This method is called each time the header command must be represented in a toolbar.

The CAAAfrEltCountRep class is a CATCommand class (Fig.4) which instantiates the graphic representation of the EltCount header (two CATDlgEditor instances). It is detailed in the Creating the Component Instantiating the Graphic Representation section, just below.  

iParent is a CATDialog component. It will be the dialog parent of the CATDlgEditor instances. Name is the command name of the CAAAfrEltCountRep class. You can set the same identifier for all CAAAfrEltCountRep class instances. 

You do not have to take care of the CAAAfrEltCountRep class instance, the returned value, oHdrRep is kept by the frame application, and the deletion of this pointer is automatically done.  

...
HRESULT CAAEAfrCommandHeaderRepForEltCount::
             CreateMenuRep (const CATDialog * iParent,CATAfrCommandHeaderRep ** oHdrRep)
{
  return  E_FAIL ;
}

HRESULT CAAEAfrCommandHeaderRepForEltCount::
          CreateCtxMenuRep (const CATDialog * iParent,CATAfrCommandHeaderRep ** oHdrRep)
{
  return E_FAIL;
}

The EltCount header has no representation in the menu bar or in a contextual menu, so CreateMenuRep and CreateCtxMenuRep return E_FAIL.

[Top]

Creating the Class Instantiating the Graphic Representation

This class is the CAAAfrEltCountRep class. Its main roles are:

Here the CAAAfrEltCountRep header file:

...
class CAAAfrEltCountRep : public CATAfrCommandHeaderRep
{
public:
  CAAAfrEltCountRep(const CATDialog * iParent, CATString & iCommandName);
  virtual ~CAAAfrEltCountRep();
  
  HRESULT Build();

private:
  void ModifiedCB(CATCallback       iEvent, 
                  void            *       , 
                  CATNotification * iNotification, 
                  CATCallbackEvent  iData,
		          CATSubscriberData iCallBack);
  HRESULT ValuateEditors() ;

  CAAAfrEltCountRep(const CAAAfrEltCountRep &iObjectToCopy);
  CAAAfrEltCountRep & operator = (const CAAAfrEltCountRep &iObjectToCopy);

private:

     CATDlgEditor      * _pEdtPoint;
     CATDlgEditor      * _pEdtLine;
     CAAISysCollection * _piSysCollection ;
};

Here the CAAAfrEltCountRep source file:

[Top]

In Short

This use case has explained how to create a command header whose the graphic representation is customized:

The component controlling the data used by the graphic representation is dependent of the document. 

[Top]

References

[1] Creating a Combo Command Header
[2] Creating a Most Recent Used Command Header
[3] The Command Headers
[4] Using the "Tools Palette" Toolbar for a Workbench
[5] The CAAGeometry Sample
[6] CATDlgEditor
[7] The Callback Mechanism
[8] Creating an Interface
[9] The Callback Mechanism
[10] Object Modeler Inheritances
[Top]

History

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

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