3D PLM Enterprise Architecture

User Interface - Frame

Making Your Document Independent Command Available in All Workbenches

Using CATIAfrGeneralWksAddin
Use Case

Abstract

This article shows how to insert a document independent command in all workbenches of a V5 application. 

What You Will Learn With This Use Case

This use case is intended to show you how to create a toolbar and modify the menu bar to integrate your document independent command in all workbenches. You will learn to implement an interface, the CATIAfrGeneralWksAddin interface, which is an Add-in [1] of the "General" workshop [2]. This workshop contains the commands which are always available even if no document is open: New, Open, Cut,.... 

[Top]

The CAAAfrGeneralWksAddin Use Case

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

[Top]

What Does CAAAfrGeneralWksAddin Do

The CAAAfrGeneralWksAddin creates an add-in to the General workshop. Is is made up of:

[Top]

How to Launch CAAAfrGeneralWksAddin

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

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

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

In this file, remove the "#" character before the two following lines:

...
#CAAAfrGeneralWksAddin       CATIWorkbenchAddin          libCAAAfrGeneralWksAddin  
#CAAAfrGeneralWksAddin       CATIAfrGeneralWksAddin      libCAAAfrGeneralWksAddin
...

and run mkCreateRuntimeView.

[Top]

Where to Find the CAAAfrGeneralWksAddin Code

The CAAAfrGeneralWksAddin use case is made of a single class named CAAAfrGeneralWksAdn located in the CAAAfrGeneralWksAddin.m module of the CAAApplicationFrame.edu framework:

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

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

[Top]

Step-by-Step

To create the add-in, you should create the module directory to store the add-in code along with its two subdirectories LocalInterfaces and src. For this example, this directory is named CAAAfrGeneralWksAddin.m and can be found in the CAAApplicationFrame.edu framework. Then you will need to create the following files.

In the CAAAfrGeneralWksAddin.m\LocalInterfaces directory:
  • CAAAfrGeneralWksAdn.h
 The header file of the add-in description class
In the CAAAfrGeneralWksAddin.m\src directory:
  • CAAAfrGeneralWksAdn.cpp
 The header file of the add-in description class
In the dictionary, that is the CNext\code\dictionary directory, referenced at run time using the CATDictionaryPath environment variable, create or update:
  • CAAApplicationFrame.edu.dico
 The interface dictionary
In the CNext\resources\msgcatalog directory, referenced at run time using the CATMsgCatalogPath environment variable:
  • CAAAfrGeneralWksAdn.CATNls
 The add-in message file
  • CAAAfrGeneralWksAddinHeader.CATNls and
      CAAAfrGeneralWksAddinHeader.CATRsc
 The command header resource files

There are four logical steps in CAAAfrGeneralWksAddin:

# Step Where
1 Create the add-in description class LocalInterfaces and src
2 Create the command headers CreateCommands method
3 Create the add-in and arrange the commands CreateToolbars method
4 Provide the resources

[Top]

Create the add-in description class

  1. Create the CAAAfrGeneralWksAdn.h file 
    #include "CATBaseUnknown.h"

class CATCmdContainer;

class CAAAfrGeneralWksAdn : public CATBaseUnknown
{
  CATDeclareClass;
  
  public:
     CAAAfrGeneralWksAdn();
     virtual ~CAAAfrGeneralWksAdn();
  
     // Creates the command headers
     void CreateCommands();

     // Arranges the commands in toolbars and menubar
     CATCmdContainer * CreateToolbars();

  private :

     // Copy constructor, not implemented
     // Set as private to prevent from compiler automatic creation as public.
     CAAAfrGeneralWksAdn(const CAAAfrGeneralWksAdn &iObjectToCopy);

     // Assigment operator, not implemented
     // Set as private to prevent from compiler automatic creation as public.
     CAAAfrGeneralWksAdn & operator = (const CAAAfrGeneralWksAdn &iObjectToCopy);
};
  2. Create the CAAAfrGeneralWksAdn.cpp file
    3. // Local Framework
#include "CAAAfrGeneralWksAdn.h"

// ApplicationFrame Framework 
#include <CATCreateWorkshop.h>    // To use NewAccess - SetAccess - SetAccessChild ...

// Declaration of a new Command Header Class 
#include "CATCommandHeader.h"        // See Creating the Command Headers
MacDeclareHeader(CAAAfrGeneralWksAddinHeader);  

CATImplementClass(CAAAfrGeneralWksAdn, DataExtension,
                  CATBaseUnknown, CAAAfrGeneralWksAddin);

#include <TIE_CATIAfrGeneralWksAddin.h>
TIE_CATIAfrGeneralWksAddin(CAAAfrGeneralWksAdn);
    CAAAfrGeneralWksAdn::CAAAfrGeneralWksAdn()
{}

CAAAfrGeneralWksAdn::CAAAfrGeneralWksAdn()
{}

void CAAAfrGeneralWksAdn::CreateCommands()
{
  ... // See Creating the Command Headers
}

CATCmdContainer * CAAAfrGeneralWksAdn::CreateToolbars()
{
  ... // See Creating the Toolbar and Arranging the Commands
}

    The CAAAfrGeneralWksAdn class states that it implements the CATIAfrGeneralWksAddin interface thanks to the TIE_CATIAfrGeneralWksAddin macro. The CATImplementClass macro declares that the CAAAfrGeneralWksAdn class is a data extension, thanks to the DataExtension keyword, that extends CAAAfrGeneralWksAddin. The third argument must always be set as CATBaseUnknown or CATNull for any kind of extension.

  3. Updating the Dictionary

    Update the interface dictionary, that is a file named, for example, CAAApplicationFrame.dico, whose directory's pathname is concatenated at run time in the CATDictionaryPath environment variable, and containing the following declaration to state that the CAAAfrGeneralWksAddin component implements the CATIAfrGeneralWksAddin interface, and whose code is located in the libCAAAfrGeneralWksAddin shared library or DLL.

    CAAAfrGeneralWksAddin CATIAfrGeneralWksAddin libCAAAfrGeneralWksAddin

    Note that the component main class name is used to refer to the component in the interface dictionary, and never the extension class names. Note also that the shared library or DLL to associate with the component/interface pair is the one that contains the code created by the call to the TIE macro (This is generally the same library than the one that contains the interface implementation code, since the TIE macro is usually included in the extension class source file.) This is because when a client asks a component for an interface pointer, the TIE class is instantiated first, and it either retrieves the existing instance of the appropriate extension class, or otherwise instantiates it.

[Top]

Create the command headers

Before reading this section, you can you refer to the "The Command Headers" article [5] to have an overview of the command header concepts, and more precisely you have the "Defining Headers in CATIAfrGeneralWksAddin implementations" section, which details the specificities of command headers created in this general add-in.  

This is done by the CreateCommands method. Each command available in your add-in should be represent by a command header. A command header is an instance of a command header class.

The command header class, named CAAAfrGeneralWksAddinHeader, is created using the MacDeclareHeader macro.

  1. Create the CAAAfrGeneralWksAddinHeader command header class. To do this, add the following lines in CAAAfrGeneralWksAdn.cpp: 
    #include "CATCommandHeader.h"
MacDeclareHeader(CAAAfrGeneralWksAddinHeader);

    The MacDeclareHeader macro creates the header file and the source file for the CAAAfrGeneralWksAddinHeader class, and associates with this class the resource files CAAAfrGeneralWksAddinHeader.CATNls and CAAAfrGeneralWksAddinHeader.CATRsc. See Providing the Resources.

  2. Create the command headers in the CreateCommands method. This method should contain one instantiation statement of the command header class per command header. Each statement has the following form. 
    void CAAAfrGeneralWksAdn::CreateCommands()
{
  ...
   new CAAAfrGeneralWksAddinHeader("CAAAfrSearchHdr", 
                             "CAACafSearch", 
                             "CAACafSearchCmd", (void *)NULL);
  ...
}

    The command header constructor has the following arguments:

The command header associated with the Viewer Feedback demonstrator - see What Does CAAAfrGeneralWksAddin Do - is described in the use case [10].

The command header associated with the Most Recent Used header is described in the use case [11].

[Top]

 

Create the add-in and arrange the commands

Finally, we'll create the toolbar and arrange the commands. This is the job of the CreateToolbars method.

[Top]

Provide the resources

You should provide the resources for the toolbar, the menu and for all its commands. They are classified into the following:

For the resources of the CAAAfrViewerFeedbackHdr command header, refer to the CAAAfrViewerFeedbackHdr use case [10].

[Top]

In Short

This use case explains how by implementing the CATIAfrGeneralWksAddin interface you can add your document independent command in all workbenches. 

[Top]

References

[1] Creating an Add-in
[2] ApplicationFrame Overview
[3] Creating Search Queries 
[4] Building and Launching a CAA V5 Use Case
[5] The Command Headers
[6] Checklist for CAA V5 C++ Naming Rules
[7] Creating Resources for Workshop and Workbenches
[8] Creating Resources for Command Headers
[9] Viewer Feedback
[10] Creating Check Button
[11] Creating a Most Recent Used command Header
[Top]

History

Version: 1 [May 2003] Document created
[Top]

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