- Dokumentation

- Bereinigung von Code

docs/locationHelper.md

@@ -0,0 +1,83 @@
+# locationHelper
+
+## Übersicht
+Dieses Modul stellt Hilfsfunktionen und Composables bereit, um die GPS-Standortbestimmung innerhalb der ArcGIS Maps SDK für Kotlin (Compose-Toolkit) zu verwalten. Es kümmert sich um die Prüfung und Abfrage von Android-Laufzeitberechtigungen sowie die Initialisierung des `LocationDisplay`.
+
+---
+
+## 1. LocationHelper (Klasse)
+`class LocationHelper(private val context: Context)`
+
+Eine Utility-Klasse zur Kapselung von Berechtigungsprüfungen.
+
+### Zweck
+Zentralisierung der Logik für die Prüfung von Standortberechtigungen (`ACCESS_COARSE_LOCATION` und `ACCESS_FINE_LOCATION`).
+
+### Methoden
+| Methode | Rückgabetyp | Beschreibung |
+| :--- | :--- | :--- |
+| `hasLocationPermissions()` | `Boolean` | Gibt `true` zurück, wenn sowohl die grobe als auch die feine Standortberechtigung vom Nutzer erteilt wurde. |
+
+---
+
+## 2. setupLocationDisplay (Composable)
+`@Composable fun setupLocationDisplay(autoPanMode: LocationDisplayAutoPanMode): LocationDisplay`
+
+Die Haupt-Einstiegsfunktion für die Standortvisualisierung in einer MapView.
+
+### Zweck
+Initialisiert das `LocationDisplay`-Objekt, setzt den Modus für die automatische Schwenkung der Karte (Auto-Pan) und startet die Datenquelle für Standortaktualisierungen.
+
+### Parameter
+| Parameter | Typ | Default | Beschreibung |
+| :--- | :--- | :--- | :--- |
+| `autoPanMode` | `LocationDisplayAutoPanMode` | `.Recenter` | Bestimmt das Verhalten der Kamera bei Standortänderung (z.B. Zentrieren oder Navigieren). |
+
+### Funktionsweise
+1. **Initialisierung**: Erzeugt ein `LocationDisplay` mittels `rememberLocationDisplay()`.
+2. **Berechtigungsprüfung**: Nutzt den `LocationHelper`, um den aktuellen Status zu prüfen.
+3. **Datenquelle starten**:
+    - Sind Berechtigungen vorhanden: Startet die `dataSource` sofort via `LaunchedEffect`.
+    - Fehlen Berechtigungen: Ruft das Composable `RequestLocationPermissions` auf.
+4. **Rückgabe**: Liefert das konfigurierte Objekt an die übergeordnete `MapView` zurück.
+
+---
+
+## 3. RequestLocationPermissions (Privates Composable)
+`@Composable private fun RequestLocationPermissions(...)`
+
+Ein UI-Komponente zur Interaktion mit dem Android-Berechtigungssystem.
+
+### Zweck
+Anforderung der erforderlichen Berechtigungen während der Laufzeit (Runtime Permissions).
+
+### Parameter
+| Parameter | Typ | Beschreibung |
+| :--- | :--- | :--- |
+| `context` | `Context` | Android-Kontext für Toast-Meldungen. |
+| `onPermissionsGranted` | `() -> Unit` | Callback, der ausgeführt wird, wenn der Nutzer alle angeforderten Rechte bestätigt hat. |
+
+### Ablauf
+1. Nutzt `rememberLauncherForActivityResult`, um auf die Antwort des Betriebssystems zu warten.
+2. Fordert im `LaunchedEffect` gleichzeitig `ACCESS_COARSE_LOCATION` und `ACCESS_FINE_LOCATION` an.
+3. **Erfolg**: Ruft `onPermissionsGranted()` auf, was in der Regel den Start des GPS-Tracking auslöst.
+4. **Ablehnung**: Zeigt eine `Toast`-Meldung an, um den Nutzer über die fehlende Funktionalität aufzuklären.
+
+---
+
+## Verwendete Berechtigungen (Manifest)
+Für die korrekte Funktion müssen folgende Tags in der `AndroidManifest.xml` vorhanden sein:
+* `android.permission.ACCESS_FINE_LOCATION`
+* `android.permission.ACCESS_COARSE_LOCATION`
+
+---
+
+## Architektur-Hinweis
+Das Modul nutzt das **ArcGIS Maps Compose Toolkit**. Das zurückgegebene `LocationDisplay` wird normalerweise direkt in einer `MapView` Composable als Parameter übergeben:
+
+```kotlin
+MapView(
+    modifier = Modifier.fillMaxSize(),
+    arcGISMap = map,
+    locationDisplay = setupLocationDisplay()
+)