Label descriptors

> > > > >

To define where a label must be placed, you must specify a label descriptor for each label. The algorithm places only those labels that have a label descriptor.

A label descriptor describes the locations that are allowed for the label. For instance, if you place a city name label in a geographic map, you want the label to be positioned close to the graphic objects that represent the city. Positions far away from the city are not reasonable for the label.

Example of label descriptors

To specify these parameters:

In CSS

Label descriptors are automatically created for all labels. You only need to specify the details of the label descriptors by using the pseudo classes labelLayout and labelLayout_ i where i is the child index of the label in IlvSDMCompositeNode or IlvSDMCompositeNode. For instance, the descriptor of a label at an IlvGeneralNode object is specified in the following way:

node:labelLayout {
    ... any bean property of the point label descriptor ...
}

The descriptor of a label which is the 3rd child of an IlvSDMCompositeLink is specified in the following way:

link:labelLayout_3 {
    ... any bean property of the polyline label descriptor ...
}

In Java™

You need to allocate a new label descriptor for each label. There are two ways to specify the label descriptors:

To set the descriptor for one label, call:
```
layout.setLabelDescriptor(label, descriptor);
```
You can retrieve the current label descriptor using the method:
```
layout.getLabelDescriptor(label); 
```
You can instead specify a label descriptor provider. IlvAnnealingLabelDescriptorProvider is an interface that delivers label descriptors for labels on the fly. The provider has the advantage that you don't need to run in advance through all labels to set the label descriptor. Instead, the layout detects the labels and asks the provider to deliver the label descriptor if none was set explicitly. The provider can then allocate the label descriptor on the fly, or can deliver a preallocated descriptor that was stored somewhere else outside layout. Using the label descriptor provider is in particular useful if the number of labels and obstacles change frequently, because you don't need to keep track of the labels that have already a label descriptor, and if you want to have a central place that manages all label descriptors.

The reference manual of the class IlvAnnealingLabelDescriptorProvider contains further information on how to implement this interface. In order to set the provider, call the following method:
```
layout.setLabelDescriptorProvider(provider);
```

Subclasses of label descriptors

There are two predefined subclasses of label descriptors:

In a diagram component with CSS styling, the point label descriptor is used for all labels at nodes, and the polyline label descriptor is used for all labels at links.

If you program the label layout directly in Java code, depending on the parameters passed during the construction, these subclasses allow you to place a label:

Close to a specific point.
Close to a specific rectangular or elliptic obstacle (such as a node).
Along an imaginary polyline.
Close to a polyline obstacle (for example, IlvLine, IlvPolyline).
Close to a link.

You can also implement your own label descriptors by subclassing IlvAnnealingLabelDescriptor. This is explained in the section For experts: implementing your own label descriptors.

Current section

Annealing label layout