add a layout debug mode that sets background colors

changes/2953.feature.rst

@@ -0,0 +1 @@
+Toga now has a layout debugging mode. If you set ``TOGA_DEBUG_LAYOUT=1`` in your app's runtime environment, widgets will be rendered with different background colors, making it easier to identify how space is being allocated by Toga's layout algorithm.

core/src/toga/widgets/base.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 from builtins import id as identifier
+from os import environ
+from random import shuffle
 from typing import TYPE_CHECKING, Any, TypeVar
 from warnings import warn
 
@@ -17,10 +19,29 @@
 StyleT = TypeVar("StyleT", bound=BaseStyle)
 
 
+# based on colors from https://davidmathlogic.com/colorblind
+debug_background_palette = [
+    "#d0e2ed",  # very light blue
+    "#b8d2e9",  # light blue
+    "#f8ccb0",  # light orange
+    "#f6d3be",  # soft orange
+    "#c7e7b2",  # light green
+    "#f0b2d6",  # light pink
+    "#e5dab0",  # light yellow
+    "#d5c2ea",  # light lavender
+    "#b2e4e5",  # light teal
+    "#e5e4af",  # light cream
+    "#bde2dc",  # soft turquoise
+]
+shuffle(debug_background_palette)
+
+
 class Widget(Node):
     _MIN_WIDTH = 100
     _MIN_HEIGHT = 100
 
+    _debug_color_index = 0
+
     def __init__(
         self,
         id: str | None = None,
@@ -34,6 +55,18 @@ def __init__(
         :param style: A style object. If no style is provided, a default style
             will be applied to the widget.
         """
+        # If the object has _USE_DEBUG_BACKGROUND=True and layout debug mode
+        # is on, change bg color.BufferError
+        if getattr(self, "_USE_DEBUG_BACKGROUND", False):
+            if environ.get("TOGA_DEBUG_LAYOUT") == "1":
+                Widget._debug_color_index += 1
+                style = style if style else Pack()
+                style.background_color = debug_background_palette[
+                    Widget._debug_color_index % len(debug_background_palette)
+                ]
+        else:
+            self._USE_DEBUG_BACKGROUND = False
+
         super().__init__(style=style if style is not None else Pack())
 
         self._id = str(id if id else identifier(self))

core/src/toga/widgets/box.py

@@ -22,6 +22,8 @@ def __init__(
             will be applied to the widget.
         :param children: An optional list of children for to add to the Box.
         """
+        # enable the debug background functionality
+        self._USE_DEBUG_BACKGROUND = True
         super().__init__(id=id, style=style)
 
         # Children need to be added *after* the impl has been created.

core/src/toga/widgets/optioncontainer.py

@@ -393,6 +393,8 @@ def __init__(
             <OptionContainerContentT>` to display in the OptionContainer.
         :param on_select: Initial :any:`on_select` handler.
         """
+        # enable the debug background functionality
+        self._USE_DEBUG_BACKGROUND = True
         super().__init__(id=id, style=style)
         self._content = OptionList(self)
         self.on_select = None

core/src/toga/widgets/scrollcontainer.py

@@ -40,6 +40,8 @@ def __init__(
         :param on_scroll: Initial :any:`on_scroll` handler.
         :param content: The content to display in the scroll window.
         """
+        # enable the debug background functionality
+        self._USE_DEBUG_BACKGROUND = True
         super().__init__(id=id, style=style)
 
         self._content: Widget | None = None

core/src/toga/widgets/splitcontainer.py

@@ -42,6 +42,8 @@ def __init__(
         :param content: Initial :any:`SplitContainer content <SplitContainerContentT>`
             of the container. Defaults to both panels being empty.
         """
+        # enable the debug background functionality
+        self._USE_DEBUG_BACKGROUND = True
         super().__init__(id=id, style=style)
         self._content: list[SplitContainerContentT] = [None, None]
 

core/tests/widgets/test_container_debug_mode.py

@@ -0,0 +1,76 @@
+from pytest import MonkeyPatch
+from travertino.colors import color
+
+import toga
+
+
+# test that a container-like widget in normal mode has a default background
+def test_box_no_background_in_normal_mode():
+    """A Box has no default background."""
+    # Disable layout debug mode
+    with MonkeyPatch.context() as mp:
+        mp.setenv("TOGA_DEBUG_LAYOUT", "0")
+        box = toga.Box()
+        # assert that the bg is default
+        assert hasattr(box.style, "background_color")
+        assert not box.style.background_color
+
+
+# test that a non-container-like widget in layout debug mode has a default background
+def test_button_debug_background():
+    """A Button in layout debug mode has a default background."""
+    # Enable layout debug mode
+    with MonkeyPatch.context() as mp:
+        mp.setenv("TOGA_DEBUG_LAYOUT", "1")
+        button = toga.Button()
+        # assert that the bg is default
+        assert hasattr(button.style, "background_color")
+        assert not button.style.background_color
+
+
+# test that a label in layout debug mode has a default background
+def test_label_no_debug_background():
+    """A Label in layout debug mode has a default background."""
+    # Enable layout debug mode
+    with MonkeyPatch.context() as mp:
+        mp.setenv("TOGA_DEBUG_LAYOUT", "1")
+        label = toga.Label("label")
+        # assert that the bg is default
+        assert hasattr(label.style, "background_color")
+        assert not label.style.background_color
+
+
+# test that a container-like widget in layout debug mode has a non-default background
+# that matches the expected debug_background_palette
+def test_box_debug_backgrounds():
+    """A Box in layout debug mode has a non-default background."""
+    # Enable layout debug mode
+    with MonkeyPatch.context() as mp:
+        mp.setenv("TOGA_DEBUG_LAYOUT", "1")
+
+        boxes = []
+        debug_bg_palette_length = len(toga.widgets.base.debug_background_palette)
+        # need enough for coverage of debug_background_palette array index rollover
+        for i in range(debug_bg_palette_length + 3):
+            boxes.append(toga.Box())
+
+        for counter, box in enumerate(boxes, start=1):
+            index = counter % debug_bg_palette_length
+            print(counter)
+            assert hasattr(box.style, "background_color")
+            assert box.style.background_color == color(
+                toga.widgets.base.debug_background_palette[index]
+            )
+
+
+# test that a scroll container widget in layout debug mode doesn't have
+# a default background
+def test_scroll_container_debug_background():
+    """A container widget has a default background."""
+    # Disable layout debug mode
+    with MonkeyPatch.context() as mp:
+        mp.setenv("TOGA_DEBUG_LAYOUT", "1")
+        sc = toga.ScrollContainer()
+        # assert that the bg is not default
+        assert hasattr(sc.style, "background_color")
+        assert sc.style.background_color != color("white")