Skip to main content
Jump to: navigation, search

Graphical Modeling Framework/Tutorial/Part 1

This tutorial will introduce the Graphical Modeling Framework (GMF), an Eclipse Technology subproject which aims to provide a generative bridge between the Eclipse Modeling Framework (EMF) and Graphical Editing Framework (GEF). In this tutorial, a mindmap application will be developed, as described here. This tutorial describes the functionality provided by GMF in its current state, using this build (1.0M4). It is expected that this tutorial will evolve with GMF to introduce new functionality as it is developed.

Overview of GMF

The use of both EMF and GEF for building Eclipse-based functionality is quite common. Many references below provide information on how to utilize these frameworks together, some of which inspired the GMF project itself. Before diving into a new GMF project, let's explore a little of how GMF approaches the task of utilizing EMF and GEF in a generative manner. Another article focusing on the runtime portion of GMF is found here.

The GMF project has adopted the term 'toolsmith' to refer to developers that use GMF to build plug-ins, while 'user' is typically refered to those who utilize said plug-ins, and who may also be developers. From a usability perspective, the number and types of 'models' utilized by GMF internally should be obfuscated to the greatest extent possible. However, it is likely that most toolsmiths are interested in knowing what is going on under the covers, so a description of each model is presented in this tutorial.

GMF Overview

This is a diagram that illustrates the main components and models used during GMF-based development. Core to GMF is the concept of a graphical definition model. This model contains information related to the graphical elements that will appear in a GEF-based runtime, but have no direct connection to the domain models for which they will provide representation and editing. An optional tooling definition model is used to design the palette and other periphery (overview, zoom, etc.), while read-only surfaces would not require no such a model.

It is expected that the graphical and tooling definitions may work equally well for several domains (for the most part). For example, the UML class diagram has many counterparts, all of which are strikingly similar in their basic appearance and structure. A goal of GMF is to allow the graphical definition to be reused for several domains. This is achieved by using a separate mapping model to link the graphical and tooling definitions to the desired domain model(s).

Once the appropriate mappings are defined, GMF provides a generator model to allow implementation details to be defined for the generation phase. The production of plug-ins based on these generator, definition, and mapping models will target a final model; that is, the diagram runtime (or "notation") model. This model is used to bridge the diagram and domain model(s) when a user is working with a diagram and also provides for persistence of both. An important aspect of this runtime is that it provides a services-based approach to GEF functionality and is also able to be leveraged by non-generated applications.

With the basics of GMF covered, let's now walk through the process of using GMF in the development of a graphical editing surface for a particular domain. First, you will need to install GMF and its dependencies.


This version of the tutorial was written using this build of GMF (1.0M4). Note that the prerequisites are listed on the build page, which must be installed prior to installing GMF, either from the download page, or from the update manager site. The TaiPan example referenced below is maintained in CVS and should remain functional with the latest builds of GMF, even if the tutorial is not quite up-to-date.

Quick Start


If you're anxious to see GMF in action, check out the Taipan example projects into your workspace from CVS by switching to the CVS Repository Exploring perspective and adding a repository location as shown in the image below. Otherwise, you can skip to the next section.

Navigate to /HEAD/org.eclipse.gmf/examples and select the three org.eclipse.gmf.examples.taipan.* modules. Right-click and select Check Out. Switch to the Plug-in Development perspective and open the models folder within the org.eclipse.gmf.examples.taipan project. Explore each of the models found here, particularly the taipan.gmfgraph and taipan.gmfmap models and their element properties.

We will look at each of the models in turn, but just to validate your configuration, you should be able to run this sample in a runtime workspace (simply accept the defaults for a new 'Eclipse Application' run configuration). In the runtime workspace, create an empty project and a new 'TaiPan Diagram' found in the Examples folder of the New dialog. Name it whatever you wish and click Finish. The generated diagram editor should open for you to explore.

Taipan diagram.png

This concludes the quick start portion of this tutorial. What follows next is a more detailed look at each of the models shown above during the creation of a mindmap modeling surface.

A New Project

As described here, one of the usage scenarios for GMF includes producing a graphical surface for a mindmap application, to be complemented with an alternative view of its temporal information (likely a Gantt chart). This section of the tutorial will demonstrate GMF's capabilities toward this end, and will continue to evolve as the project matures. If you'd prefer to follow along using a set of projects representing the complete solution to this tutorial, you can find a zip of them here.

Begin by creating an "Empty EMF Project" found under 'Eclipse Modeling Framework' in the New dialog (Ctrl+N). Name the project 'org.eclipse.gmf.examples.mindmap' and create a new folder named 'model' in its root.

Domain Model Definition

Although it may seem necessary to begin with the domain model, it is not in the case of GMF where the diagram definition is kept separate from the domain. However, we will begin with the domain in the tutorial as it is likely familiar to most, and will allow us to jumpstart our diagram definition from the domain model when the appropriate wizard is available from GMF.

GMF currently uses standard EMF facilities for working with domain models, but it is planned to provide a graphical ECore modeling surface for the 1.0 release. To begin, create a new mindmap.genmodel from the mindmap.ecore file found here using the New > Eclipse Modeling Framework > EMF Model wizard. You may wish to change the 'Base Package' property for the genmodel's 'Mindmap' package to org.eclipse.gmf.examples to have your generated packaging match the project name.

Tip : Be sure to give your genmodel file the same name as your domain model (i.e. both mindmap.*), as GMF currently expects this naming convention to identify the genmodel for the mapped domain model.

Taking a quick look at our domain model, you can see that it's rather simple. There is a Topic class, with associated Resource, Comment, and sub-Topic classes. These are contained in a Map class, with Topics able to be linked using a Relationship class.

Mindmap domain model

Tip : The image above was produced using the aforementioned GMF plug-in for graphically editing ECore (*.ecore) models. This plug-in is included with the examples download (as of Jan 18th) or can be found in CVS here.

Generate the model and edit code using the right-click menu available from the root of the generator model. There is no need to create an editor or tests, but you are welcome to do so if you'd like. Now, we're ready to begin creating the graphical and mapping definitions for our mindmap application.

Graphical Definition

Graphical Definition Model, best viewed in actual size.

A graphical definition model is used to define the figures, nodes, links, etc. that you will display on your diagram. The model you will work with to do this is seen at the right.

Right-click on the model folder within your project and select 'New > Other... > Example EMF Model Creation Wizards > GMFGraph Model' and name it 'mindmap.gmfgraph'. On the last page of the wizard, select 'Canvas' for Model Object. Note that the use of EMF's generated default wizards and editors is temporary for the diagram and mapping definitions.

Tip : You may have noticed the 'GMF' folder in the 'New' dialog, and within it, wizards for creating graphical, tooling, and mapping definitions. These are new to 1.0M4 and we'll utilize them to a greater extent in future installments of the tutorial. For now, we'll do things the old-fashioned way in order to better understand the workings of GMF.

Diagram definition.png

Give your Canvas element a name (e.g. 'MindmapDiagram') using the properties view. Then, right-click the canvas element and select 'New Child > Figure Gallery'. Give a name, e.g. 'Default'. A Figure Gallery will contain elements which correspond to GEF figures, with the idea being that these figures can be reused and/or provided in libraries for use in multiple graphical definitions. To the gallery, add a new Rectangle using the right-click menu. Give it the name 'BasicRectangle'.

Now, right-click on the Canvas element and select 'New Child > Node' and set the name attribute to TopicNode. For the 'Figure' property, select your 'BasicRectangle' element. We're done with the graphical definition for now, so let's move on to the tooling definition. This is what your mindmap.gmfgraph should look like.

Tip : There is a basic.gmfgraph model included with GMF for use in your graphical definitions. It contains a basic Figure Gallery, along with generic Node, Compartment, Connection, and Child elements that you can load into your *.gmfgraph model by using "Load Resource..." and entering platform:/plugin/org.eclipse.gmf.graphdef/models/basic.gmfgraph for the Resource URI.

Tooling Definition

Tooling Definition Model, best viewed in actual size.

As mentioned above, the tooling definition model is used to specify the palette, creation tools, actions, etc. for your graphical elements. To the right is a diagram of the model.

Let's utilize a wizard to get us started with our tooling definition. Right-click your mindmap.ecore file and select 'New > Other... > GMF > GMFTool Simple Model'. Press 'Next' and accept the default name of mindmap.gmftool for the model. The mindmap.ecore file is preselected in the next page. On the last page, we'll let the wizard create tools for all elements in our domain model, although we've only created a TopicNode so far.

Tooling model.png

Looking at the model provided for us, we see there is a top-level 'Tool Registry' element, under which we find a Palette. The palette contains a Tool Group with Creation Tool elements for each of the domain model elements identified by the wizard, and which we see in the figure above. We will reorganize these and modify them a bit in the future, but for now we'll leave the defaults and move on to the mapping definition. Feel free to browse this model and inspect its properties to familiarize yourself with tooling definitions, but be aware that this model is subject to change.

Mapping Definition

Tooling Definition Model, best viewed in actual size.

The mapping definition model will let us bind the three models we have so far: the domain, the graphical definition, and the tooling definition. To the right is an image of this model.

Right-click on the model folder again, and select 'New > Other... > EMF Model Creation Wizards > GMFMap Model' from the New dialog. Give it the name 'mindmap.gmfmap' and select 'Mapping' for the Model Object.

Load resource.png

In order to map between the graphical definition model and the domain model, you'll need to load these resources into the editor (a wizard will eventually replace this step when creating mapping models in the future). Right-click in the editor of mindmap.gmfmap and select 'Load Resource...' to bring up the selection dialog. Using the 'Browse Workspace...' option, select your mindmap.ecore, mindmap.gmfgraph, and mindmap.gmftool models before closing the 'Load Resource' dialog.

Canvas mapping.png

Now, we can map between diagram elements and domain elements, and assign a tool for creation of elements to the palette. First, select the root 'Mapping' element and right-click to create a 'New Child > Canvas Mapping' element. Configure its properties as shown in the image here:

Before moving on, let's pause to describe the mappings. In the case of the 'Diagram Canvas' property under 'Visual representation,' it's straightforward as the only option should be for our 'Canvas MindmapDiagram'. For the 'Domain Model' property under 'Domain meta information', we want to define mappings on this canvas for those elements found in the 'EPackage mindmap' domain model, although the list will also provide you with an 'ecore' option. 'Element' is the property we need to assign to a domain element that will represent the diagram itself. From the list, select 'EClass Map' to indicate that an instance of our Map is represented by a new diagram. Finally, under 'Misc' we see that our 'Palette' from the tooling definition is mapped to the 'Pallete' element under 'Misc'.

Node mapping.png

We only have a single node to map so far. Right-click on the Canvas Mapping element and select 'New Sibling > Node Mapping' and again set its properties to the values shown here:

Now, to explain the node mappings. The 'Diagram Node' maps easily to our only node from the graphical definition, 'Node TopicNode'. For its 'Tool' property, we select the 'Creation Tool Topic' from our tooling definition model. The 'Domain meta information > Element' in this case maps to the 'EClass Topic' as you'd expect, with its 'EAttribute name' mapped to the 'Edit Feature' property. Thus, when working with instances of Topic classes in our domain model, which are represented as instances of TopicNode elements on our diagram, the label of the graphical elements will be represented by the name attribute of the domain model class. Finally, the 'Containment Feature' is mapped to the element in the domain model which holds the instances of these new Topic classes, which in our case is the 'EReference topics' attribute of our Map class.

Tip : Note that it is important to select the proper element when defining mappings at this stage; that is, before GMF does the proper filtering and validation. A good way to ensure you have selected the element you intended (as several may have the same name), open the mapping definition (*.gmfmap) file in a text editor.


Tooling Definition Model, best viewed in actual size.

The last model to cover in this tutorial, and the one that is not as critical to understand at this point, is the GMF generator model. See the diagram to the right if you're interested in examining this model.

Create gmfgen.png

Now that the minimal graphical elements and mappings are defined, we can generate the code needed to test our work so far. To accomplish this, we will first create a generator model (*.gmfgen) in order to set the properties for code generation, similar to the familiar EMF genmodel. To accomplish this, right-click the mapping file and select 'Create generator model...' as shown below. When prompted, keep the default name 'mindmap.gmfgen'.

Now, we can examine the generator model to see what it includes (if you're the curious type). We'll keep all the default values for now and right-click the mindmap.gmfgen file and select 'Generate diagram code' to proceed. If all goes well, you will see a "Code generation completed successfully." message dialog. Dismiss the dialog, opting to never see it again, and notice the new org.eclipse.gmf.examples.mindmap.gmf.editor plug-in in your workspace.

Running the Diagram

Now that we have generated the plug-in needed for our diagram, let's launch a new runtime workspace and test the diagram. The default settings of a new Eclipse Application runtime configuration should work fine, while you may opt to run a minimal configuration that includes only your generated plug-ins and their runtime dependencies within an org.eclipse.platform.ide configuration.

Create an empty project and invoke the New... dialog (Ctrl+N). Under 'Examples' you'll notice your new Mindmap Diagram. Create a new diagram and explore its functionality, and look for the creation of the domain model instance as you add and save diagram elements. Of course, we've only specified enough in our diagram definition to allow for simple Topic elements. Next, we'll look at how to add connections and compartments...

Basic mindmap.png

Compartments and Connections

Let's return to our diagram definition and add a compartment to our TopicNode to allow for Comment elements to be added. First, add a new child for Comment elements to the Canvas by adding a 'New Child > Child' and name it CommentChild. For its Figure, select your new 'BasicRectangle'. Now we need to add a Compartment to hold the CommentChild elements. To do this, right-click on the Canvas element and select 'New Child > Compartment'. In the properties view, give it a name 'CommentCompartment'. Target your BasicRectangle figure by selecting it for the 'Figure' property.


While we're here, let's go ahead and add a Connection element, as we'd like to indicate a subtopic relationship between Topic nodes on our diagram. In the Figure Gallery, add a new 'Polyline Connection' with a simple 'BasicLine' name and adjust the other properties as you see fit. Add the link we'll need between topics by right-clicking on the Canvas element and selecting 'New Child > Connection'. Give it the name 'TopicLink', selecting our new BasicLine from the gallery.

Back to the top