gui: enhance UIScrollArea with scroll speed and inversion options

Author: eruvanos

CHANGELOG.md

@@ -16,6 +16,7 @@ Arcade [PyPi Release History](https://pypi.org/project/arcade/#history) page.
 - Fixed an issue where pixel scaling for high-dpi displays did not work correctly in web browsers via Pyodide. See [#2846](https://github.com/pythonarcade/arcade/pull/2846)
 - Fixed issues with update/draw rate handling that changes with Pyglet 3, rates are now handled properly between desktop and browser. See [#2845](https://github.com/pythonarcade/arcade/pull/2845)
 - Fixed caret behavior not responding appropriately when activating an input field. See [#2850](https://github.com/pythonarcade/arcade/pull/2850)
+- GUI: Fixed `UILabel.update_font` always reporting a font change when the requested font was a fallback tuple (e.g. `UIFlatButton`'s default styles), which caused a full UI re-render every frame. This made widget-heavy UIs, such as the `exp_scroll_area` example, run at a few FPS.
 ## 4.0.0.dev4
 
 ### New Features

arcade/gui/experimental/scroll_area.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from collections.abc import Iterable
 from typing import TypeVar
 
@@ -9,6 +10,7 @@
 from arcade import XYWH
 from arcade.gui.events import (
     UIEvent,
+    UIKeyPressEvent,
     UIMouseDragEvent,
     UIMouseEvent,
     UIMouseMovementEvent,
@@ -175,7 +177,26 @@ def do_render(self, surface: Surface):
 class UIScrollArea(UILayout):
     """A widget that can scroll its children.
 
-    This widget is highly experimental and only provides a proof of concept.
+    Children are laid out on an internal canvas, which resizes itself to fit
+    all children (at least the size of the scroll area itself). The visible
+    part of the canvas is controlled by :py:attr:`scroll_x` and
+    :py:attr:`scroll_y` (both range from ``0`` at the start of the content
+    to a negative value at the end).
+
+    For a typical scrollable list, add a container with ``size_hint=(1, 0)``
+    (fill the width of the scroll area, grow to the natural content height)
+    like ``UIBoxLayout``.
+
+    Scrolling is supported via mouse wheel, :class:`UIScrollBar` and, while
+    the mouse hovers the widget, the keyboard
+    (arrow keys, PageUp/PageDown, Home/End).
+
+    .. note::
+        Content containing labels may finish sizing only during the first
+        layout pass and render on the following frame. Single-frame capture
+        pipelines (e.g. CI screenshots) should draw two frames.
+
+    This widget is experimental, the API might change.
 
     Args:
         x: x position of the widget
@@ -186,18 +207,20 @@ class UIScrollArea(UILayout):
         size_hint: size hint of the widget
         size_hint_min: minimum size hint of the widget
         size_hint_max: maximum size hint of the widget
-        canvas_size: size of the canvas, which is scrollable
+        canvas_size: deprecated, the canvas is sized automatically to fit
+            all children
         overscroll_x: allow over scrolling in x direction (scroll past the end)
         overscroll_y: allow over scrolling in y direction (scroll past the end)
+        scroll_speed: speed of scrolling in pixels per scroll event,
+            defaults to :py:attr:`scroll_speed`
+        invert_scroll: invert the scroll direction,
+            defaults to :py:attr:`invert_scroll`
         **kwargs: passed to UIWidget
     """
 
     scroll_x = Property[float](default=0.0)
     scroll_y = Property[float](default=0.0)
 
-    scroll_speed = 1.8
-    invert_scroll = False
-
     def __init__(
         self,
         *,
@@ -209,11 +232,37 @@ def __init__(
         size_hint=None,
         size_hint_min=None,
         size_hint_max=None,
-        canvas_size=(300, 300),
+        canvas_size=None,
         overscroll_x=False,
         overscroll_y=False,
+        scroll_speed: float = 15.0,
+        invert_scroll: bool = False,
         **kwargs,
     ):
+        self.default_anchor_x = "left"
+        self.default_anchor_y = "bottom"
+        self.overscroll_x = overscroll_x
+        self.overscroll_y = overscroll_y
+        self.scroll_speed = scroll_speed
+        self.invert_scroll = invert_scroll
+        self._hovering = False
+
+        if canvas_size is not None:
+            warnings.warn(
+                "canvas_size is deprecated, the canvas is sized automatically to fit all children",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        else:
+            canvas_size = (max(int(width), 1), max(int(height), 1))
+
+        # The canvas has to match the window's pixel ratio,
+        # otherwise content renders at reduced resolution on hi-DPI displays.
+        self.surface = Surface(
+            size=canvas_size,
+            pixel_ratio=arcade.get_window().get_pixel_ratio(),
+        )
+
         super().__init__(
             x=x,
             y=y,
@@ -225,14 +274,6 @@ def __init__(
             size_hint_max=size_hint_max,
             **kwargs,
         )
-        self.default_anchor_x = "left"
-        self.default_anchor_y = "bottom"
-        self.overscroll_x = overscroll_x
-        self.overscroll_y = overscroll_y
-
-        self.surface = Surface(
-            size=canvas_size,
-        )
 
         bind(self, "scroll_x", UIScrollArea.trigger_full_render)
         bind(self, "scroll_y", UIScrollArea.trigger_full_render)
@@ -285,16 +326,20 @@ def do_layout(self):
             if new_rect != child.rect:
                 child.rect = new_rect
 
-        total_min_x = round(total_min_x)
-        total_min_y = round(total_min_y)
+        # the canvas covers at least the visible area, so children which do not
+        # fill the scroll area never leave the viewport partially uncovered
+        # and scroll ranges never become negative
+        total_min_x = max(round(total_min_x), round(self.content_width), 1)
+        total_min_y = max(round(total_min_y), round(self.content_height), 1)
 
         # resize surface to fit all children
         if self.surface.size != (total_min_x, total_min_y):
             self.surface.resize(
                 size=(total_min_x, total_min_y), pixel_ratio=self.surface.pixel_ratio
             )
-            self.scroll_x = 0
-            self.scroll_y = 0
+            # preserve the scroll position when content changes,
+            # only clamp it into the new scroll range
+            self._clamp_scroll()
 
     def _do_render(self, surface: Surface, force=False) -> bool:
         if not self.visible:
@@ -336,8 +381,58 @@ def _get_scroll_offset(self):
 
         return self.scroll_x, -normal_pos_y - self.scroll_y
 
+    def _clamp_scroll(self):
+        """Clamp the scroll position into the valid scroll range.
+
+        Axes with overscroll enabled are not clamped.
+        """
+        if not self.overscroll_x:
+            # clip scroll_x between 0 and -(self.surface.width - self.width)
+            scroll_range = int(self.content_width - self.surface.width)
+            scroll_range = min(0, scroll_range)  # clip to 0 if content is smaller than surface
+            self.scroll_x = max(scroll_range, min(0.0, self.scroll_x))
+
+        if not self.overscroll_y:
+            # clip scroll_y between 0 and -(self.surface.height - self.height)
+            scroll_range = int(self.content_height - self.surface.height)
+            scroll_range = min(0, scroll_range)  # clip to 0 if content is smaller than surface
+            self.scroll_y = max(scroll_range, min(0.0, self.scroll_y))
+
+    def _scroll_by_key(self, symbol: int) -> bool:
+        """Scroll on arrow keys, PageUp/PageDown, Home and End.
+
+        Returns True if the key was handled.
+        """
+        v_scrollable = self.surface.height > self.content_height
+        h_scrollable = self.surface.width > self.content_width
+
+        if symbol == arcade.key.UP and v_scrollable:
+            self.scroll_y += self.scroll_speed
+        elif symbol == arcade.key.DOWN and v_scrollable:
+            self.scroll_y -= self.scroll_speed
+        elif symbol == arcade.key.LEFT and h_scrollable:
+            self.scroll_x += self.scroll_speed
+        elif symbol == arcade.key.RIGHT and h_scrollable:
+            self.scroll_x -= self.scroll_speed
+        elif symbol == arcade.key.PAGEUP and v_scrollable:
+            self.scroll_y += self.content_height
+        elif symbol == arcade.key.PAGEDOWN and v_scrollable:
+            self.scroll_y -= self.content_height
+        elif symbol == arcade.key.HOME and v_scrollable:
+            self.scroll_y = 0.0
+        elif symbol == arcade.key.END and v_scrollable:
+            self.scroll_y = float(min(0, int(self.content_height - self.surface.height)))
+        else:
+            return False
+
+        self._clamp_scroll()
+        return True
+
     def on_event(self, event: UIEvent) -> bool | None:
         """Handle scrolling of the widget."""
+        if isinstance(event, UIMouseMovementEvent):
+            self._hovering = self.rect.point_in_rect(event.pos)
+
         if isinstance(event, UIMouseDragEvent) and not self.rect.point_in_rect(event.pos):
             return EVENT_UNHANDLED
 
@@ -347,23 +442,13 @@ def on_event(self, event: UIEvent) -> bool | None:
             self.scroll_x -= -event.scroll_x * self.scroll_speed * invert
             self.scroll_y -= event.scroll_y * self.scroll_speed * invert
 
-            # clip scrolling to canvas size
-            if not self.overscroll_x:
-                # clip scroll_x between 0 and -(self.surface.width - self.width)
-                scroll_range = int(self.content_width - self.surface.width)
-                scroll_range = min(0, scroll_range)  # clip to 0 if content is smaller than surface
-                self.scroll_x = min(0, self.scroll_x)
-                self.scroll_x = max(self.scroll_x, scroll_range)
-
-            if not self.overscroll_y:
-                # clip scroll_y between 0 and -(self.surface.height - self.height)
-                scroll_range = int(self.content_height - self.surface.height)
-                scroll_range = min(0, scroll_range)  # clip to 0 if content is smaller than surface
-                self.scroll_y = min(0, self.scroll_y)
-                self.scroll_y = max(self.scroll_y, scroll_range)
-
+            self._clamp_scroll()
             return True
 
+        if isinstance(event, UIKeyPressEvent) and self._hovering:
+            if self._scroll_by_key(event.symbol):
+                return True
+
         child_event = event
         if isinstance(event, UIMouseEvent):
             if self.rect.point_in_rect(event.pos):

arcade/gui/surface.py

@@ -50,10 +50,17 @@ def __init__(
             *self.ctx.BLEND_DEFAULT,
             *self.ctx.BLEND_ADDITIVE,
         )
-        #: Blend mode for when we're drawing the surface
+        #: Blend mode for when we're drawing the surface.
+        #: Content rendered into the surface over transparent black ends up
+        #: with premultiplied color channels, so the composite has to use
+        #: premultiplied-alpha blending. Straight alpha would multiply the
+        #: color by alpha a second time (dark fringes on anti-aliased edges)
+        #: and erode the destination alpha under semi-transparent texels.
         self.blend_func_render = (
-            *self.ctx.BLEND_DEFAULT,
-            *self.ctx.BLEND_DEFAULT,
+            self.ctx.ONE,
+            self.ctx.ONE_MINUS_SRC_ALPHA,
+            self.ctx.ONE,
+            self.ctx.ONE_MINUS_SRC_ALPHA,
         )
 
         # 5 floats per vertex (pos 3f, tex 2f) with 4 vertices
@@ -249,7 +256,14 @@ def draw(
             self.texture.filter = self.ctx.LINEAR, self.ctx.LINEAR
 
         self.texture.use(0)
-        self._geometry.render(self._program)
+        # Blending must be enforced here: pyglet toggles GL_BLEND directly
+        # (e.g. text layouts disable it after drawing), bypassing arcade's
+        # context flag cache. ctx.enabled() always issues the real enable
+        # call, so it resyncs the driver state; without it the composite can
+        # silently run in replace mode and overwrite the destination with
+        # the surface's transparent texels.
+        with self.ctx.enabled(self.ctx.BLEND):
+            self._geometry.render(self._program)
 
         # Restore blend function
         self.ctx.blend_func = blend_func

arcade/gui/widgets/dropdown.py

@@ -42,11 +42,10 @@ def __init__(
         self._scroll_area = UIScrollArea(
             width=100,
             height=100,
-            canvas_size=(100, 100),
             size_hint=(1, 1),
+            scroll_speed=scroll_speed,
+            invert_scroll=invert_scroll,
         )
-        self._scroll_area.invert_scroll = invert_scroll
-        self._scroll_area.scroll_speed = scroll_speed
         self._scroll_area.add(self._options_layout)
 
         super().add(self._scroll_area)
@@ -294,8 +293,7 @@ def do_layout(self):
         overlay_w = self.width + scroll_bar_w
 
         overlay.rect = (
-            overlay.rect
-            .resize(overlay_w, visible_h)
+            overlay.rect.resize(overlay_w, visible_h)
             .align_top(self.bottom - 2)
             .align_left(self._default_button.left)
         )

tests/unit/gui/test_surface.py

@@ -1,5 +1,6 @@
 import pytest
 
+import arcade
 from arcade import LBWH, load_texture
 from arcade.gui import Surface, NinePatchTexture
 
@@ -36,3 +37,50 @@ def test_limit_surface(window):
 
     surface.limit(None)
     assert surface._cam.viewport == LBWH(0, 0, 100, 100)
+
+
+@pytest.mark.backendgl
+def test_draw_enforces_blending(window):
+    """Surface.draw() has to enforce GL blending.
+
+    pyglet toggles GL_BLEND directly (e.g. text layouts disable it after
+    drawing), bypassing arcade's context flag cache. Without a forced enable
+    the composite runs in replace mode: the surface's transparent texels
+    overwrite the destination, punching an alpha hole through the UI.
+    """
+    from pyglet.graphics.api import gl
+
+    parent = Surface(size=(50, 50))
+    child = Surface(size=(50, 50))  # stays fully transparent
+
+    with parent.activate():
+        parent.clear((255, 255, 255, 255))
+
+        # simulate pyglet disabling blending behind arcade's state cache
+        window.ctx.enable(window.ctx.BLEND)
+        gl.glDisable(gl.GL_BLEND)
+
+        child.draw()
+
+    center = parent.to_image().getpixel((25, 25))
+    assert center == (255, 255, 255, 255)
+
+
+def test_draw_composites_premultiplied(window):
+    """Content rendered into a surface over transparent black is
+    premultiplied; a straight-alpha composite would darken the content and
+    erode the destination alpha."""
+    parent = Surface(size=(50, 50))
+    child = Surface(size=(50, 50))
+
+    with child.activate():
+        # 50% red over transparent black -> premultiplied (128, 0, 0, 128)
+        arcade.draw_rect_filled(LBWH(0, 0, 50, 50), (255, 0, 0, 128))
+
+    with parent.activate():
+        parent.clear((255, 255, 255, 255))
+        child.draw()
+
+    r, g, b, a = parent.to_image().getpixel((25, 25))
+    # 50% red over opaque white keeps full alpha
+    assert (r, g, b, a) == pytest.approx((255, 127, 127, 255), abs=2)

tests/unit/gui/test_uilabel.py

@@ -162,6 +162,23 @@ def test_size_hint_min_adapts_to_smaller_font(window):
     assert label.size_hint_min[1] < shm_h
 
 
+def test_update_font_with_unchanged_font_does_not_trigger_render(window):
+    """The label resolves a font fallback tuple to a concrete loaded font.
+
+    Re-applying the same requested tuple (button styles do this on every
+    render) must not be reported as a change, otherwise every render
+    triggers a full render of the whole UI, which repeats itself every frame.
+    """
+    # first entry does not exist, so the label falls back to a later font
+    font_names = ("NonExistentFont", "arial", "calibri")
+    label = UILabel(text="Example", font_name=font_names, text_color=Color(255, 255, 255))
+    label._requires_render = False
+
+    label.update_font(font_name=font_names, font_size=12, font_color=Color(255, 255, 255))
+
+    assert label._requires_render is False
+
+
 def test_multiline_enabled_size_hint_min_adapts_to_new_text(window):
     """Tests multiline with auto size. It should adapt to new text.