Graphical Modeling Framework/Tutorial/Part 2

In this second part of the GMF Tutorial, some of the more advanced capabilities of the generation and runtime frameworks will be explored. Specifically, information on adding compartments, connections, feature initializers, diagram validation, and nested child nodes will be covered. The complete solution to this tutorial is maintained in CVS here. Viewlets will be available after appropriate sections below to focus their content and keep them short. (warning: they are outdated)

Important note: If you previously followed this tutorial with GMF 1.0, you'll need to be aware of changes in the graphical definition model described here.

New Icons

A quick way to get a polished look for our mindmap diagram is by replacing the generated EMF icons we've seen so far with some that are more, well... distinctive ;-) The easiest way to do this is to replace the GIF images found in our org.eclipse.gmf.examples.mindmap.edit/icons/ folder.

In case you'd like to map another image file to a palette item, say in the case of our three Relationship tools, or for our Subtopic link which has no default icon, you can modify the children of your Creation Tool elements in the mindmap.gmftool model. For example, delete the 'Default Image' entry below the 'Creation Tool Subtopic' element that represents the small icon and replace it with a 'Small Icon Bundle Image' and set its Bundle to org.eclipse.gmf.examples.mindmap.edit and its Path property to /icons/full/obj16/Subtopic.gif. Regenerate and the palette will display the new icon. Of course, you'll need to provide this file or use the one found in the solution to this tutorial section.

Finally, take a look in the mindmap.gmfgen for properties to set for the default wizard and diagram file icons. While you're there, you might want to change the diagram file extension from 'mindmap_diagram' to 'mmd' or something similar. Browsing the properties available in the gmfgen model is a useful exercise.

Below is an image of our diagram and palette using some new images.

Customize Figures

There are several ways to customize the figures in your editor. Here are a the main tricks to achieve that. You can choose any of this solution, depending on how much customization you need. It's recommended to try first the first solution, then the second one if solution #1 is too limited, then solution #3 is solution #2 is too limited.

Composite Figures (via .gmfgraph)

What we'd like to do is have an actor-style representation for our resources added to our diagram. These will be linked to their respective Topic elements, much like our relationship links between Topic elements. Also, we'd like to have the labels for our Resource figures external and display both the name and email address attribute values of the corresponding domain element.

Graphical Definition

Open up your graphical definition again and add a new Figure Descriptor and Rectangle named 'ResourceFigure' to your Figure Gallery. Set its Outline property to false, along with its Fill. As you can see from the image to the right, we will be adding a series of children to the rectangle, which will act as a container for the elements that comprise our Resource figure. Specifically, right-click and add an XY Layout, and Ellipse for the head, a Polygon for the Body, and sizing elements. Rather than go through all of the gory details of these, the figure code is found below. Either paste it into your mindmap.gmfgraph in the appropriate location using a text editor, or utilize the default editor and properties view.

To our Canvas, add a new Node named Resource and assign our ResourceFigure as its Figure. Also, notice the new 'BasicLabelFigure' label that is added to the Figure Gallery in the image. Create this and add a new Diagram Label 'ResourceLabel' to the Figure Gallery and Canvas respectively. Note that the Label for our Resource is not a child element of its figure. We want the label to be external, and therefore be allowed to float and be positioned wherever the user would like it.

  <descriptors
        name="ResourceFigure">
      <actualFigure
          xsi:type="gmfgraph:Rectangle"
          name="ResourceFigure"
          outline="false"
          fill="false">
        <layout
            xsi:type="gmfgraph:StackLayout"/>
        <children
            xsi:type="gmfgraph:Rectangle"
            name="Resource"
            outline="false"
            fill="false">
          <layout
              xsi:type="gmfgraph:FlowLayout"
              vertical="true"
              forceSingleLine="true"
              minorAlignment="CENTER"
              majorSpacing="0"
              minorSpacing="0"/>
          <children
              xsi:type="gmfgraph:Ellipse"
              name="Head">
            <foregroundColor
                xsi:type="gmfgraph:RGBColor"
                red="220"
                green="220"
                blue="250"/>
            <backgroundColor
                xsi:type="gmfgraph:RGBColor"
                red="230"
                green="230"
                blue="255"/>
            <size
                x="40"
                y="20"/>
          </children>
          <children
              xsi:type="gmfgraph:Polygon"
              name="Body">
            <foregroundColor
                xsi:type="gmfgraph:RGBColor"
                red="220"
                green="220"
                blue="250"/>
            <backgroundColor
                xsi:type="gmfgraph:RGBColor"
                red="230"
                green="230"
                blue="255"/>
            <template
                x="23"
                y="19"/>
            <template
                x="23"
                y="24"/>
            <template
                x="39"
                y="24"/>
            <template
                x="39"
                y="29"/>
            <template
                x="23"
                y="29"/>
            <template
                x="23"
                y="36"/>
            <template
                x="39"
                y="48"/>
            <template
                x="39"
                y="53"/>
            <template
                x="20"
                y="42"/>
            <template
                x="1"
                y="53"/>
            <template
                x="1"
                y="48"/>
            <template
                x="17"
                y="36"/>
            <template
                x="17"
                y="29"/>
            <template
                x="1"
                y="29"/>
            <template
                x="1"
                y="24"/>
            <template
                x="17"
                y="24"/>
            <template
                x="17"
                y="19"/>
            <template
                x="23"
                y="19"/>
          </children>
        </children>
      </actualFigure>
    </descriptors>

Tip : It's a bit tedious to add multiple template points in the manner above, so feel free to open the gmfgraph file in a text editor to make life easier. To get it looking right more quickly, open the generated figure class and simply modify the GEF code directly and run the editor to see how it looks. Then, move this information back into your gmfgraph model. Of course, when the WYSIWYG features of GMF become more mature, none of this should be necessary.

Tooling Definition

We'll need a tool to add Resource nodes, so as you've done many times before, open the mindmap.gmftool model and add a new node creation tool for the Resource. Next, we'll need to add our mappings, so reopen your mindmap.gmfmap file.

Mapping Definition

First, we'll need to add a new Top Node Reference to our Mapping definition. Set the Containment Feature to our 'resources : Resource' attribute of our Map class. Add a child Node Mapping element to this Top Node Reference and select our 'Resource' for the Domain meta information Element property. Of course, we'll select our Resource node for the Diagram Node and our Resource creation tool for the palette.

Now, to add our Feature Label Mapping as a child of the Node Mapping and set the Edit and View Pattern and corresponding features from our Resource class in the domain model. Here, we'll utilize the edit and view pattern properties of the mapping model to allow a Resource label to be displayed as 'name [email@some.com]'. To allow for the proper parsing of what's entered into the direct edit field, we will define an edit and editor pattern for the label as '{0} : {1}' where a colon is used to separate the name and email attributes. The view pattern will be '{0} [{1}]' and allow our label to be displayed as shown in the image. Note that the generated plug-in code will contribute to the parserProvider extension-point, which will in turn leverages the Java MessageFormat class.

Generation

After generation, a slight tweak will need to be made to the generated figure until bug 142010 is resolved. In the generated org.eclipse.gmf.examples.mindmap.diagram.edit.parts.ResourceEditPart$ResourceFigure class, set the attribute private boolean myUseLocalCoordinates = true; You might want to set the comment above it to @generated NOT in order to preserve this change. Without doing this the polygon used for the figure's body will not be visible. With that, set the fill(true) method on the body in the generated figure code, as it seems otherwise to not be filled.

Run the diagram and check the operation of the label, as well as the look of the figure. It should look similar to the one above. Resources added to the diagram are now available in the properties view for topic assignments, thread authoring, etc. To add the ability to create links from other elements to a Resource, follow steps similar to how links are used to represent subtopics. This exercise is left to the reader ;-)

Use SVGFigure

This allows you to use Figures defined from a SVG or a SVGZ file in your editor. Here are the steps to follow in order to use it:

Install the GMF Experimental SDK from GMF Tooling repository/update-site
Use the SVGFigure in your .gmfgraph. Here are some exmpales DocumentURI:
1. platform:/plugin/a.bundle.name/path/to/a/file.svg[z] to reference a file from a bundle that is available in the target application along with the editor.
2. (not advised) file:/filesystem/path/to/a/file.svg[z] to reference a file on your filesystem
3. (not advised) platform:/resource/MyProject/path/to/a/file.svg[z] to reference a file in the workspace of the application that will run the editor.
4. any kind of URI supported by Eclipse. See http://lmap.blogspot.com/2008/03/platform-scheme-uri.html for more details.
In your .gmfgen, add a dependency to the org.eclipse.gmf.runtime.lite.svg bundle. You can add it on the GenPlugin element, in the required bundles property.

An easy and efficient way to find SVG Images is to go to Google Images, and make your request by adding to it "filetype:svg". You'll often get lots of possible images.

Create your own Figures classes and use them

Another solution is to create your own classes extending IFigure, and to use this classes you developped as Figures in your GNFGraph. It will for sure provide you more control on your figure, but it can be more complicated to set up since the GMF Tooling GMFGraph Editor won't provide helpers to configure your class. You'll have to reference setter names.

When using your own figures, don't forget to add the bundle that contains them in the additional dependencies of you .gmfgen.

Compartments

Let's add a compartment to our Topic node to allow discussion threads to be added. In order to illustrate how to allow nodes within compartments, we will represent Thread items as yellow sticky notes and allow ThreadItem elements to appear as list items within them. So, we will have nodes with a compartment list nested within a parent node compartment. A preview of where we're going is seen to the right. And yes, it's a bit contrived, but it does give us an opportunity to describe a lot of features in one section.

Some of the steps in this section are a bit complex, so the viewlet should prove helpful in getting things right.

Tip : Be careful when working with multiple models, as until there is true refactoring support, you will need to be conscious of changes in definition models and how they will impact referenced models, such as our mapping model. Editing models open in the same resource set will help, so you might consider making changes to your graphical and tooling models from within the open mapping model. Otherwise, you'll receive errors when opening the editors and will need to repair broken references in a text editor.