Difference between revisions of "GEF/GEF4/DOT"

Revision as of 09:57, 22 November 2015

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 Graphviz DOT, in terms of

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

It is internally decomposed into two modules, namely DOT and DOT.UI. There are also a couple of undeployed DOT Examples.

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

This component adds a DOT editor and a DOT Graph view to the UI. The DOT editor can be used to edit Graphviz *.dot files, while the DOT Graph view allows to render them within Eclipse using GEF4 Zest, as well as to export them as PDF using the Graphviz native executable.

Please note that the DOT editor and the GEF4 Zest-based rendering of the DOT Graph view are currently still limited to support only a subset of the DOT language (see #454629, #321775, and #441352 for details).

DOT editor

The DOT editor is registered for *.dot files within the Eclipse Workbench UI. It is based on Xtext and thus provides support for syntax coloring, content assist, and integrated validation, as well as a customized Outline view integration.

The editor also provides a 'Sync Graphviz Export (PDF)' option (toggle button in the toolbar; using the default printer icon), which - if enabled - automatically stores a PDF file representing the saved state of the edited .dot file to the directory containing the .dot file, and opens it with the associated external PDF viewer, if one is available. The export relies on executing the native Graphviz dot binary. In this example, the export looks like this:

DOT Graph view

The DOT Graph view ('Window -> Show View -> Other... -> Visualization -> DOT Graph') can be used to visualize DOT graphs contained in *.dot files or embedded in other files, which are either explicitly loaded from the workspace, or synched with the .dot file currently being edited in the active DOT editor.

The view draws the DOT graphs using GEF4 Zest and allows for PDF export of the currently visualized Zest graph (based on the Graphviz executable).

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"]
}

Loading it in the DOT Graph view will result in the following:

The DOT Graph view can be linked with the DOT editor to visualize the saved state of the currently edited .dot file (link mode):

It can further be used to display embedded DOT in other files, e.g. in source code comments or in wiki markup:

This provides a GEF4 Zest-based DOT authoring environment. If a *.dot file or embedded DOT is edited, it will be visualized in the DOT Graph view, 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.

DOT

• feature: org.eclipse.gef4.dot
• bundle: org.eclipse.gef4.dot

The DOT module of GEF4 DOT provides support for importing (DotImport) and exporting (DotExport) Graphviz DOT to/from a GEF4 Graph-based model. The GEF4 Graph-based model uses Graphviz specific properties, which are defined in DotProperties.

{Root}

• package: org.eclipse.gef4.dot

The {Root} package provides an importer (DotImport) and exporter (DotExport) between a Graphviz DOT and a related GEF4 Graph representation. The imported or to be exported graph has to make use of the properties defined in DotProperties.

DotImport

DotImport provides support for importing a Graphviz DOT into a GEF4 Graph data model, using the properties defined in DotProperties.

/* We can create Graphs based on Graphviz Dot files and strings */
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);
new DotImport("edge[style=dashed]; 3->5; 4->6").into(graph2);

The complete sample usage is available in the repository, more input samples can be found here.

Internally, DotImport is based on an Xtext-based parser. It uses the generated Xtext switch API to dynamically create GEF4 Graph graphs from the DOT abstract syntax tree (represented as an EMF model).

DotExport

DotExport can be used to serialize a GEF4 Graph-model, which uses the properties defined in DotProperties to a Graphviz DOT as follows:

/* Create a directed graph, making use of DotProperties */
Graph.Builder graph = new Graph.Builder();
Node node1 = new Node.Builder().attr(DotProperties.NODE_ID, "1").attr(DotProperties.NODE_LABEL, "Node 1").build();
Node node2 = new Node.Builder().attr(DotProperties.NODE_ID, "2").attr(DotProperties.NODE_LABEL, "Node 2").build();
Edge edge = new Edge.Builder(node1, node2).attr(DotProperties.EDGE_LABEL, "A dotted edge").attr(DotProperties.EDGE_STYLE, DotProperties.EDGE_STYLE_DOTTED).build();
graph.attr(DotProperties.GRAPH_TYPE, DotProperties.GRAPH_TYPE_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());

Internally, DotExport is based on JET to keep its runtime dependencies minimal.

DotProperties

DotProperties defines the (currently) supported Graphviz attributes.

DOT.UI

• feature: org.eclipse.gef4.dot.ui
• bundle: org.eclipse.gef4.dot.ui

The DOT.UI module of GEF4 DOT realizes the DOT editor as well as the DOT Graph viewer as end-user features. It does not provide any public API.