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

Object » ibm_ilog.graphlayout

Property Summary

Method Summary

  • GraphLayout(source) The base class of the Graph Layout algorithms.
  • GraphLayoutReport() The base class of the objects used to store information about the behavior of the layout algorithms.
  • GraphLayoutUtil() This class regroups some graph layout utilities.
  • IIterator() A class to enumerate a set of values.
  • ILayoutProvider() An interface used to specify the layout instance to be used for laying out a given graph.
  • ILinkConnectionBoxProvider() An interface used to customize the computation of the connection points of the links.
  • INodeBoxProvider() An interface used to define a rectangle associated with a node of a graph.
  • INodeSideFilter() An interface used to define complex requirements concerning the connection of the links to the different sides of the nodes.
  • ISubgraphCorrection() An interface used to define corrections of a subgraph after the layout of the subgraph was performed.
  • MultipleLayout(a0, a1) The main class for the Multiple Layout algorithm.
  • MultipleLayoutReport() The class used to store information about the behavior of the Multiple Layout algorithm.
  • RecursiveLayout(layout, layoutProvider) The main class for the Recursive Layout algorithm.
  • RecursiveLayoutProvider() The internal layout provider used by the Recursive Layout in internal provider mode.
  • RecursiveLayoutReport() The class used to store information about the behavior of the Recursive Layout algorithm.
  • RecursiveMultipleLayout(a0, a1) The main class for the Recursive Multiple Layout algorithm.
  • SplineLinkFilter() 'SplineLinkFilter' is used by the layout algorithms that support optimized spline routing.

Attached Objects

Properties

Direction
Defines the direction and alignment constants used in the graph layout API.
LightVersion
Loads a "light" version of the ibm_graphlayout module used only to run graph layouts on a web server or in a web worker.
basic
circular
forcedirected
grid
hierarchical
longlink
random
shortlink
tree

Methods

GraphLayout

The base class of the Graph Layout algorithms.

IBM ILOG Dojo Diagrammer provides special support for applications that need to display graphs (also called networks) of nodes and links. Using the ibm_ilog.diagram.Graph class, any graphic object can be defined to behave like a node and can be connected to other nodes with links, which themselves can have many different forms. Used in conjunction with layout algorithms, this feature is often used to create network topologies for telecommunications networks and system management applications.

The class GraphLayout is abstract and cannot be used directly. You must use one of its concrete subclasses.

You can also create your own subclasses to implement other layout algorithms.

The class contains layout parameters or options that can be useful for different layout algorithms. The implementation of the ibm_ilog.graphlayout.GraphLayout.layout() method is solely responsible for whether or not the current settings of the parameters are taken into account.

Note that all layout parameters that are specific to nodes or links, such as the "fixed" attribute (see ibm_ilog.graphlayout.GraphLayout.setFixed(), ibm_ilog.graphlayout.GraphLayout.isFixed()), can be accessed only while the graph that contains the nodes or links is attached to the layout instance.

To learn more about the layout algorithms and the corresponding GraphLayout subclasses, read the sections of the Reference Manual describing those classes and the IBM ILOG Dojo Diagrammer User's Manual.

Note that when implementing a subclass of GraphLayout, the initialization of all instance variables of the subclass needs to be done in the overridden implementation of the method ibm_ilog.graphlayout.GraphLayout.init(). This is to prevent execution of methods of the subclasses before the initialization of the instance variables of the subclasses.

Note also that you must call the method ibm_ilog.graphlayout.GraphLayout.detach() when you no longer need the layout instance, otherwise some objects may not be garbage collected. This is necessary only if the layout instance is directly created by your code. Calling ibm_ilog.graphlayout.GraphLayout.detach() is not necessary if the layout instance is created internally by the IBM ILOG Dojo Diagrammer Graph Layout library, when using an DefaultLayoutProvider for recursive layout.

ParameterTypeDescription
source
GraphLayoutReport

The base class of the objects used to store information about the behavior of the layout algorithms.

The layout report is returned by the method ibm_ilog.graphlayout.GraphLayout.performLayout(). It can be also obtained during the layout using the layout event listener mechanism.

GraphLayoutUtil
This class regroups some graph layout utilities.
IIterator

This class is used in the ibm_graphlayout API to return a set of values that can be enumerated. You can use either the hasNext()/next() or hasMoreElements()/nextElement() pairs of methods, as follows:

var constraints = layout.getConstraints(); // returns an IITerator
while(constraints.hasNext()){
var constraint = constraints.next();
...
}

ILayoutProvider

An interface used to specify the layout instance to be used for laying out a given graph.

This is an advanced API. In Dojo Diagrammer, you specify the layout to use for a specific Subgraph by calling ibm_diagram.Subgraph.setNodeLayout(layout) or ibm_diagram.Subgraph.setLinkLayout(layout).

ILinkConnectionBoxProvider

An interface used to customize the computation of the connection points of the links.

This interface is useful when a layout algorithm that supports this customization must place the connection points of the links at a certain distance inside or outside the bounding box of the nodes. This interface also allows a tangential "translation" of the connection points separately for each side of each node.

The following code is an example of the implementation of the method ILinkConnectionBoxProvider.getBox(). In this example, the connection points are at a distance of 10 outside the bounding box of the nodes. Therefore, the method computes the bounding box of the node and expands it with a value of 10 in all four directions:

function getBox(graphModel, node) { var bbox = graphModel.boundingBox(node); bbox.x -= 10; bbox.y -= 10; bbox.width += 20; bbox.height += 20; return bbox; }

In the second code example, the connection points on the left and right side of the nodes are shifted to the top by a fixed amount of 10. (Of course, this amount could be variable dependent on specific conditions, for example, the height of a label below a node):

function getTangentialOffset(graphModel, node, nodeSide) { switch (nodeSide) { case ibm_ilog.graphlayout.Direction.LEFT: case ibm_ilog.graphlayout.Direction.RIGHT: return -10; default: return 0; } }

INodeBoxProvider

An interface used to define a rectangle associated with a node of a graph.

This interface is useful when a layout algorithm must use a node size that is different from the bounding box (see ibm_ilog.graphlayout.AbstractGraphLayoutModel.boundingBox ).

The following code is an example of the implementation of the method INodeBoxProvider.getBox(). In this example, the height of the node box is never smaller than a predefined value (80). The additional height is added to the bottom of the original bounding box:

function getBox(graphModel, node)
{
var bbox = graphModel.boundingBox(node);
if (bbox.height < 80)
bbox.height = 80;
return bbox;
}
In the second code example, the additional height is added to the top of the original bounding box:
function getBox(graphModel, node)
{
var bbox = graphModel.boundingBox(node);
if (bbox.height < 80) {
bbox.y = bbox.y + bbox.height - 80;
bbox.height = 80;
}
return bbox;
}

INodeSideFilter

An interface used to define complex requirements concerning the connection of the links to the different sides of the nodes.

The filter is used by some layout algorithms to provide the user the capability to allow or prohibit the links to be connected on given sides (top/bottom/right/left) of the nodes.

ISubgraphCorrection
An interface used to define corrections of a subgraph after the layout of the subgraph was performed.
MultipleLayout

The main class for the Multiple Layout algorithm.

This is not a layout algorithm but rather a facility to compose multiple layout algorithms and treat them as one algorithm object. This is more convenient if a sequence of layout algorithms must be applied to subgraphs. For instance, assume that you want to apply to each subgraph a Tree layout, then a Link layout for the nontree links. It would be unfortunate to call ibm_ilog.graphlayout.GraphLayout.performLayout() multiple times to achieve this, because the tree layout of the parent graph would be finished before the link layout of its subgraph has started; hence the link layout of the subgraph invalidates the tree layout of the parent graph again. To avoid this effect, the Tree layout, Link layout, and Label layout of the subgraph should be finished before any layout of the parent graph has started. The following sample shows how to achieve this by using the Multiple Layout class:

GraphLayout layout = new MultipleLayout(
new TreeLayout(),
new LinkLayout(),
new AnnealingLabelLayout());
layout.attach(grapher);
layout.performLayout(true, true, true);
If more than two graph layouts and one label layout are necessary, you can construct an MultipleLayout from another MultipleLayout, as follows:
GraphLayout layout = new MultipleLayout(
new MultipleLayout(layout1, layout2, null),
new MultipleLayout(layout3, layout4, null),
labelLayout);
The multiple layout offers only a few layout parameters that are global to all three sublayouts (such as the allowed time), but you can specify the other layout parameters individually for each sublayout by accessing MultipleLayout.getFirstGraphLayout(), MultipleLayout.getSecondGraphLayout() , and MultipleLayout.getLabelLayout() directly.

If complex combinations of graph layouts and label layouts are needed in a nested graph, you should use the Recursive Multiple Layout (see ibm_ilog.graphlayout.RecursiveMultipleLayout) that utilizes the Multiple Layout inside a Recursive Layout.

ParameterTypeDescription
a0
a1
MultipleLayoutReport

The class used to store information about the behavior of the Multiple Layout algorithm. It stores the layout reports of its sublayouts.

RecursiveLayout

The main class for the Recursive Layout algorithm.

This is not a layout algorithm but rather a facility to perform layouts recursively in a nested graph. Unless otherwise mentioned, the normal layout algorithms such as ibm_ilog.graphlayout.hierarchical.HierarchicalLayout, ibm_ilog.graphlayout.tree.TreeLayout, ibm_ilog.graphlayout.MultipleLayout, and so forth work on a flat graph, that is, they lay out the attached graph but not the subgraphs of the attached graph. The Recursive Layout is different: it traverses the nesting structure starting from the attached graph and applies a layout recursively on all subgraphs. It can be tailored for which sublayout has to be applied to which subgraph.

There are basically two scenarios:

  • The same layout style must be applied to all subgraphs.
  • An individual layout style must be applied to each subgraphs.
First scenario: Same layout style everywhere

The following example shows the first scenario:

GraphLayout layout = new RecursiveLayout(new TreeLayout());
layout.attach(topLevelGrapher);
LayoutReport report = layout.performLayout(true, true); 
In this case, a tree layout is performed recursively to the top-level graph and to each subgraph. All layouts are performed with the same global layout parameters as for the layout instance passed as an argument to the constructor of RecursiveLayout, which is called its reference layout. You can access the reference layout instance to change the global layout parameters:
TreeLayout treeLayout = (TreeLayout)layout.getReferenceLayout();
treeLayout.setFlowDirection(Direction.Left); 
Internally, a clone of the reference instance is created for each subgraph. This clone remains attached as long as the Recursive Layout is attached to the top-level graph. Before layout is performed, the global layout parameters are copied from the reference instance to each clone. If you need to set layout parameters for individual nodes and links, you have to access the layout instance of the subgraph that owns the node or link:
TreeLayout treeLayout = (TreeLayout)layout.getLayout(subgraph);
treeLayout.setAlignment(node, TreeLayout.TIP_OVER); 

In the typical case, when you use instances of Graphic as nodes and instances of Grapher as subgraphs, it is:

TreeLayout treeLayout = (TreeLayout)layout.getLayout(node.getGraphicBag());
treeLayout.setAlignment(node, TreeLayout.TIP_OVER); 

Second scenario: Different layout styles at different subgraphs

The following example shows the second scenario: Each subgraph should be laid out by a different layout style or with individual layout parameters. In this case, we need a layout provider (see ibm_ilog.graphlayout.ILayoutProvider) that specifies which layout instance is used for which subgraph.

GraphLayout layout = new RecursiveLayout(layoutProvider);
layout.attach(topLevelGrapher);
LayoutReport report = layout.performLayout(true, true); 
The layout provider returns a different layout instance for each subgraph. For example, it may return a grid layout for the top-level graph, but a tree layout for one subgraph and a bus layout for another subgraph of the top-level graph. Furthermore, each layout can have different global layout parameters. You can implement your own application-specific layout provider, or you can use the predefined ibm_ilog.graphlayout.DefaultLayoutProvider or RecursiveLayoutProvider that allows you to specify the preferred layout of each subgraph. If neither a reference layout nor a layout provider is given to the Recursive Layout, an internal default layout provider of class RecursiveLayoutProvider is used. This allows you to specify the layouts of subgraphs in a very convenient way:
RecursiveLayout layout = new RecursiveLayout();
layout.attach(topLevelGrapher);
// specify the layout of the top-level graph
layout.setLayout(null, new GridLayout());
// specify the layout of subgraphs
layout.setLayout(subgraph1, new TreeLayout());
layout.setLayout(subgraph2, new BusLayout());
// perform the layout
LayoutReport report = layout.performLayout(true, true); 
In this scenario, there is no reference layout. All layout parameters of different subgraphs are independent. You access the layout instance of each individual subgraph in order to change global layout parameters for this subgraph as well as parameters of nodes and links of the subgraph. For instance, if the attached top-level graph contains two subgraphs, and node1 belongs to subgraph1 and node2 belongs to subgraph2, you can set individual global and local layout parameters in this way:
// access the layout of the top-level graph
GridLayout gridLayout = (GridLayout)layout.getLayout(null);
gridLayout.setLayoutMode(GridLayout.TILE_TO_COLUMNS);
// access the layouts of the subgraph
TreeLayout treeLayout = (TreeLayout)layout.getLayout(subgraph1);
treeLayout.setFlowDirection(Direction.Left);
treeLayout.setAlignment(node1, TreeLayout.TIP_OVER);
BusLayout busLayout = (BusLayout)layout.getLayout(subgraph2);
busLayout.setOrdering(BusLayout.ORDER_BY_HEIGHT);
busLayout.setBus(node2);

Notes:

  • The normal layout algorithms such as ibm_ilog.graphlayout.hierarchical.HierarchicalLayout, ibm_ilog.graphlayout.tree.TreeLayout, ibm_ilog.graphlayout.MultipleLayout, and so forth work only on a flat graph, but for convenience, you can apply ibm_ilog.graphlayout.GraphLayout.performLayout() with the traverse flag set to true. This does not mean that the normal layout instance works on the entire nested graph including the subgraphs in this case. In fact, internally it uses a Recursive Layout in reference layout mode, that is, a clone of the top-level graph layout instance is created for each subgraph, and these clones are applied recursively to the nested graph. Each clone still treats only a flat graph.
  • It is not possible to create a Recursive Layout that has a Recursive Layout as reference layout:
    layout = new RecursiveLayout(new RecursiveLayout()); 
    This calls the copy constructor of the Recursive Layout, but does not create a Recursive Layout in reference layout mode. A Recursive Layout inside another Recursive Layout would traverse the nested graph and perform the Recursive Layout for each subgraph, which, however, itself would recursively traverse the nested graph again. This would just be waste of run time.
  • The layout event listeners installed at the Recursive Layout receive layout events whenever the layout of a subgraph fires a layout event. These events, however, do not contain the information on which sublayout was started or finished. If you need this information, you should install an event listener at all sublayouts.
  • If you want to combine MultipleLayout and RecursiveLayout, you should use RecursiveMultipleLayout, in particular when you use explicitly specified labeling models. The Recursive Layout that has a Multiple Layout as the reference layout works as long as default labeling models (instances of ibm_ilog.graphlayout.label.DefaultLabelingModel) are used. The Recursive Multiple Layout is more flexible; it is in principle a Recursive Layout that has instances of Multiple Layout as sublayouts for the subgraphs. Additionally, the Recursive Multiple Layout ensures that the correct labeling models (clones of the specified labeling model) are created in the nested graph.

ParameterTypeDescription
layoutibm_ilog.graphlayout.GraphLayout:If the given layout is a recursive layout, this constructor creates a new layout instance by copying the given one. If this is another layout, this constructor creates a new instance of the Recursive Layout algorithm that allows you to apply the reference layout to the entire nested graph.
layoutProvideribm_ilog.graphlayout.ILayoutProvider:Allows to specify a different layout style or individual layout parameters to each subgraph of the nested graph. When this parameter is specified, the layout mode of this Recursive Layout is SPECIFIED_PROVIDER_MODE.
RecursiveLayoutProvider

The internal layout provider used by the Recursive Layout in internal provider mode.

The provider behaves like the ibm_ilog.graphlayout.DefaultLayoutProvider except that RecursiveLayoutProvider.getGraphLayout() returns null for a graph model that has no preferred layout. It does not clone the layout instance of the closest parent graph for which a layout has been set. This allows you to specify null as the preferred layout for those subgraphs that should not be laid out at all.

If you allocate an instance of RecursiveLayoutProvider explicitly, you must call the method ibm_ilog.graphlayout.DefaultLayoutProvider.detachLayouts() when you no longer need the layout provider instance; otherwise, some objects may not be garbage collected. However ibm_ilog.graphlayout.DefaultLayoutProvider.detachLayouts() is automatically called for the internal layout provider of the Recursive Layout when the Recursive Layout is detached.

RecursiveLayoutReport
The class used to store information about the behavior of the Recursive Layout algorithm.
RecursiveMultipleLayout

The main class for the Recursive Multiple Layout algorithm.

This is not a layout algorithm but rather a facility to perform multiple layouts recursively in a nested graph. In principle, this is just the combination of Recursive Layout and Multiple Layout.

Unless otherwise mentioned, the normal layout algorithms such as ibm_ilog.graphlayout.hierarchical.HierarchicalLayout, ibm_ilog.graphlayout.tree.TreeLayout, ibm_ilog.graphlayout.MultipleLayout, and so forth work on a flat graph, that is, they lay out the attached graph but not the subgraphs of the attached graph. Similarly, label layout algorithms work only on flat managers, not on nested graphs. The Recursive Multiple Layout is different: it traverses the nesting structure starting from the attached graph and recursively applies a first graph layout, then a second graph layout, and finally a label layout on all subgraphs. It can be tailored for which sublayouts have to be applied to which subgraph.

The Recursive Multiple Layout is a Recursive Layout (see RecursiveLayout) where all layouts of subgraphs are Multiple Layouts (see ibm_ilog.graphlayout.MultipleLayout).

For instance, assume that you want to apply to each subgraph a Tree layout, then a Link layout for the nontree links, and finally a Label layout for the link labels. It would be unfortunate to call ibm_ilog.graphlayout.GraphLayout.performLayout() multiple times to achieve this, because the tree layout of the parent graph would be finished before the link layout of its subgraph has started; hence the link layout of the subgraph invalidates the tree layout of the parent graph again. To avoid this effect, the Tree layout, Link layout, and Label layout of the subgraph should be finished before any layout of the parent graph has started. The following examples shows how to achieve this by using the Recursive Multiple Layout class. There are basically two scenarios:

  • The same set of layout algorithms must be applied to all subgraphs.
  • An individual layout style must be applied to each subgraph.
First scenario: Same layout styles everywhere

To perform a Tree Layout, a Link Layout, and an Annealing Label Layout on a nested graph, call:

GraphLayout layout = new MultipleRecursiveLayout(
new TreeLayout(),
new LinkLayout(),
new AnnealingLabelLayout());
layout.attach(grapher);
layout.performLayout(true, true); 
If you simply want to apply a label layout in a nested grapher, call:

GraphLayout layout = new MultipleRecursiveLayout(
new AnnealingLabelLayout());
layout.attach(grapher);
layout.performLayout(true, true);

In this case, each subgraph is treated bottom-up. First a tree layout is performed on the subgraph. Then a link layout is performed on the subgraph, finally the label layout is performed on the subgraph. All subgraphs of the nested graph including the top-level graph are treated in this way. All layouts are performed with the same global layout parameters as the layout instances passed as arguments to the constructor of RecursiveMultipleLayout, which are called the reference layouts. You can access the reference layout instances to change the global layout parameters:

TreeLayout treeLayout =
(TreeLayout)layout.getFirstReferenceGraphLayout();
treeLayout.setFlowDirection(Direction.Left);
LinkLayout linkLayout =
(LinkLayout)layout.getSecondReferenceGraphLayout();
linkLayout.setLinkOffset(5f);
AnnealingLabelLayout labelLayout =
(AnnealingLabelLayout)layout.getReferenceLabelLayout();
labelLayout.setObstacleOffset(20f); 
Internally, a clone of the reference instance is created for each subgraph. This clone remains attached as long as the Recursive Multiple Layout is attached to the top-level graph. Before layout is performed, the global layout parameters are copied from the reference instance to each clone. If you need to set layout parameters for individual nodes, links, or labels, you have to access the layout instance of the subgraph that owns the node, link, or label:
TreeLayout treeLayout = (TreeLayout)layout.getFirstGraphLayout(subgraph);
treeLayout.setAlignment(node, TreeLayout.TIP_OVER);
LinkLayout linkLayout = (LinkLayout)layout.getSecondGraphLayout(subgraph);
linkLayout.setLinkStyle(link, LinkLayout.ORTHOGONAL_STYLE);
AnnealingLabelLayout labelLayout = (AnnealingLabelLayout)layout.getLabelLayout(subgraph);
labelLayout.setLabelDescriptor(label, descriptor); 

In the typical case, when you use instances of Graphic as nodes and instances of Grapher as subgraphs, it is:

TreeLayout treeLayout = (TreeLayout)layout.getFirstGraphLayout(node.getGraphicBag());
treeLayout.setAlignment(node, TreeLayout.TIP_OVER);
... 

Second scenario: Different layout styles at different subgraphs

The following example shows the second scenario: Each subgraph should be laid out by a different layout style or with individual layout parameters. In this case, there are no reference layouts. You specify the layouts of subgraphs in a very convenient way:

RecursiveMultipleLayout layout = new RecursiveMultipleLayout();
layout.attach(topLevelGrapher);
// specify the layout of the top-level graph
layout.setLayout(null, new GridLayout(),
new LinkLayout(),
new RandomLabelLayout());
// specify the layout of subgraphs
layout.setLayout(subgraph1, new TreeLayout(),
new LinkLayout(),
new AnnealingLabelLayout());
layout.setLayout(subgraph2, new HierarchicalLayout(),
new LinkLayout(),
new AnnealingLabelLayout());
// perform the layout
LayoutReport report = layout.performLayout(true, true); 
In this scenario, all layout parameters of different subgraphs are independent. You access the layout instance of each individual subgraph in the same way as when you have a reference layout. This allows you to change global layout parameters for this subgraph as well as parameters of nodes , links, or labels of the subgraph.

Notes:

  • The Recursive Multiple Layout does not support the specified provider mode of RecursiveLayout.
  • It is not allowed to create a Recursive Layout that contains another Recursive Layout:
    layout = new RecursiveLayout(new RecursiveMultipleLayout());
    layout.performLayout(true, true);
    
    This would traverse the nested graph and perform the Recursive Layout for each subgraph, which, however, itself would recursively traverse the nested graph again. This would just be waste of run time.
  • The layout event listeners installed at the Recursive Multiple Layout receive layout events whenever the layout of a subgraph fires a layout event. These events, however, do not contain the information on which sublayout was started or finished. If you need this information, you should install an event listener at all sublayouts.
  • The reference labeling model cannot be saved to named properties via ibm_ilog.graphlayout.AbstractGraphLayoutModel.saveParametersToNamedProperties().

ParameterTypeDescription
a0
a1
SplineLinkFilter

SplineLinkFilter is used by the layout algorithms that support optimized spline routing. Its purpose is to detect which objects are splines so that the optimized spline routing is only applied to splines, and not to normal polyline links.