Geolocation foreground listening (#1832)

* Geolocation foreground listening.

* Edits.

Author: davidbritch

docs/platform-integration/device/geolocation.md

@@ -138,6 +138,69 @@ Not all location values may be available, depending on the device. For example,
 > [!WARNING]
 > <xref:Microsoft.Maui.Devices.Sensors.IGeolocation.GetLocationAsync%2A> can return `null` in some scenarios. This indicates that the underlying platform is unable to obtain the current location.
 
+::: moniker range=">=net-maui-8.0"
+
+## Listen for location changes
+
+In addition to querying the device for the current location, you can listen for location changes while an app is in the foreground.
+
+To check to see if the app is currently listening for location changes, there's a `IsListeningForeground` property you can query. Once you're ready to start listening for location changes you should call the `StartListeningForegroundAsync` method. This method starts listening for location updates and raises the `LocationChanged` event when the location changes, provided that the app is in the foreground. The `GeolocationLocationChangedEventArgs` object that accompanies this event has a `Location` property, of type <xref:Microsoft.Maui.Devices.Sensors.Location>, that represents the new location that's been detected.
+
+> [!NOTE]
+> When necessary, the Geolocation API prompts the user for permissions.
+
+The following code example demonstrates how to listen for a location change, and how to process the changed location:
+
+```csharp
+async void OnStartListening()
+{
+    try
+    {
+        Geolocation.LocationChanged += Geolocation_LocationChanged;
+        var request = new GeolocationListeningRequest((GeolocationAccuracy)Accuracy);
+        var success = await Geolocation.StartListeningForegroundAsync(request);
+
+        string status = success
+            ? "Started listening for foreground location updates"
+            : "Couldn't start listening";
+    }
+    catch (Exception ex)
+    {
+        // Unable to start listening for location changes
+    }
+}
+
+void Geolocation_LocationChanged(object sender, GeolocationLocationChangedEventArgs e)
+{
+    // Process e.Location to get the new location
+}
+```
+
+Error handling can be implemented by registering an event handler for the `ListeningFailed` event. The `GeolocationListeningFailedEventArgs` object that accompanies this event has an `Error` property, of type `GeolocationError`, that indicates why listening failed. When the `ListeningFailed` event is raised, listening for further location changes stops and no further `LocationChanged` events are raised.
+
+To stop listening for location changes, call the `StopListeningForeground` method:
+
+```csharp
+void OnStopListening()
+{
+    try
+    {
+        Geolocation.LocationChanged -= Geolocation_LocationChanged;
+        Geolocation.StopListeningForeground();
+        string status = "Stopped listening for foreground location updates";
+    }
+    catch (Exception ex)
+    {
+        // Unable to stop listening for location changes
+    }
+}
+```
+
+> [!NOTE]
+> The `StopListeningForeground` method has no effect when the app isn't listening for location changes.
+
+::: moniker-end
+
 ## Accuracy
 
 The following sections outline the location accuracy distance, per platform:

docs/whats-new/dotnet-8.md

@@ -44,6 +44,7 @@ For information about what's new in .NET 8, see [What's new in .NET 8](/dotnet/c
 - Shell navigation gains a `GoToAsync` overload that enables you to pass single use navigation data, that's cleared after navigation has occurred, as a `ShellNavigationQueryParameters` object. For more information, see [Pass single use object-based navigation data](~/fundamentals/shell/navigation.md#pass-single-use-object-based-navigation-data).
 - Window management can be decoupled from the `App` class. For more information, see [Decouple window management from the App class](~/fundamentals/windows.md#decouple-window-management-from-the-app-class).
 - Menu bar items and context menu items can be invoked through keyboard shortcuts known as keyboard accelerators. For more information, see [Keyboard accelerators](~/user-interface/keyboard-accelerators.md).
+- The <xref:Microsoft.Maui.Devices.Sensors.Geolocation> class can listen for location changes when app's are in the foreground. For more information, see [Listen for location changes](~/platform-integration/device/geolocation.md#listen-for-location-changes).
 
 The following types or members have been deprecated: