tree connectors - modelint/flatland-model-diagram-editor GitHub Wiki

A tree connector connects one or more leaf nodes to some other trunk node forming a hierarchical pattern. The parts of the connector that attach to the leaves are called leaf stems while the trunk is connected via a trunk stem. A straight line segment that connects multiple nodes is called a branch.

While it is nice to have all of the leaves in a nice neat row below or to the side of the trunk node, they don’t have to be. You can sprawl them out as much as you like, possibly requiring multiple connected branches. Remember, though, that Flatland doesn’t do diagonal lines, so you will get a bend or two as necessary if the leaf nodes don’t more or less line up. A simple tree will have just one branch pulling together the trunk and all of the leaf stems.

In Executable UML, we use the tree connector to draw generalization relationships.

<indent><side><connector_name> : <trunk_stem> { <leaf_stem>, ... }

In the simplest syntax, you specify the connector name and side the same as you do with binary connectors. The trunk stem is also specified just like a binary connector t or p stem though the trunk stem is always anchored, so you never use the * float specifier with it.

Each leaf stem is enclosed in { } brackets with a space after the first bracket and one before the last. This rule makes it easier to read the internal content. Each leaf stem is separated by a comma if there is more than one.

Things get a bit more complicated when we specify complex bends, so we’ll ignore those in the simple syntax.

Here we put the Aircraft class up top with two subclasses underneath:

nodes
    Aircraft 3,2
    Helicopter 1,1
    Fixed Wing 1,3
connectors
    +R1 : b|Aircraft { t|Helicopter, t+1|Fixed Wing }

After the connector name and colon, we first specify the trunk stem. The leaf stems follow and are enclosed in {} brackets.

The nodes should be placed with an empty row in between so there is enough room to draw the trunk stem and the connecting branch.

There are a few variations on the tree specification and this simple case is called an interpolated branch. This means that the branch is placed at the center point between the attached trunk node face and the closest attached leaf face.

Note that the leaf stem on the top face of the Fixed Wing node has been anchored one notch to the right of center.

If you want a tree connector branch to be placed more precisely, you can use a rut branch instead of an interpolated branch. As the name suggests, you specify the exact lane and rut where you want the branch to run.

nodes
    Aircraft 3,2
    Helicopter 1,1
    Fixed Wing 1,3
    Hybrid Wing 4,5
connectors
    +R1 : b|Aircraft { t|Helicopter, t|Fixed Wing } { l|Hybrid Wing : L4 }

Here we have specified two groups of leaf stems, each on its own branch. The first branch always includes the trunk node. Each subsequent leaf group constitutes another branch.

While the first branch is interpolated, we see that the second is a rut branch. The second branch includes only one leaf node, Hybrid Wing, which runs down the center of lane 4 (column 4). Again, Flatland is able to figure out whether a lane runs down a column or a row. Since only a lane and no rut is specified, the second branch runs through the lane center.

To make any interpolated branch a rut branch, just specify a lane and optional rut. A branch can run through only one lane, so you cannot specify more than one within a leaf group.

There is another way to precisely place a branch without interpolation or an explicit lane placement. You can use a fixed anchor on one of the leaf nodes to establish the branch position. Here’s an example:

nodes
    Aircraft 3,1
    Helicopter 5,2
    Fixed Wing 4,4
    Hybrid Wing 3,3
    X Wing 1,3
connectors
    -R1 : r|Aircraft { b-1|Helicopter>, l|Fixed Wing, l|Hybrid Wing, l|X Wing }

By placing one leaf stem (and only one) in a leaf stem group orthogonal to the others in the same group, you can use the anchor point to project the branch line segment. We say that the stem grafts from the anchor point. We indicate the grafting point with the > symbol. Note its placement at the end of the Helicopter leaf stem. In this case, the Helicopter leaf stem extends from the bottom face which is 90 degrees away from the horizontal leaf stems attached to the left faces of the other leaf nodes. If you use a graft, you must not supply a lane placement in the same leaf group. They are mutually exclusive specifications.

It is possible to specify a floating stem opposite a grafted stem on the same branch. Here’s an example:

nodes
    Aircraft 4,2
    Helicopter 3,1
    Fixed Wing 1,2
    Hybrid Wing 1,3
    X Wing 5,3
    Tie Fighter 3,4
connectors
    -R1 : b|Aircraft { r|Helicopter>, t|Fixed Wing, t|Hybrid
 Wing, b+1|X Wing, l*|Tie Fighter } // All on same line

Here we see that the Tie Fighter node is directly across from the Helicopter node on the same branch. The branch is grafted from the leaf stem as indicated by the > grafting symbol. The Tie Fighter leaf stem specifies a floating * anchor which means that the branch attaches wherever it intersects the Tie Fighter node face. Within a leaf group you may specify at most one graft and, if there is a graft, at most one floating anchor on whatever node is on the opposite side of the branch.

In this next example, we combine the many types of branches in a single tree connector.

nodes
    Aircraft 3,2
    Helicopter 1,1
    Fixed Wing 3,4
    Hybrid Wing 4,4
    X Wing 6,2
    Tie Fighter 5,1
connectors
    -R1 : b|Aircraft { t|Helicopter } { l|Fixed Wing : L3R-1 } 
{ l|Hybrid Wing>, b|X Wing, b|Tie Fighter } // all on same line

The first branch, with the Aicraft and Helicopter node is interpolated since there is no other guidance as to where to place the branch. The second is a rut branch as indicated by the lane placement specification in lane 3, rut -1. The final branch is grafted from the Hybrid Wing node as indicated by the > grafting stem symbol.