From 6075c0bf71f25601255ba4f3f1f952817250c7f1 Mon Sep 17 00:00:00 2001 From: David Britch Date: Fri, 27 Oct 2023 09:28:25 +0100 Subject: [PATCH 1/2] Geolocation foreground listening. --- .../device/geolocation.md | 63 +++++++++++++++++++ docs/whats-new/dotnet-8.md | 1 + 2 files changed, 64 insertions(+) diff --git a/docs/platform-integration/device/geolocation.md b/docs/platform-integration/device/geolocation.md index 891e281665..c0bbc100a4 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, there's a `IsListeningForeground` property you can query. Once you're ready to start listening for location changes you should call the `StartListeningForegroundAsync` method, which starts listening for location updates and raises the `LocationChanged` event when the location changes. The `GeolocationLocationChangedEventArgs` object that accompanies this event has a `Location` property, of type , that represents the new location that's been detected. + +> [!NOTE] +> The `LocationChanged` event will only be raised when the app is in the foreground. + +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: From c39845ff335ca920f1db7b5d6649059f070abb91 Mon Sep 17 00:00:00 2001 From: David Britch Date: Fri, 27 Oct 2023 09:44:27 +0100 Subject: [PATCH 2/2] Edits. --- docs/platform-integration/device/geolocation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platform-integration/device/geolocation.md b/docs/platform-integration/device/geolocation.md index c0bbc100a4..ab099fad67 100644 --- a/docs/platform-integration/device/geolocation.md +++ b/docs/platform-integration/device/geolocation.md @@ -144,10 +144,10 @@ Not all location values may be available, depending on the device. For example, 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, there's a `IsListeningForeground` property you can query. Once you're ready to start listening for location changes you should call the `StartListeningForegroundAsync` method, which starts listening for location updates and raises the `LocationChanged` event when the location changes. The `GeolocationLocationChangedEventArgs` object that accompanies this event has a `Location` property, of type , that represents the new location that's been detected. +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] -> The `LocationChanged` event will only be raised when the app is in the foreground. +> 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: