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. TransitionEditPart.java . 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.

About these ads

9 thoughts on “gmf knowledge: positioning of external labels

  1. Thanks, this was helpful. Keep it coming.

    Btw for those who look for starting with GMF, I recommend the new Eclipse Ganymede 3.4.0 modeling distribution. It works. Topcased 2 seems to not be able to run my editors made with GMF. It is missing some packages, I suppose.

  2. Thank you for this article! Since GMF still not completely documented (or, at least, is not easy to find all answers in the project wiki), this post was the best resource I found after six hours of trying to set the correct behaviour of the labels in my DSL. Thank you a lot!

    I’d liked a lot your blog (even thinking to return to post on mine after I read it), so please maintain the good work on it! ;-)

    From Ribeirão Preto, Brazil (too).

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s