Describes how to choose the appropriate coordinate space for a layout and how to specify the corresponding mode.

The distinction between zoomable and nonzoomable objects, and the notion of transformer ( IlvTransformer), are outside the level of the layout framework.

Graph layout algorithms have to deal with the geometry of the graph, that is, the position and shape of the nodes and links. They interact with the geometry of the graph using generic methods of the graph model ( IlvGraphModel), such as boundingBox(Object nodeOrLink).

The layout algorithms consider the geometry of the graph exactly as it is provided by the graph model. From the point of view of the layout algorithms, the distinction between zoomable and nonzoomable objects is completely transparent. Therefore, when writing a layout algorithm, you do not need to be concerned with such issues.

However, graph layout algorithms must also deal with the layout of an IlvGrapher.

The nodes of an IlvGrapher object can be any graphic object, that is, any subclass of IlvGraphic. The position and size of the nodes are given by their boundingBox(IlvTransformer t) method and usually depend on the transformer used for their display. Therefore, when an IlvGrapher has to be laid out, the geometry of the grapher must be considered for a specific value of the transformer.

Instead of dealing with zoomable/nonzoomable objects and transformers at the level of the layout algorithms, the Rogue Wave®  JViews graph layout package delegates this task to the IlvGrapherAdapter object.

Generally speaking, the layout of an IlvGrapher depends on the transformer. The most natural transformer value that could be chosen is the “identity” transformer.

An identity transformer has no translation, zoom, or rotation factors. In terms of Rogue Wave®  JViews, this would mean that the geometry of the IlvGrapher would be considered in the manager coordinates, not in the manager view coordinates (transformed coordinates). However, the special case of nonzoomable graphic objects must be taken into account. For this case, the idea of simply using the geometry of the grapher in manager coordinates is not pertinent.

A graphic object is said to be zoomable if its bounding box follows the zoom level. Otherwise, the object is nonzoomable. (To know whether a graphic object is zoomable, use its boolean zoomable() method, or check its documentation.)

If all the nodes and links of an IlvGrapher object are zoomable graphic objects, a layout obtained on the basis of the graph geometry in manager coordinates will look the same for any value of the transformer used for the display. Simply speaking, the drawing of the graph will just be zoomed, or translated.

When at least one nonzoomable graphic object is used as a node in an IlvGrapher, the geometry of the grapher in manager coordinates can no longer be used. When drawn with different transformer values (for instance, at different zoom levels), the same IlvGrapher can look very different.

When a grapher contains nonzoomable graphic objects, it may not be appropriate to deal with the geometry of the IlvGrapher based on the bounding boxes of the graph objects systematically computed for an identity transformer (manager coordinates). To ensure that the drawing of the laid-out graph is always correct, even when nonzoomable graphic objects are present, the transformer used for the display must be considered.

The reference transformer is the transformer that is currently being used for the display of the IlvGrapher. The IlvGrapherAdapter may need to compute the geometry of the graph for this transformer.

How a reference transformer is used

For a simple example of how a reference transformer is used, consider the boundingBox method. This abstract method of the IlvGraphModel class is implemented in the IlvGrapherAdapter. To compute the bounding box, it calls the IlvGrapher method of the graphic object that it receives as an argument. However, it does not handle zoomable objects and nonzoomable objects in the same way.

If the graphic object is zoomable, the boundingBox boundingBox(Object nodeOrLink) method of the IlvGrapherAdapter returns the bounding box in manager coordinates by calling IlvGraphic.boundingBox(null).

If the graphic object is nonzoomable, the boundingBox boundingBox(Object nodeOrLink) method computes the bounding box according to the reference transformer and returns a rectangle obtained by applying the inverse transformation to this rectangle, see the inverse IlvTransformer.inverse(IlvRect rect) method.

The geometry of the IlvGrapher is computed in such a manner that the resulting drawing inside an IlvManagerView using the reference transformer will look fine.

Reference views

Optionally, an IlvManagerView can be specified as a reference view for the IlvGrapherAdapter. If a reference view is specified, its current transformer (at the moment when the layout is started) is automatically used as the reference transformer. Usually, applications use the same manager view that is used for the display of the IlvGrapher as the reference view (but this is not mandatory).

To specify the reference view, use the following method:

To get the current reference view, use the method:

If no view has been specified as the reference view, the method returns null.

You can specify a reference transformer explicitly using the method:

The current reference transformer is returned by the method:

In most cases, it is not necessary to specify a reference transformer because the last method automatically chooses it according the following rules:

The only cases where you may need to specify a reference transformer or a reference view are:

If a grapher containing nonzoomable objects is displayed simultaneously in several views, you can use the setReferenceView method to indicate the view for which you want the drawing of the graph to be optimal.

If you specified a reference transformer but want to reset this setting and go back to the default behavior, call the method setReferenceTransformer with a null argument.

Note that if you override the setReferenceTransformer method, you must call super.setReferenceTransformer to notify the IlvGrapherAdapter that the reference transformer has changed.

Note also that a call to the setReferenceView method overrides the effect of a call to the setReferenceTransformer method. In the same way, a call to the setReferenceTransformer method overrides the effect of a call to the setReferenceView method.

By default, the IlvGrapherAdapter considers the geometry of the nodes and links of an IlvGrapher in a special coordinate space which is appropriate for most of the cases. In some situations, it can be useful to specify a different coordinate space.

To specify the coordinate space, the class IlvGrapherAdapter provides the following method:

The valid values for mode are:

The default mode is IlvGraphLayout.INVERSE_VIEW_COORDINATES.

To obtain the current choice, use the following method:

The mode for coordinates can also be specified directly on the layout instances. For details, see Coordinates mode.