Maps

Embedded native map with MapContainer (a Component) over the Map interface. Supports Google and OSM as engines.

⚠️ Four pitfalls that prevent bugs

Set the key (static) before creating the map: MapContainer.googleMapsKey = "...";.
map may be null — access mc.map only after onMapLoad (and handle null: Web/TeaVM does not support the native map).
All map operations on the render (paint) thread — come back with onUI(...) if it comes from the background.
The old phone.GoogleMaps (external viewer) was removed.

Create and center

MapContainer.googleMapsKey = "SUA_CHAVE";

MapContainer mc = new MapContainer(Map.MapEngine.GOOGLE, 0, () -> {   // onMapLoad
   if (mc.map == null) return;                          // Web/TeaVM: no native map
   mc.map.centerOnLocation(new LatLon(-23.55, -46.63), 14);
   mc.map.setMapType(Map.LayerType.NORMAL);
});
tela.add(LAY_FILL, mc);

MapEngine: GOOGLE · OSM. LayerType: NORMAL · TERRAIN · HYBRID · SATELLITE.

Pins (fluent API)

mc.map.add(new MapPin()
   .position(-23.55, -46.63)
   .title("São Paulo")
   .snippet("Centro")
   .draggable(false)
   .onClick(p -> { Hint.show(p.title, 2000); return true; }));   // true = suppresses info window

Shapes — `MapShape.Line/Polygon/Circle`

// 500 m circle (colors in ARGB 0xAARRGGBB)
MapShape.Circle c = new MapShape.Circle(2, 0xFF2196F3, 0x402196F3);
c.setPolygon(new LatLon(-23.55, -46.63), 500.0);   // center + radius in meters
mc.map.add(c);

Line(thick, color) and Polygon(borderWidth, borderColor, fillColor) follow the same pattern.

Routes and utilities

double metros = MapUtils.distanceInMeters(new LatLon(-23.55,-46.63), new LatLon(-22.90,-43.20));
Image thumb = MapUtils.getMapImage(-23.55, -46.63, false, 13, 600, 400);   // static image (null on error/no key)

Real directions (HTTP + Jackson) come from DirectionsFetcher (callback onRouteReady(List<LatLon>)), combined with MapRoute(lineShape, pins) — marshal the result with onUI(...). Detailed in Chapter 25.

Best practices

Key before instantiating; access mc.map only in onMapLoad.
Handle mc.map == null (Web) and getMapImage(...) == null.
Map operations on the render thread; network results via onUI(...).

Common mistakes

Accessing mc.map in the constructor (still null).
Forgetting MapContainer.googleMapsKey.
Using phone.GoogleMaps (removed).