Using yFiles Layout with Eclipse and GEF

Introduction

The yFiles Layout edition does not contain any graphical user interface components. It is suitable for applications with their own graphical user interface. If your application is Eclipse based and dealing with graph like structures, you probably already use the Graphical Editing Framework (GEF). This article contains an example for integrating yFiles Layout into such an application.

The example contains the source code for a procject for the com.yworks.gef.layout Plugin which encapsulates a configurable yFiles layout algorithm as an abstract action implementing org.eclipse.ui.IWorkbenchWindowActionDelegate. Subclasses just have to create and to configure a specific yFiles Layouter. The source code for a second project which uses the layout action is also included. It is a fragment for the GEF Shapes example Plugin which adds a toolbar button for doing an organic layout as an editor action for the GEF Shapes Editor.

Technical Requirements

1. Eclipse 3.4 (Ganymede), 3.5 (Galileo), 3.6 (Helios), 3.7 (Indigo), or 3.8 (Juno) with PDE and the GEF SDK
2. JDK 1.6
3. yFiles for Java Layout 2.6 or newer (or yFiles for Java Complete 2.6 or newer)

Installation Instructions and Usage

1. Extract the attached zip file and copy the y.jar file from your yFiles for Java Layout distribution to the com.yworks.gef.layout directory.
2. Open Eclipse and import the three extracted projects using File >> Import... >> General >> Existing Projects into Workspace, Next >. Push the radio button for "Select root directory:" and use the "Browse..." button to select the parent directory of the unzipped projects. Select "com.yworks.gef.examples.shapes", "com.yworks.gef.layout" and "org.eclipse.gef.examples.shapes" in the "Projects:" list. Optionally check "Copy projects into workspace" and push the "Finish" button.
3. Open the top level fragment.xml file in the com.yworks.gef.examples.shapes project by double clicking it in the Package Explorer. Switch to the "Overview" tab. Run the example using the "Launch an Eclipse application in Debug mode" entry under the "Testing" heading.
4. In the newly opened Eclipse application use the "Go to the workbench" button if necessary and then create a new project, File >> New >> Project... >> General >> Project, Next >. Enter a project name and push the "Finish" button.
5. Open the context menu for your new project and create a new shapes diagram: select New >> Example... >> Examples >> Shapes Diagram, Next >, Finish.
6. Open the diagram, add some shapes and some connections.
7. Use one of the layout toolbar entries to perform a layout. The layout is undoable and animated (currently not for edge bends).

Remarks

1. The new version of the demo also supports bends and ports for edges. Unlike the previous version some changes to the original demo plugin org.eclipse.gef.examples.shapes had to be made. They are documented below.
2. The basic class for performing a yFiles Layouter is the com.yworks.gef.layout.YLayoutProvider. It expects an implementation of the com.yworks.gef.layout.Graph interface as its input and output. The layout provider uses a factory method for creating a specific layouter.
3. The com.yworks.gef.layout.request.GraphicalEditPartGraph is an implementation of the Graph interface, which is initialized with the contents edit part of a graphical editor. It uses the child edit parts of the content edit part as the nodes of the graph and the connection edit parts connected to the nodes as the edges. Changes of the nodes of the graph (via Graph#setNodeBounds) are recorded as resize requests. Changes of the bends and ports of the edges of the graph (via Graph#setPath) are recorded as bendpoint requests.
4. The com.yworks.gef.layout.request.YGraphicalEditorLayouter initializes a GraphicalEditPartGraph for the contents of a given graphical editor, uses a YLayoutProvider to perform the layout, and finally uses the edit policies of the contents edit part to construct a compound command from the accumulated resize requests and bendpoint requests of the graph. This layout command is then added to the command stack of the editor.
5. The com.yworks.gef.layout.request.LayoutAction wraps the YGraphicalEditorLayouter as an org.eclipse.ui.IWorkbenchWindowActionDelegate. Moreover, it adds layout animation.
6. The OrganicLayoutAction, OrthogonalLayoutAction and HierarchicLayoutAction in the package com.yworks.gef.examples.shapes are custom subclasses of the LayoutAction which just implement the factory method of the super class in order create a specific layouter.

   To add another layouter create a LayoutAction and add it to the com.yworks.gef.examples.shapes\fragment.xml file analogously to the other layouters. If the added layouter came with a yFiles for Java version newer than 2.7, it is also necessary to add it to the com.yworks.gef\com.yworks.gef.layout\META-INF\MANIFEST.MF file.

7. If your GEF model does not support dimensions and locations, you can as well use another com.yworks.gef.layout.Graph implementation which directly uses the figures in a view in conjunction with a custom GEF layout manager based on the YLayoutProvider.

Changes to the GEF Shapes Example

In order to use the bends and ports computed by a yFiles layout algorithm, the routing of the edges in the shapes example had to be changed. Moreover, an additional edit policy for the bendpoint requests had to be added to the main edit part. The following is a list of the changed classes in the GEF shapes example. Each change is also indicated by a comment starting with "CHANGE yWorks" in the corresponding source file.

• org.eclipse.gef.examples.shapes.parts.DiagramEditPart
  • Use a bendpoint connection router instead of a shortest path connection router in createFigure() in order to use the bends computed by a yFiles layout action for routing the edges.
• org.eclipse.gef.examples.shapes.parts.ConnectionEditPart
  • added the MyBendpointEditPolicy inner class
  • registered an instance of MyBendpointEditPolicy in createEditPolicies()
  • disabled drawing of target arrows in createFigure() since GEF cannot compute the right direction for the arrows with the bendpoints on the bounding box of the nodes, which we use for realizing ports
• org.eclipse.gef.examples.shapes.parts.ShapeEditPart
  • Always use a chop box anchor in getConnectionAnchor() such that the edges end at the ports computed by a yFiles layout action which are placed on the chop box.