The Tree Layout uses generic parameters, common to other graph layouts, and specific parameters applicable in tree layouts only. Refer to the following sections for general information on parameters among the graph layouts:

The Tree Layout parameters are described in detail in this topic under:

The IlvTreeLayout class supports the following generic parameters defined in the IlvGraphLayout class:

The following paragraphs describe the particular way in which these parameters are used by this subclass.

The layout algorithm stops if the allowed time setting has elapsed. (For a description of this layout parameter in the IlvGraphLayout class, see Allowed Time.) If the layout stops early because the allowed time has elapsed, the nodes and links are not moved from their positions before the layout call.

The layout algorithm does not reshape the links that are specified as fixed. (For more information on link parameters in the IlvGraphLayout class, see Preserve Fixed Links and Link Style.)

The layout algorithm does not move the nodes that are specified as fixed. (For more information on node parameters in the IlvGraphLayout class, see Preserve Fixed Nodes.) Moreover, the layout algorithm ignores fixed nodes completely and also does not route the links that are incident to the fixed nodes. This can result in undesired overlapping nodes and link crossings. However, this feature is useful for individual, disconnected components that can be laid out independently.

The following parameters are specific to the IlvTreeLayout class. They apply to all layout modes.

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

The root node is placed in a prominent position. For instance, in a top-down drawing with free layout mode it is placed at the top of the tree; with radial 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 select a node explicitly as the root, use the method:

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

The layout algorithm manages a list of the root nodes that have been specified by the setRoot method. To obtain this list, use the method:

After layout, you can also retrieve the list of root nodes that were actually 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. To obtain the list of root nodes that were used by the algorithm, call the method:

Note that the returned lists are constant. You should not change them directly. However, you can iterate over the lists and retrieve the root nodes, as in the following example, to perform special root operations:

To directly manipulate the root node preference value of an individual node, you can use the method:

In this case, the layout uses the specified value instead of the heuristically calculated preference for this node. The normal preference value should be between 0 and 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 should recalculate the root node preference, using the heuristic. You can clear the root node setting as follows: If a root was specified by the setRoot method but this node should no longer be the root in subsequent layouts, then call:

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

The position of the top left corner of the layout can be set to (10, 10) in the following way:

If the graph consists of only a single tree, it is often more convenient to set the position of the root node instead. This can be done by the same method, passing IlFalse instead of IlTrue:

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

To obtain the current position, use:

This method returns a null pointer if no position was specified. If it returns a point, you can query whether the specified position is either the top left corner or the position of the first root node:

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

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

In the radial layout modes, the root node is placed in the center of the drawing, hence 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 that is further away from the root. The east direction is counterclockwise around the root, and the west direction is clockwise around the root. This 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 give uniform names to certain layout options. They occur in the alignment options, the level justification option and the east-west neighboring feature, which are explained later. In Figure 4.5 and Figure 4.15, a compass icon shows the compass directions in these drawings.

The tree layout algorithm has various layout modes. To select a layout mode, use the method:

To obtain the current layout mode, call:

The type IlvTreeLayoutMode is an IlList type defined in the file ilviews/layout/tree.h. The choices of layout modes are shown in Table 4.4: