GUI push for 3.0 (#2351)

- New FlatUI colors under arcade.uicolor
- Combined gui examples and proper documentation
- Rewrite box layout to address sizing issues, when a child provided size_hint_min
- GUI assets are now consistent in style and properly structured
- Apply feedback about UIGridLayout parameter names
- UIView provides add_widget method and a background property, which will be used for clearing screen
- UIFlatButton provides multiple default styles
- Consistent UITextureSlider parameter names, better default for height
- UIAnchorLayouts do not restrict a child size to its own size, to allow scrolling use cases
- UITextArea provides the option for pyglet attributed or html text formatting
- UIInputText emits a on_change event, when text changed
- Buttons default to Kenny font, when loaded

---------

Co-authored-by: Jaecktec <constantin@jaeck.eu.org>

Author: eruvanos

CHANGELOG.md

@@ -67,7 +67,14 @@ API in a way that is not compatible with how it was used in 2.6.
   * Removed `arcade.gui.widgets.UIPadding` this is now general available in `arcade.gui.widgets.UIWidget`
   * Removed `arcade.gui.widgets.UITexturePane` this is now general available in `arcade.gui.widgets.UIWidget`
   * Removed `arcade.gui.widgets.UIAnchorWidget` replaced by `arcade.gui.widgets.UIAnchorLayout`
-
+* Resources
+  * removed unsused resources from `resources/gui_basic_assets`
+    * `items/shield_gold.png`
+    * `items/sword_gold.png`
+    * `slider_thumb.png`
+    * `slider_track.png`
+    * `toggle/switch_green.png`
+    * `toggle/switch_red.png`
 ### Featured Updates
 
 * The texture atlas has been heavily reworked to be more efficient.
@@ -131,6 +138,10 @@ API in a way that is not compatible with how it was used in 2.6.
   * Update and add example code.
   * Iterable (providing direct children)
 
+* Updated widgets
+  * `arcade.gui.widgets.text.UIInputText` emits `on_change` event when new text input or set
+  * `arcade.gui.widgets.slider.UITextureSlider` texture names changed to fit general naming pattern
+
 * New widgets:
 
   * `arcade.gui.widgets.dropdown.UIDropdown`
@@ -152,6 +163,8 @@ API in a way that is not compatible with how it was used in 2.6.
   * `arcade.gui.UIAnchorLayout`
   * `arcade.gui.UIGridLayout` [PR1478](https://github.com/pythonarcade/arcade/pull/1478)
 
+* Added color consistent assets to `arcade.resources.gui_basic_assets`
+* Provide GUI friendly color constants in `arcade.uicolor`
 * Replace deprecated usage of `arcade.draw_text`
 
 ### Misc Changes

arcade/__init__.py

@@ -228,6 +228,7 @@ def configure_logging(level: int | None = None):
 # Module imports
 from arcade import color as color
 from arcade import csscolor as csscolor
+from arcade import uicolor as uicolor
 from arcade import camera as camera
 from arcade import key as key
 from arcade import resources as resources
@@ -387,6 +388,7 @@ def configure_logging(level: int | None = None):
     "rect",
     "color",
     "csscolor",
+    "uicolor",
     "key",
     "resources",
     "types",

arcade/examples/gui/0_basic_setup.py

@@ -0,0 +1,112 @@
+"""Demonstrates general setup.
+
+If arcade and Python are properly installed, you can run this example with:
+python -m arcade.examples.gui.0_basic_setup
+
+Content:
+- create a view manually creating UIManager and adding widgets
+- create a second view extending UIView and adding widgets
+
+"""
+
+import arcade
+from arcade.gui import (
+    UIManager,
+    UITextureButton,
+    UIAnchorLayout,
+)
+from arcade.types import Color
+
+# Preload textures, because they are mostly used multiple times, so they are not
+# loaded multiple times
+TEX_RED_BUTTON_NORMAL = arcade.load_texture(":resources:gui_basic_assets/button/red_normal.png")
+TEX_RED_BUTTON_HOVER = arcade.load_texture(":resources:gui_basic_assets/button/red_hover.png")
+TEX_RED_BUTTON_PRESS = arcade.load_texture(":resources:gui_basic_assets/button/red_press.png")
+
+
+class GreenView(arcade.View):
+    """Uses the arcade.View and shows how to integrate UIManager."""
+
+    def __init__(self):
+        super().__init__()
+
+        # Create a UIManager
+        self.ui = UIManager()
+
+        # Create a anchor layout, which can be used to position widgets on screen
+        anchor = self.ui.add(UIAnchorLayout())
+
+        # Add a button switch to the other View.
+        button = anchor.add(
+            UITextureButton(
+                text="Switch to blue view",
+                texture=TEX_RED_BUTTON_NORMAL,
+                texture_hovered=TEX_RED_BUTTON_HOVER,
+                texture_pressed=TEX_RED_BUTTON_PRESS,
+                on_click=lambda: self.window.show_view(self.window.views["other"]),
+            )
+        )
+
+        # add a button to switch to the blue view
+        @button.event("on_click")
+        def on_click(event):
+            self.window.show_view(BlueView())
+
+    def on_show_view(self) -> None:
+        self.ui.enable()
+
+    def on_hide_view(self) -> None:
+        self.ui.disable()
+
+    def on_draw(self):
+        # Clear the screen
+        self.clear(color=Color(46, 204, 113))
+
+        # Add draw commands that should be below the UI
+        # ...
+
+        self.ui.draw()
+
+        # Add draw commands that should be on top of the UI (uncommon)
+        # ...
+
+
+class BlueView(arcade.gui.UIView):
+    """Uses the arcade.gui.UIView which takes care about the UIManager setup."""
+
+    def __init__(self):
+        super().__init__()
+        self.background_color = Color(52, 152, 219)
+
+        # Create a anchor layout, which can be used to position widgets on screen
+        anchor = self.add_widget(UIAnchorLayout())
+
+        # Add a button switch to the other View.
+        button = anchor.add(
+            UITextureButton(
+                text="Switch to green view",
+                texture=TEX_RED_BUTTON_NORMAL,
+                texture_hovered=TEX_RED_BUTTON_HOVER,
+                texture_pressed=TEX_RED_BUTTON_PRESS,
+                on_click=lambda: self.window.show_view(self.window.views["my"]),
+            )
+        )
+
+        # add a button to switch to the green view
+        @button.event("on_click")
+        def on_click(event):
+            self.window.show_view(GreenView())
+
+    def on_draw_before_ui(self):
+        # Add draw commands that should be below the UI
+        pass
+
+    def on_draw_after_ui(self):
+        # Add draw commands that should be on top of the UI (uncommon)
+        pass
+
+
+if __name__ == "__main__":
+    window = arcade.Window(title="GUI Example: Basic Setup")
+    window.show_view(GreenView())
+    window.run()

arcade/examples/gui/1_layouts.py

@@ -0,0 +1,157 @@
+"""Demonstrates the use of layouts.
+
+If arcade and Python are properly installed, you can run this example with:
+python -m arcade.examples.gui.1_layouts
+
+Content:
+- Create a view with a description of layouts
+- Use UIAnchorLayout to position widgets relative to the screen edges
+- Use UIBoxLayout to position widgets in a horizontal or vertical line
+- Use UIGridLayout to position widgets in a grid
+
+"""
+
+from datetime import datetime
+
+import arcade
+from arcade.gui import UIAnchorLayout
+from arcade.types import Color
+
+arcade.resources.load_system_fonts()
+
+DESCRIPTION = """How to place widgets on the screen?
+
+Widgets can be manually placed on the screen by using the `add` method of the UIManager
+and setting the rect of a widget. This is useful for simple ui setups.
+
+This approach requires to manually calculate the position of the
+widgets and handling screen resizes.
+
+Another approach is to use layouts. Layouts are containers that automatically
+position widgets based on the layout rules. This example shows how to use
+the UIAnchorLayout, UIBoxLayout, and UIGridLayout.
+
+UIAnchorLayout:
+- UIAnchorLayout is a layout that positions widgets relative to the screen edges.
+- Widgets can be anchored to the top, bottom, left, right, center, or any combination of these.
+- Widgets can be aligned to the anchor position with a pixel offset.
+
+UIBoxLayout:
+- UIBoxLayout is a layout that positions widgets in a horizontal or vertical line.
+- Widgets can be aligned on the orthogonal axis.
+- Widgets can have a space between them.
+
+UIGridLayout:
+- UIGridLayout is a layout that positions widgets in a grid.
+- Widgets can be placed in rows and columns.
+- Widgets can have a vertical and horizontal spacing.
+
+The layouts calculate the size of the widgets based on the size_hint,
+size_hint_min, and size_hint_max.
+
+- size_hint: A tuple of two floats that represent the relative size of the widget.
+- size_hint_min: A tuple of two floats that represent the minimum size of the widget.
+- size_hint_max: A tuple of two floats that represent the maximum size of the widget.
+
+Layouts only resize widgets if the size_hint is set for the resprecitve axis.
+If the size_hint is not set, the widget will use its current size.
+
+Some widgets calculate their minimum size based on their content like UILabel
+and layouts in general.
+"""
+
+
+class LayoutView(arcade.gui.UIView):
+    """This view demonstrates the use of layouts."""
+
+    def __init__(self):
+        super().__init__()
+        self.background_color = Color(52, 152, 219)
+
+        # Create a anchor layout, which can be used to position widgets on screen
+        self.anchor = self.add_widget(UIAnchorLayout())
+
+        # Add describing text in center
+        text_area = arcade.gui.UITextArea(
+            text=DESCRIPTION,
+            text_color=Color(236, 240, 241),
+            font_name=("Lato", "proxima-nova", "Helvetica Neue", "Arial", "sans-serif"),
+            font_size=12,
+            size_hint=(0.5, 0.8),
+        )
+        self.anchor.add(text_area, anchor_x="center_x", anchor_y="center_y")
+        text_area.with_border(color=Color(149, 165, 166))
+        text_area.with_background(color=Color(149, 165, 166, 125))
+        text_area.with_padding(left=5)
+
+        # add a grid layout with the window and grid size and grid position
+        self.grid = arcade.gui.UIGridLayout(
+            column_count=2,
+            row_count=2,
+            align_horizontal="left",
+        )
+        self.grid.with_background(color=Color(149, 165, 166))
+        self.grid.with_border(color=Color(127, 140, 141))
+        self.grid.with_padding(all=10)
+        self.anchor.add(self.grid, anchor_x="left", anchor_y="top", align_x=10, align_y=-10)
+        self.grid.add(
+            arcade.gui.UILabel(text="Arcade: "),
+            row=0,
+            column=0,
+        )
+        self.grid.add(
+            arcade.gui.UILabel(text=arcade.VERSION),
+            row=0,
+            column=1,
+        )
+        self.grid.add(
+            arcade.gui.UILabel(text="Today: "),
+            row=1,
+            column=0,
+        )
+        self.grid.add(
+            arcade.gui.UILabel(text=datetime.utcnow().isoformat()[:10]),
+            row=1,
+            column=1,
+        )
+
+        # add a horizontal boxlayout with buttons
+        h_box = arcade.gui.UIBoxLayout(space_between=20, vertical=False)
+        self.anchor.add(h_box, anchor_x="center_x", anchor_y="bottom", align_y=5)
+
+        # Add a button to move the grid layout to top_right
+        # top left
+        move_left_button = arcade.gui.UIFlatButton(text="Top Left", width=150)
+        move_left_button.disabled = True
+        h_box.add(move_left_button)
+
+        @move_left_button.event("on_click")
+        def _(event):
+            self.anchor.remove(self.grid)
+            self.anchor.add(self.grid, anchor_x="left", anchor_y="top", align_x=10, align_y=-10)
+            move_left_button.disabled = True
+            move_right_button.disabled = False
+
+        move_right_button = arcade.gui.UIFlatButton(text="Top Right", width=150)
+        h_box.add(move_right_button)
+
+        @move_right_button.event("on_click")
+        def _(event):
+            self.anchor.remove(self.grid)
+            self.anchor.add(self.grid, anchor_x="right", anchor_y="top", align_x=-10, align_y=-10)
+            move_right_button.disabled = True
+            move_left_button.disabled = False
+
+    def on_draw_before_ui(self):
+        # Add draw commands that should be below the UI
+        pass
+
+    def on_draw_after_ui(self):
+        # Add draw commands that should be on top of the UI (uncommon)
+        pass
+
+
+if __name__ == "__main__":
+    window = arcade.Window(title="GUI Example: Layouts")
+    window.show_view(LayoutView())
+    window.run()