Map Labeling

INDEX PREVIOUS NEXT

The class relationship for map labeling is shown in Figure 1.3.

• The IlVMapLabeler Interface
• The IlvMapLabelManager Class
• The IlvMapLabelFactory Interface
• Controlling Renderer Parameters

The entry point for this mechanism is the IlvMapLabeler interface. A class implementing this interface is responsible for managing labels for a given IlvManager. The IlvMapLabelerProperty class is a named property used to attach an IlvMapLabeler to an IlvManager. This map labeler handles all the data sources imported into the manager. The model data is persisted and saved when you save the map.

IlvMapLabeler labeler = IlvMapLabelerProperty.GetMapLabeler(manager);

If a specific labeler is not set for the property, this method creates or returns an instance of IlvMapDefaultLabeler. This default labeler class automatically creates and configures a map layer for labels and listens for changes to the layer structure attached to the view. This allows the labeling to be updated when layer order changes. It also contains an internal IlvMapLabelFactory to create the appropriate labels for graphic objects, according to the LABEL_ATTRIBUTE field of the IlvMapLayer. For more information about IlvMapLabelFactory, see The IlvMapLabelFactory Interface.

0. Define the layer to be labeled:

IlvMapLayer layerToLabel;

0. Create a default IlvMapDefaultLabeler and set it on the manager:

IlvMapLabeler labeler =

  IlvMapLabelerProperty.GetMapLabeler(manager);

0. Since this labeler has to interact with the view, you must indicate in which view it is to display the labels:

labeler.setView(view);

0. Set the label attribute for the map layer to specify which attribute of the graphic objects should be displayed as a label (check the available attributes in the file format you read in):

layerToLabel.getStyle().setLabelAttribute("NAME");

0. Register the map layer to label with the labeler:

labeler.addLayer(layerToLabel);

0. Finally, notify the labeling thread to compute labels for all the labeled layers:

labeler.performLabeling();

The IlvMapDefaultLabeler class holds references to labeled layers (the layers to be labeled) and label layers (the layers that display the labels). This class also holds a reference to an IlvMapLabelManager that acts as a controller for label rendering operations. The IlvMapLabelManager class monitors changes in the view (scrolling, zooming...), creates labels for all the visible graphic objects in the view that require labeling, and lays them out and draws them. This is all done in a separate thread so that user interaction is not blocked. Basically, this class contains the JViews Maps rendering engine.

To create labels for graphic objects, the IlvMapLabelManager class relies on a label factory implementing the IlvMapLabelFactory interface. Any object implementing this interface is responsible for returning the appropriate IlvMapLabelingLabel instances for specified IlvGraphic objects. This is done by implementing the method:

public IlvMapLabelingLabel[] getGisLabel(IlvGraphic comp);

• It extracts an attribute from the specified IlvGraphic object (according to the label attribute in the IlvMapStyle of the IlvMapLayer being labeled), and takes its String representation as the text of the label.
• Then it creates the appropriate instance of the IlvMapLabelingLabel class, according to the kind of graphic object being labeled:
• IlvMapPointLabel for objects with an anchor point.
• IlvMapLineLabel for polyline objects (for example, label along the line).
• IlvMapAreaLabel for closed areas with a label placed within visible parts of the area.

The IlvMapLabelManager uses this default implementation of the factory, but you can provide your own implementation if you want to have fine control over what is labeled, and how. To replace the default label factory with your own label factory:

IlvMapLabelFactory myLabelFactory = new myLabelFactory(); //Your own implementation.
 
//Get the map labeler.
IlvMapLabeler labeler =
   IlvMapLabelerProperty.GetMapLabeler(manager);
 
//Set the factory, if the labeler is an IlvMapDefaultLabeler instance.
if(labeler instanceof IlvMapDefaultLabeler) {
   IlvMapDefaultLabeler dflt = (IlvMapDefaultLabeler)labeler;
   dflt.setLabelFactory(myLabelFactory);
 }

When you implement your own IlvMapLabelFactory, you can specify a set of layout and rendering parameters for each instance of IlvMapLabelingLabel that you create in the constructor.

For more information about these parameters, see the IlvMapPointLabel, IlvMapLineLabel, and IlvMapAreaLabel classes.