Basic Operations with IlvGraphLayout

When subclassing IlvGraphLayout, you will normally use the basic methods described in this section.

Instantiating a Subclass of IlvGraphLayout

The class IlvGraphLayout is an abstract class. You will instantiate a subclass as shown in the following example:

IlvOrthogonalLinkLayout* layout = new IlvOrthogonalLinkLayout();

If you want to use the layout report that is returned by the layout algorithm, you need to declare a handle for the appropriate layout report class, as in this example:

IlvGraphLayoutReport* layoutReport;

For more information on the layout report, see Using a Layout Report Using a Layout Report .

Attaching a Grapher

The IlvGraphLayout::attach method of the IlvGraphLayout class allows you to specify the grapher you want to lay out:

void attach(IlvGrapher* grapher)

For example:

IlvGrapher* grapher = new IlvGrapher(display);

// Add nodes and links to the grapher here

layout->attach(grapher);

You must attach the grapher before performing the layout. The method IlvGraphLayout::attach first detaches the grapher that is already attached, if any. You can obtain the attached grapher using the method IlvGraphLayout::getGrapher.

Performing a Layout

The IlvGraphLayout::performLayout method starts the layout algorithm using the currently attached grapher and the current settings for the layout parameters (see Layout Parameters in IlvGraphLayout ).

IlvGraphLayoutReport* performLayout()

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:

  • Nodes or links were added or removed.

  • Nodes or links were moved or reshaped.

  • The value of a layout parameter was modified.

  • The size of a manager view into which the layout must fit changed. (The layout region mechanism is explained in Layout Region Layout Region .)

Users often do not want the layout to be computed again if no changes occurred. If there were no changes, the method IlvGraphLayout::performLayout returns without performing the layout.

The protected abstract method layout is then called. This means that the control is passed to the subclasses that are implementing this method. The implementation computes the layout and moves the nodes to new positions.

The IlvGraphLayout::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 Layout Report Using a 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. Subclasses of IlvGraphLayoutReport are used to store layout algorithm-dependent information.

Detaching a Grapher

You call the detach method when you no longer need the layout instance. If the IlvGraphLayout::detach method is not called, some objects may not be deleted. This method also performs cleaning operations on the grapher (properties are removed that may have been added by the layout algorithm on the grapher’s objects) and reinitializes parameters as mentioned in Attaching a Grapher Attaching a Grapher .

void detach()