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

ibm_ilog.graphlayout.RecursiveLayout

Object » ibm_ilog.graphlayout.GraphLayout » ibm_ilog.graphlayout.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.

Property Summary

Method Summary

  • afterLayoutOfSubgraph(subgraph) Performs postprocessing operations after the layout of each subgraph or connected component.
  • attach(graphModel) Allows you to specify the top-level graph model of the nested graph you want to lay out.
  • beforeLayout() Performs preprocessing operations before the layout of the entire graph.
  • beforeLayoutOfSubgraph(subgraph) Performs preprocessing operations before the layout of each subgraph or connected component.
  • callLayoutStepPerformedIfNeeded() Calls 'onLayoutStepPerformed' when necessary.
  • cleanGraphModel(graphModel) Cleans a graph model.
  • cleanLink(graphModel, link) Cleans a link.
  • cleanNode(graphModel, node) Cleans a node.
  • connectAllLinksToCenter() Connects all links to the enter of their end nodes.
  • connectLinkToCenter(link, atFromSide, atToSide) Connects the link to the node center at both end nodes by using the link connection box interface.
  • constructor(layout, layoutProvider) Creates a new instance of the Recursive Layout algorithm that allows you to apply layouts to the entire nested graph.
  • contentsChanged(event) Called when the structure or the geometry of the graph changes.
  • copy() returns ibm_ilog.graphlayout.GraphLayout Copies the layout instance.
  • copyParameters(source) Copies the parameters from a given layout instance.
  • createLayoutReport() returns ibm_ilog.graphlayout.GraphLayoutReport Returns a new instance of the layout report.
  • detach() Detaches the graph model from the layout instance.
  • getAllowedTime() returns Number Returns the currently allowed time for the layout algorithm in milliseconds.
  • getBalanceSplineCurveThreshold() returns Number Returns the threshold for spline curves at bends which the optimized spline control point routing uses to balance the curve.
  • getCalcLayoutRegion() returns Rectangle Returns a copy of the rectangle that defines the layout region parameter.
  • getGraphModel() returns ibm_ilog.graphlayout.AbstractGraphLayoutModel Returns the graph model to lay out if a graph model is attached.
  • getInstanceId() returns int A utility method that returns a unique integer value for each layout instance.
  • getLayout(subgraph) returns ibm_ilog.graphlayout.GraphLayout Returns the layout instance to be used for the input subgraph.
  • getLayoutMode() returns int Returns the layout mode of the Recursive Layout.
  • getLayoutOfConnectedComponents() returns ibm_ilog.graphlayout.GraphLayout Returns the layout instance that lays out the connected components of the graph.
  • getLayoutOfConnectedComponentsReport() returns ibm_ilog.graphlayout.GraphLayoutReport Returns the layout report containing information about the behavior of the connected components layout.
  • getLayoutProvider() returns ibm_ilog.graphlayout.ILayoutProvider Returns the layout provider.
  • getLayoutRegion() Returns a copy of the rectangle that defines the layout region, as specified using the method ' ibm_ilog.graphlayout.GraphLayout.layoutRegion', or 'null' if no rectangle has been specified, or the specified rectangle was 'null'.
  • getLayoutRegionMode() Gets the layout region mode.
  • getLayoutReport() returns ibm_ilog.graphlayout.GraphLayoutReport Returns the layout report, that is, the object that contains information about the behavior of the layout algorithm.
  • getLayouts(preOrder) returns ibm_ilog.graphlayout.IIterator Returns the instances of 'GraphLayout' for the nested graph encapsulated by the graph model of this layout instance.
  • getLinkConnectionBoxInterface() returns ibm_ilog.graphlayout.ILinkConnectionBoxProvider Returns the link connection box interface used to calculate the connection points of links during layout.
  • getMaxSplineCurveSize() returns Number Returns the maximum curve size used when spline control point optimization routing is enabled.
  • getMinBusyTime() returns Number Returns the minimal time that the layout algorithm can be busy between two calls of ' ibm_ilog.graphlayout.GraphLayout.onLayoutStepPerformed()' when the method ' ibm_ilog.graphlayout.GraphLayout.callLayoutStepPerformedIfNeeded()' is used.
  • getMinSplineCurveSize() returns Number Returns the minimum curve size used when optimized spline control points routing is enabled.
  • getObjectParameter(graphModel, nodeOrLink, key) returns Object Returns the value of a parameter of the layout instance.
  • getParameter(key) returns Object Returns the value of a parameter of the layout instance.
  • getParentLayout() returns ibm_ilog.graphlayout.GraphLayout Returns the parent layout.
  • getRecursiveLayout() returns ibm_ilog.graphlayout.RecursiveLayout Returns the instance of Recursive Layout that is used to perform this layout recursively when you call ' ibm_ilog.graphlayout.GraphLayout.performLayout()' with the traverse flag set to 'true'.
  • getReferenceLayout() returns ibm_ilog.graphlayout.GraphLayout Returns the reference layout if the reference layout mode is used; returns 'null' otherwise.
  • getRemainingAllowedTime() returns Number Returns the remaining allowed time.
  • getSeedValueForRandomGenerator() returns Number Returns the user-defined seed value for the random generator.
  • getSpecLayoutRegion() returns Rectangle Returns a copy of the rectangle that defines the layout region, as specified using the method ' ibm_ilog.graphlayout.GraphLayout.layoutRegion'.
  • getSplineLinkFilter() returns ibm_ilog.graphlayout.SplineLinkFilter Returns the filter that detects which links are suitable for optimized spline routing.
  • getSubgraphCorrectionInterface() returns ibm_ilog.graphlayout.ISubgraphCorrection Returns the subgraph correction interface that is applied after the nodes and links of the subgraph were laid out.
  • getSubgraphLayoutReport(subgraph) returns ibm_ilog.graphlayout.GraphLayoutReport Returns the report of the graph layout of the input subgraph.
  • getViewMatrix() Returns the matrix that is applied to the first view attached to this layout.
  • increasePercentageComplete(newPercentage) Increases the percentage of completion that is stored in the layout report to the input value.
  • init() Initializes instance variables.
  • isFitToViewEnabled() returns Boolean Returns 'true' if the graph drawing must fit (exactly or approximately) an area of a specific view.
  • isFixed(nodeOrLink) returns Boolean Returns whether the node or link is specified as fixed.
  • isGeometryUpToDate() returns Boolean Returns 'false' if at least one node or link was moved or reshaped since the last time the layout was successfully performed on the same graph or if the layout has never been performed successfully on the same graph.
  • isInputCheckEnabled() returns Boolean Returns 'true' if the checks for the nodes and/or links are enabled.
  • isLayoutNeeded() returns Boolean Verifies that it is necessary to perform the layout.
  • isLayoutOfConnectedComponentsEnabled() returns Boolean Indicates whether the connected component layout mechanism is enabled.
  • isLayoutOfConnectedComponentsEnabledByDefault() returns Boolean Returns 'true' if the connected components layout mechanism is enabled by default.
  • isLayoutRunning(checkParents) returns Boolean Indicates whether this layout algorithm is running or not.
  • isLayoutTimeElapsed() returns Boolean Returns 'true' if, at the moment the method is called, the allowed layout time is exceeded; returns 'false' otherwise.
  • isLinkClipping() Gets whether links should be clipped at the shape of the end nodes.
  • isLocalRecursiveLayoutNeeded(layoutProvider, recLayout, rootModel, traverse) returns Boolean Checks whether layout is needed when layout is performed recursively on a hierarchy of nested subgraphs.
  • isParametersUpToDate() returns Boolean Returns 'false' if at least one parameter was modified since the last time the layout was successfully performed on the same graph or if the layout has never been performed successfully on the same graph.
  • isPreserveFixedLinks() returns Boolean Returns 'true' if the layout is not allowed to reshape the links indicated as fixed by the user.
  • isPreserveFixedNodes() returns Boolean Returns 'true' if the layout is not allowed to move the nodes indicated as fixed by the user.
  • isSplineRoutingEnabled() returns Boolean Tests whether the calculation of optimized spline control points is enabled.
  • isStoppedImmediately() returns Boolean Returns 'true' if the method ' ibm_ilog.graphlayout.GraphLayout.stopImmediately()' was called.
  • isStructureUpToDate() returns Boolean Returns 'false' if at least one modification occurred in the structure of the graph since the last time the layout was successfully performed on the same graph or if the layout has never been performed successfully on the same graph.
  • isUseSeedValueForRandomGenerator() returns Boolean Returns 'true' if the user-defined seed value is used for the random generator and 'false' otherwise.
  • layout() Computes the layout using the Recursive Layout algorithm.
  • performLayout(force, traverse) returns int This is different from the implementation of the base class; the Recursive Layout always ignores the <code>traverse</code> flag because the layout is always done recursively.
  • performSubgraphLayout(subgraph, force, traverse) Starts the layout algorithm with a subgraph.
  • performSublayout(subgraph, layout, force) Starts the input layout algorithm.
  • propagateLayoutOfConnectedComponents(layout) Sets the layout instance to lay out the connected components of all subgraphs having a main layout that supports the connected component layout mechanism.
  • propagateLayoutOfConnectedComponentsEnabled(enable) Enables the connected component layout mechanism for all layouts of subgraphs that support this feature.
  • propagateLinkConnectionBoxInterface(linkConnectionBoxInterface) Sets the link connection box interface for the connection points of links on all layouts of subgraphs that support this feature.
  • setAllowedTime(time) Sets the upper limit for the duration of the layout algorithm.
  • setAutoCheckAppropriateLinksEnabled(enable) returns Boolean Sets whether the layout checks whether links are appropriate.
  • setBalanceSplineCurveThreshold(threshold) Sets the threshold for spline curves at bends which the optimized spline control point routing uses to balance the curve.
  • setFixed(nodeOrLink, fixed) Sets the specified node or link as fixed.
  • setGeometryUpToDate(uptodate) Sets whether the geometry of the graph is up to date.
  • setGraphModel(graphModel) Sets the graph model to be laid out.
  • setInputCheckEnabled(enable) Sets whether checks are enabled for the nodes, links, and/or labels provided as arguments for the different methods of this layout algorithm and its sublayout algorithms.
  • setLayout(subgraph, layout) Sets the layout instance to be used for the input subgraph.
  • setLayoutImpl(subgraph, layout, detachPrevious, traverse) Sets the layout instance to be used for the input subgraph.
  • setLayoutOfConnectedComponents(layout) Sets the layout instance that lays out the connected components of the graph.
  • setLayoutOfConnectedComponentsEnabled(enable) Sets whether the generic connected component layout mechanism is enabled.
  • setLayoutRegion(rect) Sets the layout region as a rectangle 'rect'), with the dimensions of the rectangle being given in container (graph model) coordinates.
  • setLayoutRegionMode(value) Sets the layout region mode.
  • setLayoutReport(report) Sets the layout report, that is, the object that contains information about the behavior of the layout algorithm.
  • setLayoutRunning(running, fromParents) Sets whether layout is running.
  • setLinkClipping(value) Sets whether links should be clipped at the shape of the end nodes.
  • setLinkConnectionBoxInterface(linkConnectionBoxInterface) Sets the link connection box interface for the connection points of links.
  • setMaxSplineCurveSize(size) Sets the maximum curve size used when optimized spline control point routing is enabled.
  • setMinBusyTime(time) Sets the minimal time the layout algorithm can be busy between two calls of ' ibm_ilog.graphlayout.GraphLayout.onLayoutStepPerformed()' when the method ' ibm_ilog.graphlayout.GraphLayout.callLayoutStepPerformedIfNeeded()' is used.
  • setMinSplineCurveSize(size) Sets the minimum curve size used when optimized spline control point routing is enabled.
  • setObjectParameter(graphModel, nodeOrLink, key, value) returns Object Sets the value of a parameter for a node or a link, using a given graph model.
  • setParameter(key, value) returns Object Sets the value of a property for the layout instance.
  • setParametersUpToDate(uptodate) Sets whether the parameters of the graph layout are up to date.
  • setParentLayout(parent) Sets the parent layout of this layout instance.
  • setPreserveFixedLinks(option) Sets whether the layout avoids movement of fixed links.
  • setPreserveFixedNodes(option) Sets whether the layout avoids movement of fixed nodes.
  • setSeedValueForRandomGenerator(seed) Sets the seed value for the random generator.
  • setSplineLinkFilter(filter) Sets the filter that detects which links are suitable for optimized spline routing.
  • setSplineRoutingEnabled(flag) Sets whether the calculation of optimized spline control points is enabled.
  • setStructureUpToDate(uptodate) Sets whether the structure of the graph is up to date.
  • setSubgraphCorrectionInterface(ifc) Sets the correction strategy for subgraphs.
  • setUseSeedValueForRandomGenerator(option) Sets whether the user-defined seed value should be used for the random generator.
  • stopImmediately() returns Boolean Stops the running layout algorithm as soon as possible.
  • supportsAllowedTime() returns Boolean Indicates whether the layout class can stop the layout computation when a user-defined allowed time is exceeded.
  • supportsLayoutOfConnectedComponents() returns Boolean Indicates whether the layout class can cut the attached graph into connected components, apply itself on each connected component separately, and then use the layout instance returned by the method ' ibm_ilog.graphlayout.GraphLayout.getLayoutOfConnectedComponents()' to position the connected components.
  • supportsLayoutRegion() returns Boolean Indicates whether the layout class can control the position and/or size of the graph drawing according to a user-defined region (a rectangle) or a user-defined area of a manager view.
  • supportsLinkConnectionBox() returns Boolean Indicates whether the layout class can use a link connection box interface to calculate the end points of a link.
  • supportsPercentageComplete() returns Boolean Indicates whether the layout class can estimate the percentage of completion during the run of the layout.
  • supportsPreserveFixedLinks() returns Boolean Indicates whether the layout class allows the user to specify fixed links.
  • supportsPreserveFixedNodes() returns Boolean Indicates whether the layout class allows the user to specify fixed nodes.
  • supportsRandomGenerator() returns Boolean Indicates whether the layout class uses randomly generated numbers (or randomly chosen parameters) for which it can accept a user-defined seed value.
  • supportsSplineRouting() returns Boolean Indicates whether the layout class supports the generic optimization of spline control points.
  • supportsStopImmediately() returns Boolean Indicates whether the layout class can immediately interrupt the current run of the layout in a controlled way.
  • toString() returns String Returns a printable string representing this layout instance.
  • unfixAllLinks() Removes the fixed attribute from all links in the graph model.
  • unfixAllNodes() Removes the fixed attribute from all nodes in the graph model.

Event Summary

Properties

DEFAULT_RECURSIVE_ALLOWED_TIME
INTERNAL_PROVIDER_MODE
Layout mode with internal layout provider.
REFERENCE_LAYOUT_MODE
Layout mode with reference layout.
SPECIFIED_PROVIDER_MODE
Layout mode with explicitly specified provider.

Methods

afterLayoutOfSubgraph

Performs postprocessing operations after the layout of each subgraph or connected component.

The default implementation does nothing. Subclasses can override this method to perform some cleanup operations when appropriate.

ParameterTypeDescription
subgraphibm_ilog.graphlayout.AbstractGraphLayoutModelSubgraph or connected component where layout has just been performed.
attach

Allows you to specify the top-level graph model of the nested graph you want to lay out.

In addition to the functionality of the base class, the Recursive Layout prepares and attaches the reference layout in layout mode RecursiveLayout.REFERENCE_LAYOUT_MODE.

ParameterTypeDescription
graphModelibm_ilog.graphlayout.AbstractGraphLayoutModelThe graph model.
beforeLayout

Performs preprocessing operations before the layout of the entire graph. This is called in each layout run once per graph.

The default implementation calls IGraphLayoutModel.beforeLayout(GraphLayout). Subclasses can override this method to perform some initialization operations when appropriate.

beforeLayoutOfSubgraph

Performs preprocessing operations before the layout of each subgraph or connected component. This method is called in each layout run once for each connected component.

The default implementation does nothing. Subclasses can override this method to perform some initialization operations when appropriate.

ParameterTypeDescription
subgraphibm_ilog.graphlayout.AbstractGraphLayoutModelSubgraph where layout is about to be performed.
callLayoutStepPerformedIfNeeded

Calls onLayoutStepPerformed when necessary.

This method is provided for convenience in the implementation of layout algorithms. It calls ibm_ilog.graphlayout.GraphLayout.onLayoutStepPerformed() when the last call finished earlier than the minimal busy time before this call. It avoids calling ibm_ilog.graphlayout.GraphLayout.onLayoutStepPerformed() when the layout time has elapsed or when the layout is notified to stop immediately, if the algorithm supports these features.

This mechanism is used by some algorithms to avoid the overhead of ibm_ilog.graphlayout.GraphLayout.onLayoutStepPerformed() becoming too high if it is called too often. Internal routines of layout algorithms can use this method often without worrying that too many layout events are raised.

Layout algorithms call ibm_ilog.graphlayout.GraphLayout.onLayoutStepPerformed() directly instead of using this method when it is necessary to report a specific state (for example, when the layout report sets the code GraphLayoutReport.LAYOUT_STARTED or GraphLayoutReport.LAYOUT_FINISHED).

cleanGraphModel

Cleans a graph model. This method removes any data that has been stored by the layout algorithm on a graph model.

Subclasses can override this method to remove additional information stored in the graph model.

ParameterTypeDescription
graphModelibm_ilog.graphlayout.AbstractGraphLayoutModelThe graph model to be cleaned.
cleanLink

Cleans a link. This method removes any data that has been stored by the layout algorithm on a regular link or on an intergraph link.

The method is automatically called by ibm_ilog.graphlayout.GraphLayout.contentsChanged() whenever a GraphLayoutModelEvent of type GraphLayoutModelEvent.LINK_REMOVED is received.

Subclasses can override this method to remove additional information stored in the links.

Notice that the method may be called multiple times for the same link. At the time this method is called, the link may already be removed; therefore, overridden versions of this method should be implemented so that they work even if the object is no longer a link of graphModel.

ParameterTypeDescription
graphModelibm_ilog.graphlayout.AbstractGraphLayoutModelThe graph model to which the 'link' belongs.
linkObjectThe link to be cleaned.
cleanNode

Cleans a node. This method removes any data that has been stored by the layout algorithm on a node.

The method is automatically called by ibm_ilog.graphlayout.GraphLayout.contentsChanged() whenever a GraphLayoutModelEvent of type GraphLayoutModelEvent.NODE_REMOVED is received.

Subclasses can override this method to remove additional information stored in the nodes.

Notice that the method may be called multiple times for the same node. At the time this method is called, the node may already be removed; therefore, overridden versions of this method should be implemented so that they work even if the object is no longer a node of graphModel.

ParameterTypeDescription
graphModelibm_ilog.graphlayout.AbstractGraphLayoutModelThe graph model to which the 'node' belongs.
nodeObjectThe node to be cleaned.
connectAllLinksToCenter

Connects all links to the enter of their end nodes. This method is provided for convenience in the implementation of layout algorithms. The method can be called by a layout algorithm to connect links to node centers after the end nodes are placed at their final positions and the link has its final shape.

If a link connection box is set, it uses the virtual center of the connection box instead of the center of the bounding boxes of the end nodes. The virtual center is defined as the center of the connection box shifted by the average of the tangential "top" and "bottom" offset in the horizontal direction and by the average of the tangential "left" and "right" offset in the vertical direction. For instance, if the tangential offset is 20 at the top side and 10 at all other sides, the average shift offset is (20 + 10)/2 = 15 in the horizontal direction and (10 + 10)/2 = 10 in the vertical direction; hence the virtual center is at connectionBox.center() + (15, 10).

redraw: Boolean Whether the links need to be redrawn.

connectLinkToCenter

Connects the link to the node center at both end nodes by using the link connection box interface. This method is provided for convenience in the implementation of layout algorithms. The method can be called by a layout algorithm to connect links to node centers after the end nodes are placed at their final positions and the link has its final shape.

If a link connection box is set, it uses the virtual center of the connection box instead of the center of the bounding boxes of the end nodes. The virtual center is defined as the center of the connection box shifted by the average of the tangential "top" and "bottom" offset in the horizontal direction and by the average of the tangential "left" and "right" offset in the vertical direction. For instance, if the tangential offset is 20 at the top side and 10 at all other sides, the average shift offset is (20 + 10)/2 = 15 in the horizontal direction and (10 + 10)/2 = 10 in the vertical direction; hence the virtual center is at connectionBox.center() + (15, 10).

ParameterTypeDescription
linkObjectThe link to be connected.
atFromSideBoolean'true' if the link should be connected at its source node.
atToSideBoolean'true' if the link should be connected at its target node. redraw: Boolean Whether the link needs to be redrawn.
constructor

If a layout instance is provided, this constructor creates a new recursive layout instance using the layout as a reference. In this case, the recursive layout mode is REFERENCELAYOUTMODE. If the given layout is a recursive layout, this constructor creates a new recursive layout instance by copying the given one. If a layout instance is not provided, but a layout provider is passed as parameter, the recursive layout instance will have a layout mode set to SPECIFIEDPROVIDERMODE. Therefore using the layout instances as specified by the layout provider. If neither the layout nor the layout provider are specified, the recursive layout instance created is set to INTERNALLAYOUTMODE.

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.
contentsChanged

Called when the structure or the geometry of the graph changes. This method is the implementation of the ibm_ilog.graphlayout.GraphModelListener interface.

ParameterTypeDescription
eventibm_ilog.graphlayout.GraphLayoutModelEventThe event which describes the change that has occurred in the graph model.
copy
Returns ibm_ilog.graphlayout.GraphLayout: A copy of the layout instance.

Copies the layout instance.

This method copies the layout instance by calling the copy constructor. Note that the parameters which are specific to a node or a link are not copied. It depends on the layout mode what is copied.

  • RecursiveLayout.REFERENCE_LAYOUT_MODE - The reference layout is copied deeply.
  • RecursiveLayout.INTERNAL_PROVIDER_MODE - The information on which subgraph uses which sublayout is not copied.
  • RecursiveLayout.SPECIFIED_PROVIDER_MODE - The specified layout provider is copied, but not deeply.

copyParameters

Copies the parameters from a given layout instance. Note that the parameters which are specific to a node or a link are not copied. It depends on the layout mode what is copied:

  • RecursiveLayout.REFERENCE_LAYOUT_MODE - The reference layout is copied deeply.
  • RecursiveLayout.INTERNAL_PROVIDER_MODE - The information on which subgraph uses which sublayout is not copied.
  • RecursiveLayout.SPECIFIED_PROVIDER_MODE - The specified layout provider is copied, but not deeply.

ParameterTypeDescription
sourceibm_ilog.graphlayout.GraphLayoutThe layout instance from which the parameters are copied.
createLayoutReport
Returns ibm_ilog.graphlayout.GraphLayoutReport: A new instance of the recursive layout report.

Returns a new instance of the layout report.

The current implementation creates an instance of RecursiveLayoutReport.

detach

Detaches the graph model from the layout instance. When you attach a new graph model to the layout instance, you do not need to detach the old graph model because this is done automatically when you call RecursiveLayout.attach(). The detach method performs cleaning operations on the graph model. In addition to the cleaning operations in the base class, the Recursive Layout detaches the sublayouts of subgraphs. In internal provider mode, it also cleans all settings of layout instances for subgraphs.

Note that you must call this method when you no longer need the layout instance. Otherwise, some objects may not be garbage collected.

getAllowedTime
Returns Number

Returns the currently allowed time for the layout algorithm in milliseconds. The allowed time is additionally limited by the allowed time parameter on the sublayouts. The effective allowed time is the minimum of the sum of allowed times for for the sublayouts and the value returned as allowed time for this Recursive layout.

Note that the method performLayout does not automatically stop the layout when the allowed time is exceeded. It only delegates the stop to the sublayouts, and it is entirely the responsibility of the implementation of the method RecursiveLayout.layout() on the sublayouts to do this.

getBalanceSplineCurveThreshold
Returns Number: The threshold for spline curves at bends which the optimized spline control point routing uses to balance the curve.
Returns the threshold for spline curves at bends which the optimized spline control point routing uses to balance the curve.
getCalcLayoutRegion
Returns Rectangle: A copy of the rectangle that defines the layout region parameter.

Returns a copy of the rectangle that defines the layout region parameter.

This method first tries to use the layout region specification by calling ibm_ilog.graphlayout.GraphLayout.getSpecLayoutRegion(). If this method returns a non-null rectangle, the 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, this method returns a default rectangle (0, 0, 1000, 1000).

getGraphModel
Returns ibm_ilog.graphlayout.AbstractGraphLayoutModel: The graph model to lay out if one is attached.

Returns the graph model to lay out if a graph model is attached. Otherwise, the method returns null.

During the layout of a disconnected graph by a layout class that supports the connected components layout mechanism (see ibm_ilog.graphlayout.GraphLayout.supportsLayoutOfConnectedComponents()) and for which this mechanism is enabled (see ibm_ilog.graphlayout.GraphLayout.isLayoutOfConnectedComponentsEnabled()), the method ibm_ilog.graphlayout.GraphLayout.getGraphModel() may return a different graph model from the one originally attached using the method ibm_ilog.graphlayout.GraphLayout.attach(). For details, see the method ibm_ilog.graphlayout.GraphLayout.performLayout().

getInstanceId
Returns int: A unique integer value for each layout instance.

A utility method that returns a unique integer value for each layout instance. Use this method to obtain names for properties that are unique for each layout instance.

getLayout
Returns ibm_ilog.graphlayout.GraphLayout: The layout instance used to lay out the subgraph.

Returns the layout instance to be used for the input subgraph. If null is passed as the subgraph, the layout instance of the top-level graph is returned. You can use this method in all layout modes. You must attach a graph model first before using this method. The method may return null if no layout should be performed for the subgraph.

In reference layout mode, changing global layout parameters of the layout instances of subgraphs is useless, because during layout, the global parameters of the reference layout are used for each subgraph.

ParameterTypeDescription
subgraphObjectThe subgraph or 'null'.
getLayoutMode
Returns int: The layout mode.

Returns the layout mode of the Recursive Layout. The possible values are:

  • RecursiveLayout.REFERENCE_LAYOUT_MODE - The same layout style with the same global layout parameters is applied to all subgraphs of the nested graph.
  • RecursiveLayout.INTERNAL_PROVIDER_MODE - The layout is applied using an internal recursive layout provider. The layout styles of individual subgraphs can be specified by RecursiveLayout.setLayout().
  • RecursiveLayout.SPECIFIED_PROVIDER_MODE - The layout is applied using an explicitly specified layout provider.

getLayoutOfConnectedComponents
Returns ibm_ilog.graphlayout.GraphLayout

Returns the layout instance that lays out the connected components of the graph.

The method returns null if the layout instance does not support the layout of connected components. that is, if the method ibm_ilog.graphlayout.GraphLayout.supportsLayoutOfConnectedComponents() returns false.

Otherwise, if a layout instance has been specified using the method ibm_ilog.graphlayout.GraphLayout.setLayoutOfConnectedComponents(), this instance is returned. If no layout instance has been specified using the method ibm_ilog.graphlayout.GraphLayout.setLayoutOfConnectedComponents(), the method returns an instance of ibm_ilog.graphlayout.grid.GridLayout. Its layout region parameter is set by default to the rectangle (0, 0, 800, 800). The layout mode parameter is set to ibm_ilog.graphlayout.grid.GridLayout.TILE_TO_ROWS. Note that the layout instance returned by this method cannot be used independently as long as it is set as a connected component layout.

getLayoutOfConnectedComponentsReport
Returns ibm_ilog.graphlayout.GraphLayoutReport: The layout report containing information about the behavior of the connected components layout.

Returns the layout report containing information about the behavior of the connected components layout.

This method returns the instance of the layout report created by the connected components layout instance.

If the last run of the layout did not use the connected components layout (because either the graph was connected, or the layout does not support this feature, or this feature was disabled, or an exception occurred during the layout process), the method returns null.

getLayoutProvider
Returns ibm_ilog.graphlayout.ILayoutProvider: The layout provider, which is the instance that is responsible for specifying the layout instance to be used for laying out each graph.

Returns the layout provider.

If the reference layout mode is used, this method returns an internally created instance of ibm_ilog.graphlayout.DefaultLayoutProvider.

If the internal provider mode is used, this method returns an internally created instance of RecursiveLayoutProvider.

In both reference layout and internal provider modes, you should not manipulate the internally created layout provider directly.

If the specified provider mode is used, it returns the specified layout provider.

getLayoutRegion

Returns a copy of the rectangle that defines the layout region, as specified using the method ibm_ilog.graphlayout.GraphLayout.layoutRegion, or null if no rectangle has been specified, or the specified rectangle was null.

getLayoutRegionMode
Gets the layout region mode.
getLayoutReport
Returns ibm_ilog.graphlayout.GraphLayoutReport: The layout report that contains information about the behavior of the layout algorithm.

Returns the layout report, that is, the object that contains information about the behavior of the layout algorithm.

If this method is called after the method ibm_ilog.graphlayout.GraphLayout.performLayout() was called for the first time on this layout instance, it returns the instance of the layout report created by ibm_ilog.graphlayout.GraphLayout.createLayoutReport(). Otherwise, it returns null.

getLayouts
Returns ibm_ilog.graphlayout.IIterator: The instances of 'GraphLayout' for the nested graph encapsulated by the graph model of this layout instance.

Returns the instances of GraphLayout for the nested graph encapsulated by the graph model of this layout instance. You can use this method in all layout modes. You must attach a graph model before using this method.

This method returns the layout instance for the top-level graph and recursively for all subgraphs. The order of the enumeration can be preorder (that is, the layout of the parent graph comes before the layout of the subgraphs) or postorder (that is, the layout of the subgraphs comes before the layout of the parent graph).

In reference layout mode, changing global layout parameters of the layout instances of subgraphs is useless, because during layout, the global parameters of the reference layout are used for each subgraph.

ParameterTypeDescription
preOrderBooleanIf 'true', the layout instances are returned in preorder, otherwise in postorder.
getLinkConnectionBoxInterface
Returns ibm_ilog.graphlayout.ILinkConnectionBoxProvider

Returns the link connection box interface used to calculate the connection points of links during layout.

Returns null if none is specified.

getMaxSplineCurveSize
Returns Number: The maximum curve size used when spline control point optimization routing is enabled.
Returns the maximum curve size used when spline control point optimization routing is enabled.
getMinBusyTime
Returns Number
Returns the minimal time that the layout algorithm can be busy between two calls of ' ibm_ilog.graphlayout.GraphLayout.onLayoutStepPerformed()' when the method ' ibm_ilog.graphlayout.GraphLayout.callLayoutStepPerformedIfNeeded()' is used.
getMinSplineCurveSize
Returns Number: The minimum curve size used when optimized spline control points routing is enabled.
Returns the minimum curve size used when optimized spline control points routing is enabled.
getObjectParameter
Returns Object: The value of the parameter.

Returns the value of a parameter of the layout instance. This method returns null if the does not exist.

The method does not check that the specified node or link belongs to the specified graphModel. Also, the specified graph model does not need to be the graph model currently attached to this layout instance.

ParameterTypeDescription
graphModelibm_ilog.graphlayout.AbstractGraphLayoutModelThe graph model used for storing the parameter.
nodeOrLinkObjectThe node or link for which the parameter is to be retrieved.
keyStringThe key string for the parameter.
getParameter
Returns Object: The value stored for 'key'.

Returns the value of a parameter of the layout instance. The method returns null if the parameter does not exist.

ParameterTypeDescription
keyStringThe key string for the parameter.
getParentLayout
Returns ibm_ilog.graphlayout.GraphLayout

Returns the parent layout. If a layout instance A creates or uses another layout instance B to accomplish a part of or the total layout work, the layout instance A is called the "parent" of the layout instance B. The parent layout instance is responsible for declaring itself as a parent of B by calling the method ibm_ilog.graphlayout.GraphLayout.setParentLayout() on it. The layout instance B is called a sublayout of A.

Sublayouts never have their own local layout listeners. Layout events have parent layouts as the source.

The method returns null if the layout instance has no parent.

getRecursiveLayout
Returns ibm_ilog.graphlayout.RecursiveLayout: The recursive layout instance responsible for performing the layout when traversing the graph hierarchy.

Returns the instance of Recursive Layout that is used to perform this layout recursively when you call ibm_ilog.graphlayout.GraphLayout.performLayout() with the traverse flag set to true. The returned instance of Recursive Layout uses this layout as a reference layout, and it is attached to the same graph model as this graph model. You should call this method only when a graph model is attached. You should not detach the returned layout nor attach it to any other graph model.

The returned instance always uses the reference layout mode (see ibm_ilog.graphlayout.RecursiveLayout.getLayoutMode()). This is an expert feature, available when the graph layout is laying out a model that is not displayed in a Graph or Diagram.

getReferenceLayout
Returns ibm_ilog.graphlayout.GraphLayout: The reference layout if the reference layout mode is used.

Returns the reference layout if the reference layout mode is used; returns null otherwise.

In reference layout mode, the reference layout is used to lay out the top-level graph. Clones of the reference layout are used to lay out the subgraphs. The entire nested graph is laid out with the global layout parameters of the reference layout. If you change global layout parameters of the reference layout, this will affect the layout of subgraphs as well, because the global layout parameters are copied from the reference layout to the layouts of the subgraphs.

getRemainingAllowedTime
Returns Number: A negative number is returned if one of the following conditions is met:
  • The allowed time has elapsed.
  • The layout does not support the allowed time.
  • This method is called when the layout report is not yet available.
  • This method is called when the layout report is no longer available.

Returns the remaining allowed time. The remaining allowed time is the difference between the allowed time given by ibm_ilog.graphlayout.GraphLayout.getAllowedTime(), and the time elapsed since the beginning of layout execution.

getSeedValueForRandomGenerator
Returns Number

Returns the user-defined seed value for the random generator.

An Error is thrown if the layout does not support this mechanism.

getSpecLayoutRegion
Returns Rectangle: Returns a copy of the rectangle that defines the layout region.

Returns a copy of the rectangle that defines the layout region, as specified using the method ibm_ilog.graphlayout.GraphLayout.layoutRegion.

The implementation of the method ibm_ilog.graphlayout.GraphLayout.layout() in subclasses of GraphLayout is solely responsible for whether the rectangle returned by this method is taken into account when calculating the layout, and in which manner. The method returns null in the following cases:

  • The layout region mechanism is not supported (that is, ibm_ilog.graphlayout.GraphLayout.supportsLayoutRegion() returns false).
  • You do not call setLayoutRegion and no graph model is attached to the layout

Note that, except when specified using ibm_ilog.graphlayout.GraphLayout.layoutRegion, the layout region can change with time (for example, because the size of the view passed as the argument to ibm_ilog.graphlayout.GraphLayout.setLayoutRegion() changes, or its transformer is changed).

getSplineLinkFilter
Returns ibm_ilog.graphlayout.SplineLinkFilter: The filter that detects which links are suitable for optimized spline routing.
Returns the filter that detects which links are suitable for optimized spline routing.
getSubgraphCorrectionInterface
Returns ibm_ilog.graphlayout.ISubgraphCorrection

Returns the subgraph correction interface that is applied after the nodes and links of the subgraph were laid out.

It returns null if none is specified.

getSubgraphLayoutReport
Returns ibm_ilog.graphlayout.GraphLayoutReport: The layout report of the last layout run for the subgraph.

Returns the report of the graph layout of the input subgraph.

You should call this method only after layout, while the Recursive Layout is still attached to a grapher or graph model. If null is passed as the subgraph, the layout report of the top-level graph is returned. It returns null if no layout instance is available for the subgraph, or if no layout was ever performed for the subgraph. You can use this method in all layout modes.

ParameterTypeDescription
subgraphObjectThe subgraph or 'null'.
getViewMatrix
Returns the matrix that is applied to the first view attached to this layout.
increasePercentageComplete

Increases the percentage of completion that is stored in the layout report to the input value. Layout algorithms that support the percentage complete feature should call this method during the running of the layout. This method does not set the percentage to a lower value than the previous value. It also does not set the value to more than 100%. It silently ignores wrong input values.

ParameterTypeDescription
newPercentageintNew percentage of completion
init

Initializes instance variables.

You should not call this method directly. The method is called internally by the constructor without arguments and by the copy constructor. The method must be overridden by subclasses that need to initialize additional instance variables.

isFitToViewEnabled
Returns Boolean: 'true' if the graph drawing must fit (exactly or approximately) an area of the diagram view.

Returns true if the graph drawing must fit (exactly or approximately) an area of a specific view. Otherwise, the method returns false.

isFixed
Returns Boolean: 'true' if the node or link is specified as fixed.
Returns whether the node or link is specified as fixed.
ParameterTypeDescription
nodeOrLinkObjectNode or link instance present in the graph model attached to this layout.
isGeometryUpToDate
Returns Boolean

Returns false if at least one node or link was moved or reshaped since the last time the layout was successfully performed on the same graph or if the layout has never been performed successfully on the same graph. It returns true if no changes occurred.

The method returns false if the geometry of one of the sublayouts is out-of-date.

isInputCheckEnabled
Returns Boolean

Returns true if the checks for the nodes and/or links are enabled. Returns false otherwise.

isLayoutNeeded
Returns Boolean: 'true' if it is necessary to perform the layout, 'false' otherwise.

Verifies that it is necessary to perform the layout.

Basically, the method returns false if no changes occurred on the graph model (no nodes or links were inserted, removed, reshaped, or moved) and no parameters changed since the last time the layout was successfully performed using this layout instance. Otherwise, the method returns true.

isLayoutOfConnectedComponentsEnabled
Returns Boolean

Indicates whether the connected component layout mechanism is enabled.

The default value is the value returned by the method ibm_ilog.graphlayout.GraphLayout.isLayoutOfConnectedComponentsEnabledByDefault().

isLayoutOfConnectedComponentsEnabledByDefault
Returns Boolean: 'true' if the connected components layout mechanism is enabled by default.

Returns true if the connected components layout mechanism is enabled by default. Otherwise, the method returns false.

The default implementation always returns false.

Subclasses can override this method in order to return true, that is, to indicate that the connected components layout is enabled by default.

isLayoutRunning
Returns Boolean: 'true' if this layout is currently running or (if 'checkParents' is enabled) if any parent layout is currently running.

Indicates whether this layout algorithm is running or not.

If the parameter checkParents is false, this method returns true if this layout has been started and is not yet completed. If the parameter checkParents is true, this method additionally checks whether any controlling parent layout is currently running.

ParameterTypeDescription
checkParentsBooleanIndicates that this method should also check whether any controlling parent layout is currently running.
isLayoutTimeElapsed
Returns Boolean: 'false' if the layout does not support this mechanism.

Returns true if, at the moment the method is called, the allowed layout time is exceeded; returns false otherwise.

You can call this method inside the implementation of the method ibm_ilog.graphlayout.GraphLayout.layout().

isLinkClipping
Gets whether links should be clipped at the shape of the end nodes.
isLocalRecursiveLayoutNeeded
Returns Boolean: 'true' if it is necessary to perform the layout, 'false' otherwise.

Checks whether layout is needed when layout is performed recursively on a hierarchy of nested subgraphs.

This method is called on the layout of the parent graph before the layout of the subgraphs is started. This allows the parent layout to negotiate with the subgraph layouts whether the parent layout treats the subgraphs as well, or whether the layouts of the subgraphs must run individually. If this method returns false, this layout is not performed, because some parent layout can handle the subgraph already.

The method is only called during a recursive layout (started by ibm_ilog.graphlayout.RecursiveLayout ). The default implementation returns always true. This is an expert feature, available when the graph layout is laying out a model that is not displayed in a Graph or Diagram.

ParameterTypeDescription
layoutProvideribm_ilog.graphlayout.ILayoutProviderThe object that provides a layout instance to be used for laying out each subgraph.
recLayoutibm_ilog.graphlayout.GraphLayoutThe recursive layout that started the recursive application of layouts. This can be 'null'.
rootModelibm_ilog.graphlayout.AbstractGraphLayoutModelThe graph model that is the root of the nesting hierarchy of graph models.
traverseBooleanIf 'false', this layout is intended to be only applied to its own graph model. If 'true', this layout is intended to be applied to its graph model and the layout instances provided by the 'layoutProvider' are intended to be applied recursively to all nested subgraph models. The traverse flag is basically passed through from the call of ' ibm_ilog.graphlayout.GraphLayout.performLayout()'.
isParametersUpToDate
Returns Boolean

Returns false if at least one parameter was modified since the last time the layout was successfully performed on the same graph or if the layout has never been performed successfully on the same graph. It returns true if no changes occurred.

The method returns false if the parameters of one of the sublayouts is out-of-date.

isPreserveFixedLinks
Returns Boolean

Returns true if the layout is not allowed to reshape the links indicated as fixed by the user. Returns false if the layout is free to reshape all the links.

Always returns false if the layout does not support this option.

isPreserveFixedNodes
Returns Boolean

Returns true if the layout is not allowed to move the nodes indicated as fixed by the user. Returns false if the layout is free to move all the nodes.

Always returns false if the layout does not support this option.

Note that fixed nodes can be handled differently by different layout algorithms. Some layout algorithms can adapt the layout of the nonfixed nodes to take into account the current positions of the fixed nodes. For details, refer to the documentation of the layout algorithm.

isSplineRoutingEnabled
Returns Boolean: If the calculation of optimized spline control points is enabled, 'true' is returned.
Tests whether the calculation of optimized spline control points is enabled.
isStoppedImmediately
Returns Boolean: 'true' if the method 'stopImmediately' was called.

Returns true if the method ibm_ilog.graphlayout.GraphLayout.stopImmediately() was called. Layout algorithm classes can use this method to recognize that it was requested to stop the current layout run.

isStructureUpToDate
Returns Boolean

Returns false if at least one modification occurred in the structure of the graph since the last time the layout was successfully performed on the same graph or if the layout has never been performed successfully on the same graph. Returns true if no changes occurred.

The method returns false if the structure of one of the sublayouts is out-of-date.

isUseSeedValueForRandomGenerator
Returns Boolean

Returns true if the user-defined seed value is used for the random generator and false otherwise.

An error is thrown An Error is thrown if the layout does not support this mechanism.

layout

Computes the layout using the Recursive Layout algorithm.

To start the layout, call the method ibm_ilog.graphlayout.GraphLayout.performLayout().

performLayout
Returns int: The layout code (see ibm_ilog.graphlayout.GraphLayoutReport.getCode()).
This is different from the implementation of the base class; the Recursive Layout always ignores the <code>traverse</code> flag because the layout is always done recursively.
ParameterTypeDescription
force
traverse
performSubgraphLayout
The report with information about the execution of the graph layout in the given subgraph.

Layout is performed for subgraph and, the traverse flag is set to true recursively for all subgraphs contained in this subgraph. If the subgraph is set to null, the layout is started at the top level graph.

ParameterTypeDescription
subgraphThesubgraph to start the layout.
forceIf<code>true</code>, the method {@link #isLayoutNeeded} is not called. No check is made to determine if it is necessary to perform the layout.
traverseIf<code>true</code>, the layout is applied recursively to all subgraphs contained in the subgraph. Otherwise, it is only applied on the input subgraph.
performSublayout
The layout code. @see GraphLayoutReport#code

This method is used when this layout controls the input layout as a sublayout. Layout classes can override this method if changes are needed with respect to the way in which the input layout is started. You should not call this method directly. In addition to the functionality of the base class, the Recursive Layout prepares the sublayouts according to the layout mode.

ParameterTypeDescription
subgraphThesubgraph if used during nested layout, or <code>null</code>.
layoutThesublayout to be preformed.
forceIf<code>true</code>, no check is made to determine if it is necessary to perform the layout.
propagateLayoutOfConnectedComponents

Sets the layout instance to lay out the connected components of all subgraphs having a main layout that supports the connected component layout mechanism. The Recursive Layout itself does not support this feature, since the connected component layout mechanism works on the flat graph while the Recursive Layout works on a nested graph. Despite this, it may make sense in certain situations to propagate the connected component layout setting to all layouts of subgraphs.

In reference layout mode, this method calls ibm_ilog.graphlayout.GraphLayout.setLayoutOfConnectedComponents() on the reference layout, if the reference layout supports this feature. If a graph is attached and the layout mode is the internal or specified provider mode, this method traverses the nesting hierarchy and calls ibm_ilog.graphlayout.GraphLayout.setLayoutOfConnectedComponents() for all layout instances of subgraphs that support this feature. If you insert subgraphs after calling this method, or if you change the layout instances of subgraphs either in your specified provider or through RecursiveLayout.setLayout() in the internal provider after calling this method, the new layouts of these subgraphs may have a different setting.

In internal or specified provider mode, this method throws a runtime exception when no graph model has been attached.

ParameterTypeDescription
layoutibm_ilog.graphlayout.GraphLayoutThe layout instance that lays out the connected components of all subgraphs having a main layout that supports the connected component layout mechanism.
propagateLayoutOfConnectedComponentsEnabled

Enables the connected component layout mechanism for all layouts of subgraphs that support this feature. The Recursive Layout itself does not support this feature, since the connected component layout mechanism works on the flat graph while the Recursive Layout works on a nested graph. Despite this, it may make sense in certain situations to propagate the connected component layout setting to all layouts of subgraphs.

In reference layout mode, this method calls ibm_ilog.graphlayout.GraphLayout.setLayoutOfConnectedComponentsEnabled() on the reference layout, if the reference layout supports this feature. If a graph is attached and the layout mode is the internal or specified provider mode, this method traverses the nesting hierarchy and calls ibm_ilog.graphlayout.GraphLayout.setLayoutOfConnectedComponentsEnabled() for all layout instances of subgraphs that support this feature. If you insert subgraphs after calling this method, or if you change the layout instances of subgraphs either in your specified provider or through RecursiveLayout.setLayout() in the internal provider after calling this method, the new layouts of these subgraphs may have a different setting.

In internal or specified provider mode, this method throws a runtime exception when no graph model has been attached.

ParameterTypeDescription
enableBooleanIf 'true', enables the connected component layout mechanism for all layouts of subgraphs that support this feature.
propagateLinkConnectionBoxInterface

Sets the link connection box interface for the connection points of links on all layouts of subgraphs that support this feature. The Recursive Layout itself does not support this feature, since the link connection box interface works on the flat graph while the Recursive Layout works on a nested graph. Despite this, it may make sense in certain situations to propagate the link connection box setting to all layouts of subgraphs. After propagation, the same link connection box interface is shared by all layout instances for all subgraphs of the attached graph.

In reference layout mode, this method calls ibm_ilog.graphlayout.GraphLayout.setLinkConnectionBoxInterface() on the reference layout, if the reference layout supports this feature. If a graph is attached and the layout mode is the internal or specified provider mode, this method traverses the nesting hierarchy and calls ibm_ilog.graphlayout.GraphLayout.setLinkConnectionBoxInterface() for all layout instances of subgraphs that support this feature. If you insert subgraphs after calling this method, or if you change the layout instances of subgraphs either in your specified provider or through RecursiveLayout.setLayout() in the internal provider after calling this method, the new layouts of these subgraphs may have a different setting.

In internal or specified provider mode, this method throws a runtime exception when no graph model has been attached.

ParameterTypeDescription
linkConnectionBoxInterfaceibm_ilog.graphlayout.ILinkConnectionBoxProviderThe link connection box interface for the connection points of links for all layouts of subgraphs that support this feature.
setAllowedTime

Sets the upper limit for the duration of the layout algorithm.

The default value for Recursive layout is 1000000000 (1000000 seconds). The allowed time is additionally limited by the allowed time parameter on the sublayouts.

ParameterTypeDescription
timeNumberThe allowed time in milliseconds.
setAutoCheckAppropriateLinksEnabled
Returns Boolean: The previous value.

Sets whether the layout checks whether links are appropriate. This is internally used. You should not use it.

ParameterTypeDescription
enable
setBalanceSplineCurveThreshold

Sets the threshold for spline curves at bends which the optimized spline control point routing uses to balance the curve.

The parameter works only if the layout supports generic spline optimization routing, and if it is enabled.

Bends in a spline have a size that is described roughly by the triangle the surrounds the curve part of a bend.

If the side length of the triangle is larger than the threshold, the algorithm tries to create a isosceles triangle. This results in more balanced bend curves.

If the side length of the triangle is smaller than the threshold, it uses non-isosceles triangles. Using isosceles triangles, the bend curve looks too sharp.

The default value is 10.

ParameterTypeDescription
thresholdNumberThe balance spline curve threshold.
setFixed

Sets the specified node or link as fixed.

Fixed nodes are not moved during the layout only if the method isPreserveFixedNodes() returns true. By default, no node is fixed.

Fixed links are not reshaped during the layout only if the method isPreserveFixedLinks() returns true. By default, no link is fixed.

ParameterTypeDescription
nodeOrLinkObjectNode or link instance which is part of the graph model.
fixedBooleanIndicates whether the object should remain fixed or not.
setGeometryUpToDate

Sets whether the geometry of the graph is up to date.

If the argument is false, notifies the layout instance that the geometry of the graph was changed since the last time the layout was successfully performed.

Usually you do not need to call this method. The method is automatically called with a true argument each time the layout is successfully performed.

ParameterTypeDescription
uptodate
setGraphModel

Sets the graph model to be laid out. You should not call this method. Instead, use the method ibm_ilog.graphlayout.GraphLayout.attach().

ParameterTypeDescription
graphModel
setInputCheckEnabled

Sets whether checks are enabled for the nodes, links, and/or labels provided as arguments for the different methods of this layout algorithm and its sublayout algorithms.

In reference layout mode, it also calls setInputCheckEnabled at the reference layout, hence all layouts of subgraphs will use this parameter setting. If a graph is attached and the layout mode is the internal or specified provider mode, it traverses the nesting hierarchy and calls setInputCheckEnabled for all layout instances of subgraphs. However, if you insert subgraphs after calling this method, or if you change the layout instances of subgraphs in your specified provider or via RecursiveLayout.setLayout() in the internal provider after calling this method, the new layouts of these subgraphs may have a different setting.

Warning: In internal or specified provider mode, this method does not throw an exception when no graph model is yet attached. However, if no graph model is yet attached, the method cannot traverse any nesting hierarchy.

It is enabled by default.

ParameterTypeDescription
enable
setLayout

Sets the layout instance to be used for the input subgraph. If null is passed as the subgraph, the input layout is used for the top-level graph. If null is passed as the layout, no layout will be performed for the corresponding subgraph.

You can use this method only in internal provider mode. You must attach a grapher or graph model first before using this method. Each subgraph must get a different layout instance, that is, the layout instances cannot be shared among different subgraphs. The input layout is automatically attached and detached by the Recursive Layout as needed.

ParameterTypeDescription
subgraphObjectThe subgraph or 'null'.
layoutibm_ilog.graphlayout.GraphLayoutThe layout instance used to lay out the subgraph. This should be a new layout instance that is not used anywhere else.
setLayoutImpl

Sets the layout instance to be used for the input subgraph. If the traverseflag is true, it traverses the nested graph starting from the input graph and sets a clone of the input layout recursively for each subgraph. Notice that if you insert subgraphs after calling this method, the new subgraphs have no layout yet assigned.

If null is passed as the subgraph, the input layout is used for the top-level graph, and the traversal, if any, starts at the top-level graph. If null is passed as the layout, no layout will be performed for the corresponding subgraphs.

You can use this method only in internal provider mode. Each subgraph must get a different layout instance, that is, the layout instances cannot be shared among different subgraphs. You must attach a grapher or graph model first before using this method. The input layout is automatically attached and detached by the Recursive Layout as needed.

ParameterTypeDescription
subgraphObjectThe subgraph or 'null'.
layoutibm_ilog.graphlayout.GraphLayoutThe layout instance used to lay out the subgraph. This should be a new layout instance that is not used anywhere else.
detachPreviousBooleanIf 'true', the layout instance previously specified as the preferred layout of the subgraph (if any) is detached.
traverseBooleanIf 'true', clones of the input layout are recursively used for all current subgraphs of the input graph.
setLayoutOfConnectedComponents

Sets the layout instance that lays out the connected components of the graph. When this method is not called, a default layout instance (see ibm_ilog.graphlayout.GraphLayout.getLayoutOfConnectedComponents() is used. You can call this method with a null argument to return to the default connected components layout instance.

Note the following points:

  • The layout instance passed as the argument cannot be used independently as long as it is set as a connected component layout.
  • The connected component layout is not used if the graph is connected.

ParameterTypeDescription
layoutibm_ilog.graphlayout.GraphLayoutThe layout instance to set, or 'null' to return to the default layout instance.
setLayoutOfConnectedComponentsEnabled

Sets whether the generic connected component layout mechanism is enabled. If enabled on a layout class that supports this mechanism (see ibm_ilog.graphlayout.GraphLayout.supportsLayoutOfConnectedComponents()), the method ibm_ilog.graphlayout.GraphLayout.performLayout() cuts the attached graph model into connected components and lays out each connected component separately. Then the connected components are placed using the layout instance returned by the method ibm_ilog.graphlayout.GraphLayout.getLayoutOfConnectedComponents().

Notice that the connected component layout is not used if the graph is connected.

The default value is the value returned by the method ibm_ilog.graphlayout.GraphLayout.isLayoutOfConnectedComponentsEnabledByDefault().

ParameterTypeDescription
enableBooleanSet to 'true' to enable the connected component layout mechanism, or 'false' to disable.
setLayoutRegion

Sets the layout region as a rectangle rect), with the dimensions of the rectangle being given in container (graph model) coordinates. The region's new position is specified by rect.x and rect.y, and its new size is specified by rect.width and rect.height.

For subclasses that support this parameter, the layout region is usually the rectangle that the graph must fit (exactly or approximately) after the layout is performed, or the rectangle which influences the position and/or size of the resulting layout. The way the layout region parameter is taken into account is the sole responsibility of the subclasses.

You should use this method if you want to perform the layout with no manager view attached to the graph model or if you want to define the region to fit in the manager coordinates. If you want the layout to fit a region of a manager view, with its dimensions in manager view coordinates, use the method ibm_ilog.graphlayout.GraphLayout.setLayoutRegion(). If you want to revert to the default layout region, that is the layout region which is computed by default if no layout region has been previously specified, you can call this method with a null argument.

An Error is thrown if the layout does not support this mechanism, or if the width or height of rect is 0.

ParameterTypeDescription
rectRectangleThe rectangle for the layout region, or 'null'.
setLayoutRegionMode
Sets the layout region mode.
ParameterTypeDescription
value
setLayoutReport

Sets the layout report, that is, the object that contains information about the behavior of the layout algorithm.

This method is called automatically by ibm_ilog.graphlayout.GraphLayout.performLayout() with the layout report created using the method ibm_ilog.graphlayout.GraphLayout.createLayoutReport(). Subclasses can override this method to perform additional actions.

ParameterTypeDescription
reportibm_ilog.graphlayout.GraphLayoutReportNew layout report.
setLayoutRunning

Sets whether layout is running. This method is part of IBM ILOG Dojo Diagrammer internals. You should not use it.

ParameterTypeDescription
runningBooleanWhether layout is running or not.
fromParentsBooleanWhether this notification is from a parent layout or from this layout instance.
setLinkClipping
Sets whether links should be clipped at the shape of the end nodes.
ParameterTypeDescription
value
setLinkConnectionBoxInterface

Sets the link connection box interface for the connection points of links. The link connection box interface is an object that provides the rectangle to which the links are connected for each node and the tangential shift offset at each side for the connection points.

By default, the layout algorithm places the connection points of the links relative to the bounding box of the nodes (see ).

By setting a link connection box interface, the links can be connected relative to a different box (see ILinkConnectionBoxProvider.getBox()). It is furthermore possible to "shift" the links tangentially by using the method ILinkConnectionBoxProvider.getTangentialOffset() from the interface ILinkConnectionBoxProvider:

  • On the "top" and "bottom" sides of a node, the connection points are moved to the right if the offset is positive and to the left if the offset is negative.
  • On the "left" and "right" sides of a node, the connection points are moved to the bottom if the offset is positive and to the top if the offset is negative.
The details of how the link connection box is used depend on the specific layout algorithm.

You can call this method with a null argument to restore the default behavior.

An Error is thrown if the layout does not support this mechanism.

ParameterTypeDescription
linkConnectionBoxInterface
setMaxSplineCurveSize

Sets the maximum curve size used when optimized spline control point routing is enabled.

The parameter works only if the layout supports the generic spline optimization routing, and if it is enabled.

Bends in a spline have a size that is described roughly by the triangle the surrounds the curve part of a bend. Spline routing tries to set the side length of this triangle at each bend between the minimum curve size and the maximum curve size.

The default value is 30.

ParameterTypeDescription
sizeNumberThe maximum spline curve size
setMinBusyTime

Sets the minimal time the layout algorithm can be busy between two calls of ibm_ilog.graphlayout.GraphLayout.onLayoutStepPerformed() when the method ibm_ilog.graphlayout.GraphLayout.callLayoutStepPerformedIfNeeded() is used. In reference layout mode, it also calls setMinBusyTime at the reference layout, hence all layouts of subgraphs will use this parameter setting. If a graph is attached and the layout mode is the internal or specified provider mode, it traverses the nesting hierarchy and calls setMinBusyTime for all layout instances of subgraphs. However, if you insert subgraphs after calling this method, or if you change the layout instances of subgraphs in your specified provider or via RecursiveLayout.setLayout() in the internal provider after calling this method, the new layouts of these subgraphs may have a different setting.

Warning: In internal or specified provider mode, this method does not throw an exception when no graph model is yet attached. However, if no graph model is yet attached, the method cannot traverse any nesting hierarchy.

The default value is 50 (milliseconds).

ParameterTypeDescription
time
setMinSplineCurveSize

Sets the minimum curve size used when optimized spline control point routing is enabled.

The parameter works only if the layout supports the generic spline optimization routing, and if it is enabled.

Bends in a spline have a size that is described roughly by the triangle the surrounds the curve part of a bend. Spline routing tries to set the side length of this triangle at each bend between the minimum curve size and the maximum curve size.

The default value is 5.

ParameterTypeDescription
sizeNumberThe minimum spline curve size
setObjectParameter
Returns Object: The value that was previously stored for 'key', or 'null' if none.

Sets the value of a parameter for a node or a link, using a given graph model.

If value is null, the parameter is removed. Otherwise, the parameter value is set to value.

Notice that the method does not check whether the node or link actually belongs to graphModel. The input graph model does not need to be the graph model currently attached to this layout instance.

ParameterTypeDescription
graphModelibm_ilog.graphlayout.AbstractGraphLayoutModelThe graph model used for storing the parameter.
nodeOrLinkObjectThe node or link for which the parameter is to be set.
keyStringThe key string for the parameter.
valueObjectThe new value of the parameter.
setParameter
Returns Object: The value that was previously stored for 'key', or 'null' if none.

Sets the value of a property for the layout instance. If value is null, the parameter is removed. Otherwise, the parameter value is set to value.

ParameterTypeDescription
keyStringThe key string for the parameter.
valueObjectThe new value of the parameter.
setParametersUpToDate

Sets whether the parameters of the graph layout are up to date.

If the argument is false, notifies the layout instance that a parameter value was changed.

This method is automatically called with a false argument each time the value of a parameter is changed using the methods provided in this class or in its subclasses provided in IBM ILOG Dojo Diagrammer.

The method is automatically called with a true argument each time the layout is successfully performed.

ParameterTypeDescription
uptodate
setParentLayout

Sets the parent layout of this layout instance. You should not call this method directly.

ParameterTypeDescription
parent
setPreserveFixedLinks

Sets whether the layout avoids movement of fixed links. If the argument is true, specifies that the layout is not allowed to reshape the links indicated as fixed by the user. If the argument is false, the layout is free to reshape all the links of the graph. (This does not change the setting for the fixed links, which can still be used at any time in the future.)
The default value is false.

An Error is thrown if the layout class does not support this option.

ParameterTypeDescription
option
setPreserveFixedNodes

Sets whether the layout avoids movement of fixed nodes. If the argument is true, specifies that the layout is not allowed to move the nodes indicated as fixed by the user. If the argument is false, the layout is free to move all the nodes of the graph. (This does not change the setting for the fixed nodes, which can still be used at any time in the future.)

The default value is false.

Note that fixed nodes can be handled differently by different layout algorithms. Some layout algorithms can adapt the layout of the nonfixed nodes to take into account the current positions of the fixed nodes. For details, refer to the documentation of the layout algorithm.

ParameterTypeDescription
option
setSeedValueForRandomGenerator

Sets the seed value for the random generator. The default value is 0. The user-defined seed value is used only if you call setUseSeedValueForRandomGenerator(boolean) with a true argument.

An Error is thrown if the layout does not support this mechanism.

ParameterTypeDescription
seed
setSplineLinkFilter

Sets the filter that detects which links are suitable for optimized spline routing.

The parameter works only if the layout supports the generic spline optimization routing, and if it is enabled.

The filter detects which objects are splines, so that the optimized spline routing is only applied to splines, not to normal polyline links.

ParameterTypeDescription
filter
setSplineRoutingEnabled

Sets whether the calculation of optimized spline control points is enabled.

If the layout algorithm supports generic spline optimization, this option enables the optimization of spline control points. Such optimization improves the result only if the splines use a smoothness between 0.1 and 0.9. It does not affect links that are not reshaped by the layout algorithm or that are routed as straight lines.

This is an expert option. It is disabled by default.

ParameterTypeDescription
flagBooleanSet to 'true' to enable the optimization of spline control points.
setStructureUpToDate

Sets whether the structure of the graph is up to date.

If the argument is false, notifies the layout instance that the structure of the graph was changed since the last time the layout was successfully performed.

Usually you do not need to call this method. The method is automatically called with a true argument each time the layout is successfully performed.

ParameterTypeDescription
uptodate
setSubgraphCorrectionInterface

Sets the correction strategy for subgraphs. The method ISubgraphCorrection.correct() of the subgraph correction interface is called immediately after the layout of the subgraph has finished. This allows you, for instance, to correct the position of the subgraph after its contents have been laid out.

If all subgraphs are laid out completely, and the layout mode of all layouts in the nested graph is not incremental, then you do not need to install any subgraph correction interface. However, in the following situations, it is useful to install a subgraph correction interface:

  • The subgraph is laid out, but its parent graph is not laid out (because no layout is specified for the parent graph).
  • The subgraph is laid out, but the subgraph is specified as fixed inside the parent graph (for instance by ibm_ilog.graphlayout.GraphLayout.isFixed()).
  • The subgraph and its parent graph are laid out, but the layout of the parent graph uses an incremental mode that analyzes the old position of the subgraph (see for instance ibm_ilog.graphlayout.tree.TreeLayout.setIncrementalMode() or ibm_ilog.graphlayout.hierarchical.HierarchicalLayout.setIncrementalMode()).
If subgraphs of type ibm_ilog.diagram.Graph are used, the layout of the subgraph affects the bounding box of the subgraph. The subgraph may appear at a completely different position after layout, even though no layout of the parent graph was performed that contains the subgraph as a node, and even though ibm_ilog.diagram.Graph.moveObject() was never called for the subgraph. The reason for this effect is simply the internal bounding box mechanism of ibm_ilog.diagram.Graph. This effect is very unfortunate in the situations that were described above. There are two predefined subgraph correction strategies that help to eliminate this effect: SubgraphCorrectionBarycenterFixed and SubgraphCorrectionBoundsFixed.

ParameterTypeDescription
ifc
setUseSeedValueForRandomGenerator

Sets whether the user-defined seed value should be used for the random generator.

An Error is thrown if the layout does not support this mechanism.

ParameterTypeDescription
option
stopImmediately
Returns Boolean: 'true' if the algorithm can be stopped at this time.

Stops the running layout algorithm as soon as possible. This works only if all layouts of all subgraphs support stopping the layout immediately. If the currently running sublayout of a subgraph does not support this feature, the sublayout will run to completion, but the layouts of other subgraphs will not be started.

This method can be used if multiple threads are used for layout and GUI control. The GUI control thread calls this method to notify the layout thread that the layout run must be stopped. The layout algorithm will perform some final cleanup operations before terminating. Therefore, the layout thread will continue until the cleanup operations are finished. The GUI thread, however, returns immediately from this method.

If the layout algorithm is stopped before completion, the result code of the layout report is ibm_ilog.graphlayout.GraphLayoutReport.STOPPED_AND_INVALID.

supportsAllowedTime
Returns Boolean

Indicates whether the layout class can stop the layout computation when a user-defined allowed time is exceeded.

In principle, the Recursive Layout supports this feature. If, however, the sublayout of a subgraph is running and does not support this feature, then the sublayout runs to completion first before the entire nested layout is stopped when the allowed time has elapsed.

If the layout algorithm is stopped before completion, the result code of the layout report is ibm_ilog.graphlayout.GraphLayoutReport.STOPPED_AND_INVALID.

supportsLayoutOfConnectedComponents
Returns Boolean

Indicates whether the layout class can cut the attached graph into connected components, apply itself on each connected component separately, and then use the layout instance returned by the method ibm_ilog.graphlayout.GraphLayout.getLayoutOfConnectedComponents() to position the connected components.

The default implementation always returns false. Subclasses can override this method in order to return true, that is, to indicate that this option is supported.

supportsLayoutRegion
Returns Boolean

Indicates whether the layout class can control the position and/or size of the graph drawing according to a user-defined region (a rectangle) or a user-defined area of a manager view.

The default implementation always returns false.

Subclasses can override this method in order to return true, that is, to indicate that this option is supported.

supportsLinkConnectionBox
Returns Boolean

Indicates whether the layout class can use a link connection box interface to calculate the end points of a link. The link connection box interface is an object that provides the rectangle to which the links are connected for each node and the tangential shift offset at each side for the connection points.

If the layout class supports this feature and a connection box interface object is set using the method ibm_ilog.graphlayout.GraphLayout.setLinkConnectionBoxInterface(), the layout algorithm uses this object to calculate the connection points for links.

The default implementation always returns false. Subclasses can override this method in order to return true, that is, to indicate that this option is supported.

supportsPercentageComplete
Returns Boolean

Indicates whether the layout class can estimate the percentage of completion during the run of the layout. If all layouts of subgraphs support this feature, the percentage value is calculated from the sublayouts.

If some sublayouts do not support this feature, the Recursive Layout algorithm can indicate by discrete percentage values how many layouts of subgraphs are already finished. For instance, if the nesting hierarchy contains five graphs, the percentage will increase in fixed steps by 20%.

The calculated percentage values are not very precise.

supportsPreserveFixedLinks
Returns Boolean

Indicates whether the layout class allows the user to specify fixed links. Fixed links are not reshaped during the layout.

The default implementation always returns false. Subclasses can override this method in order to return true; that is, to indicate that this option is supported.

supportsPreserveFixedNodes
Returns Boolean

Indicates whether the layout class allows the user to specify fixed nodes. Fixed nodes are not moved during the layout.

The default implementation always returns false. Subclasses can override this method in order to return true, that is, to indicate that this option is supported.

Note that fixed nodes can be handled differently by different layout algorithms. Some layout algorithms can adapt the layout of the non-fixed nodes to take into account the current positions of the fixed nodes. For details, refer to the documentation of the layout algorithm.

supportsRandomGenerator
Returns Boolean

Indicates whether the layout class uses randomly generated numbers (or randomly chosen parameters) for which it can accept a user-defined seed value. When you perform the same layout on the same graph several times and use the same user-defined seed value (or some other constant value), the same random numbers are generated and, if the algorithm is deterministic, you obtain the same drawing of the graph model. If you want different drawings each time you perform the layout, you can modify the seed value and call the method ibm_ilog.graphlayout.GraphLayout.setUseSeedValueForRandomGenerator() with a true argument.

The default implementation always returns false.

Subclasses can override this method in order to return true, that is, to indicate that this option is supported.

supportsSplineRouting
Returns Boolean

Indicates whether the layout class supports the generic optimization of spline control points.

Subclasses can override this method in order to return true, that is, to indicate that this option is supported. Subclasses that do not route the links and always use straight links cannot benefit from the generic mechanism.

supportsStopImmediately
Returns Boolean

Indicates whether the layout class can immediately interrupt the current run of the layout in a controlled way.

In principle, the Recursive Layout supports this feature. If, however, the sublayout of a subgraph is running and does not support this feature, then the sublayout runs to completion first before the entire nested layout is stopped.

If the layout algorithm is stopped before completion, the result code of the layout report is ibm_ilog.graphlayout.GraphLayoutReport.STOPPED_AND_INVALID.

toString
Returns String: A printable string representing this layout instance.

Returns a printable string containing the fully qualified class name and the identifier returned by the method getInstanceId().

unfixAllLinks

Removes the fixed attribute from all links in the graph model.

An Error is thrown if the layout class does not support this option or if there is no attached graph model.

unfixAllNodes

Removes the fixed attribute from all nodes in the graph model. An Error is thrown if the layout class does not support this option or if there is no attached graph model.

Events

onLayoutStepPerformed

This method can be called by the layout classes when a step (or iteration) of the layout algorithm has been performed.

ParameterTypeDescription
layoutStarted
layoutFinished
onObjectParameterChanged

Called when a layout parameter for a specific node or link has changed.

It calls ibm_ilog.graphlayout.GraphLayout.setParametersUpToDate() with a false argument to notify the layout instance that the layout is not up-to-date. It also fires a graph layout parameter event.

If you add new parameters for specific nodes and links to your own subclass of GraphLayout, you should call this method each time they are modified.

ParameterTypeDescription
nodeOrLinkObjectNode or link instance for which a parameter has been changed.
parameterNameStringName of the parameter whose value has been changed.
onParameterChanged

Called when a global layout parameter has changed.

Global layout parameters affect all or many nodes and links. It calls ibm_ilog.graphlayout.GraphLayout.setParametersUpToDate() with a false argument to notify the layout instance that the layout is not anymore up to date. It also fires a graph layout parameter event.

If you add new global parameters in your own subclass of GraphLayout, you should call this method each time they are modified.

ParameterTypeDescription
parameterNameStringName of the parameter whose value has been changed.
onParameterChangedImpl
ParameterTypeDescription
nodeOrLink
parameterName
onSubLayoutStepPerformed

This method is called by the graph layouts of subgraphs. It forwards the layout event to this Recursive Layout.

ParameterTypeDescription
eventibm_ilog.graphlayout.GraphLayoutEventThe layout event that may contain information about the behavior of the layout algorithm