Labels and obstacles in Java

> > > > >

The diagram component works with a predefined, complex labeling model that recognizes labels at instances of IlvGeneralNode, IlvSDMCompositeNode, IlvGeneralLink and IlvSDMCompositeLink. If you use other classes or if you want to place labels at other objects, you cannot use the diagram component and you have to code the labeling model.

The IlvLabelingModel class defines a suitable, generic API to position labels automatically through a Rogue Wave JViews Diagrammer label layout algorithm. Its purpose is similar to IlvGraphModel for the graph layout framework.

The class IlvLabelingModel is an abstract base class that allows you to implement an adapter to your own data structures for the labeling algorithm (see Defining your own labeling model). To get the labeling model of an attached layout, use the method:

layout.getLabelingModel();

If labels and obstacles are contained in an IlvManager instance, you do not need to implement an adapter. You can use the default labeling model (the class IlvDefaultLabelingModel).

The default labeling model is suitable when the labels are upright rectangular objects and the overlap calculation considers their bounding boxes.

It is also suitable for rectangular labels that have a rotation that depends on the position of a label. For example, the label on a polyline link may be rotated to align the label with the gradient of the line segment of a link. The overlap calculation considers the rotated rectangle of the label in this case.

Graph
showing labels on polyline links rotated to align with the gradient
of the line segment of the link

Rotation of rectangular labels (rotation dependent on the position of the labels)

The default labeling model may not be suitable when the labels have a nonrectangular shape that leaves large parts of the bounding box of the label empty. The overlap detection will wrongly assume that the empty space inside the bounding box causes overlaps

Note

The default labeling model is not suitable for IlvGeneralNode , IlvGeneralLink , IlvSDMCompositeNode , IlvSDMCompositeLink , because these classes implement labels that are not directly contained in a manager. Therefore the diagram component uses a specialized labeling model.

The default labeling model considers subclasses of IlvLabel, IlvZoomableLabel and IlvText as labels and all other objects as obstacles. This is the most common case. However, you can redefine this meaning:

If you want a graphic to be handled as a label even though it is not a subclass of IlvLabel or IlvZoomableLabel , call:
```
defaultLabelingModel.setLabel(graphic, true); 
```
If you do not want to handle an instance of IlvLabel , IlvZoomableLabel or IlvText as a label but as an immovable obstacle, call:
```
defaultLabelingModel.setObstacle(graphic, true); 
```
If you want a graphic to be ignored by the labeling model, call:
```
defaultLabelingModel.setLabel(graphic, false); 
defaultLabelingModel.setObstacle(graphic, false); 
```
This is useful particularly if you want to create graphics that act as background images and labels should be placed on top of the background images. If the background images were obstacles, the label layout algorithm would try to avoid the area covered by the background images.

The overlap calculation of the default labeling model takes the bounding box of the obstacles into account. This is a good approximation for the most objects. For subclasses of IlvLine, IlvPolyline, and IlvLinkImage, it takes the precise polyline shape into account. However, the default labeling model does not work well with spline obstacles.

Current section

Specifying labels and obstacles