Graph::Easy - Manual

Hinting - or how to create specific graph layouts

If you haven't done so, please read the Overview first, followed by the chapter about the Layouter details.

Graph::Easy's layouter is responsible for converting a (internal) graph representation into a specific layout. Here are two example layouts, automatically produced from the same input graph:

Example layout of simple graph
+---+     +---+     +---+
| A | --> | C | --> | D |
+---+     +---+     +---+
            |
            |
            v
          +---+
          | E |
          +---+

Influencing the Layout

Although the placement of nodes, edges and labels is completely automated, you can influence the created layout by giving the layouter hints like the following:

Some of the hints will be used only as hints by the layouter, e.g. it might ignore them to produce a complete layout. Other hints like relative node placements are taken as strict "must do", and these might create dilemmas for the layouter. So use them only when absolutely neccessary.

Flow Direction

While East is the prefered direction for all edges, you can use the attribute flow to let the graph flow in another general direction.

graph { flow: south; }

[ Hamm ] -> [ Essen ] -> [ Olpe ]
+-------+
| Hamm  |
+-------+
  |
  |
  v
+-------+
| Essen |
+-------+
  |
  |
  v
+-------+
| Olpe  |
+-------+
graph { flow: left; }

[ Hamm ] -> [ Essen ] -> [ Olpe ]
+------+     +-------+     +------+
| Olpe | <-- | Essen | <-- | Hamm |
+------+     +-------+     +------+

All four flow directions (north, south, west, east) are supported, even when generating graphviz code (dot does not easily support upwards and leftwards flow directions without some trickery).

You can also change the flow on a per-node basis:

graph { flow: left; }

[ Duisburg ] -> [ Siegen ] { flow: south; }
 -> [ Adenau ]
+--------+     +----------+
| Siegen | <-- | Duisburg |
+--------+     +----------+
  |
  |
  v
+--------+
| Adenau |
+--------+

Node sizes (multi-celled nodes)

You can specify the size of a node in rows and columns by using either the rows, columns or size attribute:

[ A ] { size: 2,2; }
-> [ B ] { rows: 2; }
-> [ C ] { columns: 3; }

Here is an example that demonstrates this:

[ A ] { size: 2,2; }
-> [ B ] { rows: 2; }
-> [ C ] { columns: 3; }

[ A ] -> [ B ]
 -> [ C ]
 -> [ D ]

[ D ] -> [ C ]
[ B ] -> [ C ]

[ A ] -> [ F ]
[ A ] -> [ G ]

                      +---------+    +---------+
                      |         v    v         |
+---+     +---+     +---+     +--------+     +---+
| G | <-- |   | --> |   | --> |   C    | --> | D |
+---+     | A |     | B |     +--------+     +---+
          |   |     |   |       ^
          |   | --> |   | ------+
          +---+     +---+
            |
            |
            v
          +---+
          | F |
          +---+

Even when you do not specify a size, the layouter will grow nodes automatically to satisify the constraints of the layout, for instance when more than four edges start/end at a particular node. Likewise, when specifying edge ports, these constraints will grow the node if necessary.
As an example, if you specifiy that there are 5 edges starting/ending at the south side of the node, than the node will be made at least 5 cells wide.

Groups

Nodes can be grouped together by using braces:

( German Cities
  [ Berlin ] -> [ Potsdam ]
) {
  background: lightbrown;
  }

Putting nodes into a group gives the layouter the hint that these nodes are related and should be laid out closely together.
Please see the chapter about Advanced Syntax for details and examples.

Relative placement (via auto-split)

You can cluster nodes together by placing them relatively to each other.
Perhaps the easiest way to achive the placement is to use the auto-split feature:

Here is a few examples to make this clear:

[ A | B | C ]
+---+---+---+
| A | B | C |
+---+---+---+
[ A | B || C ]
+---+---+
| A | B |
+---+---+
| C |
+---+
[ A | B ||
  C | D | E ||
  F ]
+---+---+
| A | B |
+---+---+---+
| C | D | E |
+---+---+---+
| F |
+---+

Please see the section about attributes on how to put individual attributes on each autosplit node.

To reference an autosplit node, you need to know it's basename and the number of the part that was split up. The basename can be set via an attribute. If not specified, it will be automatically created by concatenating all the parts together, without spaces or linebreaks. If the basename already exists, an incrementing number is appended (including a leading "-"), starting with "1":

[ A | B | C ]		# basename is: ABC
[ A | B | C ]		# basename is: ABC-1

In this example, the basename for the first autosplit node is "ABC", the second one get's as basename "ABC-1".

[ A | B | C ]		# basename: ABC
[ A | B | C ]		# basename: ABC-1
[ C | D | E ]		# basename: CDE
[ C | D | E ]		# basename: CDE-1

Note that the number is unique and increasing for the entire graph, thus creating "CDE" and "CDE-2", and not "CDE-1" in the second example.

The parts are referenced by their number, with a leading ".". Here is an example referencing the second part of the autosplit node:

[ A | B | C ]
[ 1 ] -> [ ABC.2 ]
         +---+
         | 1 |
         +---+
           |
           |
           v
+---+---+----+
| A | B |  C |
+---+---+----+

Here is a more complex example, using the basename attribute:

[ A|B|C ] { basename: A } [ 1 ] -> [ A.2 ]
[ A|B|C ] [ 2 ] -> [ ABC-1.2 ]

This will be rendered like so:

         +---+
         | 2 |
         +---+
           |
           |
           v
+---+---+----+
| A | B |  C |
+---+---+----+
         +---+
         | 1 |
         +---+
           |
           |
           v
+---+---+----+
| A | B |  C |
+---+---+----+

Relative Node Placement (with offsets)

Another way is to specify an origin and offset for a node, placing it relatively to another node:

[ Left ] -> [ Right ] { origin: Left; offset: 2,1; }
+------+
| Left |
+------+
  |
  |              +-------+
  +------------> | Right |
                 +-------+

The offset should not be 0,0. Also, be carefull to node place nodes inside each other, especially when using multicelled nodes as explained below.

The offset is calculated from the left/right or top/bottom side of the node, so for a multicelled node that is 3 cells wide, an offset of 2 would still place the next node two cells from the right side (instead inside the first node):

[ A ] { size: 3,2; }

[ A ] -> [ B ] { origin: A; offset: 2,0; }
[ A ] -> [ C ] { origin: A; offset: 1,1; }
+---+     +---+
|   | --> | B |
| A |     +---+
|   |
|   |--+
+---+  v
     +---+
     | C |
     +---+

You can set an origin for each node, even if this node has an origin itself. The only exception is that you may not create loops like in the following:

[ A ] { origin: B; offset: 1,1; }
[ B ] { origin: A; offset: 1,1; }       # invalid!

[ C ] { origin: E; offset: 1,1; }
[ D ] { origin: C; offset: 1,1; }
[ E ] { origin: C; offset: 1,1; }       # invalid!

Here is an example, using a chain of origins:

[ A ] { origin: B; offset: 2,1; }

-> [ B ] { origin: C; offset: 1,1; }
-> [ C ] { origin: D; offset: 1,1; }
-> [ D ]
-> [ E ]
+---+     +---+
| D | --> | E |
+---+     +---+
  ^  +---+
  +--| C |
     +---+
       ^  +---+
       +--| B |
          +---+
            ^       +---+
            +------ | A |
                    +---+