gmf knowledge: positioning of external labels

This post is the first in a series of posts where I write down what I have found out about the Eclipse Graphical Modeling Framework (GMF) by hard work, deep digging in the web and trial-and-error. These posts are meant to complement the existing documentation of GMF. I hope that this knowledge helps others in solving their problems faster than me.

This post (or say tutorial if you like) treats the definition and positioning of external labels of nodes and arcs (or connections) in a GMF diagram. For the rest of this post we assume that you are familiar with the basic GMF workflow of deriving an editor from an .ecore file. If not, you should start with the official GMF Tutorial first and come back when you are done.

1. First you need a node class and an arc class in your Ecore meta model, each having a property which you would like to display as a label of this node.

A node and an arc class with two properties.

We define two classes Node and Arc. We are not concerned with the references between these classes here. They could be completely unrelated for the purpose of defining a label. We will use attribute name of class Node and attribute weight of class Arc as properties we want to display as labels. A sample attribute specification could be the following.

Properties specification of attribute \

2. Next you need an appropriate graphics definition. Open your .gmfgraph file. I assume you defined a Figure Descriptor for your node or Arc. For an external node label, create a new Figure Descriptor, e.g. NodeNameFigure that only contains a Label, e.g. NodeNameLabel, and a Child Access to this label. We have to create this separate Figure Descriptor to make sure that our label is not internal to the graphics of our node. To label an arc (a connection), just add a Label and a Child Access to the corresponding Figure Descriptor of the Arc, e.g. ArcFigure.

Figure Descriptor definitions for the labels

Now we need to declare the labels themselves. Create a Diagram Label for the node, e.g. nodeName and set its Figure to the Figure Descriptor for the label that you’ve just created, e.g. NodeNameFigure. Done. This automatically makes this label an external label.

Diagram Label definition for an external label

For the arc’s label also create a Diagram Label, e.g. arcWeight in our case; set its Figure to the Figure Descriptor of the arc’s figure, e.g. ArcFigure and set the Accessor to the corresponding Child Accessor, e.g. getFigureWeight. To control the distance of the label of the arc’s label to the arc, add a Label Offset Facet. Set its attributes X and Y to the distance you would like the label have from its arc. Done.

Diagram Label definition for the label of a connection

3. Now comes the mapping of graphics to the meta model. Open your .gmfmap file of your project. The relation between the graphics and meta model is defined by Feature Label Mappings. Again I assume that you’ve already defined Node Mappings and Link Mappings for your classes, we now add their labels.

For the node, find the corresponding Node Mapping. In our example this a node mapping for a Transition class which specializes the earlier Node class. Hence the Transition class also has the name attribute. At the Node Mapping, add a Feature Label Mapping and set the following properties: Diagram Label is the one you’ve just defined for your node class, e.g. nodeName. In Features choose the class attributes you want to display in the label, one attibute is suffcient; in our case this is name. Done.

Feature Label Mapping definition of an external label

For the arc, find the corresping Link Mapping, again in our example we specialized class Arc to class ArcToPlace; hence it also has the weight attribute. To add the label, add a Feature Label Mapping and set the corresponding properties, this time use the label defined for the arc.

Feature Label Mapping definition for a label of an arc.

4. Create the .gmfgen file. You can now refine the positioning of the arc label. Locate it in the tree. It will be in Gen Diagram <YourDiagram> / Gen Link <YourLink>EditPart / Gen Link Label <YourLink><Attribute>EditPart. Its sub-features control the distance of the label to the link (that you’ve just set above). The property Diagram Label / Alignment of the Gen Link Label allows you to specify where the label shall be positioned along the link (beginning, middle, end).

Gen Link Label definition of an arc label

Unfortunately, such a refined definition is not available for external labels of nodes. You have to do this in the source code (see below).

5. Generate the source code. Your arc label is now fine, but you can fine touch your node label, specifically the distiance of the external node label to its node. Open the Edit Part source file of your node in <your-package>.diagram.edit.part, e.g. . Now locate the method addBorderItem() in this class. It is responsible for registering the external label within a certain distance at your node’s graphics. The statement
locator.setBorderItemOffset(new Dimension(-20, -20));
borderItemContainer.add(borderItemEditPart.getFigure(), locator);

specifies the distance of your label. Replace (-20,-20) by the values you like. I prefer (-5,-5) for a close distance.

That’s it. Run your editor and enjoy your labels.