mapsglmaps/com.xweather.mapsgl.controls.legend/LegendControl

LegendControl

class LegendControl

The LegendControl acts as a high-level manager for map legends within a Mapbox environment.

It coordinates the lifecycle, visual state, and unit synchronization (Metric/Imperial) of legends. This class handles:

Shared Legends: Uses reference counting to ensure a single legend ID can be used by multiple layers, only removing the UI when the last layer is removed.
Unit Conversion: Supports dynamic toggling between Imperial and Metric units across all hosted legends.
UI Management: Automatically manages a LegendContainerView, including the injection of separators and specialized LegendView instances.

Constructors

LegendControl

constructor()

Types

Companion

object Companion

Coordinator

class Coordinator(provider: () -> LegendControl.Host?)

A lifecycle utility that facilitates the "Try Install" pattern between a Host and a LegendControl.

Host

interface Host

Defines a contract for a UI component (usually an Activity or Fragment) capable of hosting a LegendControl.

Properties

backgroundColor

var backgroundColor: Color

The background color of the legend container.

containerView

lateinit var containerView: LegendContainerView

isHidden

var isHidden: Boolean

Controls the visibility of the legend container. The container should also be hidden if there are no legends to display.

legends

var legends: Map<String, Legend>

The currently active legends, mapped by their unique ID. This list should be observed by the UI to render the correct legends.

mapView

var mapView: MapView?

toggleUnitsOnTap

var toggleUnitsOnTap: Boolean

Indicates whether tapping the legend view toggles between metric and imperial units. This state should be used by the UI to add a click handler.

units

var units: MeasurementUnits

Units applied to the hosted legends. Updating this value propagates the new units to each registered legend.

Functions

add

fun add(legend: Legend)

Adds a legend to the container.

getLegend

fun getLegend(id: String): Legend?

Retrieves the currently active Legend instance for the given identifier.

getView

fun getView(): LegendContainerView

Returns the LegendContainerView associated with this control. This view acts as the visual parent for all individual legend items.

removeLegend

fun removeLegend(id: String, force: Boolean = false)

Removes a legend it from the UI if no longer needed.

toggleUnits

fun toggleUnits()

Toggles the measurement units between METRIC and IMPERIAL if toggleUnitsOnTap is true. This function is intended to be called by the UI (e.g., from a click listener).

update

fun update(legend: Legend)

Updates the data of an existing legend without changing its position in the UI.