For experts: additional tips for the TL

You can specify that two unrelated nodes must be direct neighbors in a direction perpendicular to the flow direction. In the level and radial layout modes, the nodes are placed in the same level next to each other. In the free layout and tip-over modes, the nodes are placed aligned at the north border. Such nodes are called east-west neighbors because one node is placed as the direct neighbor on the east side of the other node. The other node becomes the direct neighbor on the west side of the first node. (See also Using compass directions for positional layout parameters (TL)).

Technically, the nodes are treated as parent and child, even if there is no link between them. Therefore, one of the two nodes can have a real parent, but the other node must not because its virtual parent is its east-west neighbor.

The east-west neighbor feature can be used, for example, for annotating nodes in a typed syntax tree occurring in compiler construction. Annotated syntax tree of statement a[25] = b[24] + 0.5; shows an example of such a tree.

void setEastWestNeighboring(Object eastNode, Object westNode);   

void setWestEastNeighboring(Object westNode, Object eastNode);   

Object getEastNeighbor(Object node);   

Object getWestNeighbor(Object node);   

Each node can have at most one east neighbor and one west neighbor because they are direct neighbors. If more than one direct neighbor is specified, it is partially ignored. Cyclic specifications can cause conflict as well. For instance, if node B is the east neighbor of node A and node C is the east neighbor of B, then node A cannot be the east neighbor of C. (Strictly speaking, such cycles could be technically possible in some situations in the radial layout mode, but nonetheless they are not allowed in any layout mode.)

If B is the east neighbor of A, then A is automatically the west neighbor of B. The east neighbor of A can itself have another east neighbor. You can thus create chains of east-west neighbors, which is a common way to visualize lists of trees. Two examples are shown in figure Chains of east-west neighbors to visualize lists of trees.

The Tree Layout algorithm works on a spanning tree, as mentioned in a The TL algorithm. If the graph to be laid out is not a pure tree, the algorithm ignores some links. To treat such links in a special way, you can obtain a list of nontree links.

Because there are parents and child nodes in the spanning tree, the following link categories must be distinguished:

The layout algorithm uses these link categories internally but does not store them permanently to save time and ensure memory efficiency. If you want to treat some link categories in a special way (for example, to call the Link Layout on the nontree links), you must specify before the layout that you want to access the link categories after the layout.

layout.setCategorizingLinks(true);
// now perform a layout
layout.performLayout();
// now you can access the link categories

You can work with trees that have become out-of-date, for example, the trees that need to be extended with more child nodes. If you perform a layout after an extension, you probably want to identify the parts that had already been laid out in the original graph. The Tree Layout algorithm supports these incremental changes in incremental mode because it takes the previous positions of the nodes into account. It preserves the relative order of the child nodes in the subsequent layout.

In this case, the layout is independent from the positions of the nodes before the layout. It does not preserve the relative order of the child nodes in subsequent layouts.

Incremental mode is enabled by default.

incrementalMode: "false";

layout.setIncrementalMode (false); 

The fact that the relative order of the layout is preserved is useful during interactive editing. It allows you to correct the layout easily. For instance, if the first layout places a node A left to its sibling node B but you need to reverse the order, you can simply move node A to the right of node B and start a new layout to clean up the drawing. In the second layout, A remains to the right of B, and the subtree of A “follows” node A.

Some applications require a specific relative order of the child nodes in the tree. This means that, for instance, when the flow direction is to the bottom, which child must be placed to the left of another child.

It can be achieved in non-incremental mode by specifying a node comparator as follows:

layout.setIncrementalMode(false);
layout.setNodeComparator(new Comparator() {
    public int compare(Object o1, Object o2) {
        ... // compare two nodes
    }
});

The comparator specifies the order as defined in the following table. For regular alignment, it results in increasing coordinates for the children. For tip-over alignment, it results in increasing distance from the parent. For balloon and radial modes, it results in clockwise orderings.