SnapAndSolve/docs/locationHelper.md

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:

MapView(
    modifier = Modifier.fillMaxSize(),
    arcGISMap = map,
    locationDisplay = setupLocationDisplay()
)