Generate an Editor

1. Creation of an Ecore Metamodel

1.1 Configuration and generation of the EMF tree structure editor

1.2 Configuration

1.3 Generation

2. Creation of the configurator for the graphical editor

2.1 The Editor Configurator file

2.2 The Diagram Configurator file

3. Generation of the graphical editor and customizations

3.1 Icons

3.2 Templates

3.3 EditPart customization

3.4 Figure customization

3.5 TODO tags

3.6 The diagram.graphconf file

Introduction :

The document is a user manual that explains the generation process : how from a starting metamodel, we can generate a graphical editor. The process takes a few steps :


1. Creation of an Ecore Metamodel

Create an "Empty EMF project". Give a name like org.topcased.xxx where xxx is the name of the metamodel.

empty_EMF_project

Then, you can create an Ecore model from the tree structure EMF tree structure Ecore editor : select "New > Other...", and "Example EMF Model Creation Wizards > Ecore Model". Create a new folder (model) that will contain the newly created Ecore model.

new_ecore_model

Select "EPackage" as the root model object to create.

select_model_object

Then you can make your model, create EClasses, EReferences, EAttributes, ...

Remark 1 : you have other ways to get your Ecore metamodel. You can use the graphical Ecore Editor of Topcased or import it from a Rose class model.

Remark 2 : the root EPackage attributes must be filled with the following values :

1.1 Configuration and generation of the EMF tree structure editor

The first step is to create the xxx.genmodel file that will configure what will be generated at the creation of the tree structure editor.

Remark : if you have chosen to create your Ecore metamodel from a Rose class model, the xxx.genmodel file is automatically created, you have just to customize it.

select_model_importer

Select "New > Other...", and "Eclipse Modeling Framework > EMF Model". Create the file xxx.genmodel in the same folder as the xxx.ecore file. Then select "EMF core model" as the Model Importer and reference the xxx.ecore file as the model file in the next page wizard.

1.2 Configuration


1.3 Generation

To generate the tree structure editor, open the xxx.genmodel file and right click on the GenModel element and select "Generate All".

generate_all

2. Creation of the configurators for the graphical editor

Once you have generated the tree structure editor, let us configure a more convivial editor : a graphical editor.

The first step is to create the necessary configurator files. The configurator files describe what the editor will look like, which diagrams will be available and what will be displayed in each diagram. The configuration of a graphical editor consists in describing several configuration files :


2.1 The Editor Configurator file

Select "New > Others...", and then "Topcased > Topcased Configurators > Editorconfigurator Model". selectWizard The root model object must be "Editor Configuration". When you have finished the wizard, the editor is opened. The configurator model only contains the root element "Editor Configuration". The editor configurator file is quite simple. It contains only one model object, an EditorConfiguration with a few properties. You can define here common properties of the generated editor plugin :


2.2 The Diagram Configurator file

Select "New > Others...", and then "Topcased > Topcased Configurators > Diagramconfigurator Model". selectWizard The root model object must be "Diagram Configuration". When you have finished the wizard, the editor is opened. The configurator model only contains the root element "Diagram Configuration".

Then, you will have to specify the metamodel file you will work with. Indeed, the objects we will create will depends on the model objects of the metamodel we have created. When your new empty configurator file is open, you can do this by right clicking on the editing window and selecting "Load Resource..." : then you have to select to corresponding xxx.genmodel file.

The diagram configurator file is more complete. Indeed, it is used to configure all graphical objects used in the diagram, the associated model objects and the Palette of the diagram. We advise you to edit the different part of the configurator in the following order :

2.2.1 Diagram Configuration

This is the root model object of your diagram configurator. You can define here common properties of the generated diagram plugin and furthermore, you will reference here the loaded Genmodel file.


2.2.2 ObjectConfiguration, ModelObjectConfiguration and SimpleObjectConfiguration

There are two types of ObjectConfiguration. This element will describe the model representation defined at the DiagramConfiguration level.

A ModelObjectConfiguration will be linked with a model object (that will be referenced by its GenClass). You will be able to specify one or several DiagramConfiguration that can be associated with this model object through a DiagramReference.

A SimpleObjectConfiguration will not be linked with any model object. It will be then referenced by a PartConfiguration to represent only a graphical element.



2.2.3 DiagramReference

The DiagramReference is used to indicate that a diagram will be associated with the model object referenced by the container ModelObjectConfiguration. Then you will be able to create new diagrams from this object. A same diagram may be associated with several ModelObjectConfiguration, and each diagram must be associated with at least one ModelObjectConfiguration.


2.2.4 PartConfiguration, NodePartConfiguration and EdgePartConfiguration

There are two types of PartConfiguration. This element will describe the graphical representation of an ObjectConfiguration defined at the DiagramConfiguration level.

The NodePartConfiguration is used to describe an object that will be represented as a Node in the diagram. You will have to specify its graphical properties and also its behavior in the editor (whether it is resizable, whether it will contains other Nodes, how it will arrange them, ...)

The EdgePartConfiguration is used to describe an object that will be represented as an Edge in the diagram. It will be used to connect two Nodes.




Remark : for each NodePartConfiguration, you must specify the figure that will represent the graphical object. You can define your own figures and reference them trough an extension by using the extension point (figureDeclaration) defined in the configurator.

2.2.5 PaletteConfiguration, PaletteCategory and PaletteItem

The PaletteConfiguration is used to configure the tools that will be available in a given diagram. It is composed of several PaletteCategory objects.

The PaletteCategory is used to arrange the different tools associated with PartConfigurations of the Editor. It contains PaletteItem objects.

The PaletteItem links a tool with a PartConfiguration. This is the object that will be created from this ToolType.




2.2.6 SourceTargetCouple

This defines the source and target couples for each connection that can be created. At this point, you will define the different possible ways to create an Edge between two Nodes. You will then define where the model object will be stored in the model and the different references between the source Node, the target Node and the Edge. To add a "source target couple" to your edge part, right click on the part and choose, "New Child > Source target couple".


To illustrate this section, we will configure the Implementation Edge of the UML2.0 metamodel (An Implementation is a specialized Realization relationship between a Classifier and an Interface) :


Remark : Repeat all those steps for each "source target" couples.

2.2.7 EdgeObject

The EdgeObject is used to define which are the different Labels that will be associated with an Edge. In the case of an Association in UML2, we will be able to define two Labels at the source (one for the Cardinality of the Association and the other for the name of the reference), two others at the end of the Edge and eventually one at the middle of the Association that will display the name of the current Association. This is a particular example where multiple labels are defined.

But in most case, a simple Label will be sufficient. You will be able to define where the Label should be attached (with the type attribute), and select the eStructuralFeature that will be associated with the Label (the feature should be of type EString to be well displayed). If the feature is not a direct attribute of the Edge, you will have the possibility to define the id to use : this will be then used at the generation process to create a method used to retrieve the EdgeObject. In this case, it is better to set the id as the name of the feature that will be retrieved during the customization step.


2.2.8 Constraint (since 0.10.0)

A Constraint is used to specify a constraint or a set of constraints that should be matched by a PartConfiguration to be valid, and more precisely by the model object associated with the ModelObjectConfiguration. Indeed a given model object may represent two different notions depending on its properties. The constraints are then used to check these properties at the runtime and specify which PartConfiguration should be used. At the moment, there is only one type of language which is supported : "ocl". You can easily add new languages through an extension using the extension point (evaluators) defined in the "org.topcased.modeler" plugin.


2.2.9 Configurator Annotations (since 0.10.0)

Annotations are generally used to insert additional informations that will be embedded in the configurator model and that will be used during the generation process. An Annotation is composed of one or several detail entries.


Remark : When a new type of code customization is interesting to manage directly in the configurator model, the template(s) associated should be modified to manage it.

3. Generation of the graphical editor and customizations

When you have finished to configure your editor, you can right click on your configurator file and select the corresponding action : "Topcased > Generation > Editor" or "Topcased > Generation > Diagram". It will generate a plugin according to the properties you defined in the configurator file.

Once the graphical editor plugin generated, you should be able to run it. However, the editor should be customized to get a more convivial one.

Remark : if you modify an attribute or a method that contains a '@generated' tag in a generated class, be sure to place 'NOT' after it to prevent it from being overwritten. Note that it is preferable to create '@generated NOT' tags, rather than removing the '@generated' tag completely.

3.1 Icons

The folder called "icons" contains the icons that are used by the editor. These icons are retrieved by an ImageRegistry class : it gets the Image location from the identifier that is present in the file images.properties that have been generated. After the generation none icon is generated but you can add yours. Just take a look at the file image.properties to give the corresponding name to your icons, or rename the file access in the file. Icons used in the palette should be sized to 16x16 to be well displayed.

3.2 Templates

The generated editor provides an extension point to define templates. The template files are constrained :


Remarks :


3.3 EditPart customization

The EditParts are the controller objects of the editor. They are used to link the model object with its graphical representation. There is mainly one method to customize : the createEditPolicies() method. This is the method that configure the behavior of the graphical node or edge. Lots of information is generated but you can add new behaviors.

3.4 Figure customization

The "Figures" manage the graphical aspect, that is how an object of the model should be displayed.


3.5 TODO tags

When the editor is generated, there are some code that must be customized or that will certainly be customized. So in the generated code, we introduce some TODO tags so that the developer that will have to customize the code can accede faster to the code that need some customization. There is a dedicated view in Eclipse (The Task view) that references all the TODO tags present in the java files.

todo

So, in the most cases, you will have to open the Tasks view to see the TODO tags that will help you to find where some code should be handle coded.

3.6 The diagram.graphconf file (since 0.9.0)

This file contains the graphical informations (colors, size,...) used to display graphical elements in a given diagram. Previously, these informations were generated in the java classes, but these informations were often duplicated in many classes to be always accessible. Now, these informations are stored in a unique place and are accessed in a unique way.

The file is generated from the informations present in the diagram configuration file. It is not recommended to modify this file : the better way would consist in updating the diagram.configuration file and regenerating the diagram plugin (with the option "overwriteGraphConf" set to true).

By Jacques LESCOT, Anyware Technologies

Updated June, 26 2006