Graphical Views for Xtext ctd.

(Read my previous post for a rationale on graphical views)

No matter with what graphics technology you choose to implement a diagram for your Xtext-based language, there are a few things you should know in order to connect the diagram view/editor to the rest of the infrastructure.

Let us first have a look how to implement a context menu action for the Xtext editor to show the element at the current cursor position in the diagram. In Eclipse, you have to implement a handler for such an action. Xtext offers a bunch of classes making your life easier. EditorUtils detects the Xtext editor for the handler’s action and EObjectAtOffsetHelper finds the semantic model element at a given text offset.

As the document – and thereby the model parsed from it – is subject to editing, you have to make sure nobody is changing it while you traverse it to derive your diagram. You can execute code in a read transaction on the XtextDocument by wrapping it in an IUnitOfWork that you pass to the XtextDocument#readOnly method.

The following snipped shows an example handler written in Xtend.

	class ShowInViewHandler extends AbstractHandler {
	@Inject EObjectAtOffsetHelper eObjectAtOffsetHelper
	override Object execute(ExecutionEvent event)
	throws ExecutionException {
	val editor = EditorUtils.getActiveXtextEditor(event)
	if (editor != null) {
	val selection = editor.selectionProvider.selection
	as ITextSelection
	editor.document.readOnly [
	val selectedElement = eObjectAtOffsetHelper
	.resolveElementAt(it, selection.offset)
	if (selectedElement != null) {
	... // open in view
	}
	]
	}
	return null
	}
	}

view raw Handler.xtend hosted with ❤ by GitHub

Note that the @Inject annotation in the example requires you to use your language's executable extension factory when you register the handler class it in the plugin.xml of your language's UI plug-in. See the Xtext documentation for details.

To navigate from a diagram element back to it’s element definition in the text, you need to store some back reference. The model element itself is not suitable, as its lifecycle is bound to the one of the editor, and the parser is even free to expunge model elements whenever the document is re-parsed. As Xtext is based on EMF, each model element has a unique URI. You should always use these URIs to store references to model elements beyond the boundaries of a read/write transaction. An element’s URI is provided by EMF's EcoreUtil#getURI method.

Having the URI, the navigation to the respective model element’s definition is easiest to implement using Xtext’s IURIEditorOpener. If your diagram view supports selection listeners, the respective Xtend code could look like this:

	@Inject IURIEditorOpener editorOpener
	...
	selectionListener = [ event |
	val selection = event.selection as IStructuredSelection
	if(selection.size == 1) {
	val selectedElement = selection.firstElement
	if(selectedElement instanceof URI)
	editorOpener.open(selectedElement, true)
	}
	]

view raw Opener.xtend hosted with ❤ by GitHub

Graphical Views for Xtext

Xtext provides you with a powerful IDE and a rich featured text editor for your domain-specific language with little effort. But sometimes, a picture says more than a thousand words: You want to have some additional graphical representation of your models, a set of diagrams.

Diagrams are superior to code when it comes to high-level views. But while programmers can easily cope with files that contain several hundred lines of code, the same amount of information usually blows a diagram and destroys all its suggestiveness. Diagrams with just a few nodes and edges showing on a certain aspect of the models only are best fit for human readers. Such aspects are often spread across various model files. So in order to add the best value for the language users on top of an Xtext infrastructure, we need to allow them to create multiple diagrams, each highlighting just a subset of model information, picked from multiple model files. In other words, diagrams that have a completely different structure than their associated textual models.

Traditional graphical editing frameworks focus on editing the underling model through the diagram.
But synchronizing the model changes from textual and diagram editors is very hard if their content's structures differ. In most cases, the integration will lead to major usability quirks like unexpected editor behavior, forced save operations, blocked editors or even data loss.

So rather than working around the hard challenges of integrating graphical and textual model editing, we can leave model modification to Xtext. For the graphical stuff we can concentrate on diagram editing and leave the underlying model read-only. This way we can spend our energy on the things that really matter to the user, like easy and useful ways to populate diagrams or best visual appearance.

In Eclipse, one could build such graphical views using Zest or GEF. If model and diagram do not differ too much in structure, a small code generator targeting GraphViz is a very simple solution with high quality output.

The general integration with Xtext is covered in a follow up post.

The following screencast shows another solution for an Xtext-based domain model language. The graphical editor is using FXDiagram, a diagram framework based on JavaFX. FXDiagram offers a very smooth user experience, excellent rendering, support for touch-pad gestures, animated undo/redo, diagram persistence, export to scalable vector graphics and much more. If you are interested in learning more, feel free to contact me.