ilog.views.graphlayout.recursive
Class IlvRecursiveLayout

java.lang.Object
  ilog.views.graphlayout.IlvGraphLayout
      ilog.views.graphlayout.recursive.IlvRecursiveLayout

All Implemented Interfaces:

GraphLayoutEventListener, GraphModelListener, Serializable, EventListener

Direct Known Subclasses:

IlvRecursiveMultipleLayout

public class IlvRecursiveLayout
extends IlvGraphLayout
implements GraphLayoutEventListener

The main class for the Recursive Layout algorithm.

This is not a layout algorithm but rather a facility to perform layouts recursively in a nested grapher. Unless otherwise mentioned, the normal layout algorithms such as IlvHierarchicalLayout, IlvTreeLayout, IlvMultipleLayout, and so forth work on a flat graph, that is, they lay out the attached graph but not the subgraphs of the attached graph. The Recursive Layout is different: it traverses the nesting structure starting from the attached graph and applies a layout recursively on all subgraphs. It can be tailored for which sublayout has to be applied to which subgraph.

There are basically two scenarios:

• The same layout style must be applied to all subgraphs.
• An individual layout style must be applied to each subgraphs.

First scenario: Same layout style everywhere

The following example shows the first scenario:

 IlvGraphLayout layout = new IlvRecursiveLayout(new IlvTreeLayout());
 layout.attach(topLevelGrapher);
 IlvLayoutReport report = layout.performLayout(true, true); 

In this case, a tree layout is performed recursively to the top-level graph and to each subgraph. All layouts are performed with the same global layout parameters as for the layout instance passed as an argument to the constructor of IlvRecursiveLayout, which is called its reference layout. You can access the reference layout instance to change the global layout parameters:

 IlvTreeLayout treeLayout = (IlvTreeLayout)layout.getReferenceLayout();
 treeLayout.setFlowDirection(IlvDirection.Left); 

Internally, a clone of the reference instance is created for each subgraph. This clone remains attached as long as the Recursive Layout is attached to the top-level graph. Before layout is performed, the global layout parameters are copied from the reference instance to each clone. If you need to set layout parameters for individual nodes and links, you have to access the layout instance of the subgraph that owns the node or link:

 IlvTreeLayout treeLayout = (IlvTreeLayout)layout.getLayout(subgraph);
 treeLayout.setAlignment(node, IlvTreeLayout.TIP_OVER); 

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

 IlvTreeLayout treeLayout = (IlvTreeLayout)layout.getLayout(node.getGraphicBag());
 treeLayout.setAlignment(node, IlvTreeLayout.TIP_OVER); 

Second scenario: Different layout styles at different subgraphs

The following example shows the second scenario: Each subgraph should be laid out by a different layout style or with individual layout parameters. In this case, we need a layout provider (see IlvLayoutProvider) that specifies which layout instance is used for which subgraph.

 IlvGraphLayout layout = new IlvRecursiveLayout(layoutProvider);
 layout.attach(topLevelGrapher);
 IlvLayoutReport report = layout.performLayout(true, true); 

The layout provider returns a different layout instance for each subgraph. For example, it may return a grid layout for the top-level graph, but a tree layout for one subgraph and a bus layout for another subgraph of the top-level graph. Furthermore, each layout can have different global layout parameters. You can implement your own application-specific layout provider, or you can use the predefined IlvDefaultLayoutProvider or IlvRecursiveLayoutProvider that allows you to specify the preferred layout of each subgraph. If neither a reference layout nor a layout provider is given to the Recursive Layout, an internal default layout provider of class IlvRecursiveLayoutProvider is used. This allows you to specify the layouts of subgraphs in a very convenient way:

 IlvRecursiveLayout layout = new IlvRecursiveLayout();
 layout.attach(topLevelGrapher);
 // specify the layout of the top-level graph
 layout.setLayout(null, new IlvGridLayout()); 
 // specify the layout of subgraphs
 layout.setLayout(subgraph1, new IlvTreeLayout()); 
 layout.setLayout(subgraph2, new IlvBusLayout()); 
 // perform the layout
 IlvLayoutReport report = layout.performLayout(true, true); 

In this scenario, there is no reference layout. All layout parameters of different subgraphs are independent. You access the layout instance of each individual subgraph in order to change global layout parameters for this subgraph as well as parameters of nodes and links of the subgraph. For instance, if the attached top-level graph contains two subgraphs, and node1 belongs to subgraph1 and node2 belongs to subgraph2, you can set individual global and local layout parameters in this way:

 // access the layout of the top-level graph
 IlvGridLayout gridLayout = (IlvGridLayout)layout.getLayout(null);
 gridLayout.setLayoutMode(IlvGridLayout.TILE_TO_COLUMNS);
 // access the layouts of the subgraph
 IlvTreeLayout treeLayout = (IlvTreeLayout)layout.getLayout(subgraph1);
 treeLayout.setFlowDirection(IlvDirection.Left);
 treeLayout.setAlignment(node1, IlvTreeLayout.TIP_OVER);
 IlvBusLayout busLayout = (IlvBusLayout)layout.getLayout(subgraph2);
 busLayout.setOrdering(IlvBusLayout.ORDER_BY_HEIGHT);
 busLayout.setBus(node2);
 

Notes:

• The normal layout algorithms such as IlvHierarchicalLayout, IlvTreeLayout, IlvMultipleLayout, and so forth work only on a flat graph, but for convenience, you can apply IlvGraphLayout.performLayout(boolean, boolean, boolean) with the traverse flag set to true. This does not mean that the normal layout instance works on the entire nested graph including the subgraphs in this case. In fact, internally it uses a Recursive Layout in reference layout mode, that is, a clone of the top-level graph layout instance is created for each subgraph, and these clones are applied recursively to the nested graph. Each clone still treats only a flat graph.
• It is not possible to create a Recursive Layout that has a Recursive Layout as reference layout:

   layout = new IlvRecursiveLayout(new IlvRecursiveLayout()); 

  This calls the copy constructor of the Recursive Layout, but does not create a Recursive Layout in reference layout mode. A Recursive Layout inside another Recursive Layout would traverse the nested graph and perform the Recursive Layout for each subgraph, which, however, itself would recursively traverse the nested graph again. This would just be waste of run time.
• The layout event listeners installed at the Recursive Layout receive layout events whenever the layout of a subgraph fires a layout event. These events, however, do not contain the information on which sublayout was started or finished. If you need this information, you should install an event listener at all sublayouts.
• If you want to combine IlvMultipleLayout and IlvRecursiveLayout, you should use IlvRecursiveMultipleLayout, in particular when you use explicitly specified labeling models. The Recursive Layout that has a Multiple Layout as the reference layout works as long as default labeling models (instances of IlvDefaultLabelingModel) are used. The Recursive Multiple Layout is more flexible; it is in principle a Recursive Layout that has instances of Multiple Layout as sublayouts for the subgraphs. Additionally, the Recursive Multiple Layout ensures that the correct labeling models (clones of the specified labeling model) are created in the nested graph.

Since:

JViews 5.5

See Also:

Serialized Form

Field Summary

static int	INTERNAL_PROVIDER_MODE Layout mode with internal layout provider.
static int	PROPAGATE_CLASS_MISMATCH Bitmask for the return code of the parameter propagation methods.
static int	PROPAGATE_EXCEPTION Bitmask for the return code of the parameter propagation methods.
static int	PROPAGATE_PARAMETER_AMBIGUOUS Bitmask for the return code of the parameter propagation methods.
static int	PROPAGATE_PARAMETER_MISMATCH Bitmask for the return code of the parameter propagation methods.
static int	PROPAGATE_PARAMETER_SET Bitmask for the return code of the parameter propagation methods.
static int	REFERENCE_LAYOUT_MODE Layout mode with reference layout.
static int	SPECIFIED_PROVIDER_MODE Layout mode with explicitly specified provider.

Fields inherited from class ilog.views.graphlayout.IlvGraphLayout

INVERSE_VIEW_COORDINATES, MANAGER_COORDINATES, VIEW_COORDINATES

Constructor Summary

IlvRecursiveLayout()
Creates a new instance of the Recursive Layout algorithm that allows you to apply layouts to the entire nested graph.

IlvRecursiveLayout(IlvGraphLayout referenceLayout)
Creates a new instance of the Recursive Layout algorithm that allows you to apply the reference layout to the entire nested graph.

IlvRecursiveLayout(IlvLayoutProvider layoutProvider)
Creates a new instance of the Recursive Layout algorithm that allows you to apply layouts to the entire nested graph.

IlvRecursiveLayout(IlvRecursiveLayout source)
Creates a new layout instance by copying an existing one.

Method Summary

void	addGraphLayoutEventListener(GraphLayoutEventListener listener, boolean includeSelf, boolean traverse) Adds a listener for the layout events delivered during the layout.
void	addGraphLayoutParameterEventListener(GraphLayoutParameterEventListener listener, boolean includeSelf, boolean traverse) Adds a listener for the layout parameter events delivered when layout parameters change.
void	addSubLayoutEventListener(GraphLayoutEventListener listener) Adds a listener for the layout events delivered during the layout of subgraphs.
void	attach(IlvGraphModel graphModel) Allows you to specify the top-level graph model of the nested graph you want to lay out.
void	checkAppropriateLinks() Throws an exception if the links are not appropriate for the layout.
void	contentsChanged(GraphModelEvent event) Invoked when the structure or the geometry of the graph changes.
IlvGraphLayout	copy() Copies the layout instance.
void	copyParameters(IlvGraphLayout source) Copies the parameters from a given layout instance.
protected IlvGraphLayoutGrapherProperty	createLayoutGrapherProperty(String name, boolean withDefaults) Returns a new instance of IlvRecursiveLayoutGrapherProperty that stores the parameter settings of this layout class.
IlvGraphLayoutReport	createLayoutReport() Returns a new instance of the layout report.
void	detach() Detaches the graph model from the layout instance.
IlvGraphLayout	getLayout(Object subgraph) Returns the layout instance to be used for the input subgraph.
int	getLayoutMode() Returns the layout mode of the Recursive Layout.
IlvLayoutProvider	getLayoutProvider() Returns the layout provider.
IlvGraphLayoutReport	getLayoutReport(Object subgraph) Returns the report of the graph layout of the input subgraph.
Enumeration	getLayouts(boolean preOrder) Returns the instances of IlvGraphLayout for the nested graph encapsulated by the graph model of this layout instance.
IlvGraphLayout	getReferenceLayout() Returns the reference layout, if the reference layout mode is used.
IlvSubgraphCorrectionInterface	getSubgraphCorrectionInterface() Returns the subgraph correction interface that is applied after the nodes and links of the subgraph were laid out.
protected void	init() Initializes instance variables.
boolean	isGeometryUpToDate() 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.
boolean	isLoadLayoutModeFromNamesProperties() Returns true if loading the parameters of this layout by IlvGrapherAdapter.loadParametersFromNamedProperties(IlvGraphLayout) modifies the layout mode of this instance.
boolean	isParametersUpToDate() 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.
boolean	isSavePreferredLayoutsToNamedProperties() Returns true if saving the parameters of this layout by IlvGrapherAdapter.saveParametersToNamedProperties(IlvGraphLayout, boolean) sets the preferred layout flags in the created named properties.
boolean	isStructureUpToDate() 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.
protected void	layout(boolean redraw) Computes the layout using the Recursive Layout algorithm.
void	layoutStepPerformed(GraphLayoutEvent event) This method is called by the graph layouts of subgraphs.
IlvGraphLayoutReport	performLayout(boolean force, boolean redraw) Starts the layout algorithm.
int	performLayout(boolean force, boolean redraw, boolean traverse) Starts the layout algorithm.
IlvGraphLayoutReport	performLayout(Object subgraph, boolean force, boolean redraw, boolean traverse) Starts the layout algorithm with a subgraph.
protected int	performSublayout(Object subgraph, IlvGraphLayout layout, boolean force, boolean redraw) Starts the input layout algorithm.
int	propagateAndApply(String methodName, Class layoutClass, Object nodeOrLink, Object[] args) Propagates the application of a method (specified by the method name and the arguments) to all layouts of subgraphs in the attached nested graph.
void	propagateLayoutOfConnectedComponents(IlvGraphLayout layout) Sets the layout instance that lays out the connected components of all subgraphs that have a main layout that supports the connected component layout mechanism.
void	propagateLayoutOfConnectedComponentsEnabled(boolean enable) Enables the connected component layout mechanism for all layouts of subgraphs that support this feature.
int	propagateLayoutParameter(String parameterName, Class layoutClass, boolean value) Propagates a layout parameter to all layouts of subgraphs that support the parameter.
int	propagateLayoutParameter(String parameterName, Class layoutClass, float value) Propagates a layout parameter to all layouts of subgraphs that support the parameter.
int	propagateLayoutParameter(String parameterName, Class layoutClass, int value) Propagates a layout parameter to all layouts of subgraphs that support the parameter.
int	propagateLayoutParameter(String parameterName, Class layoutClass, Object value) Propagates a layout parameter to all layouts of subgraphs that support the parameter.
int	propagateLayoutParameter(String parameterName, Class layoutClass, Object nodeOrLink, boolean value) Propagates a node or link layout parameter to all layouts of subgraphs that support the parameter and contain the node or link.
int	propagateLayoutParameter(String parameterName, Class layoutClass, Object nodeOrLink, int value) Propagates a node or link layout parameter to all layouts of subgraphs that support the parameter and contain the node or link.
int	propagateLayoutParameter(String parameterName, Class layoutClass, Object nodeOrLink, Object value) Propagates a node or link layout parameter to all layouts of subgraphs that support the parameter and contain the node or link.
void	propagateLinkClipInterface(IlvLinkClipInterface linkClipInterface) Sets the clip interface for the connection points of links at all layouts of subgraphs that support this feature.
void	propagateLinkConnectionBoxInterface(IlvLinkConnectionBoxInterface linkConnectionBoxInterface) Sets the link connection box interface for the connection points of links at all layouts of subgraphs that support this feature.
void	removeGraphLayoutEventListener(GraphLayoutEventListener listener, boolean includeSelf, boolean traverse) Removes a listener for the layout events delivered during the layout.
void	removeGraphLayoutParameterEventListener(GraphLayoutParameterEventListener listener, boolean includeSelf, boolean traverse) Removes a listener for the layout parameter events delivered when layout parameters change.
void	removeSubLayoutEventListener(GraphLayoutEventListener listener) Removes a listener for the layout events delivered during the layout of subgraphs.
void	setAutoLayout(boolean enable) Enables the auto layout mode.
void	setConnectionPointCheckEnabled(boolean enable) Enables or disables the checks of the connection points of the links on the origin or destination node in the attached graph model and recursively in all graph models of subgraphs of the attached nested graph.
void	setCoordinatesMode(int mode) Sets the coordinates mode.
void	setInputCheckEnabled(boolean enable) Enables the checks for the nodes, links, and/or labels provided as arguments for the different methods of this layout algorithm and its sublayout algorithms.
void	setLayout(Object subgraph, IlvGraphLayout layout) Sets the layout instance to be used for the input subgraph.
void	setLayout(Object subgraph, IlvGraphLayout layout, boolean detachPrevious, boolean traverse) Sets the layout instance to be used for the input subgraph.
void	setLinkCheckEnabled(boolean enable) Enables or disables the checks of the links in the attached graph model and recursively in all graph models of subgraphs of the attached nested graph.
void	setLoadLayoutModeFromNamesProperties(boolean flag) Sets whether loading the parameters of this layout by IlvGrapherAdapter.loadParametersFromNamedProperties(IlvGraphLayout) modifies the layout mode of this instance.
void	setMinBusyTime(long time) Sets the minimal time the layout algorithm can be busy between two calls of layoutStepPerformed when the method callLayoutStepPerformedIfNeeded is used.
void	setSavePreferredLayoutsToNamedProperties(boolean flag) Sets whether saving the parameters of this layout by IlvGrapherAdapter.saveParametersToNamedProperties(IlvGraphLayout, boolean) sets the preferred layouts in the created named properties.
void	setSubgraphCorrectionInterface(IlvSubgraphCorrectionInterface ifc) Sets the correction strategy for subgraphs.
void	setUseDefaultParameters(boolean option) Specifies whether default parameters are to be used in the layout.
boolean	stopImmediately() Stops the running layout algorithm as soon as possible.
boolean	supportsAllowedTime() Indicates whether the layout class can stop the layout computation when a user-defined allowed time is exceeded.
boolean	supportsPercentageComplete() Indicates whether the layout class can estimate the percentage of completion during the run of the layout.
boolean	supportsSaveParametersToNamedProperties() Indicates whether the layout class can transfer the layout parameters to named properties.
boolean	supportsStopImmediately() Indicates whether the layout class can immediately interrupt the current run of the layout in a controlled way.
boolean	useAnimateRedraw() Returns true if animation is supported and enabled for any sublayout of the Recursive Layout.

Methods inherited from class ilog.views.graphlayout.IlvGraphLayout

addGraphLayoutEventListener, addGraphLayoutParameterEventListener, afterLayoutOfSubgraph, attach, beforeLayout, beforeLayoutOfSubgraph, callLayoutStepPerformedIfNeeded, checkAppropriateLink, cleanGraphModel, cleanLink, cleanNode, clipAllLinks, clipLink, createLayoutLinkProperty, createLayoutNodeProperty, getAllowedTime, getAutoLayoutHandler, getBalanceSplineCurveThreshold, getCalcLayoutRegion, getCoordinatesMode, getGrapher, getGraphModel, getInstanceId, getLayoutOfConnectedComponents, getLayoutOfConnectedComponentsReport, getLayoutRegion, getLayoutReport, getLinkClipInterface, getLinkConnectionBoxInterface, getMaxSplineCurveSize, getMinBusyTime, getMinSplineCurveSize, getMovingNodes, getParentLayout, getProperty, getProperty, getRecursiveLayout, getRemainingAllowedTime, getSeedValueForRandomGenerator, getSpecLayoutRegion, getSplineLinkFilter, increasePercentageComplete, isAnimate, isAutoLayout, isFitToView, isFixed, isInputCheckEnabled, isLayoutNeeded, isLayoutOfConnectedComponentsEnabled, isLayoutOfConnectedComponentsEnabledByDefault, isLayoutRunning, isLayoutTimeElapsed, isMemorySavings, isPreserveFixedLinks, isPreserveFixedNodes, isSplineRoutingEnabled, isStoppedImmediately, isUseDefaultParameters, isUseSeedValueForRandomGenerator, layoutStepPerformed, onParameterChanged, onParameterChanged, performAutoLayout, performLayout, PerformLayout, removeGraphLayoutEventListener, removeGraphLayoutParameterEventListener, setAllowedTime, setAnimate, setAutoLayoutHandler, setBalanceSplineCurveThreshold, setFixed, setGeometryUpToDate, setGrapher, setGraphModel, setLayoutOfConnectedComponents, setLayoutOfConnectedComponentsEnabled, setLayoutRegion, setLayoutRegion, setLayoutRegion, setLayoutReport, setLinkClipInterface, setLinkConnectionBoxInterface, setMaxSplineCurveSize, setMemorySavings, setMinSplineCurveSize, setParametersUpToDate, setParentLayout, setPreserveFixedLinks, setPreserveFixedNodes, setProperty, setProperty, setSeedValueForRandomGenerator, setSplineLinkFilter, setSplineRoutingEnabled, setStructureUpToDate, setUseSeedValueForRandomGenerator, supportsAnimation, supportsLayoutOfConnectedComponents, supportsLayoutRegion, supportsLinkClipping, supportsLinkConnectionBox, supportsMemorySavings, supportsPreserveFixedLinks, supportsPreserveFixedNodes, supportsRandomGenerator, supportsSplineRouting, unfixAllLinks, unfixAllNodes

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

REFERENCE_LAYOUT_MODE

public static final int REFERENCE_LAYOUT_MODE

Layout mode with reference layout.

See Also:

IlvRecursiveLayout(IlvGraphLayout), getLayoutMode(), Constant Field Values

INTERNAL_PROVIDER_MODE

public static final int INTERNAL_PROVIDER_MODE

Layout mode with internal layout provider.

See Also:

IlvRecursiveLayout(), getLayoutMode(), Constant Field Values

SPECIFIED_PROVIDER_MODE

public static final int SPECIFIED_PROVIDER_MODE

Layout mode with explicitly specified provider.

See Also:

IlvRecursiveLayout(IlvLayoutProvider), getLayoutMode(), Constant Field Values

PROPAGATE_PARAMETER_SET

public static final int PROPAGATE_PARAMETER_SET

Bitmask for the return code of the parameter propagation methods. The parameter propagation methods allow to set a parameter in all layout instances of subgraphs of a nested graph. If the bit is set in the return code of a parameter propagation method, the layout parameter was successfully set at some layout instance of a subgraph. Note that the layout parameter setting may be successful for some subgraphs but fail for others, hence the return code can be a bitwise-Or combination of various bitmasks. If the bit is not set, the propagation was not successful at all or there was no subgraph.

Since:

JViews 6.0

See Also:

propagateLayoutParameter(java.lang.String, java.lang.Class, int), Constant Field Values

PROPAGATE_PARAMETER_AMBIGUOUS

public static final int PROPAGATE_PARAMETER_AMBIGUOUS

Bitmask for the return code of the parameter propagation methods. The parameter propagation methods allow to set a parameter in all layout instances of subgraphs of a nested graph. If the bit is set in the return code of a parameter propagation method, the method to set the parameter could not be uniquely determined at some layout instance of some subgraph. This means there were several possible overloaded methods, so that the method invocation via reflection was ambiguous. While the compiler refuses to compile in ambiguous situations, the propagation mechanism selects an arbitrary method to invoke (assuming that with a proper design of the graph layout class, the overloaded methods are closely related). Note that the layout parameter setting may be ambiguous for some subgraphs but fail for others, hence the return code can be a bitwise-Or combination of various bitmasks. If the bit is not set, there was no ambiguity. This is normally the case for layout parameters.

Since:

JViews 6.0

See Also:

propagateLayoutParameter(String, Class, Object), Constant Field Values

PROPAGATE_CLASS_MISMATCH

public static final int PROPAGATE_CLASS_MISMATCH

Bitmask for the return code of the parameter propagation methods. The parameter propagation methods allow to set a parameter in all layout instances of subgraphs of a nested graph. If the bit is set in the return code of a parameter propagation method, the layout parameter could not be set at some layout instance of a subgraph because the class of the layout instance did not match the desired layout class. Note that the layout parameter setting may be successful for some subgraphs but fail for others, hence the return code can be a bitwise-Or combination of various bitmasks.

Since:

JViews 6.0

See Also:

propagateLayoutParameter(String, Class, Object), Constant Field Values

PROPAGATE_PARAMETER_MISMATCH

public static final int PROPAGATE_PARAMETER_MISMATCH

Bitmask for the return code of the parameter propagation methods. The parameter propagation methods allow to set a parameter in all layout instances of subgraphs of a nested graph. If the bit is set in the return code of a parameter propagation method, the layout parameter could not be set at some layout instance of a subgraph because no matching set-method with appropriate argument type was found via reflection. Note that the layout parameter setting may be successful for some subgraphs but fail for others, hence the return code can be a bitwise-Or combination of various bitmasks.

Since:

JViews 6.0

See Also:

propagateLayoutParameter(String, Class, Object), Constant Field Values

PROPAGATE_EXCEPTION

public static final int PROPAGATE_EXCEPTION

Bitmask for the return code of the parameter propagation methods. The parameter propagation methods allow to set a parameter in all layout instances of subgraphs of a nested graph. If the bit is set in the return code of a parameter propagation method, the layout parameter could not be set at some layout instance of a subgraph because calling the matching set-method raised an exception. Note that the layout parameter setting may be successful for some subgraphs but fail for others, hence the return code can be a bitwise-Or combination of various bitmasks.

Since:

JViews 6.0

See Also:

propagateLayoutParameter(String, Class, Object), Constant Field Values

Constructor Detail

IlvRecursiveLayout

public IlvRecursiveLayout(IlvGraphLayout referenceLayout)

Creates a new instance of the Recursive Layout algorithm that allows you to apply the reference layout to the entire nested graph. You should use this constructor if you want to apply the same layout style with the same global layout parameters to all subgraphs of the nested graph. The layout mode of this Recursive Layout is REFERENCE_LAYOUT_MODE.

The reference layout must not be an instance of IlvRecursiveLayout.

To indicate the top-level grapher of the nesting hierarchy you want to lay out, use the method attach(IlvGrapher).
To indicate the graph model of the top-level graph of the nesting hierarchy you want to lay out, use the method attach(IlvGraphModel).
To perform the layout, use the method performLayout(boolean, boolean).

See Also:

IlvGraphLayout.attach(ilog.views.IlvGrapher), attach(ilog.views.graphlayout.IlvGraphModel), IlvGraphLayout.performLayout(), getLayoutMode()

IlvRecursiveLayout

public IlvRecursiveLayout()

Creates a new instance of the Recursive Layout algorithm that allows you to apply layouts to the entire nested graph. You should use this constructor if you want to apply a different layout style or individual layout parameters to each subgraph of the nested graph. After attaching the top-level grapher or graph model, you can specify which layout is applied to which subgraph by using setLayout(Object, IlvGraphLayout). The layout mode of this Recursive Layout is INTERNAL_PROVIDER_MODE.

To indicate the top-level grapher of the nesting hierarchy you want to lay out, use the method attach(IlvGrapher).
To indicate the graph model of the top-level graph of the nesting hierarchy you want to lay out, use the method attach(IlvGraphModel).
To perform the layout, use the method performLayout(boolean, boolean).

See Also:

IlvGraphLayout.attach(ilog.views.IlvGrapher), attach(ilog.views.graphlayout.IlvGraphModel), IlvGraphLayout.performLayout(), getLayoutMode()

IlvRecursiveLayout

public IlvRecursiveLayout(IlvLayoutProvider layoutProvider)

Creates a new instance of the Recursive Layout algorithm that allows you to apply layouts to the entire nested graph. You should use this constructor if you want to apply a different layout style or individual layout parameters to each subgraph of the nested graph, and you have implemented your own layout provider that delivers the layout instances for each subgraph. The layout mode of this Recursive Layout is SPECIFIED_PROVIDER_MODE.

In this mode, loading and saving parameters to named properties works only if the Recursive Layout that loads the parameters uses a layout provider that is compatible with the layout provider of the Recursive Layout that was saved (that is, both layout providers should deliver instances of the same layout class for the same subgraph). If the layout provider implements the IlvPersistentObject interface, the Recursive Layout tries to save the layout provider to named properties so that it can be loaded again, but otherwise it is the responsibility of the user to make sure that the layout providers during loading and saving are compatible.

To indicate the top-level grapher of the nesting hierarchy you want to lay out, use the method attach(IlvGrapher). To indicate the graph model of the top-level graph of the nesting hierarchy you want to lay out, use the method attach(IlvGraphModel). To perform the layout, use the method performLayout(boolean, boolean).

See Also:

IlvGraphLayout.attach(ilog.views.IlvGrapher), attach(ilog.views.graphlayout.IlvGraphModel), IlvGraphLayout.performLayout(), getLayoutMode(), setLoadLayoutModeFromNamesProperties(boolean)

IlvRecursiveLayout

public IlvRecursiveLayout(IlvRecursiveLayout source)

Creates a new layout instance by copying an existing one. This constructor is used by the copy() method. Any subclass should provide a copy constructor.

The parameters of the source layout are copied using the method copyParameters(IlvGraphLayout).

Parameters:

source - The layout instance that is copied.

See Also:

copy(), copyParameters(ilog.views.graphlayout.IlvGraphLayout)

Method Detail

init

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

Overrides:

init in class IlvGraphLayout

copy

public IlvGraphLayout copy()

Copies the layout instance.

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

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

Specified by:

copy in class IlvGraphLayout

Returns:

A copy of the layout instance.

See Also:

IlvRecursiveLayout(IlvRecursiveLayout), copyParameters(ilog.views.graphlayout.IlvGraphLayout), getLayoutMode()

copyParameters

public void copyParameters(IlvGraphLayout source)

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

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

Overrides:

copyParameters in class IlvGraphLayout

Parameters:

source - The layout instance from which the parameters are copied.

See Also:

copy(), getLayoutMode()

getLayoutMode

public int getLayoutMode()

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

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

See Also:

IlvRecursiveLayout(), IlvRecursiveLayout(IlvGraphLayout), IlvRecursiveLayout(IlvLayoutProvider), setLoadLayoutModeFromNamesProperties(boolean)

getLayoutProvider

public IlvLayoutProvider getLayoutProvider()

Returns the layout provider.

If the reference layout mode is used, it returns an internally created instance of IlvDefaultLayoutProvider.

If the internal provider mode is used, it returns an internally created instance of IlvRecursiveLayoutProvider.

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

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

See Also:

getLayoutMode()

getReferenceLayout

public IlvGraphLayout getReferenceLayout()

Returns the reference layout, if the reference layout mode is used. It 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.

See Also:

getLayoutMode(), IlvRecursiveLayout(IlvGraphLayout)

setLayout

public void setLayout(Object subgraph,
                      IlvGraphLayout layout)

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

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

Parameters:

subgraph - The subgraph or null.

layout - The layout instance used to lay out the subgraph. This should be a new layout instance that is not used anywhere else.

See Also:

IlvGraphLayout.attach(ilog.views.IlvGrapher), attach(ilog.views.graphlayout.IlvGraphModel), getLayoutMode(), IlvRecursiveLayout(), getLayout(java.lang.Object)

setLayout

public void setLayout(Object subgraph,
                      IlvGraphLayout layout,
                      boolean detachPrevious,
                      boolean traverse)

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

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

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

Parameters:

subgraph - The subgraph or null.

layout - The layout instance used to lay out the subgraph. This should be a new layout instance that is not used anywhere else.

detachPrevious - If true, the layout instance previously specified as the preferred layout of the subgraph (if any) is detached.

traverse - If true, clones of the input layout are recursively used for all current subgraphs of the input graph.

See Also:

setLayout(Object, IlvGraphLayout), IlvGraphLayout.attach(ilog.views.IlvGrapher), attach(ilog.views.graphlayout.IlvGraphModel), getLayoutMode(), IlvRecursiveLayout(), getLayout(java.lang.Object)

getLayout

public IlvGraphLayout getLayout(Object subgraph)

Returns the layout instance to be used for the input subgraph. If null is passed as the subgraph, the layout instance of the top-level graph is returned. You can use this method in all layout modes. You must attach a 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.

Overrides:

getLayout in class IlvGraphLayout

Parameters:

subgraph - The subgraph or null.

Returns:

The layout instance used to lay out the subgraph.

See Also:

IlvGraphLayout.attach(ilog.views.IlvGrapher), attach(ilog.views.graphlayout.IlvGraphModel), getLayoutMode(), setLayout(Object,IlvGraphLayout)

getLayouts

public Enumeration getLayouts(boolean preOrder)

Returns the instances of IlvGraphLayout 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 grapher or graph model first before using this method.

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

Overrides:

getLayouts in class IlvGraphLayout

Parameters:

preOrder - If true, the layout instances are returned in preorder, otherwise in postorder.

See Also:

IlvGraphLayout.attach(ilog.views.IlvGrapher), attach(ilog.views.graphlayout.IlvGraphModel), getLayoutMode(), getLayout(java.lang.Object)

attach

public void attach(IlvGraphModel graphModel)

Allows you to specify the top-level graph model of the nested graph you want to lay out. In addition to the functionality of the base class, the Recursive Layout prepares and attaches the reference layout in layout mode REFERENCE_LAYOUT_MODE.

Overrides:

attach in class IlvGraphLayout

Parameters:

graphModel - The graph model.

See Also:

detach()

detach

public void 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 attach(ilog.views.graphlayout.IlvGraphModel). The detach method performs cleaning operations on the graph model. In addition to the cleaning operations in the base class, the Recursive Layout detaches the sublayouts of subgraphs. In internal provider mode, it also cleans all settings of layout instances for subgraphs.

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

Overrides:

detach in class IlvGraphLayout

See Also:

IlvGraphLayout.attach(ilog.views.IlvGrapher), attach(ilog.views.graphlayout.IlvGraphModel), setLayout(Object,IlvGraphLayout)

createLayoutReport

public IlvGraphLayoutReport createLayoutReport()

Returns a new instance of the layout report. The current implementation creates an instance of IlvRecursiveLayoutReport.

Overrides:

createLayoutReport in class IlvGraphLayout

See Also:

createLayoutReport(), IlvRecursiveLayoutReport

getLayoutReport

public IlvGraphLayoutReport getLayoutReport(Object 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.

Parameters:

subgraph - The subgraph or null.

Returns:

The layout report of the last layout run for the subgraph.

See Also:

IlvGraphLayout.attach(ilog.views.IlvGrapher), attach(ilog.views.graphlayout.IlvGraphModel), getLayoutMode()

performLayout

public int performLayout(boolean force,
                         boolean redraw,
                         boolean traverse)
                  throws IlvGraphLayoutException

Starts the layout algorithm. This is different from the implementation of the base class; the Recursive Layout always ignores the traverse flag because the layout is always done recursively.

Overrides:

performLayout in class IlvGraphLayout

Parameters:

force - If true, the method IlvGraphLayout.isLayoutNeeded() is not called. No check is made to determine if it is necessary to perform the layout.

redraw - If true, the attached graph model will be asked to redraw the graph after layout. To move the nodes and reshape the links, the implementation of this method passes the value of the redraw argument to the methods IlvGraphModel.moveNode(java.lang.Object, float, float, boolean) and IlvGraphModel.reshapeLink(java.lang.Object, ilog.views.IlvPoint, ilog.views.IlvPoint[], int, int, ilog.views.IlvPoint, boolean).

traverse - If true, the layout is applied to the attached graph model and recursively to all subgraph models of the attached graph model. Otherwise, it is only applied on the attached graph model.

Returns:

The layout code (see IlvGraphLayoutReport.getCode()).

Throws:

IlvGraphLayoutException - A new instance of IlvGraphLayoutException is thrown if one of the following occurs:

• No graph model is attached.
• The attached graph model is null.
• The layout report created by the method IlvGraphLayout.createLayoutReport() is null.

The method also throws any IlvGraphLayoutException thrown by the method IlvGraphLayout.layout(boolean). In particular, the following subclasses of IlvGraphLayoutException can be thrown:

• IlvInappropriateGraphException
• IlvInappropriateLinkException

For details, refer to the documentation of the layout exception classes.

See Also:

IlvGraphLayout.performLayout(), IlvGraphLayout.performLayout(boolean, boolean), IlvGraphLayout.PerformLayout(IlvGraphModel, IlvLayoutProvider, boolean, boolean, boolean), IlvGraphModel.performLayout(IlvLayoutProvider, boolean, boolean, boolean), IlvGraphLayout.layout(boolean), IlvGraphLayout.isLayoutNeeded(), IlvGraphLayout.isStructureUpToDate(), IlvGraphLayout.isGeometryUpToDate(), IlvGraphLayout.isParametersUpToDate(), IlvRecursiveLayout,