RADE

Getting Started

Even if the Code Generator commands are available, they cannot work until you open a CAA V5 workspace. If you try to use them before opening a workspace you will get an error message (see picture opposite.)

In order to remedy the situation, open or create a V5 workspace. Below is a short summary explaining how to open a V5 workspace. For more information, see Principles of use - How to open and build a CAAV5 workspace.

[Top]

Opening a Workspace

To open a workspace, proceed as follows:

From the File menu, select Open CAA V5 Workspace. In the With: combo box, select Mkmk (if need be.) Note that both modes will enable you to access the Code Generator features. Enter the workspace root directory or click the ... button to select it. In the Tool level combo box, select the Mkmk level that you want to use (if there is only one level available, Default should display in the combo box). Click OK when done. A log window is displayed while your environment is updated and the workspace opened. When this window has disappeared Visual Studio 2005 loads the project files stored in your workspace. You are ready to work.

[Top]

Overview

The commands available in the Code Generator are a set of wizards where you specify a series of parameters. The Code Generator will generate the code for you. Before creating the code, a report window is displayed enabling you to check that the code generated is as expected.

Some generated source files contain commented out statements such as "DO NOT EDIT :: THE CAA2 WIZARDS WILL INSERT CODE HERE". Do not modify what you find between these commented lines or the wizards will no longer be able to insert code into the source file.

[Top]

Generating a V5 directory structure

Code Generator commands enable you to create the necessary V5 directory structure. The wizard will assist you in creating new frameworks and modules using the available tools. You can then start populating your directories either using the available wizards, or creating new objects, using Visual Studio 2005.

[Top]

Creating a Framework

To create a framework, proceed as follows:

From the File menu, select Add CAAV5 Project…->New Framework…. In the Framework name field, enter the name of your framework (MyFramework in this example) and click OK. Click OK in the CAA V5 Generation window. Your framework is created.

The wizard creates the following directory structure:

Education type frameworks are suffixed ".edu" and Test frameworks are suffixed ".tst". The wizard appends these suffixes to the framework name.

[Top]

Creating an Interface Framework

An interface framework is a framework that contains (mainly) interfaces in both C++ or IDL language. The structure of this interface is very specific. V5 naming conventions need these interfaces to be distinguishable through an "Interfaces" suffix. Therefore if you type in "Bird" in the framework name, the generated framework will be called "BirdInterfaces". The generated structure is the following:

After the file structure has been created, the C++ Interactive Dashboard updates your project to take the new files and directories into account. Note that the framework is set as the current active project.

Defining Prerequisite Frameworks

Any framework - whatever its type is (code, education, test) - must provide an IdentityCard file in which it defines its prerequisite frameworks.

To define prerequisite frameworks proceed as follows:

[Top]

Creating a Module

If you want to create a module, you should be in a valid framework. Make the framework your active project.

To create a new module, proceed as follows:

From the File menu, select Add CAAV5 Project->New Module. The New Module window is displayed. In the Module name field, enter the name of your module (MyModule in this example) and click OK. Click OK in the CAA V5 Generation window. Note that this window shows you the files and directories that will be created. Your module is created.

The following file structure is created:

The newly created module is set as the current active one.

[Top]

Generating V5 Source Code

Code Generator wizards enable you to create specific V5 objects that implement customary V5 patterns. These currently include:

• Object modeler interfaces (both C++ and IDL)
• Object modeler implementations
• V5 documents
• V5 features.

The source code is generated in the currently active module. If the active project is not a module, a warning box will ask you to set your module as the active project. To activate the module, right-click the project in the Solution Explorer view, and select Set as StartUp Project (see picture opposite.)

[Top]

Creating a CAA V5 C++ Class

To create a class, proceed as follows:

From the File menu, select Add CAAV5 Item/CAA V5 Class.... The Insert CAA V5 Class is displayed. In the Class name field, enter the class name. Click OK when done. Click OK in the CAA V5 Generation window. It is recommended to use this command rather than MsDev own class creator because it takes the CAAV5 File Tree, and the standard macros included in the CAA classes into account.

The wizard creates a header and a source file including a standard constructor and destructor, an equal operator and a copy constructor. The following files are created.

[Top]

Creating a C++ Interface

To create an interface, proceed as follows:

From the File menu, select Add CAAV5 Item…->Interface…. The Insert Interface window is displayed. In the Interface name field, enter the name of your new interface (CATIWingedCreature here) and click OK. Click OK in the CAA V5 Generation window. Your interface is created.

V5 naming conventions require that your interface have a 3 letter prefix, followed by the letter 'I' in upper case, followed by anything else, as in CATINavigateObject.

The following files are created.

[Top]

Creating an IDL Interface

IDL interfaces can only be generated in an Interface framework. The IDL radio button will be grayed out in any other type of framework.

From the File menu, select Add CAAV5 Item…->Interface…. The Insert Interface window is displayed. In the Interface name field, enter the name of your new interface (CATIWingedCreature here) and click OK.   V5 naming conventions require that automation interface have a 3-letter prefix, followed by the letters IA in upper case, followed by anything else. The automation alias will be generated by extracting the XXXIA prefix from the interface name.

4. Click OK in the CAA V5 Generation window showing you the files that will be created or affected (see graphic below).

[Top]

Creating an Object Modeler Implementation

Component implementations are written in C++. They cannot be included into interface frameworks. To create a component, proceed as follows:

1. From the File menu, select Add CAAV5 Item…->Component…. The Insert Component window is displayed.
2. In the Component name field, enter the name of your new component (CATDovesFly in this example) and click OK.
3. Select the mode you want to use and click OK.

You can choose to specify interfaces to implement manually, or using the dialog box showing available interfaces. To generate code correctly, we must find interfaces declarations.
If you use the dialog box showing available interfaces, the search is done when finding all interfaces. So no search will be done when generating code.

	If you add interfaces manually, when clicking OK, the search will be launched for each added interface. First, we try to find .h files and then we try to find .idl files. This search is performed, by default, in the current workspace. If you check the Check interfaces existence in prerequisite workspaces (slower) option, you will extend the search to all workspaces defined as prerequisite which can be time consuming (particularly if you are trying to implement many interfaces). That is why, after 25 seconds, you can choose to keep on searching interface location, or to cancel the search. When canceling, only the pending search is canceled. That is to say, if you are looking for 3 interfaces, and you cancel when seeking  the first one, the search will go on with others.
	At the end of the search, a dialog box displays all the interfaces that were not found, and will suggest you to remove these interfaces. If you cancel, you can decide to remove them manually, or to check their existence in the prerequisite workspaces (if you did not select it before).

Even though you can create an implementation from either a C++ or an IDL interface, the wizard will not work on an uncompiled IDL header. If you directly enter the name of the interface you want to implement, the command will prompt you to specify the header file that contains the definition of the interface. You may also ask the wizard for the list of all available interfaces in your workspace, or in your prerequisite workspaces (this may take some time as it parses all the interfaces in the workspace).

Differences between TIE and BOA

• A BOA (Basic Object Adapter) directly links the application to the implementation. Every request to an interface method uses the implementation method owing the C++ inheritance mechanism between classes. When using a BOA, the implementation inherits from the interface, so Object Modeler inheritance is no more possible.

        Principle graphic:

• A TIE is the object that links the interface to the implementation. Every request to an interface method is redirected to the corresponding implementation method through the TIE.
  Object Modeler inheritance is possible since no C++ inheritance is needed for this mechanism.

Principle graphic:

• TIE: When a pointer to an interface is required, a new TIE instance is returned even if there is already one. By default, use TIE as adhesion type.

• TIEchain: When a pointer to an interface is required, an existing one is returned if possible. That implies better performance, better memory usage, but needs reference counting on interfaces. You should use this type, rather than the standard TIE,  when many "QueryInterface"  calls to the interface are performed in the application.

When you click OK in the Insert Component window, a CAA V5 Generation window is displayed showing you the files that will be created (see below.)

[Top]

Creating an Object Modeler Extension

This command is similar to the previous one. It lets you add new extensions to already existing implementations. To add extensions, proceed as follows:

1. From the File menu, select Add CAAV5 Item…->Component extension... The Insert Component window is displayed.
2. In the Extension name field, enter the name of the extension (CATDovesPeck in this example).
3. In the Extended component field, enter the name of your new component (CATDovesFly in this example).
4. Select the mode you want to use and click OK.

The generated objects for extensions are the same as for components.

FAQ on Implementation and Extension (after creation with RADE builders)

How can I...
... change an interface adhesion from the TIE mode  to the BOA mode (for components and extensions)?	First, you cannot use BOA if you have a Code extension. Besides,  your extension must inherit from your interface, so your extension and your interface must have the same function signatures. As multiple inheritances are forbidden, your extension must not already inherit from any C++ class (except CATBaseUnknown). In the source code, just do the following changes. In the picture opposite, the class Extension implements the interface CATInterface in TIE mode, and we want to switch to the BOA mode) and check the dictionary file.
...change an extension type?	Type change depends on the content of your extension. If you want to convert a Data extension into a Code extension, you have to check if your class has no members and no interfaces adhesion in TIEchain mode. By default, all the TIEchains contained in this file will be converted into TIE to ensure a good execution. Moreover, your extension does not have to inherit from an interface, so BOA mode for interfaces adhesion is prohibited with a Code extension. Finally, in the source code of your extension, you have to check two rules : - no pointer "this" as function parameter - no callback on the extension itself No prerequisite is required to convert a Code extension into a Data extension. In the source code, just do the following changes (see picture opposite): Example: DataExtension --> CodeExtension.
... use an adapter?	By default, the inheritance in the Component builder implies the "ObjectModeler inheritance". But, some of you may want to derive from an adapter, to prevent from redefining all methods. The graphic below explains how to use an adapter for an interface.

Creating a Command

You can create several different types of new commands that you can add to your workshops. To do so, proceed as follows:

From the File menu, select Add CAAV5 Item…->CATIA Resource->Command... . The Insert Command window is displayed. In the Command name field, enter the name of the command that you want to create (CATIFlightSimulateCommand). Select the Command style that you want to create. Statechart command enables you to create a command driven by a finite state machine. Dialog box based command enables you to create a command driven by a dialog box. Basic command enables you to create a user defined command. Select the command mode (see picture opposite). Check Include in workshop if you want your command to be inserted into a workshop. Note that when specifying the name of a workshop (or workbench), the wizard will locate the code for that workshop and generate a command header for you. If no command header is found, a new type of header will be generated. Even though you have selected Include in workshop, you will still need to use the Customize functionality of CATIA to access the command from your palette. Click OK to validate. Click OK in the CAA V5 Generation window that shows you the generated files (see picture below). Your command is created.

[Top]

Creating a Dialog Object

You can create interactively a new dialog element based on the Dialog framework. To do so, proceed as follows:

From the File menu, select Add CAAV5 Item->CATIA Resource->Dialog....

When you select this command, a new page is inserted into your MsDev environment with a new and empty dialog. To find out more, see Dialog builder features.

[Top]

Creating a V5 Test-Case

You can create interactively a new test case script inside a test-dedicated framework. To do so, proceed as follows:

1. From the File menu, select Add CAAV5 Item->Test-Case... The Insert Test Case dialog box is displayed.
2. Select the type of script that you want to use. 4 script types are available:

   Simple test case: Test case used to test product capabilities. Switch test case: Test case used to validate the initialization of a new release (switch from a version to the other) and to test the core functions of a product. Batch: Test case used to launch a program that replays scenarios without user interaction. Record: Test case used to create a macro that records end-user scenarios in scripts you can then use as is or modify.

3. Click OK when done.

A new test case script is created in your framework. This test case can be run using Replay Test-Cases available in the Tools menu.

[Top]

Creating a V5 Pattern 

The component builder currently only allows you to generate one type of V5 patterns: Workshops (or workbenches). To do so, proceed as follows:

1. From the File menu, select Add CAAV5 Item…->CATIA Resource->CATIA Pattern... . The Insert CATIA Pattern window is displayed.
2. Select the type of component you want to create and click OK. The Create Workshop/Workbench dialog box is displayed.

	The wizard guides you through a series of windows that prompts you to enter the characteristics of the object you wish to create. After filling in each window, you can move on to the next window using the wizard navigation bar. When all the steps have been completed, click the Finish button to generate the component.

3. In the WorkObject type field, select Workshop or Workbench.
4. In the WorkObject name field, enter the name of the workbench and click Next>.

5. Define if you want to include the Select command.

6. Click the ... button to add your commands and click Next>.

7. Click the Finish button.

[Top]

References

History

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