ibm_ilog.graphlayout.RecursiveMultipleLayout (version 1.1-SNAPSHOT)
The main class for the Recursive Multiple Layout algorithm.
This is not a layout algorithm but rather a facility to perform multiple layouts recursively in a nested graph. In principle, this is just the combination of Recursive Layout and Multiple Layout.
Unless otherwise mentioned, the normal layout algorithms such as
ibm_ilog.graphlayout.hierarchical.HierarchicalLayout
,
ibm_ilog.graphlayout.tree.TreeLayout
,
ibm_ilog.graphlayout.MultipleLayout
, and so forth work on a
flat graph, that is, they lay out the attached graph but not the
subgraphs of the attached graph. Similarly, label layout algorithms
work only on flat managers, not on nested graphs. The Recursive
Multiple Layout is different: it traverses the nesting structure
starting from the attached graph and recursively applies a first
graph layout, then a second graph layout, and finally a label layout
on all subgraphs. It can be tailored for which sublayouts have to be
applied to which subgraph.
The Recursive Multiple Layout is a Recursive Layout (see
RecursiveLayout
) where all layouts of subgraphs are Multiple
Layouts (see ibm_ilog.graphlayout.MultipleLayout
).
For instance, assume that you want to apply to each subgraph a Tree
layout, then a Link layout for the nontree links, and finally a
Label layout for the link labels. It would be unfortunate to call
ibm_ilog.graphlayout.GraphLayout.performLayout()
multiple times to achieve this, because the tree layout of the parent
graph would be finished before the link layout of its subgraph has
started; hence the link layout of the subgraph invalidates the tree
layout of the parent graph again. To avoid this effect, the Tree
layout, Link layout, and Label layout of the subgraph should be
finished before any layout of the parent graph has started. The
following examples shows how to achieve this by using the Recursive
Multiple Layout class. There are basically two scenarios:
- The same set of layout algorithms must be applied to all subgraphs.
- An individual layout style must be applied to each subgraph.
To perform a Tree Layout, a Link Layout, and an Annealing Label Layout on a nested graph, call:
GraphLayout layout = new MultipleRecursiveLayout( new TreeLayout(), new LinkLayout(), new AnnealingLabelLayout()); layout.attach(grapher); layout.performLayout(true, true);If you simply want to apply a label layout in a nested grapher, call:
GraphLayout layout = new MultipleRecursiveLayout( new AnnealingLabelLayout()); layout.attach(grapher); layout.performLayout(true, true);In this case, each subgraph is treated bottom-up. First a tree layout is performed on the subgraph. Then a link layout is performed on the subgraph, finally the label layout is performed on the subgraph. All subgraphs of the nested graph including the top-level graph are treated in this way. All layouts are performed with the same global layout parameters as the layout instances passed as arguments to the constructor of
RecursiveMultipleLayout
, which are called
the reference layouts. You can access the reference layout
instances to change the global layout parameters:
TreeLayout treeLayout = (TreeLayout)layout.getFirstReferenceGraphLayout(); treeLayout.setFlowDirection(Direction.Left); LinkLayout linkLayout = (LinkLayout)layout.getSecondReferenceGraphLayout(); linkLayout.setLinkOffset(5f); AnnealingLabelLayout labelLayout = (AnnealingLabelLayout)layout.getReferenceLabelLayout(); labelLayout.setObstacleOffset(20f);Internally, a clone of the reference instance is created for each subgraph. This clone remains attached as long as the Recursive Multiple Layout is attached to the top-level graph. Before layout is performed, the global layout parameters are copied from the reference instance to each clone. If you need to set layout parameters for individual nodes, links, or labels, you have to access the layout instance of the subgraph that owns the node, link, or label:
TreeLayout treeLayout = (TreeLayout)layout.getFirstGraphLayout(subgraph); treeLayout.setAlignment(node, TreeLayout.TIP_OVER); LinkLayout linkLayout = (LinkLayout)layout.getSecondGraphLayout(subgraph); linkLayout.setLinkStyle(link, LinkLayout.ORTHOGONAL_STYLE); AnnealingLabelLayout labelLayout = (AnnealingLabelLayout)layout.getLabelLayout(subgraph); labelLayout.setLabelDescriptor(label, descriptor);
In the typical case, when you use instances of Graphic
as nodes and instances of Grapher
as subgraphs, it is:
TreeLayout treeLayout = (TreeLayout)layout.getFirstGraphLayout(node.getGraphicBag()); treeLayout.setAlignment(node, TreeLayout.TIP_OVER); ...
Second scenario: Different layout styles at different subgraphs
The following example shows the second scenario: Each subgraph should be laid out by a different layout style or with individual layout parameters. In this case, there are no reference layouts. You specify the layouts of subgraphs in a very convenient way:
RecursiveMultipleLayout layout = new RecursiveMultipleLayout(); layout.attach(topLevelGrapher); // specify the layout of the top-level graph layout.setLayout(null, new GridLayout(), new LinkLayout(), new RandomLabelLayout()); // specify the layout of subgraphs layout.setLayout(subgraph1, new TreeLayout(), new LinkLayout(), new AnnealingLabelLayout()); layout.setLayout(subgraph2, new HierarchicalLayout(), new LinkLayout(), new AnnealingLabelLayout()); // perform the layout LayoutReport report = layout.performLayout(true, true);In this scenario, all layout parameters of different subgraphs are independent. You access the layout instance of each individual subgraph in the same way as when you have a reference layout. This allows you to change global layout parameters for this subgraph as well as parameters of nodes , links, or labels of the subgraph.
Notes:
- The Recursive Multiple Layout does not support the specified
provider mode of
RecursiveLayout
. - It is not allowed to create a Recursive Layout that contains
another Recursive Layout:
layout = new RecursiveLayout(new RecursiveMultipleLayout()); layout.performLayout(true, true);
This would traverse the nested graph and perform the Recursive Layout for each subgraph, which, however, itself would recursively traverse the nested graph again. This would just be waste of run time. - The layout event listeners installed at the Recursive Multiple Layout receive layout events whenever the layout of a subgraph fires a layout event. These events, however, do not contain the information on which sublayout was started or finished. If you need this information, you should install an event listener at all sublayouts.
- The reference labeling model cannot be saved to named properties
via
ibm_ilog.graphlayout.AbstractGraphLayoutModel.saveParametersToNamedProperties()
.
Property Summary
- ACTIVE The sublayout is active for all subgraphs.
- AMASK
- DEFAULT_RECURSIVE_ALLOWED_TIME
- 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.
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
- onSubLayoutStepPerformed(event) This method is called by the graph layouts of subgraphs.
Properties
Methods
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
.
Parameter | Type | Description |
---|---|---|
graphModel | ibm_ilog.graphlayout.AbstractGraphLayoutModel | The graph model. |
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.
Parameter | Type | Description |
---|---|---|
a0 | ||
a1 |
Called when the structure or the geometry of the graph changes.
This method is the implementation of the
ibm_ilog.graphlayout.GraphModelListener
interface.
Parameter | Type | Description |
---|---|---|
event | ibm_ilog.graphlayout.GraphLayoutModelEvent | The event which describes the change that has occurred in the graph model. |
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.
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.
Parameter | Type | Description |
---|---|---|
source | ibm_ilog.graphlayout.GraphLayout | The layout instance from which the parameters are copied. |
Returns a new instance of the layout report.
The current implementation creates an instance of
RecursiveLayoutReport
.
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.
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.
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.
Parameter | Type | Description |
---|---|---|
subgraph | Object | The subgraph or 'null'. |
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.
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.
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.
Parameter | Type | Description |
---|---|---|
subgraph | Object | The subgraph or 'null'. |
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 byRecursiveLayout.setLayout()
. -
RecursiveLayout.SPECIFIED_PROVIDER_MODE
- The layout is applied using an explicitly specified layout provider.
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.
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.
Parameter | Type | Description |
---|---|---|
preOrder | Boolean | If 'true', the layout instances are returned in preorder, otherwise in postorder. |
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.
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.
Parameter | Type | Description |
---|---|---|
subgraph | Object | The subgraph or 'null'. |
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()
).
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.
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.
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.
Parameter | Type | Description |
---|---|---|
subgraph | Object | The subgraph or 'null'. |
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.
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.
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.
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.
Computes the layout using the Recursive Layout algorithm.
To start the layout, call the method
ibm_ilog.graphlayout.GraphLayout.performLayout()
.
Parameter | Type | Description |
---|---|---|
force | ||
traverse |
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.
Parameter | Type | Description |
---|---|---|
subgraph | The | subgraph to start the layout. |
force | If | <code>true</code>, the method {@link #isLayoutNeeded} is not called. No check is made to determine if it is necessary to perform the layout. |
traverse | If | <code>true</code>, the layout is applied recursively to all subgraphs contained in the subgraph. Otherwise, it is only applied on the input subgraph. |
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.
Parameter | Type | Description |
---|---|---|
subgraph | Object | The subgraph if used during nested layout, or 'null'. |
layout | ibm_ilog.graphlayout.GraphLayout | The sublayout to be performed. |
force | Boolean | If 'true', no check is made to determine if it is necessary to perform the layout. |
redraw | Boolean | If 'true', the attached graph model will be asked to redraw the graph after layout. |
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.
Parameter | Type | Description |
---|---|---|
active | Boolean | 'true' if the first graph layout is active, or 'false' otherwise. |
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.
Parameter | Type | Description |
---|---|---|
layout | ibm_ilog.graphlayout.GraphLayout | The layout instance that lays out the connected components of all subgraphs having a main layout that supports the connected component layout mechanism. |
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.
Parameter | Type | Description |
---|---|---|
enable | Boolean | If 'true', enables the connected component layout mechanism for all layouts of subgraphs that support this feature. |
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.
Parameter | Type | Description |
---|---|---|
linkConnectionBoxInterface | ibm_ilog.graphlayout.ILinkConnectionBoxProvider | The link connection box interface for the connection points of links for all layouts of subgraphs that support this feature. |
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.
Parameter | Type | Description |
---|---|---|
active | Boolean | Set to 'true' if the second graph layout is active. |
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.
Parameter | Type | Description |
---|---|---|
time | Number | The allowed time in milliseconds. |
Sets whether the layout checks whether links are appropriate. This is internally used. You should not use it.
Parameter | Type | Description |
---|---|---|
enable |
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 callingibm_ilog.graphlayout.MultipleLayout.setFirstGraphLayoutActive()
to control whether the first graph layout should be active or inactive.
Parameter | Type | Description |
---|---|---|
value | int | Sets whether the first graph layout is active. |
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.
Parameter | Type | Description |
---|---|---|
enable |
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.
Parameter | Type | Description |
---|---|---|
subgraph | Object | The subgraph or 'null'. |
layout | ibm_ilog.graphlayout.GraphLayout | The layout instance used to lay out the subgraph. This can be 'null', or must be an instance of 'MultipleLayout'. |
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.
Parameter | Type | Description |
---|---|---|
subgraph | Object | The subgraph or 'null'. |
layout | ibm_ilog.graphlayout.GraphLayout | The layout instance used to lay out the subgraph. This must be an instance of 'MultipleLayout'. |
detachPrevious | Boolean | If 'true', the layout instance previously specified as the preferred layout of the subgraph (if any) is detached. |
traverse | Boolean | If 'true', clones of the input layout are recursively used for all current subgraphs of the input graph. |
Sets whether layout is running. This method is part of IBM ILOG Dojo Diagrammer internals. You should not use it.
Parameter | Type | Description |
---|---|---|
running | Boolean | Whether layout is running or not. |
fromParents | Boolean | Whether this notification is from a parent layout or from this layout instance. |
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).
Parameter | Type | Description |
---|---|---|
time |
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.
Parameter | Type | Description |
---|---|---|
subgraph | Object | The subgraph or 'null'. |
layout1 | ibm_ilog.graphlayout.GraphLayout | The first graph layout used to lay out the subgraph. |
layout2 | ibm_ilog.graphlayout.GraphLayout | The second graph layout used to lay out the subgraph. |
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 callingibm_ilog.graphlayout.MultipleLayout.setSecondGraphLayoutActive()
to control whether the second graph layout should be active or inactive.
Parameter | Type | Description |
---|---|---|
value | int | Sets whether the second graph layout is active. |
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()
oribm_ilog.graphlayout.hierarchical.HierarchicalLayout.setIncrementalMode()
).
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
.
Parameter | Type | Description |
---|---|---|
ifc |
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
.
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
.
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.
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
This method is called by the graph layouts of subgraphs. It forwards the layout event to this Recursive Multiple Layout.
Parameter | Type | Description |
---|---|---|
event | ibm_ilog.graphlayout.GraphLayoutEvent | The layout event that may contain information about the behavior of the layout algorithm. |