General information

What is multiple layout?

The Multiple Layout class, class IlvMultipleLayout from the package ilog.views.graphlayout.multiple, is useful mainly when applying layout in Java™ code. The class is also internally used by the graph layout renderer of a diagram component, but in the diagram component, the rendering mechanism is transparent so that you seldom need to deal with the class IlvMultipleLayout .

Important

The Multiple Layout can be used only in Java code. No CSS syntax is available for this layout.

The Multiple Layout class is not a layout algorithm but rather a facility to compose multiple layout algorithms and treat them as one algorithm object.

This is necessary in particular when dealing with the recursive layout of nested submanagers, because performing the layouts recursively one after the other has a different effect than combining the layouts into one algorithm object and applying this object all at once.

See Recursive layout and Layout of nested graphs in code. Multiple Layout should also be used to combine a normal layout with a Link Layout that routes intergraph links. This is shown in the following sample.

Java code sample

You can, for instance, combine a Tree Layout, a Link Layout, and an Annealing Label Layout into one object of type IlvGraphLayout in the following way:

 ...
import ilog.views.*;
import ilog.views.graphlayout.*;
import ilog.views.graphlayout.multiple.*;
import ilog.views.graphlayout.tree.*;
import ilog.views.graphlayout.link.*;
import ilog.views.graphlayout.labellayout.annealing.*;

IlvTreeLayout treeLayout = new IlvTreeLayout();
IlvLinkLayout linkLayout = new IlvLinkLayout();
IlvAnnealingLabelLayout labelLayout = new IlvAnnealingLabelLayout();
IlvMultipleLayout multipleLayout = 
        new IlvMultipleLayout(treeLayout, linkLayout, labelLayout);

IlvGrapher grapher = ...
layout.attach(grapher);

... /* Fill in code to set the layout parameters of treeLayout,
     * linkLayout and labelLayout.
     */
linkLayout.setInterGraphLinksMode(true);
...

By constructing a Multiple Layout instance in this way, the Tree Layout, Link Layout, and Label Layout become sublayouts of the Multiple Layout instance. Attaching the Multiple Layout will automatically attach its sublayouts.

The Multiple Layout has two slots for graph layouts and one slot for the label layout. Not all slots need to be used. You can pass null as the sublayout for unused slots. If you need more slots, you can compose a Multiple Layout that contains another Multiple Layout as a sublayout.

To perform the composed layout you use one of:

Simple layout

You can perform the composed layout on a flat grapher (one which contains no submanagers) in the following way:

try {
        IlvMultipleLayoutReport layoutReport =
              (IlvMultipleLayoutReport)multipleLayout.performLayout();

        int code = layoutReport.getCode();

        System.out.println("Layout completed (" +
          layoutReport.codeToString(code) + ")");
}
catch (IlvGraphLayoutException e) {
        System.err.println(e.getMessage());
}

The statement with multipleLayout.performLayout() in this case has the same effect as the following sequence of statements:

treeLayout.performLayout();
linkLayout.performLayout();

labelLayout.performLayout();

Recursive layout

If you perform the Multiple Layout on a grapher that contains submanagers, there is a difference in the order of the layout (see Order of layouts in recursive layouts. You apply a recursive layout on the grapher and its submanagers in the following way:

IlvRecursiveLayout recursiveLayout = new IlvRecursiveLayout(multipleLayout);
try {
        IlvGraphLayoutReport layoutReport = recursiveLayout.performLayout();
        ...
}
catch (IlvGraphLayoutException e) {
        System.err.println(e.getMessage());
}

or alternatively, in the following way (both ways are equivalent):

try {
        int layoutCode =
                (IlvMultipleLayoutReport)multipleLayout.performLayout(
                                                        true, true, true);
        ...
}
catch (IlvGraphLayoutException e) {
        System.err.println(e.getMessage());
}

Assume the attached grapher A contains a subgrapher B .

The combined Multiple Layout applies its sublayouts in reverse order, as follows:

Tree Layout on B
Link Layout on B
Label Layout on B
Tree Layout on A
Link Layout on A
Label Layout on A

This means that all layouts of subgrapher B have finished before the layout of grapher A starts. It is the correct order for a recursive layout.

If you do not combine the three component layouts into a Multiple Layout, you can only apply them sequentially:

treeLayout.performLayout(true, true, true);
linkLayout.performLayout(true, true, true);
labelLayout.performLayout(true, true, true);

The effect of these statements is slightly different than the effect of the Multiple Layout. The layouts are now applied in the following order:

Tree Layout on B
Tree Layout on A
Link Layout on B
Link Layout on A
Label Layout on B
Label Layout on A

This order is not usually suitable for the layout of nested graphers because the Tree Layout of grapher A is started too early. The Label Layout on grapher B in Step 5 may change the position of grapher B within grapher A , invalidating the result of the Tree Layout in Step 2. Hence, it is recommended that you combine multiple layout algorithms into one Multiple Layout object and apply this object as a whole to a nested grapher.