KIELER Lightweight Diagrams (KLighD) allows you to develop visualizations for data structures quite easily. In this tutorial, we will install Eclipse and all the necessary components to develop KLighD visualizations before moving on to actually develop a visualization of a state machine.

TODO: Add a screenshot of what the outcome of this tutorial will be.

Preliminaries

There's a few things to do before we dive into the tutorial itself. For example, to do Eclipse programming, you will have to get your hands on an Eclipse installation first. Read through the following sections to get ready for the tutorial tasks.

Required Software

For this tutorial, we need you to have Eclipse installed:

Install Eclipse. For what we do, we recommend installing the Eclipse Modeling Tools (not Classic, not Java Developers).
Install the KIELER KGraph Editing and Visualization for this tutorial.
1. Go to Help > Install New Software
2. Use either of our nightly update site at http://rtsys.informatik.uni-kiel.de/~kieler/updatesite/nightly/ or one of the releases.
3. Check KIELER Lightweight Diagrams - Developer Resources & Examples and finish the wizard.

Finding Documentation

During the tutorial, we will cover each topic only briefly, so it is always a good idea to find more information online. Here's some more resources that may prove helpful:

Java™ Platform, Standard Edition 8 API Specification
As Java programmers, you will already know this one, but it's so important and helpful that it's worth repeating. The API documentation contains just about everything you need to know about the API provided by Java.
Eclipse Help System
Eclipse comes with its own help system that contains a wealth of information. You will be spending most of your time in the Platform Plug-in Developer Guide, which contains the following three important sections:
- Programmer's Guide
  When you encounter a new topic, such as SWT or JFace, the Programmer's Guide often contains helpful articles to give you a first overview. Recommended reading.
- References -> API Reference
  One of the two most important parts of the Eclipse Help System, the API Reference contains the Javadoc documentation of all Eclipse framework classes. Extremely helpful.
- References -> Extension Points Reference
  The other of the two most important parts of the Eclipse Help System, the Extension Point Reference lists all extension points of the Eclipse framework along with information about what they are and how to use them. Also extremely helpful.
Eclipsepedia
The official Eclipse Wiki. Contains a wealth of information on Eclipse programming.
Eclipse Resources
Provides forums, tutorials, articles, presentations, etc. on Eclipse and Eclipse-related topics.
Eclipse Layout Kernel
Documentation on how the layout infrastructure works and on how to write your own layout algorithms. This is our project, so if you find that something is unclear or missing, tell us about it!

You will find that despite of all of these resources Eclipse is still not as well commented and documented as we'd like it to be. Finding out how stuff works in the world of Eclipse can thus sometimes be a challenge. However, you are not alone: this also applies to many people who are conveniently connected by something called The Internet. It should go without saying that if all else fails, Google often turns up great tutorials or solutions to problems you may run into. And if it doesn't, your advisers will be happy to help.

As far as KIELER documentation is concerned, you will find documentation at the KIELER Confluence. The documentation is not as complete as we (and especially everyone else) would like it to be, however, so feel free to ask those responsible for help if you have questions that the documentation fails to answer.

Setting Up Your Workspace

Once you have started your (possibly brand new) Eclipse installation, your workspace is completely empty. For this tutorial, however, we need a bit of sample code to work with:

Download the zip file with all our prepared tutorial plugins from our Stash. Unzip the file.
Open the context menu within the Package-Explorer (on the very left, right-click the empty space).
Select Import. Then chose General > Existing Projects into Workspace.
Browse to the location where you unzipped the downloaded plug-ins. Check the checkbox in front of all the de.cau.cs.kieler.tutorials.klighd.* projects and press Finish.

The imported projects contain a meta model for Turing machines. (You may notice that this tutorial thus also slips in a perfect opportunity to brush up on your knowledge of Turing machines. Consider it a public service and thank us later.) It does not model the tape or the head, only its states and transitions. It is these Turing machines that we will develop a visualization for over the course of this tutorial.

Creating a Visualization

Now that we have the model of what we want to visualize, it's time to program the actual visualization. But first, let's take a minute to think about what we need to do here. Take a look at the following diagram:

In our visualization, what we have is an instance of a Turing machine model, and what we want to end up with is a proper diagram that visualizes it. Of course, Lightweight Diagrams has not the slightest clue about what we want our diagrams to look like. That is where the synthesis, highlightes above, comes into play. The synthesis is what transforms an instance of our source model into a KGraph that Lightweight Diagrams knows how to render. (Along the way, KIELER Layout is invoked by KLighD to compute positions for all diagram elements.) However, the KGraph itself does not suffice to render the diagram: it only specifies its structure, but not its appearance. To specify the latter, we also need to augment our KGraph by KRendering information. See its documentation to learn more about what it can do.

Right, let's dive right in and develop our synthesis.

Adding a Visualization Project

Right-click in the Package Explorer and select New -> Other. From the list, select KIELER Lightweight Diagrams -> KLighD Project.
Give your new project a proper name and select the base element of the model you want to visualize. Here's what you should enter here before clicking Finish:

Programming the Visualization

The wizard should have created a new project and opened a file that contains a skeleton synthesis:

/* Package and import statements... */

class TuringMachineDiagramSynthesis extends AbstractDiagramSynthesis<TuringMachine> {
    
    @Inject extension KNodeExtensions
    @Inject extension KEdgeExtensions
    @Inject extension KPortExtensions
    @Inject extension KLabelExtensions
    @Inject extension KRenderingExtensions
    @Inject extension KContainerRenderingExtensions
    @Inject extension KPolylineExtensions
    @Inject extension KColorExtensions
    extension KRenderingFactory = KRenderingFactory.eINSTANCE
    
    
    override KNode transform(TuringMachine model) {
        val root = model.createNode().associateWith(model);
        
        // Your dsl element <-> diagram figure mapping goes here!!
        
        return root;
    }
    
}

Note that this is not Java, but Xtend code. Xtend is a language that compiles to Java and has a bunch of nifty little features that make writing a synthesis easier. The main entry point of our synthesis is the transform method. As you can see, the method gets a TuringMachine instance and returns a KNode. That KNode will contain our actual diagram. Let's start by adding nodes for all states in the Turing machine.

Add a new method to your synthesis that transforms a State into a corresponding KNode:

private def KNode transform(State state) {
    val stateNode = state.createNode().associateWith(state);

    return stateNode;
}

Page tree