skip to main content
Programmer's documentation > Using graph layout algorithms > Using advanced features > Choosing the layout coordinate space
 
Choosing the layout coordinate space
Describes how to choose the appropriate coordinate space for a layout and how to specify the corresponding mode.
*General considerations about layout and coordinates
*Discusses the way layout algorithms operate and the impact of transformers and nonzoomable objects.
*Transformers for graphers
*Describes what a transformer is and its relevance to layout in a grapher.
*Nonzoomable graphic objects as nodes
*Explains what nonzoomable objects are and their relevance to layout in a grapher.
*Reference transformer for grapher
*Discusses the concept and relevance of the reference transformer for a grapher.
*Specifying a reference transformer
*Explains how a reference transformer is set automatically or explicitly.
*Specifying the mode for layout coordinates
*Describes how to specify the coordinate space by setting a mode value.
General considerations about layout and coordinates
Important To understand this section better, read section Using the graph model first.
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.
Transformers for graphers
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.
Nonzoomable graphic objects as nodes
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.
Reference transformer for grapher
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:
 
void setReferenceView(IlvManagerView view)
To get the current reference view, use the method:
 
IlvManagerView getReferenceView()
If no view has been specified as the reference view, the method returns null.
Specifying a reference transformer
You can specify a reference transformer explicitly using the method:
 
void setReferenceTransformer(IlvTransformer transformer)
The current reference transformer is returned by the method:
 
IlvTransformer getReferenceTransformer()
In most cases, it is not necessary to specify a reference transformer because the last method automatically chooses it according the following rules:
*If a reference transformer is specified, the specified transformer is returned.
*If a reference view has been specified, the transformer of the reference view is returned.
*If the IlvGrapher attached to the IlvGrapherAdapter has at least one manager view, the transformer of the first manager (as returned by the method IlvManager.getViews() ) is returned.
The only cases where you may need to specify a reference transformer or a reference view are:
*The IlvGrapher contains nonzoomable objects (that is, the layout cannot be correctly computed independently of the transformer used for drawing the graph) and more than one manager view is attached to the grapher.
*The IlvGrapher contains nonzoomable objects and you want to perform the layout without attaching a manager view to the grapher. (Therefore, the default rule for choosing the current transformer of the first manager view as the reference transformer cannot be applied.)
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.
Specifying the mode for layout coordinates
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:
 
void setCoordinatesMode(int mode)
The valid values for mode are:
*IlvGraphLayout.MANAGER_COORDINATES
The geometry of the graph is computed using the coordinate space of the manager (that is, the IlvGrapher encapsulated by the adapter) without applying any transformation.
This mode should be used if you visualize the graph at zoom level 1, or you do not visualize it at all, or the grapher contains only fully zoomable objects. In all these cases there is no need to take the transformer into account during the layout.
Note that in this mode the dimensional parameters of the layout algorithms are considered as being specified in manager coordinates. The reference transformer and the reference view are not used.
*IlvGraphLayout.VIEW_COORDINATES
The geometry of the graph is computed in the coordinate space of the manager view. More exactly, all the coordinates are transformed using the current reference transformer.
This mode should be used if you want the dimensional parameters of the layout algorithms to be considered as being specified in manager view coordinates.
*IlvGraphLayout.INVERSE_VIEW_COORDINATES
The geometry of the graph is computed using the coordinate space of the manager view and then applying the inverse transformation using the reference transformer. This mode is equivalent to the "manager coordinates" mode if the geometry of the graphic objects strictly obeys the transformer. (A small difference may exist because of the limited precision of the computations.)
On the contrary, if some graphic objects are either nonzoomable or semizoomable (for example, links with a maximum line width), this mode gives different results than the manager coordinates mode. These results are optimal if the grapher is visualized using the same transformer as the one taken into account during the layout.
Note that in this mode the dimensional parameters of the layout algorithms are considered as being specified in manager coordinates.
The default mode is IlvGraphLayout.INVERSE_VIEW_COORDINATES.
To obtain the current choice, use the following method:
 
long getCoordinatesMode()
The mode for coordinates can also be specified directly on the layout instances. For details, see Coordinates mode.

Copyright © 2018, Rogue Wave Software, Inc. All Rights Reserved.