Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Info
titlePrerequisites

Before starting the tutorial, make sure that you have an Eclipse installation with the KIELER KGraph Editing and Visualization feature installed.

Expand
titleDetails for KIELER developers...

The feature adds the following plug-ins to your Eclipse installation that are necessary for using KGraph Text:

  • de.cau.cs.kieler.core
  • de.cau.cs.kieler.core.krendering
  • de.cau.cs.kieler.kgraph
  • de.cau.cs.kieler.kgraph.text
  • de.cau.cs.kieler.kgraph.text.ui
  • de.cau.cs.kieler.kiml

It also adds the following plug-ins that visualize KGraphs as you're writing them:

  • de.cau.cs.kieler.core.annotations
  • de.cau.cs.kieler.core.ui
  • de.cau.cs.kieler.core.kivi
  • de.cau.cs.kieler.core.model
  • de.cau.cs.kieler.kiml.service
  • de.cau.cs.kieler.kiml.ui
  • de.cau.cs.kieler.klighd
  • de.cau.cs.kieler.klighd.piccolo
  • de.cau.cs.kieler.klighd.xtext
  • de.cau.cs.kieler.krendering.extensions
  • edu.umd.cs.piccolo
  1. Make sure that a KLighD view will be created for you once you start editing a KGT file. Open the Eclipse preferences and navigate to the KIELER View Management page. Make sure that Graphical representations of textually formulated KGraphs is checked.
  2. Create an empty project in your Eclipse workspace. Right-click the project and select New -> Other... In the dialog that pops up, select Empty KGraph from the KGraph category. Give the new file a proper name and click Finish to create it.
  3. Open the new file. The KGraph editor should open, as should a KLighD view. Both should be empty.
  4. Start by adding a few nodes. Enter the following text into the editor:

    Code Block
    titleThree nodes
    linenumberstrue
    knode node1 {
        size: width=100 height=100
    }

    The KLighD view should update itself and show a rectangle that represents the node. Add two other nodes, node2 and node3, to the graph.

  5. Let's add connection points to the nodes. Add two ports to node1 by adding the following text under the size specification of the node:

    Code Block
    titleNodes with ports
    linenumberstrue
    kport port1_1 {
        size: width=10 height=10
    }
    
    kport port1_2 {
        size: width=10 height=10
    }
    

    One of the nodes in the KLighD view should now have black ports in the top left corner. This is of course not where we want the ports to end up, so we will have to tell the layout algorithm to place them wherever it's most convenient. The corresponding layout option is called port constraints. Add the following two lines under the size specification of node1 to set the proper constraints on it:

    Code Block
    titlePort constraints
    linenumberstrue
        properties:
            de.cau.cs.kieler.portConstraints=FREE 
    Info
    titleHint

    The KGT editor has auto completion that you can trigger by pressing Ctrl+Space. The list that pops up shows you everything that can be added at the current cursor position. This is especially handy when it comes to property IDs and possible property values.


    The KLighD view should be updated again and place all ports on the left side of their node. Add two ports, port2_1 and port2_2, to node2. Also, add a port port3_1 to node3.

  6. It's now time to connect the nodes. Add two edges to the graph that originate at node1 by adding the following lines under the port definitions of node1:

    Code Block
    titleEdges
    linenumberstrue
    kedge (:port1_2 -> node2:port2_1)
    kedge (:port1_1 -> node3:port3_1) 

    Edges can start and end at a node or at a port. The source node does not need to be explicitly specified since it is clear from the context (the edges are defined in the body of the source node, after all). The target needs the node to be specified, with an optional target port. Add another edge that starts at port2_2 and ends at port3_1. By now, the KLighD view should show something like this:

  7. One of the problems here is that it is not immediately clear from the drawing which rectangle belongs to which node. This can easily be remedied by adding labels. Start by adding a label to the first node:

    Code Block
    titleLabels
    linenumberstrue
    klabel "Node 1"

    In the same way, add labels to the other nodes. You will notice that the placement of the labels is not very good. Add the following line to the properties section of each node:

    Code Block
    titleLabel placement
    linenumberstrue
    de.cau.cs.kieler.nodeLabelPlacement="INSIDE H_LEFT V_TOP"

    This will place the labels at the top left corner inside each node. Of course, there are other possible placements you can experiment with. Note that while the value of the port constraints option above could be simply written as FREE, the value of this option needs to be put in quotation marks. This is because this option's value is actually a set of values.

    Tip
    titleTry this

    Labels can also be added to ports and are then properly placed by the layout algorithm as well...

  8. Let's add a final touch to the graph. Currently, the edges are routed as polylines with slanted edge segments. If we want to change that, we need to tell the layout algorithm to use another edge routing algorithm. Add a new properties section to the beginning of the file:

    Code Block
    titleEdge Routing
    linenumberstrue
    properties:
        de.cau.cs.kieler.edgeRouting=ORTHOGONAL

    Your result could look something like this:

...