Class MapOverlayElement

Namespace

MapLibreNative.Maui.Handlers.Overlays

Base class for declarative "draw over the map" overlay elements (Circle, Polyline, Polygon, Pin).

public abstract class MapOverlayElement : StyleView

Inheritance

object

StyleView

MapOverlayElement

Derived

Circle

Pin

Polygon

Polyline

Inherited Members

StyleView.IsAdded

StyleView.OnParentChanged()

StyleView.FindParentMapLibreMap(Element)

Remarks

The element model mirrors Microsoft.Maui.Controls.Maps (Pin/Polyline/Polygon/Circle), but each element is wired as a declarative child of MapLibreMap — the same StyleView pattern used by the low-level sources and layers. On the map's StyleLoaded event the element materialises itself as a GeoJSON source plus one or more style layers, so it renders inside the MapLibre surface and therefore composites correctly on every platform. Changing a visual or geometry property after the element has been added rebuilds it in place.

Fields

StrokeColorProperty

public static readonly BindableProperty StrokeColorProperty

Field Value

BindableProperty

StrokeWidthProperty

public static readonly BindableProperty StrokeWidthProperty

Field Value

BindableProperty

Properties

ElementId

Stable per-element id used to derive source and layer ids.

protected string ElementId { get; }

Property Value

string

Map

The parent map, cached once the element is materialised.

protected MapLibreMap? Map { get; }

Property Value

MapLibreMap

SourceId

The GeoJSON source id backing this element.

protected string SourceId { get; }

Property Value

string

StrokeColor

public Color? StrokeColor { get; set; }

Property Value

Color?

StrokeWidth

public double StrokeWidth { get; set; }

Property Value

double

Methods

AddLayerToParentMap()

protected override sealed void AddLayerToParentMap()

BuildOverlay(MapLibreMap)

Adds this element's source and layer(s) to map.

protected abstract void BuildOverlay(MapLibreMap map)

Parameters

map MapLibreMap

BuildSourceFeatures()

Returns the element's source features when the geometry can be updated in place, or null to fall back to a full rebuild. Overridden by geometry-based elements (Circle/Polyline/Polygon) so that geometry changes update the existing source via SetGeoJsonSource instead of removing and re-adding the source and its layers.

protected virtual FeatureCollection? BuildSourceFeatures()

Returns

FeatureCollection?

OnGeometryChanged(BindableObject, object, object)

Property-changed handler for a geometry property (updates the source in place).

protected static void OnGeometryChanged(BindableObject bindable, object oldValue, object newValue)

Parameters

bindable BindableObject

oldValue object

newValue object

OnVisualChanged(BindableObject, object, object)

Property-changed handler for a style property that rebuilds the element's layers.

protected static void OnVisualChanged(BindableObject bindable, object oldValue, object newValue)

Parameters

bindable BindableObject

oldValue object

newValue object

Refresh()

Rebuilds the element in place. Called when a bindable property changes after add.

protected void Refresh()

RemoveLayerFromParentMap()

Removes this element's contribution (sources/layers) from the map. Called when the element is removed from the map's visual tree. The default implementation does nothing.

protected override sealed void RemoveLayerFromParentMap()

RemoveOverlay(MapLibreMap)

Removes this element's layer(s) and source from map.

protected abstract void RemoveOverlay(MapLibreMap map)

Parameters

map MapLibreMap

ToFeatureCollection(IGeometryObject, IDictionary<string, object>?)

Builds a single-feature FeatureCollection for the given geometry.

protected FeatureCollection ToFeatureCollection(IGeometryObject geometry, IDictionary<string, object>? properties = null)

Parameters

geometry IGeometryObject

properties IDictionary<string, object>?

Returns

FeatureCollection

ToMlnColor(Color?, Color)

Converts a MAUI Color to a MapLibre rgba(r,g,b,a) style string.

protected static string ToMlnColor(Color? color, Color fallback)

Parameters

color Color?

fallback Color

Returns

string

ToPositions(IEnumerable<Location>)

Converts a list of Location to GeoJSON positions.

protected static List<IPosition> ToPositions(IEnumerable<Location> locations)

Parameters

locations IEnumerable<Location>

Returns

List<IPosition>

UpdateGeometryInPlace()

Updates the source data in place (no layer churn — which can destabilise the renderer) when the element supports it; otherwise falls back to a full rebuild.

protected void UpdateGeometryInPlace()