diff --git a/docs/platform-integration/device/geolocation.md b/docs/platform-integration/device/geolocation.md index 891e281665..ab099fad67 100644 --- a/docs/platform-integration/device/geolocation.md +++ b/docs/platform-integration/device/geolocation.md @@ -138,6 +138,69 @@ Not all location values may be available, depending on the device. For example, > [!WARNING] > 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 , 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: diff --git a/docs/whats-new/dotnet-8.md b/docs/whats-new/dotnet-8.md index 8b4926e8b9..3743fb4328 100644 --- a/docs/whats-new/dotnet-8.md +++ b/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 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: