Using advanced features

All the advanced features are available only for programming in Java™, they cannot specified by CSS. The label layout renderer uses these advanced features internally, thus if you are using a diagram component with CSS styling, you do not need to learn about these advanced features. However, if you program label layout in Java, it gives you a powerful way to adapt or extend the label layout.

Filtering manager layers

Graphic objects within an IlvManagerLayer instance can be managed by layers. Rogue Wave® JViews Diagrammer allows you to specify that only the labels and obstacles belonging to certain layers must be taken into account when performing the layout. Use the following methods of the IlvDefaultLabelingModel class:

void addLayer(IlvManagerLayer layer)

boolean removeLayer(IlvManagerLayer layer)

boolean removeAllLayers()

To get an enumeration of the manager layers to be taken into account during the layout, use the method:

Enumeration getLayers()

To determine whether a manager layer belongs to the layers to be taken into account during layout, use the method:

boolean isLayerAdded(IlvManagerLayer layer)

If no layers have been specified or all the specified layers have been removed, all layers in the manager a re used. In this case, the getLayers method returns null and isLayerAdded returns false for any layer.

Transformers for label layout

The most natural transformer value that could be chosen is the “identity” transformer.

An identity transformer has no translation, zoom, or rotation factors. This means that the geometry of the IlvManager instance is 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.

Label layout algorithms have to deal with the geometry of labels and obstacles. In a manager, labels and obstacles can be any graphic objects, that is, any subclass of IlvGraphic. Their position and size are given by their boundingBox(IlvTransformer t) method and usually depend on the transformer used for their display. Therefore, when you need to perform layout on a IlvManagerLayer object, you need to consider the geometry of the manager for a specified value of the transformer.

Nonzoomable graphic objects as labels and obstacles

A graphic object is said to be zoomable if its bounding box follows the zoom level. Otherwise, the object is nonzoomable. For instance, IlvLabel objects are nonzoomable while IlvZoomableLabel objects are zoomable. To determine whether a graphic object is zoomable, use its boolean zoomable() method or check its documentation.

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

When at least one nonzoomable graphic object is used as a label or obstacle, the geometry in manager coordinates can no longer be used. When drawn with different transformer values (for instance, at different zoom levels), the same IlvManager instance may look very different. In this case, you cannot use multiple manager views because only one of them can look correct. All other views will look wrong.

Reference transformer for labeling

The reference transformer is the transformer that is currently being used for the display of the IlvManager object. The IlvDefaultLabelingModel might have to compute the geometry of the manager for this transformer.

How a reference transformer is used

The mechanism by which the reference view and reference transformer are used is similar to that of the IlvGrapherAdapter class in graph layout. For details, see Reference transformer for grapher and Reference views.

NOTE 	The reference transformer is used only if the coordinates mode is IlvLabelLayout.VIEW_COORDINATES or IlvLabelLayout.INVERSE_VIEW_COORDINATES. If you change the reference transformer, the layout is no longer up-to-date. A subsequent layout is necessary. Hence, changing the zoom level of the reference view also renders the layout out-of-date.

Reference views

To specify the reference view, use the method:

void setReferenceView(IlvManagerView view)

If no reference view is explicitly specified, the first manager view is used.

The default labeling model needs to know the transformer of the reference view or an explicitly specified reference transformer.

Specifying a reference transformer

To specify the reference transformer explicitly use the method:

void setReferenceTransformer(IlvTransformer transformer)

Specifying the mode for labeling coordinates

The default labeling model provides several coordinates mode values. The coordinates mode can be specified on the default labeling model and on the layout instance. The coordinates mode of the layout instance is used during layout, while the coordinates mode specified for the default labeling model is used on operations of the labeling model when layout is not currently performed.

To specify the coordinates mode, use the following method, available in the classes IlvDefaultLabelingModel and IlvLabelLayout:

void setCoordinatesMode(int mode)

Valid options of the coordinates mode are:

IlvLabelLayout.MANAGER_COORDINATES - The geometry of obstacles and labels is computed using the coordinate space of the manager without applying any transformation. This mode is suitable if the manager does not contain any nonzoomable labels.

IlvLabelLayout.VIEW_COORDINATES - The geometry of obstacles and labels is computed in the coordinate space of the reference manager view. This mode is suitable if the manager contains nonzoomable objects. The layout will be correct with respect to the reference view but not correct with respect to any other view. Dimensional layout parameters (such as the label offset) are specified in the coordinate space of the reference view.

IlvLabelLayout.INVERSE_VIEW_COORDINATES - This is the default. The geometry of the graph is computed using the coordinate space of the reference manager view and then applying the inverse transformation. This simulates the manager coordinate space. This mode is also suitable if the manager contains nonzoomable objects. The layout will be correct only with respect to the reference view. Dimensional layout parameters (such as the label offset) are specified in the coordinate space of the manager.

To make sure that manager coordinates are used during layout, call:

layout.setCoordinatesMode(IlvLabelLayout.MANAGER_COORDINATES);

This does not change the coordinates mode of the labeling model until layout is started. Most of the time, however, it is recommended that you use the same coordinates mode for the default labeling model and the layout instance, so you call it twice:

defaultLabelingModel.setCoordinatesMode(IlvLabelLayout.MANAGER_COORDINATES);

layout.setCoordinatesMode(IlvLabelLayout.MANAGER_COORDINATES);

Using named properties to save layout parameters

Graph Layout offers the facility to convert graph layout parameters into named properties of IlvGrapher. The same facility is available to convert label layout parameters into named properties of the IlvManager. Named properties can be stored in .ivl files.

The following method indicates whether a label layout class supports this mechanism:

supportsSaveParametersToNamedProperties

It returns true if the layout class can transfer the parameter settings to named properties.

Saving layout parameters to .ivl files

The following example shows how to save an IlvManager instance, including all label layout parameter settings, to an .ivl file.

IlvDefaultLabelingModel labelingModel =

(IlvDefaultLabelingModel)labelLayout.getLabelingModel();

// transfer the layout parameters to named properties

if (labelLayout.supportsSaveParametersToNamedProperties())

labelingModel.saveParametersToNamedProperties(labelLayout, false);

// save the attached manager with the named layout properties to file

labelingModel.getManager().write("abcd.ivl");

// remove the named layout properties because they are no longer needed

labelingModel.removeParametersFromNamedProperties();

The mechanism is the same as in the graph layout module. See Saving layout parameters to .ivl files.

Loading layout parameters from .ivl files

The following example shows how to load and recover the parameters of the label layout when the layout settings are stored in an .ivl file:

// Read the IVL file. This reads all named properties as well.

manager.read("abcd.ivl");

IlvDefaultLabelingModel labelingModel =

(IlvDefaultLabelingModel)labelLayout.getLabelingModel();

// Transfer the parameter settings from the named properties to the layout.

// At this time point, the manager must be attached to the label layout

labelingModel.loadParametersFromNamedProperties(labelLayout);

// just to be sure that no named layout properties remain in the memory

labelingModel.removeParametersFromNamedProperties();

The mechanism is the same as in the graph layout Module. See Loading layout parameters from .ivl files.