Specific parameters (for all tree layout modes)

Root node (TL)

The final layout is influenced mainly by the choice of the root node.

The root node is placed in a prominent position. For example, in a top-down drawing with free layout mode, it is placed at the top of the tree. With a radial layout mode, it is placed at the center of the tree.

The spanning tree is calculated starting from the root node. If the graph is disconnected, the layout algorithm needs one root node for each connected component.

The layout algorithm automatically selects a root node when needed. It uses a heuristic that calculates preferences for all nodes to become a root. It chooses the node with the highest preference. The heuristic gives nodes without incoming links the highest preference and leaf nodes without outgoing links the lowest preference. Hence, in a directed tree, the canonical root is always chosen automatically.

It is possible to influence the choice of the root node.

To set a node explicitly as the root:

In CSS

Specify a rule that selects the node, for instance:

#node1 {
  Root: "true";
}

In Java

Use the method:

void setRoot(Object node);

In this case, the node argument must be a graphic node (subclass of IlvGraphic).

It gives the node the maximum preference to become the root during layout. If only one node is specified in this way, the algorithm selects this node. If several nodes of the same connected component are specified in this way, the layout algorithm chooses one of them as the root.

For experts: additional options for root nodes (TL)

The layout algorithm manages a list of the root nodes that have been specified by the setRoot method.

In Java

To obtain the nodes in this list, use the method:

Enumeration getSpecRoots();

After layout, you can also retrieve the list of root nodes that were used by the algorithm. This list is not necessarily the same as the list of specified roots. For instance, it contains the chosen root nodes if none were specified or if too many were specified.

In Java

To obtain the root nodes that were used by the algorithm, use the method:

Enumeration getCalcRoots();

This example shows how to iterate over the calculated root nodes and print the root node preferences:

In Java

Enumeration e = layout.getCalcRoots();
while (e.hasMoreElements()) {
  node = e.nextElement();
  System.out.println("Preference:" + layout.getRootPreference(node));
}

To directly manipulate the root node preference value of an individual node:

In CSS

Write a rule to select the node:

#node1 {
  RootPreference: "1000";
}

In Java

Use the method:

setRootPreference(Object node, int preference);

In this case, the layout uses the specified value instead of the heuristically calculated preference for the node. The normal preference value must be 0 - 10000 . Specifying a root node explicitly corresponds to setting the preference value to 10000 . If you want to prohibit a node from becoming the root, specify a preference value of zero ( 0 ).

A negative preference value indicates that the layout algorithm must recalculate the root node preference using the heuristic. If a root was specified by the setRoot method but this node must no longer be the root in subsequent layouts, use the following call to clear the root node setting:

layout.setRootPreference(node, -1);

This call also removes the node from the list of specified roots.

Position parameters (TL)

To set the position of the upper left corner of the layout to (10, 10):

In CSS

Specify:

GraphLayout {
    position          : "10,10";
    rootPosition      : "false";
}

In Java

In Java, use the method:

layout.setPosition(new IlvPoint(10, 10), false);

If the graph consists of only a single tree, it is often more convenient to set the position of the root node instead. To do so:

In CSS

Specify in the GraphLayout section:

GraphLayout {
    position          : "10,10";
    rootPosition      : "true";
}

In Java

Use the same method and pass true instead of false :

layout.setPosition(point, true);

If no position is specified, the layout keeps the root node at its previous position.

Using compass directions for positional layout parameters (TL)

The compass directions north, south, east, and west are used to simplify the explanations of the layout parameters. The center of the root node of a tree is considered the north pole.

In nonradial layout modes, the link flow direction always corresponds to south. If the root node is placed at the top of the drawing, north is at the top, south at the bottom, east to the right, and west to the left. If the root node is placed at the left border of the drawing, north is to the left, south to the right, east at the top, and west at the bottom.

In radial layout modes, the root node is placed in the center of the drawing. The meaning of north and south depends on the position relative to the root: the north side of the node is the side closer to the root and the south side is the side further away from the root. The east direction is counterclockwise around the root and the west direction is clockwise around the root. It is similar to a cartographic map of a real globe that shows the area of the north pole as if you were looking down at the top of the globe.

Compass directions are used to provide uniform naming conventions for certain layout options. They occur in the alignment options, the level alignment option, and the east-west neighboring feature, which are explained later. In Flow directions and Radial layout mode, the compass icons show the compass directions in these drawings.

Layout modes (TL)

The tree layout algorithm has several layout modes. The following example shows how to specify the layout mode.

In CSS

Add to the GraphLayout section:

layoutMode: "FREE";

In Java

Use the method:

void setLayoutMode(int mode);

The available layout modes are:

IlvTreeLayout.FREE (the default)
IlvTreeLayout.LEVEL
IlvTreeLayout.RADIAL
IlvTreeLayout.ALTERNATING_RADIAL
IlvTreeLayout.BALLOON
IlvTreeLayout.TIP_OVER
IlvTreeLayout.TIP_ROOTS_OVER
IlvTreeLayout.TIP_LEAVES_OVER
IlvTreeLayout.TIP_ROOTS_AND_LEAVES_OVER

In CSS, you omit the prefix IlvTreeLayout when specifying the value of the layout mode.