UI: Add Transitions to arcade GUI [after 3.0 release]

CHANGELOG.md

@@ -10,12 +10,19 @@ Arcade [PyPi Release History](https://pypi.org/project/arcade/#history) page.
   - Supports `hovered`, `pressed`, and `disabled` states with `on_click` event dispatch.
   - Widget size defaults to the sprite's texture dimensions, overridable with explicit `width`/`height`.
 - Added `TextPool` - provides a mechanism for caching Text objects for re-use
+- GUI: Added an experimental animation API in `arcade.gui.experimental` — `UIAnimatedGroup` wraps a widget subtree and tweens its transform properties over time via `animate()`.
+  - `UIAnimatedGroup` caches its subtree into a surface and exposes non-layouting transform properties (`scale`, `angle`, `alpha`, `offset_x`, `offset_y`, `tint`); it is interactive, hit-testing `hovered`/`pressed`/`on_click` against its untransformed rect. `UIRenderGroup` is the non-interactive caching primitive.
+  - `animate()` supports multiple properties per call, sequencing via `then()`, repetition (`repeat`, `yoyo`), relative targets (`rel()`), easing, delays and `on_finish` callbacks.
+  - Animations are resolved per property: starting a new animation takes over its properties from running ones, other properties keep animating.
+  - Interpolates numbers, tuples, `Color` and vector types; non-interpolatable values snap at the end.
+  - The low level `Transition*` classes remain available for custom behavior.
 
 ### Fixes
 
 - 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/draw/rect.py

@@ -48,6 +48,7 @@ def draw_texture_rect(
     # Clamp alpha to 0-255
     alpha_normalized = max(0, min(255, alpha)) / 255.0
 
+    blend_state = ctx.is_enabled(ctx.BLEND)
     if blend:
         ctx.enable(ctx.BLEND)
     else:
@@ -76,7 +77,9 @@ def draw_texture_rect(
 
     geometry.render(program, mode=gl.TRIANGLE_STRIP, vertices=4)
 
-    if blend:
+    if blend_state:
+        ctx.enable(ctx.BLEND)
+    else:
         ctx.disable(ctx.BLEND)
 
 
@@ -387,17 +390,15 @@ def draw_rect_filled(rect: Rect, color: RGBOrA255, tilt_angle: float = 0) -> Non
     # Validate & normalize to a pass the shader an RGBA float uniform
     color_normalized = Color.from_iterable(color).normalized
 
-    ctx.enable(ctx.BLEND)
-
-    # Pass data to the shader
-    program["color"] = color_normalized
-    program["shape"] = rect.width, rect.height, tilt_angle
-    buffer.orphan()
-    buffer.write(data=array.array("f", (rect.x, rect.y)))
-
-    geometry.render(program, instances=1)
+    # contextmanager will restore state which existed before
+    with ctx.enabled(ctx.BLEND):
+        # Pass data to the shader
+        program["color"] = color_normalized
+        program["shape"] = rect.width, rect.height, tilt_angle
+        buffer.orphan()
+        buffer.write(data=array.array("f", (rect.x, rect.y)))
 
-    ctx.disable(ctx.BLEND)
+        geometry.render(program, instances=1)
 
 
 # These might be "oddly specific" and also needs docstrings. Disabling or 3.0.0

arcade/examples/gui/exp_animations.py

@@ -0,0 +1,260 @@
+"""A game main menu with animated widgets.
+
+This example combines two new GUI features:
+
+- :class:`UIAnimatedGroup` renders a widget subtree into a cached surface,
+  which can be drawn with rotation, scaling, fading and tinting.
+  The wrapped widgets are only re-rendered when they actually change,
+  animating the group itself is basically free.
+- Animations (:meth:`UIAnimatedGroup.animate`) tween properties over time and
+  support sequencing (``then()``), repetition (``repeat``, ``yoyo``) and
+  relative targets (``rel()``). Starting a new animation takes over its
+  properties from running ones, so state changes like hover just start
+  a new animation.
+
+The menu shows:
+
+- the whole menu popping in when the view is shown, and fading out on "Quit"
+- a gently pulsing and swaying title
+- buttons popping in staggered, popping and wiggling when hovered
+- decorative spinning letter tiles
+- a spinning "Play" button when clicked
+
+If Arcade and Python are properly installed, you can run this example with:
+python -m arcade.examples.gui.exp_animations
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+import arcade
+import pyglet
+from arcade import uicolor
+from arcade.anim import Easing
+from arcade.gui import (
+    UIAnchorLayout,
+    UIBoxLayout,
+    UIFlatButton,
+    UILabel,
+    UIView,
+    UIWidget,
+    bind,
+)
+from arcade.gui.experimental import Animation, UIAnimatedGroup, rel
+from arcade.types import Color
+
+BACKGROUND = Color(110, 148, 132)
+TILE_COLORS = [
+    uicolor.GREEN_GREEN_SEA,
+    uicolor.RED_ALIZARIN,
+    uicolor.YELLOW_SUN_FLOWER,
+    uicolor.DARK_BLUE_WET_ASPHALT,
+]
+
+IdleFactory = Callable[["AnimatedWidget"], Animation]
+"""Starts an idle animation on a group and returns it, so it can be stopped."""
+
+
+def pulse(scale=1.05, period=1.2) -> IdleFactory:
+    """Idle animation: gently pulsing scale."""
+
+    def start(group: AnimatedWidget) -> Animation:
+        return group.animate(
+            scale=scale, duration=period / 2, ease=Easing.SINE, repeat=True, yoyo=True
+        )
+
+    return start
+
+
+def sway(angle=2.0, period=2.4) -> IdleFactory:
+    """Idle animation: swaying 0 -> angle -> -angle -> 0, forever."""
+
+    def start(group: AnimatedWidget) -> Animation:
+        return (
+            group.animate(angle=angle, duration=period / 4, ease=Easing.SINE, repeat=True)
+            .then(angle=-angle, duration=period / 2, ease=Easing.SINE)
+            .then(angle=0.0, duration=period / 4, ease=Easing.SINE)
+        )
+
+    return start
+
+
+def spin(period=8.0) -> IdleFactory:
+    """Idle animation: endless clockwise rotation."""
+
+    def start(group: AnimatedWidget) -> Animation:
+        return group.animate(angle=rel(-360), duration=period, repeat=True)
+
+    return start
+
+
+class AnimatedWidget(UIAnimatedGroup):
+    """A UIAnimatedGroup with little animation helpers.
+
+    Args:
+        child: The wrapped widget.
+        idle: Optional idle animation factory (or list of factories),
+            started after entrance and hover animations finish.
+    """
+
+    def __init__(
+        self,
+        *,
+        child: UIWidget,
+        idle: IdleFactory | list[IdleFactory] | None = None,
+    ):
+        super().__init__(child=child)
+        self._idle_factories = [idle] if callable(idle) else list(idle or [])
+        self._idle_animations: list[Animation] = []
+
+    def start_idle(self):
+        """(Re-)start the idle animations, unless the group is hovered."""
+        if self.hovered:
+            return
+        self.stop_idle()
+        self._idle_animations = [factory(self) for factory in self._idle_factories]
+
+    def stop_idle(self):
+        for animation in self._idle_animations:
+            animation.stop()
+        self._idle_animations = []
+
+    def pop_in(self, delay: float = 0.0):
+        """Scale and fade in, then continue with the idle animation."""
+        self.scale = 0.0
+        self.alpha = 0
+        self.animate(scale=1.0, duration=0.5, delay=delay, ease=Easing.BACK_OUT).on_finish(
+            self.start_idle
+        )
+        self.animate(alpha=255, duration=0.35, delay=delay)
+
+    def pop_on_hover(self, scale: float = 1.08, angle: float = 2.5):
+        """Pop and wiggle while the group is hovered."""
+
+        def on_hover_change():
+            if self.hovered:
+                self.stop_idle()
+                self.animate(scale=scale, duration=0.15, ease=Easing.BACK_OUT)
+                self.animate(angle=angle, duration=0.06).then(angle=-angle, duration=0.12).then(
+                    angle=0.0, duration=0.06
+                )
+                # in case an interrupted entrance left the group transparent
+                self.animate(alpha=255, duration=0.1)
+            else:
+                self.animate(scale=1.0, angle=0.0, duration=0.15).on_finish(self.start_idle)
+
+        bind(self, "hovered", on_hover_change)
+
+
+class MainMenuView(UIView):
+    def __init__(self):
+        super().__init__()
+        # self.ui._pixelated = True
+
+        self.background_color = BACKGROUND
+
+        root = UIAnchorLayout(size_hint=(1, 1))
+
+        # title, gently pulsing and swaying
+        title = UILabel(
+            "New GUI\nAnimations",
+            font_size=72,
+            bold=True,
+            multiline=True,
+            align="center",
+            text_color=uicolor.DARK_BLUE_MIDNIGHT_BLUE,
+        )
+        self.title = AnimatedWidget(child=title, idle=[pulse(1.04, 2.4), sway(2, 2.4)])
+        root.add(self.title, anchor_x="center", anchor_y="top", align_y=-60)
+
+        # main menu buttons, the resume button pulses to attract attention
+        resume = AnimatedWidget(
+            child=UIFlatButton(text="Resume", width=240, height=50),
+            idle=pulse(1.05, 1.2),
+        )
+        play = AnimatedWidget(child=UIFlatButton(text="Play", width=240, height=50))
+        quit_ = AnimatedWidget(
+            child=UIFlatButton(text="Quit", width=240, height=50, style=UIFlatButton.STYLE_RED)
+        )
+        self.menu_buttons = [resume, play, quit_]
+
+        menu = UIBoxLayout(space_between=12)
+        for group in self.menu_buttons:
+            group.pop_on_hover()
+            menu.add(group)
+        root.add(menu, anchor_x="center", anchor_y="center", align_y=-40)
+
+        # side menu buttons
+        self.side_buttons = []
+        side = UIBoxLayout(space_between=8)
+        for text in ("Leaderboard", "Librarium", "Settings", "Credits"):
+            group = AnimatedWidget(child=UIFlatButton(text=text, width=180, height=36))
+            group.pop_on_hover(scale=1.1)
+            self.side_buttons.append(group)
+            side.add(group)
+        root.add(side, anchor_x="left", anchor_y="bottom", align_x=40, align_y=40)
+
+        # decorative letter tiles, slowly spinning or swaying
+        self.tiles = []
+        for letter, color, anchor, align, idle in [
+            ("N", TILE_COLORS[0], ("left", "top"), (140, -90), spin(9)),
+            ("E", TILE_COLORS[1], ("left", "center"), (230, 30), sway(14, 4)),
+            ("V", TILE_COLORS[2], ("right", "top"), (-380, -10), sway(-10, 5)),
+            ("B", TILE_COLORS[3], ("right", "bottom"), (-200, 20), spin(12)),
+        ]:
+            label = UILabel(letter, font_size=26, bold=True, text_color=uicolor.WHITE_CLOUDS)
+            tile = (
+                label.with_padding(all=12)
+                .with_background(color=color)
+                .with_border(width=3, color=uicolor.DARK_BLUE_MIDNIGHT_BLUE)
+            )
+            group = AnimatedWidget(child=tile, idle=idle)
+            self.tiles.append(group)
+            root.add(
+                group, anchor_x=anchor[0], anchor_y=anchor[1], align_x=align[0], align_y=align[1]
+            )
+
+        # the whole menu is wrapped in another group, to fade it out on quit
+        self.root_group = AnimatedWidget(child=root)
+        self.add_widget(self.root_group)
+
+        play.child.on_click = self.on_play
+        quit_.child.on_click = self.on_quit
+        self._play_group = play
+
+    def on_show_view(self):
+        super().on_show_view()
+
+        # staggered entrance animation
+        self.title.pop_in(delay=0.1)
+        for i, group in enumerate(self.menu_buttons):
+            group.pop_in(delay=0.3 + i * 0.1)
+        for i, group in enumerate(self.side_buttons):
+            group.pop_in(delay=0.6 + i * 0.08)
+        for i, group in enumerate(self.tiles):
+            group.pop_in(delay=0.9 + i * 0.1)
+
+    def on_play(self, event):
+        """Spin the play button once."""
+        self._play_group.animate(angle=rel(-360), duration=0.6, ease=Easing.CUBIC)
+
+    def on_quit(self, event):
+        """Scale and fade out the whole menu, then close the window."""
+        group = self.root_group
+        group.animate(alpha=0, duration=0.5, ease=Easing.SINE_IN)
+        group.animate(scale=0.8, duration=0.5, ease=Easing.SINE_IN).then(duration=0.1).on_finish(
+            arcade.exit
+        )
+
+
+def main():
+    window = arcade.Window(1280, 720, "GUI Example: Animated Main Menu", resizable=True)
+    window.show_view(MainMenuView())
+    arcade.run()
+
+
+if __name__ == "__main__":
+    pyglet.options.text_antialiasing = False
+
+    main()