Skip to content

DOT User Guide

Jump to bottom
Tamas Miklossy edited this page Jul 28, 2018 · 22 revisions

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 DOT component provides the Graphviz DOT authoring environment consisting of the DOT Editor, the DOT Graph View, the Dot Preference Page and the Sync Graphviz Export toggle button to the Eclipse UI. The DOT Editor can be used to edit Graphviz *.dot files, while the DOT Graph View allows to render them in Eclipse using Zest. The Sync Graphviz Export feature uses the Graphviz native executable to export the *.dot files into different image formats such as *.pdf, *.png, *.svg ..., which can be configured on the Dot Preference Page.

The Graphviz DOT authoring environment provides a simple way to visualize *.dot file outputs of any kind of program (e.g. to visualize and debug internal data structures, results, ...etc) running in Eclipse. If a *.dot file in the Eclipse workspace appears or updated, the DOT Graph View and the image export is also updated automatically.

Please note that the DOT Editor and the 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 an Xtext-based textual editor registered for the *.dot files in the Eclipse workbench UI. It provides – amongst others – support for the following features:

  1. Syntax Highlighting: the DOT Editor uses different visual styles (different colors and fonts) for the different dot language elements. The keywords - such as 'graph', 'digraph', 'subgraph', 'node', 'edge' ... - are represented in bold, the dot attribute names appear in blue, their values are shown in brown (or in red if they are quoted), while the embedded single line/multi-line comments are highlighted in green. This kind of text decoration not only makes it easier to distinguish between the different dot language elements but also helps the user to find possible errors within the currently opened dot file: a missing closing double quote or a non-properly closed multi line comment.

  2. Content Assistant - AutoCompletion: the DOT Editor is able to provide suggestions on how to complete the statement/expression the user has just started to type. The content assist functionality can be accessed on any place within the opened dot file using the keyboard shortcut CTRL + SPACE. Depending on the current cursor position, only those language elements will be offered that make sense within the given context: graph attributes names within a graph context, edge attribute names within an edge context and all possible attribute values within a certain attribute context.

  3. Template Proposals: the DOT Editor is capable of inserting complex templates at once with a single content assistant action. For example, the 'Edge Template' can be used to insert a directed/non-directed edge with corresponding placeholder variables for the source and target node.

  4. AutoEditing - AutoInsertion/AutoDeletion: the DOT Editor assist the user to insert some elements automatically e.g. inserting/deleting closing pair elements when the user inserts/deletes the opening ones: closing double quotes, closing parenthesis, closing square brackets, closing curly braces. The auto-indenting functionality also ensures the indentation-awareness of new lines: hitting the ENTER key in a graph definition also indents the cursor in the subsequent line.

  5. Hovering: the DOT Editor is able to provide additional information while hovering over a certain element. E.g. when the user moves the mouse over a color value, a hover popup appears with additional information such as the color preview, the color scheme, the color name and the color code.

  6. Error Checking - Background Validation: the DOT Editor continuously validates the opened dot file while the user is editing, even if the file has not been saved yet. When the editor issues a warning/error, e.g. in case of invalid language elements, it underlines the corresponding part in yellow/red that contains the warning/error. It also puts some warning/error markers with a meaningful message on the left and right side of the editor and also populates the Problems View with all the recognized issues. With such a support the user can easily identify the parts of the dot file that need to be fixed.

  7. Quickfixes: the DOT Editor is – in certain cases – able to automatically fix the problems the user made while editing a dot file. In such cases, the editor offers so called quickfixes to the user. This functionality is available via the warning/error marker or using the keyboard shortcut CTRL + 1 either in the editor or on the corresponding Problems View entry. Applying such a quickfix can for instance replace an invalid dot attribute value by a valid one.

  8. Formatting: the DOT Editor is able to format (aka pretty print) the content of an opened dot file. The formatter can be invoked either via the Source -> Format context menu of the editor or via the keyboard shortcut CTRL + SHIFT + F.

  9. Outline View: the DOT Editor provides an Outline View to help the user navigating through the opened dot file. It provides a hierarchical view of the graph nodes and edges together with their attributes. By default, it represents the elements in the same order as defined in the dot file, but also allows the user to sort them alphabetically. Moreover, the user can choose to synchronize the Outline View selection with the editor selection by switching the 'Link with Editor' mode on, so a selection on an element within the Outline View automatically highlights the corresponding text element in the editor.

  10. Quick Outline View: the DOT Editor also provides a Quick Outline View : the CTRL + O keyboard shortcut opens the Outline View in a popup window. The Quick Outline View also supports searching for elements using wildcard symbols such as * or camel case search.

  11. Folding: the DOT Editor supports collapsing certain parts of the currently opened dot file. This functionality is especially handy for large dot files to hide the unnecessary details, e.g. the attributes belonging to a certain edge. Hovering on a collapsed part still enables the user to take a look at the hidden part without explicitly expanding it.

  12. Hyperlink Navigation: the DOT Editor provides hyperlinking support on the dot elements. You can either CTRL + click or hit F3 e.g. on a source/target node of an edge to navigate to the node definition.

  13. Marking Occurrences: the DOT Editor is able to highlight all occurrences of a certain element in the opened dot file. Once the user selects an element in the text editor via double click while the 'Toggle Mark Occurrences' button is enabled, all occurrences are highlighted with corresponding markers on the right side of the editor. This functionality is useful e.g. to highlight all the edges where a certain node is referred to.

  14. Find References: the DOT Editor is able to locate all references in the entire workspace where a certain element is referred to. Invoking the 'Find References' context menu on the selected element lists all the references in the Search View.

  15. Rename Refactoring: the DOT Editor also provides rename refactoring support of the dot language elements. Invoking the 'Rename Element' context menu on a selected element or using the keyboard shortcut ALT + SHIFT + R triggers the in-place linked editing inclusive validation and preview. The performed action renames the selected element (e.g: a node) together with all the references (e.g: in edges) even across language/file boundaries. The 'Rename Element' action is even undoable via the Edit -> Undo Rename Element submenu or using the keyboard shortcut CTRL + Z.

  16. Adding/Toggling Comments: the DOT Editor accepts single line (starting with the // symbols) and multi-line (surrounded by the /* */ symbols) comments at any place in a dot file. The user can even use the toggle comment keyboard shortcut CTRL + / to comment/uncomment the current line/the currently selected lines in the editor.

  17. TODO/FIXME/XXX statements: the DOT Editor is able to highlighting/recognize special tags (such as TODO, FIXME, XXX) in comments. It places corresponding marker symbols on the left and right side of the editor and populates the Tasks View with all the recognized tags. This functionality assists the user to mark places in a dot file that require more attention. The 'TODO' tag usually marks something for later work, later revision or later reconsideration. The 'FIXME' tag is usually placed near a piece of code that is bogus, broken and needs rework. The 'XXX' tag usually flags something that is bogus but works.

  18. Preferences: the DOT Editor can be customized via the Window -> Preferences -> Dot preference pages. They enable to change the default syntax highlighting styles, to defining additional template proposals ...etc.

  19. Integration with other editors: the DOT Editor is registered as the default editor for the *.dot files and used when the user opens the dot file via double click. However, via the Open With -> Other context menu, a dot file can be opened with other editors: with the 'Sample Ecore Model Editor', with the 'Sample Reflective Ecore Model Editor', ...etc. It is even possible to assign the selected editor as the default one for all the *.dot files.

  20. Sync Graphviz Export: the DOT Editor also provides a Sync Graphviz Export option via the toggle button in the toolbar, which - if enabled - automatically stores an image file (.pdf, .png, ...) into the directory containing the .dot file, and opens it with the associated external image viewer, if one is available.

    The export relies on executing the native Graphviz dot binary, which can be configured under the Windows -> Preferences -> Dot -> Graphviz preference page.

  21. Visualizing the DOT Graph: the DOT Graph View can be opened via the Show In -> DOT Graph context menu of the DOT Editor to visualize the contained DOT graph definition.

DOT Graph View

The DOT Graph View (Window -> Show View -> Other... -> Visualization -> DOT Graph) is able to visualize DOT graphs either contained in *.dot files, embedded in other files, or synched with the .dot file currently being edited in the active DOT Editor. E.g. loading the DOT graph definition

/*
 * sample Graphviz DOT graph
 */
digraph {
	edge[dir=both]
	1
	2 [shape=diamond style=filled fillcolor="/greys3/2" fontcolor="blue"]
	3
	4 [shape=circle xlabel="external node label" style="bold, dashed"]
	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=teeodot]

	2 -> 5 [arrowhead=vee, xlabel="external edge label"]
}

into the DOT Graph View results either in the 'native mode' representation (when the dot executable is configured, it is used for layouting), or in the 'emulated mode' representation (when the dot executable is not configured, the layouting is emulated by using a comparable Layout algorithm).

The DOT Editor is also able to automatically notify the Graph View when the user saves the currently modified dot file. Using the 'Link with DOT Editor' functionality, there is no need to manually trigger the graph visualization to re-render the currently edited dot file within the DOT Graph View.

The DOT Graph View can even be used to visualize DOT graph definitions embedded in other files e.g. in source code comments or in wiki markups:

Back to Home

Clone this wiki locally