For experts: more on layout providers

> > > > >

For information on using the Recursive Layout with a specified layout provider, see Specified provider mode.

The library provides a default implementation of the interface IlvLayoutProvider, named IlvDefaultLayoutProvider. In many cases, it is simpler either to use this class as is, or to subclass it, rather than directly implementing the interface.

The class IlvDefaultLayoutProvider allows you to set the layout instance to be used for each graph (called the preferred layout) with the method:

setPreferredLayout(IlvGraphModel graphModel, IlvGraphLayout layout, boolean 
detachPrevious)

The layout instance specified as the preferred layout is stored in a property of the graph. The current preferred layout is returned by the method:

getPreferredLayout(IlvGraphModel graphModel)

The method returns null if no layout has been specified for this graph.

When the method getGraphLayout is called on the default provider, the previously specified preferred layout is returned, if any. Otherwise, a new layout instance is allocated by a call to the method:

createGraphLayout(IlvGraphModel graphModel)

This newly created layout is recorded as the preferred layout of this graph, which is attached to the layout instance.

When a preferred layout has been specified for a graph, the default implementation of the method createGraphLayout copies the layout instance that is the preferred layout of the nearest parent graph. Therefore, if a preferred layout L is specified for a graph G and no preferred layout is set for its subgraphs, then the graph G and all its subgraphs are laid out using the same layout algorithm L (copies of it are used for the subgraphs).

Note

You must call the method detachLayouts when you no longer need the layout provider instance; otherwise, the garbage collector may fail to remove some objects.

The settings of the preferred layout made using the class IlvDefaultLayoutProvider can be saved in .ivl files. For details, see Saving layout parameters and preferred layouts.

Java code sample

The following Java™ code sample illustrates the use of the class IlvDefaultLayoutProvider.

...
IlvGrapher grapherA = new IlvGrapher();
IlvGrapher grapherB = new IlvGrapher();

// Fill the graphers with nodes and links;
// grapherB is added as a subgraph of grapherA
grapherA.addNode(grapherB, false);

// Create a grapher adapter for the topmost graph
IlvGrapherAdapter adapterA = new IlvGrapherAdapter(grapherA);

// Get a grapher adapter for the subgraph
IlvGraphModel adapterB = adapterA.getGraphModel(grapherB);

// Create the layout provider
IlvDefaultLayoutProvider provider = new IlvDefaultLayoutProvider();

// Specify the preferred layouts for each grapher
// (this automatically attaches the layouts)
provider.setPreferredLayout(adapterA, new IlvTreeLayout());
provider.setPreferredLayout(adapterB, new IlvGridLayout());

// Create a recursive layout in specified provider mode
IlvRecursiveLayout layout = new IlvRecursiveLayout(provider);

// Perform the layout
try {
        IlvRecursiveLayoutReport layoutReport =
              (IlvRecursiveLayoutReport)layout.performLayout();

        int code = layoutReport.getCode();

        System.out.println("Layout completed (" +
          layoutReport.codeToString(code) + ")");
}
catch (IlvGraphLayoutException e) {
        System.err.println(e.getMessage());
}
...
// detach the layouts when the provider is no longer needed
provider.detachLayouts(adapterA, true);
// dispose the topmost adapter when no longer needed
adapterA.dispose();
...

Current section

Recursive layout