Using a graph layout report
Describes what graph layout reports are and how to use them.
Lists the layout classes and corresponding layout report classes.
Explains how to create a layout report.
Explains how to access a layout report.
Lists the fields in a layout report.
Layout report classes
Graph layout reports are objects used to store information about the particular behavior of a layout algorithm. After the layout is completed, this information is available to be read from the layout report.
Each layout class instantiates a particular class of ilog.views.graphlayout.IlvGraphLayoutReport each time the layout is performed. The following table shows the layout classes and their corresponding layout reports.
Layout report classes
Layout Class | Layout Report Class |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
Creating a layout report
All layout classes inherit the performLayout method from the IlvGraphLayout class. This method calls createLayoutReport to obtain a new instance of the layout report. This instance is returned when performLayout returns. The default implementation in the base layout class creates an instance of IlvGraphLayoutReport. Some subclasses override this method to return an appropriate subclass. Other classes, such as IlvRandomLayout, do not need specific information to be stored in the layout report and do not override createLayoutReport. In this case, the base class IlvGraphLayoutReport is used.
When using the layout classes with Rogue Wave® JViews Diagrammer, you do not need to instantiate the layout report yourself. It is done automatically.
Accessing a layout report
In a diagram component (a subclass of
IlvDiagrammer), you can access a layout report in the following way:
IlvGraphLayoutReport layoutReport =
diagrammer.getEngine().getNodeLayoutRenderer().
getGraphLayout().getLayoutReport();
Notice that null is returned if the layout renderer was never executed (that is, layout was never called).
If you do not use a diagram component, you usually call layout via the method performLayout which returns the layout report. The following example shows how to read the information from the layout report in this case:
:
...
try {
IlvGraphLayoutReport layoutReport = layout.performLayout();
if (layoutReport.getCode() ==
IlvGraphLayoutReport.LAYOUT_DONE)
System.out.println("Layout done.");
else
System.out.println("Layout not done, code = " +
layoutReport.getCode());
}
catch (IlvGraphLayoutException e) {
System.err.println(e.getMessage());
}
Information stored in a layout report
The base class
IlvGraphLayoutReport stores the following information:
Code
This field contains information about special, predefined cases that have occurred during the layout. The possible values are:
LAYOUT_DONE appears if the layout was performed successfully.
STOPPED_AND_VALID appears if the layout was performed but was stopped before completion, either because the layout time elapsed or because the method
stopImmediately was called. The positions of nodes and links are valid at the stopping point because the layout algorithm uses an iterative mechanism.
STOPPED_AND_INVALID appears if a (noniterative) layout was performed but was stopped before completion, either because the layout time elapsed or because the method
stopImmediately was called. The positions of nodes and links are not valid at the stopping point. Often, they have not yet been changed at all.
NOT_NEEDED appears if the layout was not performed because no changes occurred in the grapher and parameters since the last time the layout was performed successfully.
EMPTY_GRAPHER appears if the grapher is empty.
To read the code, use the method:
int getCode()
Layout time
This field contains the total duration of the layout algorithm at the end of the layout. To read the time (in milliseconds), use the method:
long getLayoutTime()
Percentage of completion
This field contains an estimation of the percentage of the layout that has been completed. It can be used if the layout algorithm supports the generic percentage completion calculation feature, see
Percentage of completion calculation. It is typically used inside layout event listeners that are described in the following section.
To access the percentage, use the method:
int getPercentageComplete()
Additional information
Additional information for particular layout algorithms is stored by the subclasses of IlvGraphLayoutReport. For details, see the reference documentation of these classes:
Copyright © 2018, Rogue Wave Software, Inc. All Rights Reserved.
