ibm_ilog.graphlayout
Property Summary
- 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
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
Methods
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.
Parameter | Type | Description |
---|---|---|
source |
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.
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(); ... }
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)
.
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:
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 getBox(graphModel, node) { var bbox = graphModel.boundingBox(node); bbox.x -= 10; bbox.y -= 10; bbox.width += 20; bbox.height += 20; return bbox; }
function getTangentialOffset(graphModel, node, nodeSide) { switch (nodeSide) { case ibm_ilog.graphlayout.Direction.LEFT: case ibm_ilog.graphlayout.Direction.RIGHT: return -10; default: return 0; } }
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; }
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.
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.
Parameter | Type | Description |
---|---|---|
a0 | ||
a1 |
The class used to store information about the behavior of the Multiple Layout algorithm. It stores the layout reports of its sublayouts.
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.
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 applyibm_ilog.graphlayout.GraphLayout.performLayout()
with thetraverse
flag set totrue
. 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
andRecursiveLayout
, you should useRecursiveMultipleLayout
, 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 ofibm_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.
Parameter | Type | Description |
---|---|---|
layout | ibm_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. |
layoutProvider | ibm_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. |
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.
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.
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()
.
Parameter | Type | Description |
---|---|---|
a0 | ||
a1 |