Page History
...
- 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.
- 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.
- Open the new file. The KGraph editor should open, as should a KLighD view. Both should be empty.
Start by adding a few nodes. Enter the following text into the editor:
Code Block title Three nodes linenumbers true 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
andnode3
, to the graph.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 title Nodes with ports linenumbers true 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 title Port constraints linenumbers true properties: de.cau.cs.kieler.portConstraints=FREE
Info title Hint 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
andport2_2
, tonode2
. Also, add a portport3_1
tonode3
.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 ofnode1
:Code Block title Edges linenumbers true 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 atport3_1
. By now, the KLighD view should show something like this: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 title Labels linenumbers true 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 title Label placement linenumbers true 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.Infotip title Something to Try this Labels can also be added to ports and are then properly placed by the layout algorithm as well...
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 title Edge Routing linenumbers true properties: de.cau.cs.kieler.edgeRouting=ORTHOGONAL
Your result could look something like this:
...
In this section, we will take a closer look at the KGT syntax. We will start with the basic syntax. We will then take a look at the different kinds of objects available in KGT and at specifying parameters and properties of these objects.
Info | ||
---|---|---|
| ||
If you prefer reading Xtext grammars, you will find it over here. |
Basic Syntax
In KGT, the KGraph is specified by listing the nodes in the graph, their ports, edges, and labels. The specification of each type of object follows the same basic syntax:
Code Block |
---|
type [id] <details> |
An ID is only necessary if an object needs to be referenced later. For example, if you define a port that you want to connect an edge to, the port better have an ID or you won't be able to specify which port the edge should connect to. The details
field doesn't always contain information. In fact, it is only necessary for the text of labels and for the source and target points of edges (see the next section for more details).
With this basic syntax, the following text specifies a complete KGraph with three nodes with the IDs n1
, n2
, and n3
:
Code Block | ||||
---|---|---|---|---|
| ||||
knode n1
knode n2
knode n3 |
The KGraph itself is simply a list of objects. Some objects can be (and are sometimes expected to be) nested in other objects. For instance, a port must always belong to a node. To be able to add objects to other objects, we extend the basic syntax a little:
Code Block |
---|
type [id] <details> {
<declarations>
} |
If nodes n2
and n3
should be nested inside n1
, the previous example must be changed a little:
Code Block | ||||
---|---|---|---|---|
| ||||
knode n1 {
knode n2
knode n3
} |
Types of Objects in the KGraph
Now that we know the basic way of specifying objects, it's time to see what types of objects there are, which other objects they can appear in, and whether they require any details.
Type | Keyword | Details | To appear in | Remarks |
---|---|---|---|---|
Node | knode | Empty | Top level, nodes | |
Port | kport | Empty | Nodes | |
Label | klabel | String (label text):"My gigantically useful label text" | Nodes, ports, edges | |
Edge | kedge | Source and target:(:sourcePortId -> targetNodeId:targetPortId) | Nodes | Edges must always be defined in their source node. That is why the source node is not defined in the details. |
When specifying edges, each port ID and the colon preceding it is optional. After all, edges don't have to connect ports, but can also connect nodes directly.
Object Parameters
So far, we have learned how the objects in a KGraph can be specified in the KGT format. However, this doesn't help us much since we don't know yet how to add basic parameters to the objects. This includes, for instance, the size of nodes.
Parameters are the first thing inside a block (the curly braces) of an object. There are three basic parameters that can be attached to a nodes, ports, and labels:
Code Block |
---|
pos: x=<xPosition> y=<yPosition>
size: width=<width> height=<height>
insets: top=<top> bottom=<bottom> left=<left> right=<right> |
A node with a predefined size could be written like this:
Code Block | ||||
---|---|---|---|---|
| ||||
knode n1 {
size: width=100 height=50
} |
Edges are somewhat different. Position, size, and insets aren't meaningful to edges, so edges have a different parameter that defines their list of bend points:
Code Block |
---|
points: <source>;<bend>*;<target> |
Each of the points is defined by their x and y coordinate as such:
Code Block |
---|
<x>,<y> |
Object Properties
If you have already used a layout algorithm through KIML, you will know that layout algorithms are configured through properties attached to the different graph objects. In KGT, this is done through the properties
section that follows the parameters:
Code Block |
---|
properties:
<propertyId> = <propertyValue> |
The properties
section can of course contain an arbitrary number of lines, each specifying the value of one property. For example, if we want to add ports and a label to a node, we will often have to set certain properties on it as well to tell the layout algorithm what to do:
Code Block | ||||
---|---|---|---|---|
| ||||
knode n1 {
properties:
de.cau.cs.kieler.sizeConstraint="PORTS NODE_LABELS"
de.cau.cs.kieler.nodeLabelPlacement="INSIDE V_TOP H_CENTER"
de.cau.cs.kieler.portConstraints=FIXED_SIDE
klabel "Node 1"
kport p1 {
size: width=5 height=5
properties:
de.cau.cs.kieler.portSide=WEST
klabel "West port 1"
}
kport p2 {
size: width=5 height=5
properties:
de.cau.cs.kieler.portSide=WEST
klabel "West port 2"
}
kport p3 {
size: width=5 height=5
properties:
de.cau.cs.kieler.portSide=EAST
klabel "East port 1"
}
} |
Often enough, we also have to set properties on the graph itself (for instance, which layout algorithm to use). In that case, simply include a properties
section at the top of the file:
Code Block | ||||
---|---|---|---|---|
| ||||
properties:
de.cau.cs.kieler.algorithm="de.cau.cs.kieler.klay.tree"
knode n1 {
kedge (-> n2)
kedge (-> n3)
}
knode n2
knode n3 |
A More Complex Example