Chapter 12. Graphical Modeling Framework FAQs

Graphical Modeling Framework (GMF) is such an extensive framework and tooling infrastructure that many questions often appear on the newsgroup. Some have been collected into FAQ content on the GMF wiki pages, but here you find a collection of the most commonly asked questions about how to use GMF. Where possible, the answer references information within the book and its sample projects.

12.1 General FAQs

The FAQs in this section relate to general topics on GMF, the project.

How do I get started with GMF?

Aside from reading this book, you can find a number of wiki pages at http://wiki.eclipse.org/Graphical_Modeling_Framework that contain information on a wide range of GMF topics. Many tutorials on both the tooling side of GMF and its runtime have been posted, along with FAQs, new and noteworthy documents, and more.

What advantages does GMF offer over Graphical Editing Framework (GEF)?

GMF simplifies the integration of EMF as the underlying model for a GEF diagram. With that, it provides a separate notation model that is used to segregate the domain from diagram information. A number of services, extension-points, and APIs are provided with GMF to make developing diagrams easier than if you had started with GEF alone. Add to this the capability to define diagrams using a series of models and generate a large portion of the diagram code using the GMF tooling Software Development Kit (SDK). You can find discussions on the differences between GEF and GMF throughout Chapter 9, “Graphical Editing Framework”; Chapter 10, “Graphical Modeling Framework Runtime”; and Chapter 11, “Graphical Modeling Framework Tooling.”

What are the prerequisites for GMF?

GMF depends on GEF, Eclipse Modeling Framework (EMF), the EMF Transaction and Validation components, Model Development Tools Object Constraint Language (MDT OCL), and, when working with Scalable Vector Graphics (SVG) figure support, Apache Batik and Xerces. Furthermore, the Eclipse Packaging Project and Modeling Amalgam projects provide downloads that include GMF and all its dependencies.

How can I contribute to GMF?

Okay, so this isn’t a frequently asked question—but since it’s here…. The best way to contribute to GMF or any Eclipse project is to interact with project Committers in the newsgroup and, after reaching an agreement, apply a patch to a Bugzilla item. All contributions must go through Bugzilla, must be in the format of a CVS patch, and should have unit tests associated with the functionality or fix.

12.2 Diagramming FAQs

The FAQs in this section relate to figures—how to change them dynamically, alter their properties, and so on.

How do I change the figure of an existing element dynamically?

You can change the figure of an EditPart by configuring requests and executing commands to first remove the existing view element and add the new one; you must save the location information so that the new element is positioned properly. This is done within the UML2 Tools project. A different approach relies on the underlying diagram refresh method and layout invocation in Section 4.3.3, “Subtopic Figure.” Yet another approach is to use the runtime’s extensibility features, as illustrated in the scenario diagram customization of Section 10.9.1, “Scenario Diagram Custom View and Edit Providers.”

How can I change a figure’s appearance based on a preference change?

The basic process involves adding a PreferencePropertyChangeListener to the EditPart by overriding the addNotationalListeners() method and invoking the change on the corresponding figure when the corresponding PropertyChangeEvent is sent. Section 4.6.6, “Color Preferences,” outlines an example of this.

How can I change a property of a figure when a domain property changes?

The most straightforward approach is to override the handleNotificationEvent() method in the EditPart and determine whether the change was on the domain property of interest. If so, update the corresponding figure accordingly. Section 4.3.3, “Subtopic Figure,” gives an example of a domain change being detected to invoke diagram layout.

How can I make my figure nonresizable?

Using code, you install a NonResizeableEditPolicy for the EditPolicy.LAYOUT_ROLE. To accomplish this in the definition model, set the Resize Constraint of the Node element to NONE and provide a Default Size Facet, as illustrated in Section 4.5.5, “Gateways.”

What does canonical mean in the context of GMF?

In terms of the runtime, canonical refers to the capability of a container to maintain its children views in synchronization with their underlying domain elements. For example, consider a compartment within a Class element in a UML diagram. New elements added to the underlying domain model are synchronized with the compartment view automatically. In this case, the compartment is a canonical container and keeps track of changes to its children.

Why can’t I see elements I place on the diagram?

This can happen when you use certain versions of Linux that might not have the Cairo graphics library installed or that have Windows 2000 without the GDI+ library. The selection border for elements typically is shown, so try using Select All (Ctrl+A) to verify this. If this is your issue, install the missing libraries. You can also disable anti-aliasing for the diagram to resolve the problem; this option is available in the preferences of your diagram.

12.3 Tooling FAQs

The FAQs in this section relate to using the GMF Tooling models for diagram generation.

How do I modify the output of the generation templates?

You can modify the templates for both figure generation and diagram code using the extensibility options provided by the underlying Xpand model-to-text framework. This book explores each of these techniques. See Section 4.2.2, “Customization Options,” for a general overview and Sections 4.6.5, “Gradient Figures,” and Sections 4.6.6, “Color Preferences,” for specific examples.

Do I have to use the tooling component to use GMF?

No. As described in Section 10.8, “Developing a Diagram,” you can develop a diagram manually using the provided extension-points and APIs. Using the tooling to get started is generally recommended because you can generate a lot of the code you need to write from its models.

How can I include a diagram as one page in a multipage editor?

The process for doing this is currently long and involved, although it eventually might become easier if the generation of both EMF and GMF is modified to facilitate this common request. You can refer to an Eclipse Corner article on this topic (see Section 4.4.4, “Integrating EMF and GMF Editors”).

How can I get nodes to stick to the border of a parent?

In the Node element of the graphical definition model, set the Affixed Parent Side property to something other than NONE. Based on the Node mapping for the parent, or the domain element that has a containment reference that holds instances of the child, the generated EditPart has a BorderItemSelectionEditPolicy installed for its EditPolicy.LAYOUT_ROLE. Section 4.5.5, “Requirement to Scenario Partition,” illustrates this.

Why does GMF have its own version of Xpand?

Historically, GMF adopted Xpand to replace Java Emitter Templates (JET) as the primary template engine, but Xpand had some IP cleanliness issues. The GMF team refactored Xpand to use the LALR Parser Generator (LPG) parser generator, in addition to some other enhancements. Currently, additional refactoring is underway to replace Xtend with Object Constraint Language (OCL)/QVT Operational (QVTO), so this variant of Xpand likely will migrate to the Model-to-Text Transformation (M2T) project as a distinct, though similar, alternative to the original Xpand. Furthermore, the Xpand team is working to implement its next version, based on Xtext.

12.4 Summary

In this chapter, we look into some typical FAQs about the GMF runtime and tooling. While not exhaustive, many other FAQs can be found on the project website.