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).
For details, see Laying out connected components of a disconnected graph.
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.

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.

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.