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:
+---+ +---+ +---+
| 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:
- adjusting the flow direction
- setting node sizes
- grouping nodes together
- Creating rows/columns of nodes
- placing nodes relativ to each other
- specify edge starting/ending ports
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 (see below,
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:
- a
|(vertical bar) in the node name will split the node into two parts, and place them next to each other, horizontally - likewise,
||(two vertical bars) in the node name will split the node into two parts, but place the second part at the start of a new row - If a part between two
|consists of exactly one space, an invisible cell will be generated, e.g. one without borders and background - If a part between two
|consists of more than one space, an empty cell (e.g. with borders and background) will be generated - Trailing empty parts will be ignored, so
[ A|B| ]equals[A|B]. If you want an empty/invisible cell as last part, add anoter|:[ A|B| |]
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-2
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 |
+---+
Edge start/end ports
.................................................. : : : : : : : : : 0,0 :north,0:north,1: 3,0 : 4,0 : 5,0 : 6,0 : : :left,0 :left,1 : : : : : : : : : : : : : .................................................. : :+-------------+: : : : : :west,0:| |:east,0 : 4,1 : 5,1 : 6,1 : :back,1:| |:front,0: : : : : :| |: : : : : ........| Node |........................... : :| |: : : : : :west,1:| |:east,1 : 4,2 : 5,2 : 6,2 : :back,1:| |:front,1: : : : : :+-------------+: : : : : ................................................. : : : : : : : : : 0,3 :south,0:south,1: 3,3 : 4,3 : 5,3 : 6,3 : : :right,0:right,1: : : : : : : : : : : : : .................................................
Each side of a node can be named. The reason that there are two names
(north and left)
has to do with graph/node flow. The south side of the node is always
the same side, no matter what the flow at the node is. The right
side is always perpendicular to the front side - and the
front side always points in the direction of the flow.
Here is an example that should make this clear:
[ Node ] -> { start: south; } [ south ] { origin: Node; offset: 0,2; }
[ Node ] -> { start: north; } [ north ] { origin: Node; offset: 0,-2; }
[ Node ] -> { start: east; } [ east ] { origin: Node; offset: 2,0; }
[ Node ] -> { start: west; } [ west ] { origin: Node; offset: -2,0; }
+-------+
| north |
+-------+
^
|
|
+------+ +-------+ +------+
| west | <-- | Node | --> | east |
+------+ +-------+ +------+
|
|
v
+-------+
| south |
+-------+
graph { flow: east; }
[ Node ] -> { start: right; } [ right ] { origin: Node; offset: 0,2; }
[ Node ] -> { start: left; } [ left ] { origin: Node; offset: 0,-2; }
[ Node ] -> { start: front; } [ front ] { origin: Node; offset: 2,0; }
[ Node ] -> { start: back; } [ back ] { origin: Node; offset: -2,0; }
+-------+
| left |
+-------+
^
|
|
+------+ +-------+ +-------+
| back | <-- | Node | --> | front |
+------+ +-------+ +-------+
|
|
v
+-------+
| right |
+-------+
Both graphs look the same, so there does not seem much point in using
right or south. However changing the flow of the
graph will show a difference:
graph { flow: down; }
[ Node ] -> { start: south; } [ south ] { origin: Node; offset: 0,2; }
[ Node ] -> { start: north; } [ north ] { origin: Node; offset: 0,-2; }
[ Node ] -> { start: east; } [ east ] { origin: Node; offset: 2,0; }
[ Node ] -> { start: west; } [ west ] { origin: Node; offset: -2,0; }
+-------+
| north |
+-------+
^
|
|
+------+ +-------+ +------+
| west | <-- | Node | --> | east |
+------+ +-------+ +------+
|
|
v
+-------+
| south |
+-------+
graph { flow: down; }
[ Node ] -> { start: right; } [ right ] { origin: Node; offset: 0,2; }
[ Node ] -> { start: left; } [ left ] { origin: Node; offset: 0,-2; }
[ Node ] -> { start: front; } [ front ] { origin: Node; offset: 2,0; }
[ Node ] -> { start: back; } [ back ] { origin: Node; offset: -2,0; }
+-------+
| north | <+
+-------+ |
|
+------------+ |
v | |
+------+ +-------+ | +------+
| west | +--| Node |--+ | east |
+------+ | +-------+ +------+
| | ^
| +-------------+
|
| +-------+
+->| south |
+-------+
You can see that the first graph did not change at all.
The second one looks different, though. Since the node offsets are fixed
(they do not change with the flow, as this is not possible yet), all the nodes
are still placed at the same position.
But the starting ports moved (rotated) with the flow direction!
Summary: To make graphs flow-invariant, use south etc, to make it possible
to rotate graphs, use left, right, front
or back.
.
Port numbers
By setting the start/end port to one side, you instruct the layouter to place the edge on one arbitrary port on that side:
graph { flow: east; }
[ Left ] -> { start: left; end: left; } [ Right ]
+------------+ | v +------+ +-------+ | Left | | Right | +------+ +-------+