# LocationView

> GPS निर्देशांक (lat, lon, fix का समय, गति, दिशा) को टेक्स्ट के रूप में प्रदर्शित करता है, समय-समय पर अपडेट होता है।

Source: https://crossfly.dev/hi/docs/ui/widgets/locationview — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# LocationView

`LocationView` एक विजेट है जो GPS डेटा को टेक्स्ट के रूप में **प्रदर्शित** करता है: अक्षांश और देशांतर (N/S और E/W प्रत्यय के साथ अंश/मिनट/सेकंड में), fix का समय, गति, दिशा और उपग्रहों की संख्या। यह समय-समय पर एक `Location` (GPS स्रोत — COM/Bluetooth/IR पोर्ट या नेटिव API) से पढ़ता है और एक `VerticalLayout` में ढेर किए गए पाँच `Label` को अपडेट करता है।

यह **मानचित्र नहीं बनाता** — केवल संख्याएं दिखाता है। डिवाइस की स्थिति पर मानचित्र को केंद्रित करने के लिए, `Map` का उपयोग करें (देखें अध्याय 25)।

> 🟡 · **पैकेज:** `dev.crossfly.ui` · **एक्सटेंड करता है:** `Component` · **डेटा स्रोत:** `dev.crossfly.device.Location`

## कब उपयोग करें
- डिवाइस के वर्तमान निर्देशांक टेक्स्ट में दिखाना (डायग्नोस्टिक, HUD, GPS स्टेटस स्क्रीन)।
- टाइमर लूप लिखे बिना स्थिति की स्वचालित आवधिक रीडिंग प्राप्त करना।

## कब उपयोग न करें
- मानचित्र रेंडर करना या स्थिति को दृश्य रूप में चिह्नित करना → `Map` का उपयोग करें (अध्याय 25)।
- बिना UI के केवल एक बार कोड में स्थिति पढ़ना → सीधे `Location` क्लास का उपयोग करें।

## दिखावट
पाँच टेक्स्ट लाइनें (lat, lon, fix, speed, direction), बाईं ओर संरेखित, एक `VerticalLayout` में। जब तक डेटा नहीं होता, "Location Initialising" दिखाता है; बिना सिग्नल के, स्थानीयकरण योग्य स्ट्रिंग्स `LAT_LOW_SIGNAL` / `LON_LOW_SIGNAL` दिखाता है।

## पूरा उदाहरण (कॉपी करें, पेस्ट करें और चलाएं)
`LocationView` एक सामान्य कंपोनेंट है: यह `add(LAY_AUTO, ...)` के साथ सीधे स्क्रीन में जाता है। कंस्ट्रक्टर `throws IOException` घोषित करता है, जो `onShow() throws Exception` द्वारा पहले से ही कवर है। टाइमर `onAdd` में शुरू होता है और `onRemove` में रुकता है — इसे मैन्युअल रूप से प्रबंधित करने की आवश्यकता नहीं है।

```java
package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

/** चलाने योग्य मुख्य स्क्रीन। launcher (classname) की ओर संकेत करें और चलाएँ: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      add(LAY_AUTO, new Label("Coordenadas do GPS:"));

      LocationView gps = new LocationView(1000);   // हर 1 s पर पढ़ता है; throws IOException
      gps.onAction(c -> {}); // हर आवधिक रीडिंग पर ट्रिगर होता है (वैकल्पिक)
      add(LAY_AUTO, gps);
      // timer onAdd में शुरू होता है और onRemove में स्वचालित रूप से रुक जाता है।
   }
}
```

> नीचे दिए गए स्निपेट **केवल मुख्य भाग** दिखाते हैं (जो `onShow()` के अंदर जाता है)। चलाने के लिए, उन्हें ऊपर के `MainWindow` ढांचे में रखें।

## बुनियादी उपयोग
```java
LocationView gps = new LocationView(1000);   // हर 1 s पर पढ़ता है; throws IOException
container.add(LAY_AUTO, gps);
// स्क्रीन छोड़ते समय, onRemove timer को रोक देता है; या gps.stop() कॉल करें।
```

## कंस्ट्रक्टर
| कंस्ट्रक्टर | विवरण |
|---|---|
| `LocationView()` | 2000 ms का रीडिंग अंतराल, `location = null`। `throws IOException`। |
| `LocationView(int readInterval)` | कस्टम अंतराल (ms; प्रभावी न्यूनतम 100), `location = null`। `throws IOException`। |
| `LocationView(Location location, int readInterval)` | स्पष्ट GPS स्रोत + अंतराल। `throws IOException`। |

## प्रॉपर्टीज़ और अनुकूलन
| मेथड / फ़ील्ड | प्रकार | क्या करता है |
|---|---|---|
| `location` | `Location` (फ़ील्ड) | GPS डेटा स्रोत; कंस्ट्रक्टर में पास किया जा सकता है या `null` रह सकता है। |
| `stop()` | `void` | टाइमर को रोकता है और `location.stop()` कॉल करता है। `throws IOException`। |
| `retrieveGPSData()` | `void` | स्थिति पढ़ता है और लेबल अपडेट करता है (टाइमर द्वारा कॉल किया गया)। |
| `getAutoHeight()` | `int` | पसंदीदा ऊंचाई = `font.scaledHeight() * 5 + ingap.height()`। |
| `LocationView.LAT_LOW_SIGNAL` | स्टैटिक `String` | अक्षांश प्राप्त न होने पर प्रदर्शित टेक्स्ट (स्थानीयकरण योग्य)। |
| `LocationView.LON_LOW_SIGNAL` | स्टैटिक `String` | देशांतर प्राप्त न होने पर प्रदर्शित टेक्स्ट (स्थानीयकरण योग्य)। |

## कॉलबैक और इवेंट
| कॉलबैक | कब ट्रिगर होता है |
|---|---|
| `onAction(Action)` | प्रत्येक आवधिक रीडिंग पर (`retrieveGPSData()` `runActions()` कॉल करता है), सिग्नल के साथ या बिना। इसे अपडेट सूचना बिंदु के रूप में उपयोग करें। |

## स्थितियां
- **आरंभ हो रहा है**: पहले fix से पहले, "Location Initialising" दिखाता है।
- **सिग्नल के साथ**: lat/lon को अंश/मिनट/सेकंड में, fix का समय (12/24 घंटे का प्रारूप `LocaleFormats.is24Hour` से आता है), गति/दिशा जब `!= Location.INVALID` और उपग्रह जब `> 0`।
- **बिना सिग्नल के**: `LAT_LOW_SIGNAL` / `LON_LOW_SIGNAL` और अंतिम लाइन में विफलता का कारण दिखाता है।
- **जीवनचक्र**: टाइमर `onAdd` में शुरू होता है और `onRemove` में (या `stop()` द्वारा) रुक जाता है, संसाधन मुक्त करते हुए।

### स्पष्ट GPS स्रोत + प्रत्येक अपडेट पर प्रतिक्रिया
```java
Location fonte = /* प्लेटफॉर्म से प्राप्त / dev.crossfly.device */;
LocationView gps = new LocationView(fonte, 1000);
gps.onAction(c -> atualizarStatusBarra());  // हर रीडिंग पर ट्रिगर होता है
container.add(LAY_AUTO, gps);

// कम सिग्नल के संदेश खोजें:
LocationView.LAT_LOW_SIGNAL = "lat: sem sinal";
LocationView.LON_LOW_SIGNAL = "lon: sem sinal";
```

## सर्वोत्तम अभ्यास
- जीवनचक्र को टाइमर संभालने दें: विजेट जोड़ना इसे शुरू करता है, हटाना इसे रोकता है। यदि आपको पहले `Location` मुक्त करना हो तो ही स्पष्ट रूप से `stop()` कॉल करें।
- आवश्यकता के अनुसार `readInterval` समायोजित करें — छोटे अंतराल अधिक बैटरी खर्च करते हैं; प्रभावी न्यूनतम 100 ms है।

## सामान्य गलतियां
- कंस्ट्रक्टर के `throws IOException` को भूल जाना।
- मानचित्र की उम्मीद करना: `LocationView` केवल टेक्स्ट दिखाता है; दृश्यीकरण के लिए `Map` का उपयोग करें।
- समयक्षेत्र के बिना स्थानीय समय मानना: fix को समयक्षेत्र के ऑफ़सेट द्वारा `TimeZone.getDefault().getRawOffset()` से समायोजित किया जाता है।

## यह भी देखें
- क्षेत्र गाइड: [`ui/`](/docs/ui) · रेसिपी: [`cookbook/`](/docs/cookbook)
- अवधारणा (i18n, locale प्रारूप): [`concepts/`](/docs/concepts)
- संबंधित कंपोनेंट: [`webcontainer`](/docs/ui/widgets/webcontainer)