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

Object » ibm_ilog.graphlayout.GraphLayout » ibm_ilog.graphlayout.RecursiveLayout » ibm_ilog.graphlayout.RecursiveMultipleLayout
dojo.require("ibm_ilog.graphlayout.RecursiveMultipleLayout");

The main class for the Recursive Multiple Layout algorithm.

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

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

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

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

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

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

GraphLayout layout = new MultipleRecursiveLayout(
new TreeLayout(),
new LinkLayout(),
new AnnealingLabelLayout());
layout.attach(grapher);
layout.performLayout(true, true); 
If you simply want to apply a label layout in a nested grapher, call:
GraphLayout layout = new MultipleRecursiveLayout(
new AnnealingLabelLayout());
layout.attach(grapher);
layout.performLayout(true, true);
In this case, each subgraph is treated bottom-up. First a tree layout is performed on the subgraph. Then a link layout is performed on the subgraph, finally the label layout is performed on the subgraph. All subgraphs of the nested graph including the top-level graph are treated in this way. All layouts are performed with the same global layout parameters as the layout instances passed as arguments to the constructor of RecursiveMultipleLayout, which are called the reference layouts. You can access the reference layout instances to change the global layout parameters:
TreeLayout treeLayout =
(TreeLayout)layout.getFirstReferenceGraphLayout();
treeLayout.setFlowDirection(Direction.Left);
LinkLayout linkLayout =
(LinkLayout)layout.getSecondReferenceGraphLayout();
linkLayout.setLinkOffset(5f);
AnnealingLabelLayout labelLayout =
(AnnealingLabelLayout)layout.getReferenceLabelLayout();
labelLayout.setObstacleOffset(20f); 
Internally, a clone of the reference instance is created for each subgraph. This clone remains attached as long as the Recursive Multiple Layout is attached to the top-level graph. Before layout is performed, the global layout parameters are copied from the reference instance to each clone. If you need to set layout parameters for individual nodes, links, or labels, you have to access the layout instance of the subgraph that owns the node, link, or label:
TreeLayout treeLayout = (TreeLayout)layout.getFirstGraphLayout(subgraph);
treeLayout.setAlignment(node, TreeLayout.TIP_OVER);
LinkLayout linkLayout = (LinkLayout)layout.getSecondGraphLayout(subgraph);
linkLayout.setLinkStyle(link, LinkLayout.ORTHOGONAL_STYLE);
AnnealingLabelLayout labelLayout = (AnnealingLabelLayout)layout.getLabelLayout(subgraph);
labelLayout.setLabelDescriptor(label, descriptor); 

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

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

Second scenario: Different layout styles at different subgraphs

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

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

Notes:

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

Property Summary

Method Summary

  • attach(graphModel) Allows you to specify the top-level graph model of the nested graph you want to lay out.
  • constructor(a0, a1) 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.
  • getFirstGraphLayout(subgraph) returns ibm_ilog.graphlayout.GraphLayout Returns the layout instance to be used for the input subgraph as the first layout.
  • getFirstGraphLayoutActive() returns int Returns whether the first graph layout of all subgraphs is active.
  • getFirstReferenceGraphLayout() returns ibm_ilog.graphlayout.GraphLayout Returns the first reference graph layout, if the reference layout mode is used.
  • 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.
  • getLayoutProvider() returns ibm_ilog.graphlayout.ILayoutProvider Returns the layout provider.
  • 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.
  • getReferenceLayout() returns ibm_ilog.graphlayout.GraphLayout Returns the reference layout if the reference layout mode is used; returns 'null' otherwise.
  • getSecondGraphLayout(subgraph) returns ibm_ilog.graphlayout.GraphLayout Returns the layout instance to be used for the input subgraph as the second layout.
  • getSecondGraphLayoutActive() returns int Tests if the second graph layout of all subgraphs is active.
  • getSecondReferenceGraphLayout() returns ibm_ilog.graphlayout.GraphLayout Returns the second reference graph layout, if the reference layout mode is used.
  • 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.
  • init() Initializes instance variables.
  • 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.
  • 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.
  • 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.
  • layout() Computes the layout using the Recursive Layout algorithm.
  • performLayout(force, traverse) 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, redraw) returns int Starts the input layout algorithm.
  • propagateFirstGraphLayoutActive(active) Sets whether the first graph layout of all subgraphs is active.
  • 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.
  • propagateSecondGraphLayoutActive(active) Sets whether the second graph layout of all subgraphs is active.
  • 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.
  • setFirstGraphLayoutActive(value) Sets whether the first graph layout of all subgraphs is active.
  • 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.
  • setLayoutRunning(running, fromParents) Sets whether layout is running.
  • 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.
  • setMultipleLayout(subgraph, layout1, layout2) Sets the layout instances to be used for the input subgraph.
  • setSecondGraphLayoutActive(value) Sets whether the second graph layout of all subgraphs is active.
  • setSubgraphCorrectionInterface(ifc) Sets the correction strategy for subgraphs.
  • 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.
  • supportsPercentageComplete() returns Boolean Indicates whether the layout class can estimate the percentage of completion during the run of the layout.
  • supportsStopImmediately() returns Boolean Indicates whether the layout class can immediately interrupt the current run of the layout in a controlled way.

Event Summary

Properties

ACTIVE
The sublayout is active for all subgraphs.
AMASK
INACTIVE
The sublayout is inactive for all subgraphs.
INTERNAL_PROVIDER_MODE
Layout mode with internal layout provider.
MIXED
The sublayout can be active or inactive for individual subgraphs.
REFERENCE_LAYOUT_MODE
Layout mode with reference layout.
SHIFT_FOR_AUTOLAYOUT
SPECIFIED_PROVIDER_MODE
Layout mode with explicitly specified provider.

Methods

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 Multiple Layout prepares and attaches the reference layouts in layout mode RecursiveMultipleLayout.REFERENCE_LAYOUT_MODE. If a label layout algorithm is used but no reference labeling model was specified before, it tries to use an ibm_ilog.graphlayout.label.DefaultLabelingModel.

ParameterTypeDescription
graphModelibm_ilog.graphlayout.AbstractGraphLayoutModelThe graph model.
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
a0
a1
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. The reference labeling model is not copied. It depends on the layout mode what is copied:

  • RecursiveMultipleLayout.REFERENCE_LAYOUT_MODE - The reference layouts are copied deeply.
  • RecursiveMultipleLayout.INTERNAL_PROVIDER_MODE - The information which subgraph uses which sublayouts is not copied.

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. The reference labeling model is not copied. It depends on the layout mode what is copied:

  • RecursiveMultipleLayout.REFERENCE_LAYOUT_MODE - The reference layouts are copied deeply.
  • RecursiveMultipleLayout.INTERNAL_PROVIDER_MODE - The information which subgraph uses which sublayouts is not copied.

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 ibm_ilog.graphlayout.GraphLayout.attach(). The detach method performs cleaning operations on the graph model. In addition to the cleaning operations in the base class, the Recursive Multiple Layout detaches the sublayouts of subgraphs and disposes of the labeling models including the reference labeling model. 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.

getFirstGraphLayout
Returns ibm_ilog.graphlayout.GraphLayout: The layout instance used as the first layout for the subgraph.

Returns the layout instance to be used for the input subgraph as the first layout. 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 grapher or 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 first reference graph layout are used for each subgraph.

ParameterTypeDescription
subgraphObjectThe subgraph or 'null'.
getFirstGraphLayoutActive
Returns int: If the first graph layout of all subgraphs is active, ' RecursiveMultipleLayout.ACTIVE' is returned. If the first graph layout of all subgraphs is inactive, ' RecursiveMultipleLayout.INACTIVE' is returned. Otherwise ' RecursiveMultipleLayout.MIXED' is returned.

Returns whether the first graph layout of all subgraphs is active. This holds for calls of ibm_ilog.graphlayout.GraphLayout.performLayout(), except for calls triggered by automatic layout. See RecursiveLayout.setAutoLayout() for more information.

getFirstReferenceGraphLayout
Returns ibm_ilog.graphlayout.GraphLayout

Returns the first reference graph 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.

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

Returns the layout instance to be used for the input subgraph. Here, it always returns an instance of MultipleLayout. 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 grapher or 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.

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.

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

getSecondGraphLayout
Returns ibm_ilog.graphlayout.GraphLayout: The layout instance used as the second layout for the subgraph.

Returns the layout instance to be used for the input subgraph as the second layout. 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 grapher or 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 second reference graph layout are used for each subgraph.

ParameterTypeDescription
subgraphObjectThe subgraph or 'null'.
getSecondGraphLayoutActive
Returns int: If the second graph layout of all subgraphs is active, ' RecursiveMultipleLayout.ACTIVE' is returned. If the second graph layout of all subgraphs is inactive, ' RecursiveMultipleLayout.INACTIVE' is returned. Otherwise ' RecursiveMultipleLayout.MIXED' is returned.

Tests if the second graph layout of all subgraphs is active. This holds for calls to ibm_ilog.graphlayout.GraphLayout.performLayout(), except for calls triggered by automatic layout (see RecursiveLayout.setAutoLayout()).

getSecondReferenceGraphLayout
Returns ibm_ilog.graphlayout.GraphLayout

Returns the second reference graph 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.

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

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.

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.

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.

layout

Computes the layout using the Recursive Layout algorithm.

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

performLayout
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
Returns int: The layout code. See ' ibm_ilog.graphlayout.GraphLayoutReport.getCode()'.

Starts the input layout algorithm. This method is used when this layout controls the input layout as the 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 Multiple Layout prepares the sublayouts according to the layout mode.

ParameterTypeDescription
subgraphObjectThe subgraph if used during nested layout, or 'null'.
layoutibm_ilog.graphlayout.GraphLayoutThe sublayout to be performed.
forceBooleanIf 'true', no check is made to determine if it is necessary to perform the layout.
redrawBooleanIf 'true', the attached graph model will be asked to redraw the graph after layout.
propagateFirstGraphLayoutActive

Sets whether the first graph layout of all subgraphs is active. This allows you to temporarily disable the first graph layouts. The first graph layouts are active by default. However, if you want to perform a layout using only the second graph layouts or the label layouts of the subgraphs, you can set the first layout inactive. In this case, none of the first graph layouts of subgraphs are performed when calling ibm_ilog.graphlayout.GraphLayout.performLayout() on the Recursive Multiple layout instance.

In reference layout mode, it calls ibm_ilog.graphlayout.MultipleLayout.setFirstGraphLayoutActive() at the reference layout, which is in this case a Multiple Layout. If a graph is attached and the layout mode is the internal provider mode, it traverses the nesting hierarchy and calls ibm_ilog.graphlayout.MultipleLayout.setFirstGraphLayoutActive() for all Multiple Layout instances of subgraphs. However, if you insert subgraphs after calling this method, or if you change the layout instances of subgraphs in the internal provider after calling this method, the new layouts of these subgraphs may have a different setting.

This method throws a runtime exception when no graph model is yet attached.

ParameterTypeDescription
activeBoolean'true' if the first graph layout is active, or 'false' otherwise.
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.
propagateSecondGraphLayoutActive

Sets whether the second graph layout of all subgraphs is active. This allows you to temporarily disable the second graph layouts. The second graph layouts are active by default. To perform a layout using only the first graph layouts or the label layouts of the subgraphs, set the second layout to be inactive. In this case, none of the second graph layouts of subgraphs are performed when calling ibm_ilog.graphlayout.GraphLayout.performLayout() on the Recursive Multiple layout instance.

In reference layout mode, ibm_ilog.graphlayout.MultipleLayout.setSecondGraphLayoutActive() is called at the reference layout, which is in this case a Multiple Layout. If a graph is attached and the layout mode is the internal provider mode, it traverses the nesting hierarchy and calls ibm_ilog.graphlayout.MultipleLayout.setSecondGraphLayoutActive() for all Multiple Layout instances of subgraphs. If you insert subgraphs after calling this method, or if you change the layout instances of subgraphs in the internal provider after calling this method, the new layouts of these subgraphs may have a different setting.

This method throws a runtime exception when no graph model is yet attached.

ParameterTypeDescription
activeBooleanSet to 'true' if the second graph layout is active.
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
setFirstGraphLayoutActive

Sets whether the first graph layout of all subgraphs is active. This holds for calls of ibm_ilog.graphlayout.GraphLayout.performLayout() , except for calls that were triggered by automatic layout. See RecursiveLayout.setAutoLayout() for more. Possible values are:

  • RecursiveMultipleLayout.ACTIVE: the first graph layout is active for all subgraphs.
  • RecursiveMultipleLayout.INACTIVE: the first graph layout is inactive for all subgraphs.
  • RecursiveMultipleLayout.MIXED: it is unspecified whether the first layout is active or inactive for all subgraphs. Instead, it is possible to specify for each subgraph individually by calling ibm_ilog.graphlayout.MultipleLayout.setFirstGraphLayoutActive() to control whether the first graph layout should be active or inactive.

ParameterTypeDescription
valueintSets whether the first graph layout is active.
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. The input layout must be an instance of MultipleLayout. 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 Multiple Layout as needed.

ParameterTypeDescription
subgraphObjectThe subgraph or 'null'.
layoutibm_ilog.graphlayout.GraphLayoutThe layout instance used to lay out the subgraph. This can be 'null', or must be an instance of 'MultipleLayout'.
setLayoutImpl

Sets the layout instance to be used for the input subgraph. The input layout must be an instance of MultipleLayout. If the traverse flag is true, it traverses the nested graph starting from the input graph and sets a clone of the input layout recursively for each subgraphs. 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 Multiple Layout as needed.

ParameterTypeDescription
subgraphObjectThe subgraph or 'null'.
layoutibm_ilog.graphlayout.GraphLayoutThe layout instance used to lay out the subgraph. This must be an instance of 'MultipleLayout'.
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.
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.
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
setMultipleLayout

Sets the layout instances to be used for the input subgraph. If null is passed as the subgraph, the input layout is used for the top-level graph. Internally, a Multiple Layout is created that contains the input layouts as sublayouts.

When the Recursive Multiple Layout is performed, layout1 is applied first and layout2 second to the input subgraph.

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

ParameterTypeDescription
subgraphObjectThe subgraph or 'null'.
layout1ibm_ilog.graphlayout.GraphLayoutThe first graph layout used to lay out the subgraph.
layout2ibm_ilog.graphlayout.GraphLayoutThe second graph layout used to lay out the subgraph.
setSecondGraphLayoutActive

Sets whether the second graph layout of all subgraphs is active. This holds for calls to ibm_ilog.graphlayout.GraphLayout.performLayout(), except calls triggered by automatic layout (see RecursiveLayout.setAutoLayout()). Possible values are:

  • RecursiveMultipleLayout.ACTIVE: the second graph layout is active for all subgraphs.
  • RecursiveMultipleLayout.INACTIVE: the second graph layout is inactive for all subgraphs.
  • RecursiveMultipleLayout.MIXED: it is unspecified whether the second layout is active or inactive for all subgraphs. Instead, it is possible to specify for each subgraph individually by calling ibm_ilog.graphlayout.MultipleLayout.setSecondGraphLayoutActive() to control whether the second graph layout should be active or inactive.

ParameterTypeDescription
valueintSets whether the second graph layout is active.
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
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.

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.

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.

Events

onSubLayoutStepPerformed

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

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