Gtk4 migration

.github/workflows/ci.yml

@@ -168,7 +168,7 @@ jobs:
             # work either. Blackbox is the lightest WM we've found that works.
             pre-command: |
               sudo apt update -y
-              sudo apt install -y blackbox pkg-config python3-dev libgirepository1.0-dev libcairo2-dev gir1.2-webkit2-4.0
+              sudo apt install -y blackbox pkg-config python3-dev libgirepository1.0-dev libcairo2-dev gir1.2-webkit2-4.0 libgtk-4-dev
 
               # Start Virtual X server
               echo "Start X server..."

android/tests_backend/icons.py

@@ -35,5 +35,8 @@ def assert_default_icon_content(self):
             == Path(toga_android.__file__).parent / "resources/toga.png"
         )
 
-    def assert_platform_icon_content(self):
-        assert self.icon._impl.path == self.app.paths.app / "resources/logo-android.png"
+    def assert_platform_icon_content(self, platform):
+        assert (
+            self.icon._impl.path
+            == self.app.paths.app / f"resources/logo-{platform}.png"
+        )

android/tests_backend/window.py

@@ -19,6 +19,9 @@ def content_size(self):
             self.root_view.getHeight() / self.scale_factor,
         )
 
+    def assert_as_image(self, screenshot, window_content_size):
+        self.assert_image_size(screenshot.size, window_content_size)
+
     async def close_info_dialog(self, dialog):
         dialog_view = self.get_dialog_view()
         self.assert_dialog_buttons(dialog_view, ["OK"])

changes/1978.misc.rst

@@ -0,0 +1 @@
+Now, Toga is using ``Gtk4`` instead of ``Gtk3`` as the native GUI backend for Linux.

cocoa/tests_backend/icons.py

@@ -36,5 +36,8 @@ def assert_default_icon_content(self):
             == Path(toga_cocoa.__file__).parent / "resources/toga.icns"
         )
 
-    def assert_platform_icon_content(self):
-        assert self.icon._impl.path == self.app.paths.app / "resources/logo-macOS.icns"
+    def assert_platform_icon_content(self, platform):
+        assert (
+            self.icon._impl.path
+            == self.app.paths.app / f"resources/logo-{platform}.icns"
+        )

cocoa/tests_backend/window.py

@@ -24,6 +24,7 @@ class WindowProbe(BaseProbe):
     supports_move_while_hidden = True
     supports_multiple_select_folder = True
     supports_unminimize = True
+    supports_positioning = True
 
     def __init__(self, app, window):
         super().__init__()
@@ -75,6 +76,9 @@ def minimize(self):
     def unminimize(self):
         self.native.deminiaturize(None)
 
+    def assert_as_image(self, screenshot, window_content_size):
+        self.assert_image_size(screenshot.size, window_content_size)
+
     async def close_info_dialog(self, dialog):
         self.native.endSheet(
             self.native.attachedSheet,

core/src/toga/widgets/base.py

@@ -2,6 +2,7 @@
 
 from builtins import id as identifier
 from typing import TYPE_CHECKING
+from weakref import ref
 
 from travertino.node import Node
 
@@ -214,7 +215,7 @@ def window(self) -> Window | None:
         If the widget has a value for :any:`window`, it *must* also have a value for
         :any:`app`.
         """
-        return self._window
+        return self._window() if self._window else self._window
 
     @window.setter
     def window(self, window: Window | None) -> None:
@@ -226,7 +227,7 @@ def window(self, window: Window | None) -> None:
             # If the widget is being assigned to a window for the first time, add it to the widget registry
             window.app.widgets._add(self)
 
-        self._window = window
+        self._window = ref(window) if window else window
         self._impl.set_window(window)
 
         for child in self.children:

core/src/toga/window.py

@@ -386,14 +386,17 @@ def close(self) -> None:
         self._impl.close()
         self._closed = True
 
-    def as_image(self, format: type[ImageT] = Image) -> ImageT:
-        """Render the current contents of the window as an image.
-
-        :param format: Format to provide. Defaults to :class:`~toga.images.Image`; also
-            supports :any:`PIL.Image.Image` if Pillow is installed
-        :returns: An image containing the window content, in the format requested.
+    def as_image(self, format: type[ImageT] = Image) -> ImageT | None:
+        """Render the current contents of the window as an image if it's possible
+        otherwise nothing will be rendered.
+
+        :param format: Format to provide. Defaults to :class:`~toga.images.Image`;
+            also supports :any:`PIL.Image.Image` if Pillow is installed.
+        :returns: An image containing the window content, in the format requested
+            if possible otherwise return None.
         """
-        return Image(self._impl.get_image_data()).as_format(format)
+        image_data = self._impl.get_image_data()
+        return Image(image_data).as_format(format) if image_data else None
 
     ############################################################
     # Dialogs

docs/how-to/contribute-code.rst

@@ -745,7 +745,7 @@ the Toga public API doesn't provide a way to determine the physical size of a
 widget, or interrogate the font being used to render a widget; the probe
 implementation does. This allows a testbed test case to verify that a widget has
 been laid out correctly inside the Toga window, is drawn using the right font,
-and has any other other appropriate physical properties or internal state.
+and has any other appropriate physical properties or internal state.
 
 The probe also provides a programmatic interface for interacting *with* a
 widget. For example, in order to test a button, you need to be able to press
@@ -762,10 +762,10 @@ test case can call ``await probe.redraw()``. This guarantees that any
 outstanding redraw events have been processed. These ``redraw()`` requests are
 also used to implement slow mode - each redraw is turned into a 1 second sleep.
 
-If a widget doesn't have a probe for a given widget, the testbed should call
-``pytest.skip()`` for that platform when constructing the widget fixture (there
-is a ``skip_on_platforms()`` helper method in the testbed method to do this).
-If a widget hasn't implemented a specific probe method that the testbed
+If a Toga widget doesn't have a probe for a given widget, the testbed should
+call ``pytest.skip()`` for that platform when constructing the widget fixture
+(there is a ``skip_on_platforms()`` helper method in the testbed method to do
+this). If a widget hasn't implemented a specific probe method that the testbed
 required, it should call ``pytest.skip()`` so that the backend knows to skip the
 test.
 

docs/reference/api/resources/icons.rst

@@ -38,7 +38,7 @@ The following formats are supported (in order of preference):
 * **Android** - PNG
 * **iOS** - ICNS, PNG, BMP, ICO
 * **macOS** - ICNS, PNG, PDF
-* **GTK** - PNG, ICO, ICNS. 32px and 72px variants of each icon can be provided;
+* **GTK** - PNG, ICO, ICNS
 * **Windows** - ICO, PNG, BMP
 
 The first matching icon of the most specific platform, with the most specific
@@ -54,15 +54,13 @@ will cause Toga to look for (in order):
 
 On GTK, Toga will look for (in order):
 
-* ``myicon-linux-72.png``
-* ``myicon-72.png``
-* ``myicon-linux-32.png``
-* ``myicon-32.png``
 * ``myicon-linux.png``
+* ``myicon-freebsd.png``
 * ``myicon.png``
-* ``myicon-linux-72.ico``
-* ``myicon-72.ico``
-* ``myicon-linux-32.ico``, and so on.
+* ``myicon-linux.ico``
+* ``myicon-freebsd.ico``
+* ``myicon.ico``
+* ``myicon-linux.ico``, and so on.
 
 An icon is **guaranteed** to have an implementation, regardless of the path
 specified. If you specify a path and no matching icon can be found, Toga will

docs/reference/api/window.rst

@@ -81,16 +81,20 @@ Notes
   these are ultimately at the discretion of the OS (or window manager). For
   example, on macOS, depending on a user's OS-level settings, new windows may
   open as tabs on the main window; on Linux, some window managers (e.g., tiling
-  window managers) may not honor an app's size and position requests. You should
-  avoid making UI design decisions that are dependent on specific size and
-  placement of windows.
+  window managers) may not honor an app's size request. You should avoid making
+  UI design decisions that are dependent on specific size of windows.
+
+* GTK doesn't allow window positioning and it suggests leaving the positioning task
+  to the window managers. See `this discussion`_ for details.
 
 * A mobile application can only have a single window (the :class:`~toga.MainWindow`),
   and that window cannot be moved, resized, hidden, or made full screen. Toga will raise
   an exception if you attempt to create a secondary window on a mobile platform. If you
   try to modify the size, position, or visibility of the main window, the request will
   be ignored.
 
+.. _this discussion: https://discourse.gnome.org/t/how-to-center-gtkwindows-in-gtk4/3112/4
+
 Reference
 ---------
 

docs/spelling_wordlist

@@ -41,6 +41,7 @@ OTF
 Pango
 parameterization
 platformer
+positioning
 pre
 prepending
 programmatically