# मानचित्र

> MapContainer, पिन, आकृतियाँ, रूट और उपयोगिताएँ — key, null और thread की गड़बड़ियों के साथ।

Source: https://crossfly.dev/hi/docs/data-and-services/maps — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# मानचित्र

`Map` इंटरफ़ेस के ऊपर **`MapContainer`** (एक `Component`) के साथ एम्बेडेड नेटिव मानचित्र। इंजन के रूप में Google और
OSM का समर्थन करता है।

## ⚠️ चार गड़बड़ियाँ जो बग से बचाती हैं
1. मानचित्र बनाने से पहले **key कॉन्फ़िगर करें** (स्टैटिक): `MapContainer.googleMapsKey = "...";`.
2. **`map` `null` हो सकता है** — `mc.map` को **केवल** `onMapLoad` के **बाद** ही एक्सेस करें (और `null` को संभालें: Web/TeaVM
   नेटिव मानचित्र **समर्थित नहीं करता**)।
3. **मानचित्र के सभी ऑपरेशन render (paint) thread पर** — यदि बैकग्राउंड से आया हो तो `onUI(...)` के साथ लौटें।
4. पुराना `phone.GoogleMaps` (बाहरी व्यूअर) **हटा दिया गया है**।

## बनाना और केंद्रित करना
```java
MapContainer.googleMapsKey = "SUA_CHAVE";

MapContainer mc = new MapContainer(Map.MapEngine.GOOGLE, 0, () -> {   // onMapLoad
   if (mc.map == null) return;                          // Web/TeaVM: कोई नेटिव मैप नहीं
   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`.

## पिन (फ़्लुएंट API)
```java
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 = info window को दबाता है
```

## आकृतियाँ — `MapShape.Line/Polygon/Circle`
```java
// 500 m का वृत्त (रंग ARGB 0xAARRGGBB में)
MapShape.Circle c = new MapShape.Circle(2, 0xFF2196F3, 0x402196F3);
c.setPolygon(new LatLon(-23.55, -46.63), 500.0);   // केंद्र + मीटर में त्रिज्या
mc.map.add(c);
```
`Line(thick, color)` और `Polygon(borderWidth, borderColor, fillColor)` भी वही पैटर्न अपनाते हैं।

## रूट और उपयोगिताएँ
```java
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);   // स्थिर छवि (त्रुटि/बिना key होने पर null)
```
वास्तविक दिशाएँ (HTTP + **Jackson**) `DirectionsFetcher` से आती हैं (कॉलबैक `onRouteReady(List<LatLon>)`),
जो `MapRoute(lineShape, pins)` के साथ संयोजित होती हैं — परिणाम को `onUI(...)` के साथ मार्शल करें। विवरण
अध्याय 25 में है।

## सर्वोत्तम अभ्यास
- इंस्टैंशिएट करने से **पहले** key; `mc.map` का एक्सेस **केवल** `onMapLoad` में।
- `mc.map == null` (Web) और `getMapImage(...) == null` को संभालें।
- मानचित्र के ऑपरेशन render thread पर; नेटवर्क के परिणाम `onUI(...)` के ज़रिए।

## सामान्य त्रुटियाँ
- कंस्ट्रक्टर में `mc.map` को एक्सेस करना (अभी भी `null`)।
- `MapContainer.googleMapsKey` भूल जाना।
- `phone.GoogleMaps` (हटा दिया गया) का उपयोग करना।

## यह भी देखें
- [स्थान और GPS](/docs/data-and-services/device-location-gps) · [LocationView](/docs/ui/widgets/locationview)