docs(gui): convert to google doc and little cleanup (#2305)

* docs(gui): convert to google doc and little cleanup

* docs(gui): next round, document all the things

* docs(gui): fix format

* docs(gui): fix more format

* docs(gui): fix more format

* docs(gui): fix more format

* docs(gui): fix more format, clean up color refs

* docs(gui): re-add attr in UITextEvents

* Fix phrasing in UIEvent docstring

* Update docstrings for base class events

* Remove extra whitespace line

* Add missing Args for property.bind

* Add missing Args for unbind

* Use code-block and make a phrasing tweak to module-level bind function

* Spacing?

* Use code-block: python in odule-level unbind

* Spacing in DictProperty top-level docstring

* Spacing in ListProperty top-level docstring

* Fix whitespace in surface.activate docstring

* Rephrase for Surface's top-level docstring

* Clean up and annotate Surface.activate

* Formatting fix

---------

Co-authored-by: pushfoo <36696816+pushfoo@users.noreply.github.com>

Author: eruvanos

arcade/gui/constructs.py

@@ -1,6 +1,4 @@
-"""
-Constructs, are prepared widget combinations, you can use for common use-cases
-"""
+"""Constructs, are prepared widget combinations, you can use for common use-cases"""
 
 from __future__ import annotations
 
@@ -16,8 +14,7 @@
 
 
 class UIMessageBox(UIMouseFilterMixin, UIAnchorLayout):
-    """
-    A simple dialog box that pops up a message with buttons to close.
+    """A simple dialog box that pops up a message with buttons to close.
     Subclass this class or overwrite the 'on_action' event handler with
 
     .. code-block:: python
@@ -27,11 +24,12 @@ class UIMessageBox(UIMouseFilterMixin, UIAnchorLayout):
         def on_action(event: UIOnActionEvent):
             pass
 
+    Args:
+      width: Width of the message box
+      height: Height of the message box
+      message_text: Text to show as message to the user
+      buttons: List of strings, which are shown as buttons
 
-    :param width: Width of the message box
-    :param height: Height of the message box
-    :param message_text: Text to show as message to the user
-    :param buttons: List of strings, which are shown as buttons
     """
 
     def __init__(
@@ -100,19 +98,20 @@ def on_action(self, event: UIOnActionEvent):
 
 
 class UIButtonRow(UIBoxLayout):
-    """
-    Places buttons in a row.
-
-    :param vertical: Whether the button row is vertical or not.
-    :param align: Where to align the button row.
-    :param size_hint: Tuple of floats (0.0 - 1.0) of how much space of the parent
-        should be requested.
-    :param size_hint_min: Min width and height in pixel.
-    :param size_hint_max: Max width and height in pixel.
-    :param space_between: The space between the children.
-    :param style: Not used.
-    :param Tuple[str, ...] button_labels: The labels for the buttons.
-    :param callback: The callback function which will receive the text of the clicked button.
+    """Places buttons in a row.
+
+    Args:
+        vertical: Whether the button row is vertical or not.
+        align: Where to align the button row.
+        size_hint: Tuple of floats (0.0 - 1.0) of how much space of the
+            parent should be requested.
+        size_hint_min: Min width and height in pixel.
+        size_hint_max: Max width and height in pixel.
+        space_between: The space between the children.
+        callback: The callback function which will receive the text of
+            the clicked button.
+        button_factory: The factory to create the buttons. Default is py:class:`UIFlatButton`.
+        **kwargs: Passed to UIBoxLayout
     """
 
     def __init__(
@@ -124,8 +123,8 @@ def __init__(
         size_hint_min: Optional[Any] = None,
         size_hint_max: Optional[Any] = None,
         space_between: int = 10,
-        style: Optional[Any] = None,
         button_factory: type = UIFlatButton,
+        **kwargs,
     ):
         super().__init__(
             vertical=vertical,
@@ -134,7 +133,7 @@ def __init__(
             size_hint_min=size_hint_min,
             size_hint_max=size_hint_max,
             space_between=space_between,
-            style=style,
+            **kwargs,
         )
         self.register_event_type("on_action")  # type: ignore  # https://github.com/pyglet/pyglet/pull/1173  # noqa
 
@@ -147,12 +146,20 @@ def add_button(
         style=None,
         multiline=False,
     ):
+        """Add a button to the row.
+
+        Args:
+            label: The text of the button.
+            style: The style of the button.
+            multiline: Whether the button is multiline or not.
+        """
         button = self.button_factory(text=label, style=style, multiline=multiline)
         button.on_click = self._on_click  # type: ignore
         self.add(button)
         return button
 
     def on_action(self, event: UIOnActionEvent):
+        """Called when button was pressed, override this method to handle button presses."""
         pass
 
     def _on_click(self, event: UIOnClickEvent):

arcade/gui/events.py

@@ -3,51 +3,84 @@
 from dataclasses import dataclass
 from typing import Any
 
+from pyglet.math import Vec2
+
 
 @dataclass
 class UIEvent:
-    """
-    An event created by the GUI system. Can be passed using widget.dispatch("on_event", event).
-    An event always has a source, which is the UIManager for general input events,
-    but will be the specific widget in case of events like on_click events.
+    """An event created by the GUI system.
+
+    Can be passed as follows:
+
+    .. code-block:: python
+
+       widget.dispatch("on_event", event)
+
+    An event always has a source. This is the UIManager for general input
+    events, but will be the specific widget in case of events like click
+    events.
+
+    Args:
+        source: The source of the event.
     """
 
     source: Any
 
 
 @dataclass
 class UIMouseEvent(UIEvent):
-    """
-    Covers all mouse event
+    """Base class for all UI mouse events.
+
+    Args:
+        x: The x coordinate of the mouse.
+        y: The y coordinate of the mouse.
     """
 
     x: int
     y: int
 
     @property
-    def pos(self):
-        return self.x, self.y
+    def pos(self) -> Vec2:
+        """Return the position as tuple (x, y)"""
+        return Vec2(self.x, self.y)
 
 
 @dataclass
 class UIMouseMovementEvent(UIMouseEvent):
-    """Triggered when the mouse is moved."""
+    """Triggered when the mouse is moved.
+
+    Args:
+        dx: The change in x coordinate.
+        dy: The change in y coordinate.
+    """
 
     dx: int
     dy: int
 
 
 @dataclass
 class UIMousePressEvent(UIMouseEvent):
-    """Triggered when a mouse button(left, right, middle) is pressed."""
+    """Triggered when a mouse button(left, right, middle) is pressed.
+
+    Args:
+        button: The button pressed.
+        modifiers: The modifiers pressed.
+    """
 
     button: int
     modifiers: int
 
 
 @dataclass
 class UIMouseDragEvent(UIMouseEvent):
-    """Triggered when the mouse moves while one of its buttons being pressed."""
+    """Triggered when the mouse moves while one of its buttons being pressed.
+
+    Args:
+        dx: The change in x coordinate.
+        dy: The change in y coordinate.
+        buttons: The buttons pressed.
+        modifiers: The modifiers pressed.
+    """
 
     dx: int
     dy: int
@@ -57,23 +90,38 @@ class UIMouseDragEvent(UIMouseEvent):
 
 @dataclass
 class UIMouseReleaseEvent(UIMouseEvent):
-    """Triggered when a mouse button is released."""
+    """Triggered when a mouse button is released.
+
+    Args:
+        button: The button released.
+        modifiers: The modifiers pressed
+    """
 
     button: int
     modifiers: int
 
 
 @dataclass
 class UIMouseScrollEvent(UIMouseEvent):
-    """Triggered by rotating the scroll wheel on the mouse."""
+    """Triggered by rotating the scroll wheel on the mouse.
+
+    Args:
+        scroll_x: The horizontal scroll amount.
+        scroll_y: The vertical scroll
+    """
 
     scroll_x: int
     scroll_y: int
 
 
 @dataclass
 class UIKeyEvent(UIEvent):
-    """Covers all keyboard event."""
+    """Base class for all keyboard-centric UI events.
+
+    Args:
+        symbol: The key pressed.
+        modifiers: The modifiers pressed.
+    """
 
     symbol: int
     modifiers: int
@@ -114,46 +162,67 @@ class UITextInputEvent(UITextEvent):
     * a platform-specific input method, such as pen input on a tablet PC
 
     To learn more, see pyglet's `relevant documentation <https://pyglet.readthedocs.io/en/development/modules/window.html#pyglet.window.Window.on_text>`_.
+
+    Args:
+        text: The text inputted. Often a single character.
     """
 
     text: str
 
 
 @dataclass
 class UITextMotionEvent(UITextEvent):
-    """Triggered when text cursor moves."""
+    """Triggered when text cursor moves.
+
+    Args:
+        motion: The motion of the cursor
+    """
 
     motion: Any
 
 
 @dataclass
 class UITextMotionSelectEvent(UITextEvent):
-    """Triggered when the text cursor moves selecting the text with it."""
+    """Triggered when the text cursor moves selecting the text with it.
+
+    Args:
+        selection: The selection of the cursor
+    """
 
     selection: Any
 
 
 @dataclass
 class UIOnClickEvent(UIMouseEvent):
-    """Triggered when a widget is clicked."""
+    """Triggered when a widget is clicked.
+
+    Args:
+        button: The button clicked.
+        modifiers: The modifiers pressed.
+    """
 
     button: int
     modifiers: int
 
 
 @dataclass
 class UIOnUpdateEvent(UIEvent):
-    """
-    Arcade on_update callback passed as :class:`UIEvent`
+    """Arcade on_update callback passed as :class:`UIEvent`.
+
+    Args:
+        dt: Time since last update
     """
 
     dt: int
 
 
 @dataclass
 class UIOnChangeEvent(UIEvent):
-    """
-    Value of a widget changed
+    """Value of a widget changed.
+
+    Args:
+        old_value: The old value.
+        new_value: The new value.
     """
 
     old_value: Any
@@ -162,10 +231,10 @@ class UIOnChangeEvent(UIEvent):
 
 @dataclass
 class UIOnActionEvent(UIEvent):
-    """
-    Notification about an action
+    """Notification about an action.
 
-    :param action: Value describing the action, mostly a string
+    Args:
+        action: Value describing the action, mostly a string
     """
 
     action: Any

arcade/gui/examples/__init__.py

@@ -1,5 +1,4 @@
-"""
-This package contains GUI specific examples.
+"""This package contains GUI specific examples.
 
 These show explicit GUI examples, and are not part of the main examples.
 

arcade/gui/examples/anchor_layout.py

@@ -1,5 +1,4 @@
-"""
-Positioning UI elements with UIAnchorLayout
+"""Positioning UI elements with UIAnchorLayout
 
 UIAnchorLayout aligns widgets added to it to directional anchors, which
 include  "left", "center_x", or "top". Dummy widgets react to click events

arcade/gui/examples/box_layout.py

@@ -1,5 +1,4 @@
-"""
-Arrange widgets in vertical or horizontal lines with UIBoxLayout
+"""Arrange widgets in vertical or horizontal lines with UIBoxLayout
 
 The direction UIBoxLayout follows is controlled by the `vertical` keyword
 argument. It is True by default. Pass False to it to arrange elements in

arcade/gui/examples/button_with_text.py

@@ -1,5 +1,4 @@
-"""
-Customizing buttons with text & textures.
+"""Customizing buttons with text & textures.
 
 This example showcases arcade's range of different built-in button types
 and how they can be used to customize a UI. A UIGridLayout is used to

arcade/gui/examples/dropdown.py

@@ -1,5 +1,4 @@
-"""
-Creating a dropdown menu with UIDropDown
+"""Creating a dropdown menu with UIDropDown
 
 When an option in the UIDropDown is chosen, this example will respond
 by changing the text displayed on screen to reflect it.
@@ -30,7 +29,7 @@ def __init__(self):
         self.dropdown.center_on_screen()
         self.ui.add(self.dropdown)
 
-        self.label = self.ui.add(UILabel(text=" ", text_color=(0, 0, 0)))
+        self.label = self.ui.add(UILabel(text=" ", text_color=arcade.color.BLACK))
 
         @self.dropdown.event()
         def on_change(event: UIOnChangeEvent):

arcade/gui/examples/exp_hidden_password.py

@@ -1,5 +1,4 @@
-"""
-Creating a hidden password field
+"""Creating a hidden password field
 
 This example demonstrates how to create a custom text input
 which hides the contents behind a custom character, as often

arcade/gui/examples/exp_scroll_area.py

@@ -1,5 +1,4 @@
-"""
-This example is a proof-of-concept for a UIScrollArea.
+"""This example is a proof-of-concept for a UIScrollArea.
 
 You can currently scroll through the UIScrollArea in the following ways: