Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "GEF/GEF4/DOT/User Guide"

< GEF‎ | GEF4‎ | DOT
(DOT Editor)
 
(6 intermediate revisions by 2 users not shown)
Line 4: Line 4:
  
 
=== Introduction ===
 
=== Introduction ===
The [[GEF/GEF4/DOT| GEF4 DOT]] component adds a DOT editor and a ''DOT Graph'' view to the UI. The DOT editor can be used to edit [http://www.graphviz.org Graphviz] *.dot files, while the DOT Graph view allows to render them within Eclipse using [[GEF/GEF4/Zest | GEF4 Zest]], as well as to export them into different image formats (such as PDF, PNG, ...) using the [http://www.graphviz.org/ Graphviz] native executable.  
+
The [[GEF/GEF4/DOT| GEF4 DOT]] component adds a ''DOT Editor'' and a ''DOT Graph View'', as well as a ''Dot'' preference page and a 'Sync Graphviz Export' toggle button to the UI. The ''DOT Editor'' can be used to edit [http://www.graphviz.org Graphviz] *.dot files, while the ''DOT Graph View'' allows to render them within Eclipse using [[GEF/GEF4/Zest | GEF4 Zest]]. The additional ''Sync Graphviz Export'' feature that is related to the ''DOT Editor'' (provided via a toggle button in the main toolbar) further allows to export them into different image formats (such as PDF, PNG, ...) using the [http://www.graphviz.org/ Graphviz] native executable.  
  
<small>Please note that the DOT editor and the [[GEF/GEF4/Zest | GEF4 Zest]]-based rendering of the DOT Graph view are currently still limited to support only a subset of the DOT language (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=454629 #454629], [https://bugs.eclipse.org/bugs/show_bug.cgi?id=321775 #321775], and [https://bugs.eclipse.org/bugs/show_bug.cgi?id=441352 #441352] for details).</small>
+
In combination, the ''DOT Editor'', ''DOT Graph View'', and the ''Sync Graphviz Export'' feature, provide a [[GEF/GEF4/Zest|GEF4 Zest]]-based [http://www.graphviz.org Graphviz] DOT authoring environment. If a *.dot file or embedded DOT is edited, it can be visualized in the ''DOT Graph View'', and/or can be exported as a PDF or image by using the ''Sync Graphviz Export''. At the same time the ''DOT Graph View'' and ''Sync Graphviz Export'' provide 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 ''DOT Graph View'' and the export will be updated accordingly.
  
=== DOT editor ===
+
<small>Please note that the ''DOT Editor'' and the [[GEF/GEF4/Zest | GEF4 Zest]]-based rendering of the ''DOT Graph View'' are currently still limited to support only a subset of the DOT language (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=454629 #454629], [https://bugs.eclipse.org/bugs/show_bug.cgi?id=321775 #321775], and [https://bugs.eclipse.org/bugs/show_bug.cgi?id=441352 #441352] for details).</small>
  
The DOT editor is registered for *.dot files within the Eclipse Workbench UI. It is based on [https://www.eclipse.org/Xtext/ Xtext] and thus provides support for syntax coloring, content assist, and integrated validation, as well as a customized Outline view integration.
+
=== DOT Editor ===
  
[[Image:DotEditor.png|892px]]
+
The ''DOT Editor'' is registered for *.dot files within the Eclipse Workbench UI. It is based on [https://www.eclipse.org/Xtext/ Xtext] and thus provides support for syntax coloring, content assist, and integrated validation, as well as a customized Outline view integration.
 +
 
 +
[[Image:DotEditor.png]]
  
 
The editor validates the currently edited .dot file on the fly and issues warnings/errors e.g in case of using deprecated/invalid dot language elements:
 
The editor validates the currently edited .dot file on the fly and issues warnings/errors e.g in case of using deprecated/invalid dot language elements:
Line 19: Line 21:
 
[[Image:dot_editor_error_detection.png]]
 
[[Image:dot_editor_error_detection.png]]
  
The editor also provides a 'Sync Graphviz Export' option (toggle button in the toolbar; using the default Graphviz icon), which - if enabled - automatically stores an image file (.pdf, .png, ...) representing the saved state of the edited .dot file to the directory containing the .dot file, and opens it with the associated external image viewer, if one is available. In this example, the export looks like this:
+
The editor also provides a ''Sync Graphviz Export'' option (toggle button in the toolbar; using the default Graphviz icon), which - if enabled - automatically stores an image file (.pdf, .png, ...) representing the saved state of the edited .dot file to the directory containing the .dot file, and opens it with the associated external image viewer, if one is available. In this example, the export looks like this:
  
 
[[Image:DotZestM2Rendered.png|150px]]
 
[[Image:DotZestM2Rendered.png|150px]]
Line 28: Line 30:
 
[[Image:Graphviz_preference_page2.png|600px]]
 
[[Image:Graphviz_preference_page2.png|600px]]
  
=== DOT Graph view ===
+
=== 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 ''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 [[GEF/GEF4/Zest | GEF4 Zest]] and allows exporting the currently visualized Zest graph into different image formats (such as PDF, PNG, ...) based on the [http://www.graphviz.org/ Graphviz] executable.  
+
  
 
For instance, consider a file with the .dot extension, containing the following DOT graph definition:  
 
For instance, consider a file with the .dot extension, containing the following DOT graph definition:  
  
  digraph s{  
+
  digraph {
  n1[label="Node 1"]; n2[label="Node 2"];  
+
    edge[dir="both"]
  n1 -> n2[style=dotted label="A dotted edge"]
+
    1;
 +
    2 [shape="diamond"];
 +
    3
 +
    4 [shape="circle", xlabel="external node label"];
 +
    5 [shape=box, label="internal node label"];
 +
    1 -> 2 [style=dashed, headlabel="head label", taillabel="tail label"]
 +
    3 -> 2 [style=dotted, label="edge label"]
 +
    2 -> 4 [arrowtail="box"]
 +
    4 -> 5 [arrowhead="tee"]
 +
    2 -> 5 [arrowhead = "open", xlabel="external edge label"]
 
  }
 
  }
  
Loading it in the DOT Graph view will result either in the following representation on the left side in ''''native mode'''' (when the dot executable is configured, it is used for layouting), or in the following representation on the right side in ''''emulated mode'''' (when the dot executable is not configured, the layouting is emulated with GEF4 Layout algorithms).
+
Loading it in the view will result either in the following representation on the left side in ''''native mode'''' (when the dot executable is configured, it is used for layouting), or in the following representation on the right side in ''''emulated mode'''' (when the dot executable is not configured, the layouting is emulated by using a comparable [[GEF/GEF4/Layout | GEF4 Layout]] algorithm).
  
[[Image:DOT Graph view native.jpg|540px]]
+
[[Image:DOT Graph view native.jpg|550px]]
[[Image:DOT Graph view emulated.jpg|500px]]
+
[[Image:DOT Graph view emulated.jpg|540px]]
  
The DOT Graph view can be linked with the DOT editor to visualize the saved state of the currently edited .dot file (Link with DOT Editor).
+
The view can be linked with the ''DOT Editor'' to visualize the saved state of the currently edited .dot file through the 'Link with DOT Editor' toggle button in the view's toolbar:
The visualized graph in ''''native mode'''':
+
  
 
[[Image:tree_native.png|1000px]]
 
[[Image:tree_native.png|1000px]]
Line 54: Line 62:
  
 
[[Image:embedded_emulated.png|600px]]
 
[[Image:embedded_emulated.png|600px]]
 
This provides a [[GEF/GEF4/Zest|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.
 

Latest revision as of 09:15, 27 May 2016

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 adds a DOT Editor and a DOT Graph View, as well as a Dot preference page and a 'Sync Graphviz Export' toggle button 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. The additional Sync Graphviz Export feature that is related to the DOT Editor (provided via a toggle button in the main toolbar) further allows to export them into different image formats (such as PDF, PNG, ...) using the Graphviz native executable.

In combination, the DOT Editor, DOT Graph View, and the Sync Graphviz Export feature, provide a GEF4 Zest-based Graphviz DOT authoring environment. If a *.dot file or embedded DOT is edited, it can be visualized in the DOT Graph View, and/or can be exported as a PDF or image by using the Sync Graphviz Export. At the same time the DOT Graph View and Sync Graphviz Export provide 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 DOT Graph View and the export will be updated accordingly.

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.

DotEditor.png

The editor validates the currently edited .dot file on the fly and issues warnings/errors e.g in case of using deprecated/invalid dot language elements:

Dot editor warning detection.png Dot editor error detection.png

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

DotZestM2Rendered.png

The export relies on executing the native Graphviz dot binary, which can be configured under 'Windows -> Preferences -> Dot -> Graphviz' preference page. The following two screenshots represent the Graphviz preference page before/after the path to the dot executable is defined.

Graphviz preference page1.png Graphviz preference page2.png

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.

For instance, consider a file with the .dot extension, containing the following DOT graph definition:

digraph {
    edge[dir="both"]
    1;
    2 [shape="diamond"];
    3 
    4 [shape="circle", xlabel="external node label"];
    5 [shape=box, label="internal node label"];
    1 -> 2 [style=dashed, headlabel="head label", taillabel="tail label"]
    3 -> 2 [style=dotted, label="edge label"]
    2 -> 4 [arrowtail="box"]
    4 -> 5 [arrowhead="tee"]
    2 -> 5 [arrowhead = "open", xlabel="external edge label"]
}

Loading it in the view will result either in the following representation on the left side in 'native mode' (when the dot executable is configured, it is used for layouting), or in the following representation on the right side in 'emulated mode' (when the dot executable is not configured, the layouting is emulated by using a comparable GEF4 Layout algorithm).

DOT Graph view native.jpg DOT Graph view emulated.jpg

The view can be linked with the DOT Editor to visualize the saved state of the currently edited .dot file through the 'Link with DOT Editor' toggle button in the view's toolbar:

Tree native.png

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

Embedded emulated.png

Back to the top