ilog.views.graphlayout
Class IlvDefaultLayoutProvider

java.lang.Object
  ilog.views.graphlayout.IlvDefaultLayoutProvider

All Implemented Interfaces:

IlvLayoutProvider

Direct Known Subclasses:

IlvRecursiveLayoutProvider

public class IlvDefaultLayoutProvider
extends Object
implements IlvLayoutProvider

A default implementation of the interface IlvLayoutProvider.

This class is mainly useful when laying out nested graphs, that is, graphs containing nodes that are other graphs. It provides the following services:

• Allows you to set a layout instance for a given graph model (see the method setPreferredLayout(IlvGraphModel, IlvGraphLayout)).
• When no layout instance is specified for a given graph model using the method setPreferredLayout(IlvGraphModel, IlvGraphLayout), the protected method (createGraphLayout(IlvGraphModel)) is called. The default implementation of this method "clones" the layout instance of the closest parent graph for which a layout has been set. You can override this method to change this behavior.

  Warning: to avoid repeatedly "cloning" the layout instance, the method getGraphLayout(IlvGraphModel) stores the "cloned" layout instance as the preferred layout of the given graph model. This means that any change to the parameters of the layout that has been "cloned," after the call of getGraphLayout(IlvGraphModel), does not affect the "cloned" layout instance. This allows you to set parameters independently on each layout instance. However, if you need to replicate the same parameter settings on the layout instance that has been previously "cloned," you can, for instance, delete the preferred layout (setPreferredLayout(model, null)). This way the layout instance of the parent graph will be "cloned" again with its new parameter settings.

Note that you must call the method detachLayouts(IlvGraphModel, boolean) when you no longer need the layout provider instance; otherwise, some objects may not be garbage collected.

Since:

JViews 5.0

See Also:

IlvLayoutProvider, IlvGraphLayout.performLayout(), IlvRecursiveLayout.IlvRecursiveLayout(IlvLayoutProvider), IlvRecursiveLayout.getLayoutProvider()

Constructor Summary

IlvDefaultLayoutProvider()
Creates a new IlvDefaultLayoutProvider.

Method Summary

protected IlvGraphLayout	copy(IlvGraphLayout layout) Returns a copy of a layout instance.
protected IlvGraphLayout	createGraphLayout(IlvGraphModel graphModel) Returns a layout instance to be used to lay out a graph model for which no layout has been specified using the method setPreferredLayout(IlvGraphModel, IlvGraphLayout).
void	detachLayouts(IlvGraphModel graphModel, boolean traverse) Detaches the layout instances from graphModel and cleans the preferred layout settings.
IlvGraphLayout	getGraphLayout(IlvGraphModel graphModel) Returns the layout instance to be used to lay out graphModel.
int	getInstanceId() Returns a unique integer value for each layout provider instance inside the same Java program.
IlvGraphLayout	getPreferredLayout(IlvGraphModel graphModel) Returns the layout instance that has been specified using the method setPreferredLayout(IlvGraphModel, IlvGraphLayout) for laying out graphModel, or null if none has been specified or a null layout has been specified (that is, no layout should be applied to this graph model).
void	setPreferredLayout(IlvGraphModel graphModel, IlvGraphLayout layout) Sets the layout instances to be used for laying out graphModel.
void	setPreferredLayout(IlvGraphModel graphModel, IlvGraphLayout layout, boolean detachPrevious) Deprecated. Beginning with ILOG JViews 5.5, use the method setPreferredLayout(IlvGraphModel, IlvGraphLayout, boolean, boolean) instead.
void	setPreferredLayout(IlvGraphModel graphModel, IlvGraphLayout layout, boolean detachPrevious, boolean traverse) Sets the layout instances to be used for laying out graphModel.
protected void	storePreferredLayout(IlvGraphModel graphModel, IlvGraphLayout layout) Stores the layout for the graph model.

Methods inherited from class java.lang.Object

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

Constructor Detail

IlvDefaultLayoutProvider

public IlvDefaultLayoutProvider()

Creates a new IlvDefaultLayoutProvider. Use the method setPreferredLayout(IlvGraphModel, IlvGraphLayout) to specify preferred layouts.

Method Detail

getInstanceId

public final int getInstanceId()

Returns a unique integer value for each layout provider instance inside the same Java program. This utility method can be used to obtain names for properties that are unique for each layout provider instance.

setPreferredLayout

public void setPreferredLayout(IlvGraphModel graphModel,
                               IlvGraphLayout layout)

Sets the layout instances to be used for laying out graphModel. The method simply calls setPreferredLayout(IlvGraphModel, IlvGraphLayout, boolean), passing its arguments and the value true for the detachPrevious argument.

Parameters:

graphModel - The graph model (the graph model that encapsulates the topmost grapher, or a subgraph).

layout - The layout instance to be used for laying out graphModel, or null.

See Also:

setPreferredLayout(IlvGraphModel, IlvGraphLayout, boolean, boolean)

setPreferredLayout

public void setPreferredLayout(IlvGraphModel graphModel,
                               IlvGraphLayout layout,
                               boolean detachPrevious)

Deprecated. Beginning with ILOG JViews 5.5, use the method setPreferredLayout(IlvGraphModel, IlvGraphLayout, boolean, boolean) instead.

Sets the layout instances to be used for laying out graphModel. The method simply calls setPreferredLayout(IlvGraphModel, IlvGraphLayout, boolean, boolean), passing its arguments and the value false for the traverse argument.

Parameters:

graphModel - The graph model (the graph model that encapsulates the topmost grapher, or a subgraph).

layout - The layout instance to be used for laying out graphModel, or null.

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

See Also:

setPreferredLayout(IlvGraphModel, IlvGraphLayout, boolean, boolean)

setPreferredLayout

public void setPreferredLayout(IlvGraphModel graphModel,
                               IlvGraphLayout layout,
                               boolean detachPrevious,
                               boolean traverse)

Sets the layout instances to be used for laying out graphModel.

If the argument traverse is false, layout is stored as the preferred layout of graphModel. If the argument traverse is true, layout is stored as the preferred layout of graphModel and, recursively, a clone of layout is stored as preferred layout of all the models encapsulating the subgraphs of graphModel. The clones are obtained by calling the method copy(IlvGraphLayout).

You can call this method with a null value for the argument layout to reset previous settings. By default, there is no preferred layout and the method getPreferredLayout(IlvGraphModel) returns null.

If it is not already attached, the method attaches the layout instance to the graph model using the method IlvGraphLayout.attach(IlvGraphModel). The layout instance is stored in the provider until it is detached using the method IlvGraphLayout.detach(). If a different layout instance was previously specified and the argument detachPrevious is true, the graph model is detached from it using the method IlvGraphLayout.detach().

If no layout instance is specified for a subgraph, then the layout instance specified for the nearest parent graph will be used (see getGraphLayout(IlvGraphModel)).

The same layout instance should not be used for different subgraphs in the same nested graph, and should not be used inside a different default layout provider. Also, the method should not be called for graph models that are adapter created internally by the method IlvGraphLayout.attach(ilog.views.IlvGrapher) on a layout instance which is not layout.

Note that the settings are valid only for this instance of IlvDefaultLayoutProvider. The persistence of the choice of the layouts to be applied to each subgraph in IVL files (using named properties) can be obtained using the methods IlvGrapherAdapter.savePreferredLayoutsToNamedProperties(IlvDefaultLayoutProvider, boolean, boolean, boolean) and IlvGrapherAdapter.loadPreferredLayoutsFromNamedProperties(IlvDefaultLayoutProvider, boolean, boolean).

Parameters:

graphModel - The graph model (the graph model that encapsulates the topmost grapher, or a subgraph).

layout - The layout instance to be used for laying out graphModel, or null.

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

traverse - If true, layout is stored as the preferred layout of graphModel, and clones of layout are recursively stored on the submodels of graphModel. Otherwise, the method does not go recursively into the submodels.

Since:

JViews 5.5

See Also:

setPreferredLayout(IlvGraphModel, IlvGraphLayout)

getPreferredLayout

public IlvGraphLayout getPreferredLayout(IlvGraphModel graphModel)

Returns the layout instance that has been specified using the method setPreferredLayout(IlvGraphModel, IlvGraphLayout) for laying out graphModel, or null if none has been specified or a null layout has been specified (that is, no layout should be applied to this graph model). The layout instance is already attached. If you detach the layout instance, it is automatically removed from the provider.

Parameters:

graphModel - The graph model (the graph model that encapsulates the topmost grapher, or a subgraph).

storePreferredLayout

protected void storePreferredLayout(IlvGraphModel graphModel,
                                    IlvGraphLayout layout)

Stores the layout for the graph model. This method is overridden in some subclasses. You should not use this method.

Since:

JViews 8.0

detachLayouts

public void detachLayouts(IlvGraphModel graphModel,
                          boolean traverse)

Detaches the layout instances from graphModel and cleans the preferred layout settings.

This method allows you to easily detach all the layout instances used for a nested graph. The layout instances are obtained using the method getGraphLayout(IlvGraphModel). If the argument traverse is true, the method is applied recursively on the subgraphs of graphModel.

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

Parameters:

graphModel - The graph model (the graph model that encapsulates the topmost grapher, or a subgraph).

traverse - If true, the method applies to graphModel and recursively to all subgraph models. Otherwise, it applies only to graphModel itself.

See Also:

IlvGraphLayout.detach(), IlvGraphModel.dispose()

getGraphLayout

public IlvGraphLayout getGraphLayout(IlvGraphModel graphModel)

Returns the layout instance to be used to lay out graphModel.

The default implementation first searches for a preferred layout specified using setPreferredLayout(IlvGraphModel, IlvGraphLayout). If none is found, the method returns the layout instance returned by the method createGraphLayout(IlvGraphModel).

Specified by:

getGraphLayout in interface IlvLayoutProvider

Parameters:

graphModel - The graph model (the graph model that encapsulates the topmost grapher, or a subgraph).

Returns:

The layout instance to be used for graphModel, or null if no layout is need for graphModel.

createGraphLayout

protected IlvGraphLayout createGraphLayout(IlvGraphModel graphModel)

Returns a layout instance to be used to lay out a graph model for which no layout has been specified using the method setPreferredLayout(IlvGraphModel, IlvGraphLayout).

The method clones (using the method copy(IlvGraphLayout)) the layout instance of the nearest parent graph model for which a non-null preferred layout has been specified. If no non-null preferred layout has been specified for any of its parents, including the topmost (root) graph model, the method returns null.

The layout instance that is returned does not need to be attached to the specified graph model. The attachment (using the method IlvGraphLayout.attach(IlvGraphModel) is done in the method getGraphLayout(IlvGraphModel).

Parameters:

graphModel - The graph model (the graph model that encapsulates the topmost grapher, or a subgraph).

Returns:

The layout instance to be used for graphModel, or null if no layout is need for graphModel.

See Also:

getGraphLayout(ilog.views.graphlayout.IlvGraphModel), setPreferredLayout(IlvGraphModel, IlvGraphLayout)

copy

protected IlvGraphLayout copy(IlvGraphLayout layout)

Returns a copy of a layout instance. The method is called by createGraphLayout(IlvGraphModel) to obtain a clone of the preferred layout of the closest parent graph. The method calls IlvGraphLayout.copy() to copy the layout instance. The method returns null if the argument layout is null.

Parameters:

layout - The preferred layout of the closest parent graph that has a specified preferred layout, or null.

Returns:

A copy of the layout instance, or null.