Graph layout: using the API

The base class

The IlvGraphLayout class is the base class for all layout algorithms. This class is an abstract class and cannot be used directly. You must use one of its subclasses: IlvHierarchicalLayout, IlvTreeLayout, IlvUniformLengthEdgesLayout, IlvTopologicalMeshLayout, IlvLinkLayout, IlvRandomLayout, IlvBusLayout, IlvCircularLayout, IlvGridLayout. You can also create your own subclasses to implement other layout algorithms. See Defining your own type of layout.

Although only subclasses of IlvGraphLayout are directly used to obtain the layouts, you need to learn about this class because it contains methods that are inherited (or overridden) by the subclasses. You must understand it to create your own subclasses.

UML diagram
showing IlvGraphLayout and its subclasses, as well as IlvGraphLayoutReport
and its subclasses

The Class IlvGraphLayout and its subclasses and relationships to layout reports

Instantiating a subclass of the base class

The class IlvGraphLayout is an abstract class. It has no constructors. You instantiate a subclass as shown in the following example:

IlvLinkLayout layout = new IlvLinkLayout();

Attaching or detaching a grapher

You must attach the grapher before performing the layout. The following method, defined on the class IlvGraphLayout, allows you to specify the grapher you want to lay out:

void attach(IlvGrapher grapher)

For example:

...
IlvGrapher grapher = new IlvGrapher();
/* Add nodes and links to the grapher here */
layout.attach(grapher);

The attach method does nothing if the specified grapher is already attached. If a different grapher is attached, this method first detaches this old grapher, then attaches the new one. You can obtain the attached grapher using the method getGrapher. If the grapher is attached in this way, a default graph model is created internally. For details on the graph model, see Using the graph model. The attached graph model can be obtained by:

IlvGraphModel graphModel = layout.getGraphModel();

Warning

You are not allowed to attach a default model created internally to any other layout instance, nor to use it in any way once it has been detached from the layout instance. For details, see Using the class IlvGrapherAdapter.

After layout, when you no longer need the layout instance, you should call the method

void detach()

If the detach method is not called, some objects may not be garbage-collected. This method also performs clean-up operations on the grapher, such as removing properties that may have been added to the grapher objects by the layout algorithm. It also removes layout parameters of nodes and links.

Note

A layout instance should stay attached as long as its layout parameters are relevant for the grapher. Only when the layout parameters, and therefore the entire layout instance, become irrelevant for this grapher should it be detached.

Performing a layout

The performLayout method starts the layout algorithm using the currently attached grapher and the current settings for the layout parameters. The method returns a report object that contains information about the behavior of the layout algorithm.

IlvGraphLayoutReport performLayout()

IlvGraphLayoutReport performLayout(boolean force, boolean redraw)

The first version of the method simply calls the second one with a false value for the first argument and a true value for the second argument. If the argument force is false , the layout algorithm first verifies whether it is necessary to perform the layout. It checks internal flags to see whether the grapher or any of the parameters have been changed since the last time the layout was successfully performed. A “change” can be any of the following ones:

Nodes or links have been added or removed.
Nodes or links have been moved or reshaped.
The value of a layout parameter has been modified.
The transformer of a manager view ( IlvManagerView) of the grapher has changed.

Users often do not want the layout to be computed again if no changes occurred. If there were no changes, the method performLayout returns without performing the layout. Note that if the argument force is passed as true , the verification is no longer performed.

The argument redraw determines whether a redraw of the graph is requested. For details, see Redrawing the grapher after layout.

The protected abstract method layout(boolean redraw) is then called. This means that the control is passed to the subclasses that implement this method. The implementation computes the layout and moves the nodes to new positions or reshapes the links, or both moves the nodes and reshapes the links.

The performLayout method returns an instance of IlvGraphLayoutReport (or of a subclass) that contains information about the behavior of the layout algorithm. It tells you whether the algorithm performed normally, or whether a particular, predefined case occurred. (For a more detailed description of the layout report, see Using a graph layout report.)

Note that the layout report that is returned can be an instance of a subclass of IlvGraphLayoutReport depending on the particular subclass of IlvGraphLayout you are using. For example, it will be an instance of IlvTopologicalMeshLayoutReport if you are using the class IlvTopologicalMeshLayout. Subclasses of IlvGraphLayoutReport are used to store layout algorithm-dependent information.

You must call the method performLayout inside a try block because it can throw an exception. The exception can be of the type IlvGraphLayoutException or one of its subclasses, IlvInappropriateGraphException and IlvInappropriateLinkException. The first indicates internal problems in the layout algorithm or an unexpected situation. The second exception indicates that a particular grapher cannot be laid out with the layout algorithm. For example, the Topological Mesh Layout cannot be used on a tree). The third exception indicates that a particular type of link (or link connector) cannot be used for this layout. The recommended type of link is IlvPolylineLinkImage or IlvSplineLinkImage (or subclasses). For layouts that do not reshape the links by adding intermediate points, the class IlvLinkImage can also be used. See Layout exceptions for details and solutions.

Further information

You can find more information about the class IlvGraphLayout in the following sections:

Base class parameters and features contains the methods that are related to the customization of the layout algorithms.
Using event listeners tells you about the layout event listener mechanism.
Defining your own type of layout tells you how to implement new subclasses.

For details on IlvGraphLayout and other graph layout classes, see the Java™ API Reference Documentation.