Via the API, DOT can be imported to Zest graph instances, and Zest graph instances can be exported to DOT.

Via the API, DOT can be imported to Zest graph instances, and Zest graph instances can be exported to DOT.

−

To use the API, create a new Plug-in project, add ''org.eclipse.zest.dot.core'' to the MANIFEST.MF dependencies, paste the code below into the source folder of the created project, and select ''Run As > Java Application'':

+

To use the API, create a new Plug-in project, add ''org.eclipse.gef4.zest.dot.core'' to the MANIFEST.MF dependencies, paste the code below into the source folder of the created project, and select ''Run As > Java Application'':

import org.eclipse.swt.SWT;

import org.eclipse.swt.SWT;

Line 58:

Line 58:

import org.eclipse.swt.widgets.Display;

import org.eclipse.swt.widgets.Display;

import org.eclipse.swt.widgets.Shell;

import org.eclipse.swt.widgets.Shell;

−

import org.eclipse.zest.dot.DotGraph;

+

import org.eclipse.gef4.zest.dot.DotGraph;

public class SampleUsage {

public class SampleUsage {

Revision as of 15:29, 21 August 2013

Graphviz DOT as a DSL for Zest

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

This Eclipse feature provides support for the GraphvizDOT language in Zest: The Eclipse Visualization Toolkit, both as an input and output format. It provides API und UI elements to transform both DOT graphs to Zest visualizations (to be used in Java SWT applications), and Zest visualizations to DOT graphs (to be rendered as image files with Graphviz).

User Documentation

Installation

GUI

This feature adds a DOT editor and a Zest graph view to the UI:

Zest Graph View

The Zest 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:

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:

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:

API

Via the API, DOT can be imported to Zest graph instances, and Zest graph instances can be exported to DOT.

To use the API, create a new Plug-in project, add org.eclipse.gef4.zest.dot.core to the MANIFEST.MF dependencies, paste the code below into the source folder of the created project, and select Run As > Java Application:

Developer Documentation

The goal of this feature is to implement the GraphvizDOT language as a domain-specific language (DSL) for Zest: The Eclipse Visualization Toolkit, both as an input and output format. In other words, the goal is to transform both DOT graphs to Zest visualizations (to be used in Java SWT applications), and Zest visualizations to DOT graphs (to be rendered as image files with Graphviz).

Resources

Bundles and dependencies

The main bug for this feature is bug 277380. View a complete list of related bugs. If you have suggestions for this feature you can file a new bug. The code for this feature is part of the Zest 2.0 Git repository. The dot4zest bundles are named org.eclipse.zest.dot.*. See the general instructions for setting up Zest 2.0.

After changes to the Xtext grammar, run (Run As -> MWE2 workflow) the GenerateDot.mwe2 in the /src/org/eclipse/zest/internal/dot/parser folder of the core bundle. Make sure to set the project or workspace encoding to UTF-8.

Run the All*.java test suites of the test bundle (org.eclipse.zest.tests) as JUnit or JUnit Pug-in tests to get an impression of the current implementation state. To use the UI components, run an Eclipse application configured with org.eclipse.zest.dot.ui and required plugins. See details on usage in the user documentation above.

Motivation

Graphviz is a very popular tool and its DOT language is widely used. Support for it could make using Zest very easy for many people who are familiar with DOT.

On the output side, Zest can benefit from Graphviz output as it provides a way to produce high-quality export into different file formats, e.g. for printing Zest visualizations, or using them in digital publications.

Implementation

The dot4zest 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 Zest

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

Zest to DOT

There are two reasons to use JET instead of Xpand here. First, this allows us to transform any Zest 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 Zest 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).

Future Ideas

Add support for different Graphviz shapes through Zest custom figures, e.g. for UML class diagrams

Add support to visualize Graphviz subgraphs as separate Zest graphs that can be accessed from the main graph

Add animation support using something like subgraph cluster_animation_1 { label = "Step 1"; 1->2 } etc., where animation steps are represented as subgraphs in the DOT input (which if rendered with Graphviz results in a static description of the animation)

For instance, for the input below a Zest animation could be created that changes like this (this is an experimental illustation of the idea):

The same input file, exported with Graphviz, shows the animation steps as subgraphs:

A possible use case for defining such animations with DOT is to easily create animated documentation, e.g. to explain data structures. The same file defining the animation could be used to export a PDF illustrating the steps in a static way.