EuGENia GMF Tutorial

EuGENia is a tool that automatically generates the .gmfgraph, .gmftool and .gmfmap models needed to implement a GMF editor from a single annotated Ecore metamodel. For example, from the following annotated EMF metamodel (expressed using Emfatic) it can generate a fully functional GMF editor, a screenshot of which is displayed below.

The Filesystem metamodel:

@namespace(uri="filesystem", prefix="filesystem")
@gmf
package filesystem;

@gmf.diagram
class Filesystem {
    val Drive[*] drives;
    val Sync[*] syncs;
}

class Drive extends Folder {

}

class Folder extends File {
    @gmf.compartment
    val File[*] contents;
}

class Shortcut extends File {
    @gmf.link(target.decoration="arrow", style="dash")
    ref File target;
}

@gmf.link(source="source", target="target", style="dot", width="2")
class Sync {
    ref File source;
    ref File target;
}

@gmf.node(label = "name")
class File {
    attr String name;
}

The generated editor:

Supported Annotations

EuGENia supports the following annotations on Ecore elements.

Note: some of the annotations may only be available in interim builds or in the latest version of the source code. Please check the current list of open bugs for details. These new annotations will be made available on subsequent interim and stable releases.

gmf

Applies to the top EPackage only and denotes that GMF-related annotations are expected in its elements. This doesn't affect the forthcoming model transformations, only the ECore validation process.

gmf.diagram

Denotes the root object of the metamodel. Only one (non-abstract) EClass must be annotated as gmf.diagram. Accepts the following details

gmf.node

Applies to an EClass and denotes that it should appear on the diagram as a node. Accepts the following details

gmf.link

Applies to EClasses that should appear on the diagram as links and to non-containment EReferences.

gmf.link (for EClass)

It accepts the following details: For an example see the Sync class in the filesystem metamodel

gmf.link (for non-containment EReference)

It accepts the following details:

gmf.compartment (for containment EReference)

Defines that the containment reference will create a compartment where model elements that conform to the type of the reference can be placed. It accepts the following detail:

gmf.affixed (for containment EReference)

Defines that the containment reference will create nodes which are affixed to the edges of the containing node. See an example.

gmf.label (for EAttribute)

Defines additional labels for the containing EClass. These labels will be displayed underneath the default label for the containing EClass. It accepts the following details:

Installing EuGENia (New Instructions!)

EuGENia is a part of the main Epsilon distribution. The update site of Epsilon is http://download.eclipse.org/epsilon/updates, and detailed instructions for installing it are available here.

Although not necessary, you should also install the Emfatic toolkit mentioned above through the following update site: http://download.eclipse.org/emfatic/update/

Running EuGENia

To run EuGENia you need to do the following:
  1. Create a new project
  2. Create and annotate your Ecore metamodel in the "model" folder of your project
  3. Right-click your Ecore metamodel (or Emfatic file) and select Eugenia→Generate GMF editor
  4. Launch a new Eclipse instance from the "Run - Eclipse Application" menu using "-XX:PermSize=64M -XX:MaxPermSize=128M -Xms512M -Xmx1024M" as VM arguments in the Run Configuration
  5. In the new Eclipse instance create a new General Project and in it create a new Filesystem diagram through the File→New→Other... dialog

Re-running EuGENia

If you now change your metamodel you'll have to rerun EuGENia to generate your updated editor:
  1. Right-click your Ecore metamodel (or Emfatic file) and select Eugenia→Generate GMF editor
  2. Run a new instance of Eclipse
(Please note that any changes you have done manually to .gmfgraph, .gmftool and .gmfmap will be overwritten. Have a look here for an alternative way to customize these models)

Troubleshooting

Recipes

Customizing your editor

Click here to find out how you can further customize the generated .gmfgraph, .gmfmap and .gmftool models in ways that are not supported by the annotations provided by EuGENia, and still preserve the customizations when EuGENia is re-invoked.

Adding Copyright

To add copyright information to your generated .gmfgen model, simply create a file named copyright.txt next to it. Next time you invoke Eugenia→Synchronize GMF gen model, EuGENia will pick it up and place its contents in the root GenDiagramEditor of your .gmfgen model. If you have added the copyright.txt file, you can also inject its contents to your .genmodel model (EMF generator model) by right-clicking it and invoking Eugenia→Synchronize EMF gen model.

Next Steps

Now that you've learned how to generate a GMF-based editor using EuGENia, you may also want to add some constraints to your editor, which you can then evaluate (explicitly or on-save) to check the correctness/consistency of your models:

To do