Jump to: navigation, search

GEF/GEF4/DOT

< GEF‎ | GEF4

Note to non-wiki readers: This documentation is generated from the Eclipse wiki - if you have corrections or additions it would be awesome if you added them in the original wiki page.

Introduction

The GEF4 DOT component provides support for the Graphviz DOT language, in terms of

  • API to import/export DOT files to/from GEF4 Graph representations (which can be visualized with GEF4 Zest)
  • an Xtext-based DOT file editor
  • support for GraphViz-based generating of PDF-output for DOT files
  • a GEF4 Zest-based DOT Graph Viewer

This component was started as a project in the Google Summer of Code 2009 by Fabian Steeg, mentored by Ian Bull, for Zest. It was initially included in Zest 2 and has finally been migrated to GEF4 DOT, being now based on GEF4 Graph, GEF4 Layout, and GEF4 Zest.

User Documentation

API

Via the API, DOT can be imported to GEF4 Graph graph instances, and GEF4 Graph graph instances can be exported to DOT. To use the API, create a new Plug-in project, add GEF4 DOT and GEF4 Graph to the MANIFEST.MF dependencies, paste the code below into the source folder of the created project, and select Run As > Java Application.

Dot-Export example:

import org.eclipse.gef4.dot.DotExport;
import org.eclipse.gef4.graph.Edge;
import org.eclipse.gef4.graph.Graph;
import org.eclipse.gef4.graph.Graph.Attr;
import org.eclipse.gef4.graph.Node;

public final class DotExportExample {

	public static void main(final String[] args) {
		/* Set up a directed graph with a single connection: */
		Graph.Builder graph = new Graph.Builder();
		Node node1 = new Node.Builder().attr(Attr.Key.ID.toString(), "1")
				.attr(Attr.Key.LABEL.toString(), "Node 1").build();
		Node node2 = new Node.Builder().attr(Attr.Key.ID.toString(), "2")
				.attr(Attr.Key.LABEL.toString(), "Node 2").build();
		Edge edge = new Edge.Builder(node1, node2)
		.attr(Attr.Key.LABEL.toString(), "A dotted edge")
		.attr(Attr.Key.EDGE_STYLE.toString(), Graph.Attr.Value.LINE_DOT)
		.build();
		graph.attr(Graph.Attr.Key.EDGE_STYLE.toString(),
				Graph.Attr.Value.CONNECTIONS_DIRECTED).nodes(node1, node2)
				.edges(edge);

		/* Export the graph to a DOT string or a DOT file: */
		DotExport dotExport = new DotExport(graph.build());
		System.out.println(dotExport.toDotString());
	}

}

Dot-Import example:

import org.eclipse.gef4.dot.DotImport;
import org.eclipse.gef4.graph.Graph;

public final class DotImportExample {

	public static void main(final String[] args) {
		/* We can create Graphs based on GraphViz Dot files/string */
		Graph graph = new DotImport("graph { 1--2 ; 1--3 }").newGraphInstance();
		Graph digraph = new DotImport("digraph { 1->2 ; 1->3 }")
				.newGraphInstance();

		/* We can also import GraphViz Dot files/string into an existing graph */
		Graph.Builder graph2 = new Graph.Builder();
		new DotImport("digraph{1->2}").into(graph2);
		new DotImport("node[label=zested]; 2->3; 2->4").into(graph2); //$NON-NLS-1$
		new DotImport("edge[style=dashed]; 3->5; 4->6").into(graph2); //$NON-NLS-1$
	}

}

The complete sample usage is available in the repository, as well as working DOT input samples.

During import and exports of DOT graphs to/rom GEF4 Graph graphs, the DOT layout specified in the input is mapped to the most suitable GEF4 Layout layout algorithm - e.g. for the following DOT graph:

graph { 1--2--3; 2--4--5 }

If the graph defines a Graphviz layout, it is mapped to a GEF4 Layout layout as below:

graph[layout=dot];

Zest2-dot-zest.png

graph[layout=fdp];

Zest2-fdp-zest.png

graph[layout=twopi];

Zest2-twopi-zest.png

graph[layout=osage];

Zest2-osage-zest.png

GUI

This component adds a DOT editor and a DOT Graph View to the UI:

DotZestViewSelection.png

DOT Graph View

The DOT Graph view can visualize DOT graphs in *.dot files or embedded in other files in the workspace. The view draws the DOT graphs using Zest and allows for image export of the current Zest graph. When automatic updating is enabled (see below), and a *.dot file or embedded DOT content is added to the workspace or altered in an editor, the Zest graph view is updated with the graph created from the DOT input. For instance, consider a file with the .dot extension, containing the following DOT graph definition:

digraph s{ 
 n1[label="Node 1"]; n2[label="Node 2"]; 
 n1 -> n2[style=dotted label="A dotted edge"]
}
 

The view will display:

DotZestGraphView.png

The view contains buttons to toggle automatic updates, to load a specific file containing a DOT graph, and to layout the current graph. To export the current Zest graph as an image file by calling the dot executable, the view contains buttons to re-select the directory containing the dot executable, to enable export of the original DOT input, and to export as an image file (from left to right). When the image export button is selected, a PDF for the current graph is saved in the directory containing the file with the DOT input, and opened with the associated external editor, if one is available. In this example, the export looks like this:

DotZestM2Rendered.png

This provides a Zest-based DOT authoring environment. If a *.dot file or embedded DOT is edited, it will be visualized in the Zest Graph view (e.g. during editing), and can be exported as a PDF with Graphviz.

At the same time the view provides a simple way to visualize *.dot file output of any kind of program, e.g. to visualize and debug internal data structures, results, etc: if a program running in Eclipse outputs any *.dot file in the workspace and the workspace is refreshed, the view will be updated with the corresponding Zest graph (if automatic updating is enabled, see above).

Editing

The Zest view can be used with the included DOT editor to visualize a DOT file:

DotZestEditor.png

Additionally, the Zest view also displays embedded DOT in other files, e.g. in source code comments or in wiki markup:

DotZestWikiText.png

Developer Documentation

Implementation

The import/export functionality is implemented based on Eclipse Modeling technologies, in particular Xtext (part of TMF) for the input part (parse DOT, generate Zest) and JET for the output (see details below).

Implementation of Graphviz DOT input and output for Zest using Eclipse modeling technology

DOT to Graph/Zest

Based on an Xtext grammar, GEF4 DOT interprets the parsed DOT EMF model using the generated Xtext switch API to dynamically create GEF4 Graph graphs. The Dot Graph view uses this to display DOT with GEF4 Zest (see above).

Graph/Zest to DOT

To transform GEF4 Graph graph instances to the Graphviz DOT language GEF4 DOT uses JET.

There are two reasons to use JET instead of Xpand here. First, this allows us to transform any GEF4 Graph graph instance to DOT directly (not only those for which we have a DOT meta model instance that could act as the input to Xpand).

Second, even if we had a DOT meta model instance (which we could create from the GEF4 Graph graph), using Xpand would introduce a runtime dependency on the Modeling Workflow Engine, whereas with JET we only introduce a dependency on a single class (the generator class JET created from the template).