In an application that works directly on an IlvGrapher object, operations such as attaching or detaching a graph layout instance must be performed explicitly.

Nodes are instances of the class IlvGraphic and links are instances of the class IlvLinkImage.

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.

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

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:

For example:

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:

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

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.

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.

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:

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.

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

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