Base class parameters and features

The ibm_ilog.graphlayout.GraphLayout class defines a number of generic features and parameters. These features and parameters can be used to customize the layout algorithms.
Although the GraphLayout class defines the generic parameters, it does not control how they are used by its subclasses. Each layout algorithm (that is, each subclass of GraphLayout) supports a subset of the generic features and determines the way in which it uses the generic parameters. When you create your own layout algorithm by subclassing GraphLayout, you decide whether you want to use the features and the way in which you are going to use them.
The GraphLayout class defines the following generic features:
Support by algorithms of generic features and parameters provides a summary of the generic parameters supported by each layout algorithm. If you are using one of the subclasses provided with the graph layout API, check the documentation for that subclass to know whether it supports a specific parameter and how it interprets the parameter.

Allowed time

Several layout algorithms can be designed to stop computation when a user-defined time specification is exceeded. It can be done for different reasons: for security to avoid a long computation time on large graphs, or as an upper limit for algorithms that iteratively improve a current solution and have no other criteria to stop the computation.
Example of specifying allowed time
To specify that the layout is allowed to run for 60 seconds:
Call:
layout.setAllowedTime(60000); 
The time is in milliseconds. The default value is 32000 (32 seconds).
If you subclass ibm_ilog.graphlayout.GraphLayout, use the following method to know whether the specified time was exceeded:
layout.isLayoutTimeElapsed();
To indicate whether a subclass of GraphLayout supports this mechanism, use the method:
layout.supportsAllowedTime();
The default implementation returns false. A subclass can override this method to return true to indicate that this mechanism is supported.

Layout of connected components

The base class ibm_ilog.graphlayout.GraphLayout provides generic support for the layout of a disconnected graph (composed of connected components).
Example of layout
To enable the placement of disconnected graphs:
Call:
layout.setLayoutOfConnectedComponentsEnabled(true);
Note
Some of the layout classes (HierarchicalLayout, CircularLayout) have a built-in algorithm for placing connected components. This algorithm is enabled by default and fits the most common situations. For this layout class, the generic mechanism provided by the base class GraphLayout is disabled by default.
When enabled, a default instance of the class ibm_ilog.graphlayout.grid.GridLayout is used internally to place the disconnected graphs. If necessary, you can customize this layout.
Example of customizing layout
To customize this layout:
Call:
var gridLayout = new ibm_ilog.graphlayout.grid.GridLayout();
gridLayout.setLayoutMode(ibm_ilog.graphlayout.grid.GridLayout.TILE_TO_ROWS);
gridLayout.setTopMargin(20);
layout.setLayoutOfConnectedComponents(gridLayout);

Example for experts
The various capabilities of the class ibm_ilog.graphlayout.grid.GridLayout cover most of the likely needs for the placement of disconnected graphs. If necessary, you can write your own subclass of ibm_ilog.graphlayout.GraphLayout to place disconnected graphs and specify it instead of GridLayout:
Call:
var myGridLayout = new MyGridLayout();
// settings for myGridLayout, if necessary
layout.setLayoutOfConnectedComponents(myGridLayout);
To indicate whether a subclass of GraphLayout supports this mechanism, use the method:
layout.supportsLayoutOfConnectedComponents();
The default implementation returns false. You can write a subclass to override this behavior.

Layout region

Some layout algorithms can control the size of the graph drawing and can take into account a user-defined layout region.
Example of specifying layout region
To specify a region of 100 by 100:
layout.setLayoutRegion({x:0, y:0, width:100, height:100});
To access the layout region, use the method:
var rect = layout.getSpecLayoutRegion();  
This method returns a copy of the rectangle that defines the specified layout region.
The layout algorithms call a different method:
var rect = layout.getCalcLayoutRegion();  
This method first tries to use the layout region specification by calling the method ibm_ilog.graphlayout.GraphLayout.getSpecLayoutRegion. If this method returns a non-null rectangle, this rectangle is returned. Otherwise, the method tries to estimate an appropriate layout region according to the number and size of the nodes in the attached graph. If no graph is attached, or the attached graph is empty, it returns a default rectangle {x:0, y:0, width:1000, height:1000}.
To indicate whether a subclass of GraphLayout supports the layout region mechanism, use the method:
layout.supportsLayoutRegion(); 
The default implementation returns false. A subclass can override this method in order to return true to indicate that this mechanism is supported.
Note
The implementation of the method ibm_ilog.graphlayout.GraphLayout.layout() is solely responsible for whether the layout region is taken into account when calculating the layout, and in which manner. For details, refer to the documentation of the layout algorithms.

Link connection box

If a layout algorithm calculates specific connection points, it places the connection points of links by default at the border of the bounding box of the nodes symmetrically with respect to the middle of each side. Sometimes it can be necessary to place the connection points on a rectangle smaller or larger than the bounding box, possibly asymmetrically. For example, connection points can be placed asymmetrically when labels are displayed above or below nodes. See Effect of link connection box interface. It can be achieved by specifying a link connection box interface. The link connection box interface allows you to specify for each node a node box different from the bounding box that is used to connect the links to the node.
Example of link connection box interface
To set a link connection box interface, call:
layout.setLinkConnectionBoxInterface(provider);
You implement the link connection box interface by defining a class that implements the ibm_ilog.graphlayout.ILinkConnectionBoxProvider. This interface defines the following method:
getBox(graphModel, node)    
This method allows you to return the effective rectangle on which the connection points of the links are placed.
A second method defined on the interface allows the connection points to be “shifted” tangentially, in a different way for each side of each node:
getTangentialOffset(graphModel, node, nodeSide)  
How the interfaces are used and which connection points are the final result are specific to each layout algorithm.
Hierarchical Layout, Tree Layout, and Short and Long Link Layouts use the link connection box to define the box of the node where links should be attached.
The following figure shows the effects of customizing the connection box. On the left is the result without any link connection box interface. On the right is the result that shows the effect when the link connection box interface returns the dashed rectangle for the blue node.
Two graphs,
one on the left and one on the right, that show the effect of the
link connection box or link connection box provider interface.
Effect of link connection box interface
Circular Layout, Random Layout, and Force-directed Layout do not spread out links at the node border, but can route links to point to the node center.
If a node has an irregular shape, the links should sometimes not point towards the center of the node bounding box, but to a virtual center inside the node. The link connection box interface can be used to define the virtual node center. The following figure shows an example of the effect.
Picture
illustrating the effect of the link connection box in combination
with link clipping
Combined effect of link clipping interface and link connection box
If the links are clipped at the irregular green star node on the left of the figure, they will not point toward the center of the star, but toward the center of the bounding box of the node. You can correct this effect by specifying a link connection box interface that returns a smaller node box than the bounding box, such as shown on the right of the figure. Alternatively, the problem could be corrected by specifying a link connection box interface that returns the bounding box as the node box, but with additional tangential offsets that shift the virtual center of the node.
For example, to set a link connection box interface that returns a link connection rectangle that is smaller than the bounding box for all nodes of type MyNode and shifts up the connection points on the left and right of all the nodes, call:
dojo.declare('MyLinkConnectionBoxProvider', 
 ibm_ilog.graphlayout.ILinkConnectionBoxProvider,
{
 getBox: function(graphModel, node)
 {
  var rect:Rectangle = graphModel.getBounds(node);
  if (node is MyNode) {
     // for example, the size of the bounding box is reduced:
     rect.x += 4;
     rect.y += 4;
     rect.width -= 8;
     rect.height -= 8;
    }
    return rect;
   }
   getTangentialOffset: function(graphModel, node, side)
   {
     switch (side) {
      case ibm_ilog.graphlayout.Direction.LEFT:
      case ibm_ilog.graphlayout.Direction.RIGHT:
       return -10; // shift up with 10 for both left and right side
      case ibm_ilog.graphlayout.Direction.TOP:
      case ibm_ilog.graphlayout.Direction.BOTTOM:
      default:
       return 0; // no shift for top and bottom side
     }
    }
});
layout.setLinkConnectionBoxProvider(new MyLinkConnectionBoxProvider());

To indicate whether a subclass of ibm_ilog.graphlayout.GraphLayout supports the link connection box provider interface, use the method ibm_ilog.graphlayout.GraphLayout.supportsLinkConnectionBox().
The default implementation returns false. You can write a subclass to override this method to return true to indicate that this mechanism is supported.

Percentage of completion calculation

Some layout algorithms can provide an estimation of how much of the layout has been completed. This estimation is made available as a percentage value that is stored in the graph layout report. When the algorithm starts, the percentage value is set to 0. The layout algorithm calls the following method from time to time to increase the percentage value by steps until it reaches 100:
layout.increasePercentageComplete(newPercentage);  
The percentage value can be accessed from the layout report by using the following method:
var percentage = layoutReport.getPercentageComplete(); 
To indicate whether a subclass of ibm_ilog.graphlayout.GraphLayout supports this mechanism, use the method:
layout.supportsPercentageComplete(); 
The default implementation returns false. A subclass can override this method to return true to indicate that this mechanism is supported.

Preserve fixed links

Sometimes, you want some links of the graph to be “pinned” (that is, to stay in their current shape when the layout is performed). You want a way to indicate the links that the layout algorithm cannot reshape. It makes sense especially when using a semiautomatic layout (the method where the user fine-tunes the layout by hand after the layout is completed) or when using an incremental layout (the method where the graph, the shape of the links, or both are modified after the layout has been performed, and then the layout is performed again).
Example of fixing links
To specify that a link is fixed:
Use the method:
layout.setFixed(link, fixed);  
If the fixed parameter is set to true, it means that the link is fixed. To obtain the current setting for a link:
layout.isFixed(link);  
The default value is false.
To remove the fixed attribute from all links in the graph, use the method:
layout.unfixAllLinks();   
The fixed attributes on links are considered only if you additionally call the following statement:
layout.setPreserveFixedLinks(true);
To indicate whether a subclass of GraphLayout supports this mechanism, use the method:
layout.supportsPreserveFixedLinks(); 
The default implementation returns false. A subclass can override this method to return true to indicate that this mechanism is supported.

Preserve fixed nodes

At times, you might want some nodes of the graph to be “pinned” (that is, to stay in their current position when the layout is performed). You need a way to indicate the nodes that the layout algorithm cannot move. It makes sense especially when using a semiautomatic layout (the method where the user fine-tunes the layout by hand after the layout is completed) or when using an incremental layout (the method where the graph, the position of the nodes, or both are modified after the layout has been performed, and then the layout is performed again).
Example of fixing nodes
To specify that a node is fixed:
Use the method:
layout.setFixed(node, fixed); 
If the fixed parameter is set to true, it means that the node is fixed. To obtain the current setting for a node:
layout.isFixed(node); 
The default value is false.
To remove the fixed attribute from all nodes in the graph, use the method:
layout.unfixAllNodes();  
The fixed attributes on nodes are considered only if you also call:
layout.setPreserveFixedNodes(true);
To indicate whether a subclass of GraphLayout supports this mechanism, use the method:
layout.supportsPreserveFixedNodes(); 
The default implementation returns false. A subclass can override this method to return true to indicate that this mechanism is supported.

Stop immediately

Several layout algorithms can stop computation when an external event occurs, for instance when the user presses a “Stop” button.
To stop the layout, you can call:
layout.stopImmediately();  
The method returns true if the stop was initiated and false if the algorithm cannot stop. The method returns immediately, but the layout thread usually needs some additional time after initiating the stop to clean up data structures.
The consequences of stopping a layout process depend on the specific layout algorithm. Some layout algorithms have an iterative nature. Stopping the iteration process results in a slight loss of quality in the drawing, but the layout can still be considered valid. Other layout algorithms have a sequential nature. Interrupting the sequence of the layout steps might not result in a valid layout. Usually, these algorithms return to the situation before the start of the layout process.
To indicate whether a subclass of GraphLayout supports this mechanism, use the method:
layout.supportsStopImmediately(); 
The default implementation returns false. You can write a subclass to override this method in order to return true to indicate that this mechanism is supported.