IBM ILOG Dojo Diagrammer 1.1.1 API Documentation
Legend: Array Boolean Constructor Date DomNode Error Function Namespace Number Object RegExp Singleton String

ibm_ilog.graphlayout.tree

Object » ibm_ilog.graphlayout.tree
dojo.require("ibm_ilog.graphlayout.tree.TreeLayout");

Method Summary

  • TreeLayout(source) The main class for the Tree Layout algorithm.

Attached Objects

Methods

TreeLayout

The main class for the Tree Layout algorithm.

The Tree Layout algorithm places the nodes of a tree starting from the root of the tree to the leaves. If the graph has parts that are disconnected, it arranges each connected component as an individual tree. The Tree Layout algorithm is primarily designed for a forest of pure trees. In a tree, each node except the root has a parent node. All the nodes that have the same parent are called children with respect to the parent and siblings with respect to each other. The Tree Layout algorithm can also be used for non-trees (for example, cyclic graphs). In this case, the layout algorithm ignores those links that violate the tree structure and takes only the spanning tree of the graph into account.

The algorithm has several layout modes:

  • The nodes can be arranged freely in a horizontal or vertical way. This is suitable for a graph with a large variation of node sizes.
  • The nodes can be arranged in horizontal or vertical levels. This is suitable for a graph that contains nodes of approximately the same size.
  • The nodes can be arranged radially on concentric circles or on ellipses around the root of the tree.
  • The nodes can be arranged radially around parents like balloons.
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 the north pole. If the root node is placed at the top border, north is always upwards, south towards the bottom, west towards the left, and east towards the right side of the layout. If the root node is placed at the left border, north is left and south is right. In radial mode, the root is placed in the center, and so the notation of north and south depends on where a node is placed relative to the root. The north side of any node is the side that is closer to the root and the south side is the side that is farther away from the root. In balloon mode, the compass directions make no sense.

Several alignment options are provided. In particular, the free layout mode allows the tip-over alignment, which means that subtrees are arranged serially rather than in parallel. If the subtrees starting at one node are normally arranged horizontally, the tip-over alignment arranges them vertically. The tree layout provides layout modes that automatically adapt the tip-over alignment to best fit the layout to a given aspect ratio.

The following sample drawings are produced by the Tree Layout algorithm. The left drawing uses the level layout mode. The flow direction of the links is towards the bottom, and the nodes are south-justified (that is, they are aligned to the bottom) within each level. The right drawing is the same tree in free layout mode (which always uses north level alignment):

Sample drawing produced with the Tree Layout

Here is another sample drawing in free layout mode with the tip-over alignment at some leaf nodes:

Sample drawing produced with the Tree Layout

The following are two sample drawings in the two radial layout modes. The normal radial mode in the left drawing places the nodes of the same level on a circle around the root node. The alternating radial mode in the right drawing places the nodes of the same level alternating on two circles around the root node. This results in better usage of the space.

Sample drawing produced with the Tree Layout

In nonradial layout modes, the Tree Layout algorithm supports different styles of links in the same drawing. The following sample drawing shows orthogonal and straight-line links. It also shows nodes that are aligned to the center (see the red nodes), to the east (green), and to the west (blue) of their children. The drawing was created by the free layout mode with the link flow direction to the right, and so north is to the left.

Sample drawing produced with the Tree Layout

The Tree Layout algorithm supports node neighboring in all modes. The following sample drawing shows a tree layout with the flow direction towards the top. Some nodes are not placed as children but rather as neighbors at the same level as the corresponding parent node. The red links, which are perpendicular to the flow direction, are between nodes that were specified as neighbored.

Sample drawing produced with the Tree Layout

See the corresponding chapter of the User's Manual for details on the algorithm, the types of graphs for which this algorithm can be used, the features and limitations, code samples, and so on.

Note the following points:

  • If no root node is specified, the layout algorithm takes the direction of links into account to calculate a root node. Other than that, the direction of links does not affect the layout.
  • The layout algorithm has an incremental mode that is designed to be stable when incremental changes are made. If nodes are added or removed after a layout, the next layout uses a heuristic to try to adjust the layout only minimally and to avoid major structural reorganization.
  • In incremental mode, the initial position of the nodes (at the moment you start the layout) affects the resulting layout because the algorithm tries to preserve the relative order of the children on incremental changes.

ParameterTypeDescription
source