Merge pull request #2999 from sarayourfriend/add/gtk-geoclue-geolocation

Add Location implementation to Toga GTK

.github/workflows/ci.yml

@@ -264,7 +264,7 @@ jobs:
         - backend: "linux-x11"
           platform: "linux"
           runs-on: "ubuntu-24.04"
-          # The package list should be the same as in tutorial-0.rst, and the BeeWare
+          # The package list should be the same as in unix-prerequisites.rst, and the BeeWare
           # tutorial, plus blackbox to provide a window manager. We need a window
           # manager that is reasonably lightweight, honors full screen mode, and
           # treats the window position as the top-left corner of the *window*, not the
@@ -275,7 +275,7 @@ jobs:
             sudo apt update -y
             sudo apt install -y --no-install-recommends \
               blackbox pkg-config python3-dev libgirepository1.0-dev libcairo2-dev \
-              gir1.2-webkit2-4.1 gir1.2-xapp-1.0
+              gir1.2-webkit2-4.1 gir1.2-xapp-1.0 gir1.2-geoclue-2.0 gir1.2-flatpak-1.0
 
             # Start Virtual X Server
             echo "Start X server..."
@@ -293,13 +293,13 @@ jobs:
         - backend: "linux-wayland"
           platform: "linux"
           runs-on: "ubuntu-24.04"
-          # The package list should be the same as in tutorial-0.rst, and the BeeWare
+          # The package list should be the same as in unix-prerequisites.rst, and the BeeWare
           # tutorial, plus mutter to provide a window manager.
           pre-command: |
             sudo apt update -y
             sudo apt install -y --no-install-recommends \
               mutter pkg-config python3-dev libgirepository1.0-dev libcairo2-dev \
-              gir1.2-webkit2-4.1 gir1.2-xapp-1.0
+              gir1.2-webkit2-4.1 gir1.2-xapp-1.0 gir1.2-geoclue-2.0 gir1.2-flatpak-1.0
 
             # Start Virtual X Server
             echo "Start X server..."

android/tests_backend/hardware/location.py

@@ -11,6 +11,8 @@
 
 
 class LocationProbe(HardwareProbe):
+    supports_background_permission = True
+
     def __init__(self, monkeypatch, app_probe):
         super().__init__(monkeypatch, app_probe.app)
 
@@ -100,3 +102,10 @@ async def simulate_location_error(self, location):
         await self.redraw("Wait for location error")
 
         pytest.xfail("Android's location service doesn't raise errors on failure")
+
+    def setup_location_error(self):
+        # location error simulation handled by ``simulate_location_error``
+        pass
+
+    def setup_tracking_start_error(self):
+        pytest.xfail("Tracking start cannot fail on Android")

changes/2990.feature.rst

@@ -0,0 +1 @@
+Toga GTK now supports location services via integration with GeoClue and the XDG Location Portal.

cocoa/tests_backend/hardware/location.py

@@ -1,5 +1,6 @@
 from unittest.mock import Mock, PropertyMock
 
+import pytest
 from rubicon.objc import ObjCClass
 
 from toga_cocoa import libs as cocoa
@@ -16,6 +17,8 @@
 
 
 class LocationProbe(AppProbe):
+    supports_background_permission = True
+
     def __init__(self, monkeypatch, app_probe):
         super().__init__(app_probe.app)
 
@@ -173,3 +176,10 @@ async def simulate_location_error(self, location):
         )
 
         return await location
+
+    def setup_location_error(self):
+        # location error simulation handled by ``simulate_location_error``
+        pass
+
+    def setup_tracking_start_error(self):
+        pytest.xfail("Tracking start cannot fail on macOS")

docs/reference/api/hardware/location.rst

@@ -72,6 +72,31 @@ location is obtained:
 
 If you no longer wish to receive location updates, call :any:`Location.stop_tracking()`.
 
+.. _location-system-requires:
+
+System requirements
+-------------------
+
+* Using location services on Linux requires that the user has installed the system
+  packages for GeoClue2, plus the GObject Introspection bindings for GeoClue2. The name
+  of the system package required is distribution dependent:
+
+  - Ubuntu and Debian: ``gir1.2-geoclue-2.0``
+  - Fedora: ``geoclue2-libs``
+  - Arch/Manjaro: ``geoclue``
+  - OpenSUSE Tumbleweed: ``geoclue2 typelib(geoclue2)``
+  - FreeBSD: ``geoclue``
+
+* The GeoClue service must be enabled for Toga GTK location services to work. Some
+  distributions are pre-configured with GeoClue and require no action from users to
+  enable location services. Others, for example, `Ubuntu, have special controls
+  for managing location services, which must be turned on before GeoClue will
+  function <ubuntu-location-services_>`_. Refer to your distribution's documentation
+  on GeoClue and location services for details on how to manage and configure
+  the GeoClue service.
+
+.. _ubuntu-location-services: https://help.ubuntu.com/stable/ubuntu-help/privacy-location.html
+
 Notes
 -----
 
@@ -91,8 +116,18 @@ Notes
     want to track location while the app is in the background, you must also define the
     permission ``android.permission.ACCESS_BACKGROUND_LOCATION``.
 
-* On macOS, there is no distinction between "background" permissions and "while-running"
-  permissions.
+* On macOS and GTK, there is no distinction between "background" permissions and "while-running"
+  permissions for location tracking.
+
+* On Linux, there are no reliable permission controls for non-sandboxed applications.
+  Sandboxed applications (e.g., Flatpak apps) request location information via the XDG
+  Portal Location API, which has coarse grained permissions allowing users to reliably
+  disallow location access on a per-app basis. However, `Linux users should be aware of
+  the limitations of location privacy for non-sandboxed applications
+  <linux-location-privacy_>`_. This applies to all Linux applications, not just ones
+  using Toga GTK's Location implementation.
+
+.. _linux-location-privacy: https://gitlab.freedesktop.org/geoclue/geoclue/-/issues/111
 
 * On iOS, if the user has provided "allow once" permission for foreground location
   tracking, requests for background location permission will be rejected.

docs/reference/data/widgets_by_platform.csv

@@ -30,7 +30,7 @@ ScrollContainer,Layout Widget,:class:`~toga.ScrollContainer`,A container that ca
 SplitContainer,Layout Widget,:class:`~toga.SplitContainer`,A container that divides an area into two panels with a movable border,|y|,|y|,|y|,,,,
 OptionContainer,Layout Widget,:class:`~toga.OptionContainer`,A container that can display multiple labeled tabs of content,|y|,|y|,|y|,|y|,|y|,,
 Camera,Hardware,:class:`~toga.hardware.camera.Camera`,A sensor that can capture photos and/or video.,|y|,,,|y|,|y|,,
-Location,Hardware,:class:`~toga.hardware.location.Location`,A sensor that can capture the geographical location of the device.,|y|,,,|y|,|y|,,
+Location,Hardware,:class:`~toga.hardware.location.Location`,A sensor that can capture the geographical location of the device.,|y|,|y|,,|y|,|y|,,
 Screen,Hardware,:class:`~toga.screens.Screen`,A representation of a screen attached to a device.,|y|,|y|,|y|,|y|,|y|,|b|,|b|
 App Paths,Resource,:class:`~toga.paths.Paths`,A mechanism for obtaining platform-appropriate filesystem locations for an application.,|y|,|y|,|y|,|y|,|y|,,|b|
 Command,Resource,:class:`~toga.Command`,Command,|y|,|y|,|y|,,|y|,,

docs/reference/platforms/unix-prerequisites.rst

@@ -43,4 +43,7 @@ know so we can improve this documentation!)
 
 Some widgets (most notably, the :ref:`WebView <webview-system-requires>` and
 :ref:`MapView <mapview-system-requires>` widgets) have additional system requirements.
-See the documentation of those widgets for details.
+Likewise, certain hardware features (:ref:`Location <location-system-requires>`) have
+system requirements.
+
+See the documentation of those widgets and hardware features for details.

docs/spelling_wordlist

@@ -23,8 +23,10 @@ Ctrl
 dialogs
 Django
 draggable
+Flatpak
 Flexbox
 GBulb
+GeoClue
 geolocation
 GMail
 GObject
@@ -66,6 +68,7 @@ Ren
 resizable
 reStructuredText
 runtime
+sandboxed
 scrollable
 scrollers
 Segoe

gtk/src/toga_gtk/factory.py

@@ -4,6 +4,7 @@
 from .app import App
 from .command import Command
 from .fonts import Font
+from .hardware.location import Location
 from .icons import Icon
 from .images import Image
 from .paths import Paths
@@ -48,6 +49,8 @@ def not_implemented(feature):
     "Image",
     "Paths",
     "dialogs",
+    # Hardware
+    "Location",
     # Status icons
     "MenuStatusIcon",
     "SimpleStatusIcon",