MapLayerPriorityBuilder class abstract

MapLayerPriorityBuilder is an interface used to define the rendering priority of a layer and its categories, relative to other layers or layer-category pairs.

Map layers are rendered in an order according to specified priorities. Rendering order of elements in a single map layer can be controlled with categories. Layer names are unique, and category names have to be unique within a layer. The layer's default, main category is unnamed.

The concept of 'category' is tightly linked to styling. The idea behind category is that one should be able to style separately elements in a map layer. Take, for instance, roads. If one wants to style separately the bridges it will create a category 'bridges' and style it accordingly in the style file. If the user does not intend to or cannot style elements of the layer diffenrently then it should opt for a layer with only the default category (e.g. raster layer).

One way to define layers' priorities is by using a layer priority list in the scene configuration.

For example, a priority list in a scene configuration could define:

• background
• water
• roads:outline
• roads
• labels

This means layer "background" is rendered first. Next up is layer "water". Then category "outline" of layer "roads", followed by the main category of layer "roads". Layer "labels" is then rendered last.

Now let's consider a newly created layer 'zone' and its categories:

• zone
• zone:background
• zone:lines-outline
• zone:lines

The user wants to alter the rendering order so that it looks like:

• background
• water
• zone:background
• zone
• road:outline
• road
• zone:lines-outline
• zone:lines
• labels

This could be achieved with the help of the MapLayerPriorityBuilder and a sequence of calls to its renderedBeforeLayer() and renderedAfterLayer() member functions.

Note that the order of calls matters and one can use a previously defined layer or category as a reference:

  final zoneLayerPriority = MapLayerPriorityBuilder()
       .renderedAfterLayer("water")          // places "zone" after "water"
                                             // in the rendering order
       .withCategory("background")
       .renderedAfterLayer("water")          // places "zone:background" after "water"
                                             // in the rendering order and thus shifts
                                             // "zone" to be rendered later
       .withCategory("lines-outline")
       .renderedAfterLayer("road")           // places "zone:lines-outline" after "road"
                                             // in the rendering order
       .withCategory("lines")
       .renderedAfterLayer("zone", "lines-outline") // places "zone:lines" after
                                                    // "zone:lines-outline" in the rendering order
       .build();

  zoneLayer.setPriority(zoneLayerPriority);  // applies the priority to the zone layer
                                             // and its categories in one single operation.

In case an empty MapLayerPriority without any ordering commands is built, it is assumed that the target layer is going to be rendered last.

Due to a current limitation for point map layers, the mentioned APIs to control the rendering order are not implemented. All labels will be rendered within the "labels" layer, defined in the scene configuration file. By default, all labels rendered by a point map layer are rendered last and no overlapping is allowed. The following categories can be used to have a different behaviour:

• 'custom-labels' A label should be rendered first, is allowed to overlap with other labels of the same category and block map labels.
• 'custom-labels-no-self-overlap' A label should be rendered after 'custom-labels', is not allowed to overlap with other labels of the same categoty and block map labels.
• 'custom-labels-overlap-all' A label should be rendered last, is allowed to overlap all predefined categories, also map labels. These categories are configured accordingly in the basic map scene configurations. Category assignment to features can be done in the style based on data attributes. The category assignment can be done for all types of data: points, lines, polygons.