PlayPy 0.2.1__py3-none-any.whl

playpy/__init__.py

@@ -0,0 +1,222 @@
+from .resources import * 
+from .state import *
+from .elements import * 
+from .workspace import *
+from .builtin import *
+
+__doc__ = r'''
+# PlayPy
+
+PlayPy is a lightweight Python library for creating simple games and interactive applications with ease. It provides a straightforward API for handling graphics, input, and basic game mechanics, making it ideal for beginners and those looking to quickly prototype their ideas.
+
+## Requirements
+
+- Python `>=3.11`
+- `pygame(-ce) >=2.6.1`
+
+## Installation
+
+To install PlayPy, enter the following line into your terminal: `pip install playpy`, or `python -m pip install playpy` if the first line does not work.
+
+## Core Concepts
+
+### Workspace
+
+`Workspace` owns the window, render loop, input state, scene stack, and modal stack.
+
+Key methods:
+
+- `run()` starts runtime loop
+- `quit()` stops runtime loop
+- `queue_scene_change(scene)` replaces the current scene
+- `queue_scene_push(scene)` / `queue_scene_pop()` stacks scenes
+- `queue_modal_push(element)` / `queue_modal_pop()` manages overlays
+
+### Layout Values
+
+PlayPy uses two rectangle value types:
+
+- `FRect(*args)`
+  Relative scale (fraction of parent rectangle).
+- `Rect(*args)`
+  Absolute pixel offsets applied on top of scale.
+- Overloads are: `x, y, w, h` \ `topleft, size` \ `(x, y, w, h)` \ `(topleft, size)`
+
+Final element rect = `scale * parent_size + offset`.
+
+### Parenting
+
+Any `UIElement` can contain children. Assigning parent wires it automatically:
+
+```python
+child.parent = parent
+```
+
+Or use helpers:
+
+```python
+parent.add_child(child)
+```
+
+You can use the `parent`, `ancestors`, `children`, and `descendants` properties to find ancestors or descendants of an element.
+
+You can use other built-in methods to tell descendance:
+- `is_parent_of(child)`, `is_child_of(parent)`
+- `is_ancestor_of(descendant)`, `is_descendant_of(ancestor)`
+
+## Built-in Elements
+
+- `UIPanel`: colored rectangle container
+- `UIScrollablePanel`: panel with wheel scrolling
+- `UIText`: wrapped text rendering with alignment
+- `UIButton`: clickable button with hover/pressed colors
+- `UITextbox`: single-line text input with placeholder/caret
+- `Scene`: root container for scene lifecycle
+
+## Modifiers
+
+Modifiers attach style/behavior to a single element.
+
+- `UIPadding(scale=0, offset=10)` - Adds padding to the element.
+- `UIOutline(color, width, edge_type)` - Adds an outline to the element.
+- `UIBorderRadius(radius)` - Adds a border radius (rounded corners) to the element.
+- `UIGradient(start_color, end_color, direction)` - Converts the background color of the element to a gradient.
+- `UIFont(font_path=None, font_size=None, bold=None, italic=None, antialias=None)` - Changes the font of the text.
+- `GlobalElement()` - If added to a `Workspace` descended element, makes this object shown and handled even when another scene is running.
+
+Attach/get/remove:
+
+```python
+element.set_modifier(plp.UIOutline((0, 0, 0), 2, "middle"))
+outline = element.get_modifier(plp.UIOutline)
+element.remove_modifier(plp.UIOutline)
+```
+
+## Event Helpers
+
+Decorator helpers create `Event` elements attached to a workspace, scene, or element.
+
+- `@on_start(target)` - Runs when the scene/workspace starts running/
+- `@on_update(target)`
+- `@on_quit(target)`
+- `@on_scene_change(target)`
+- `@on_modal_change(target)`
+- `@create_event(target, condition)` for custom conditions
+
+Events created on the main workspace will trigger in all scenes. Pass in `global_event=false` to disable this.
+
+Example:
+
+```python
+@plp.on_update(ws)
+def tick(w: plp.Workspace):
+    if plp.Key.ESCAPE in w.input.key_downs:
+        w.quit()
+
+@plp.on_update(ws, global_event=false)
+def tick(w: plp.Workspace):
+    if plp.Key.UP in w.input.key_downs:
+        w.push_scene(s)
+```
+
+## Scene and Modal Behavior
+
+- If a modal is active, input is only routed to the modal tree
+- Scene descendants are clipped to the scene rectangle for both drawing and hit-testing
+- `Workspace` tracks scene/modal transitions with:
+  - `current_scene`, `previous_scene`, `scene_changed`
+  - `current_modal`, `previous_modal`, `modal_changed`
+- Scenes can implement lifecycle hooks:
+  - `on_enter`, `on_exit`, `on_pause`, `on_resume`
+
+## Input State
+
+Read per-frame input from `workspace.input`:
+
+- `keys_pressed`, `key_downs`, `key_ups` contain `plp.Key` values
+- `mouse_buttons_pressed`, `mouse_downs`, `mouse_ups` contain `plp.MouseButton` values
+- `mouse_pos`, `mouse_delta`, `mouse_wheel`
+- `text_input`
+- `dt`, `runtime`, `quit`
+- `key_held(key)`, `key_up(key)`, `key_down(key)`
+- `mousebutton_held(mb)`, `mousebutton_up(mb)`, `mousebutton_down(mb)`
+
+### Hover State
+
+You can check the hovered objects and top hovered object using the helper methods in `Workspace`.
+
+- `is_mouse_top(element)`, `just_hovered(element)`, `just_unhovered(element)` are for checking only the top hovered object.
+- `is_mouse_over(element)`, `just_hovered_inclusive(element)`, `just_unhovered_inclusive(element)` are for checking all of the hovered objects.
+
+event helpers come with these too.
+
+- `@on_hover(scope, hovered)`, `@on_unhover(scope, hovered)`, `while_hovered(scope, hovered)` for only top.
+- `@on_hover_inclusive(scope, hovered)`, `@on_unhover_inclusive(scope, hovered)`, `while_hovered_inclusive(scope, hovered)` for all.
+
+These are useful because they can then be used to check if the user is clicking an object
+
+```python
+obj = plp.UIPanel(plp.FRect(1, 1, 0, 0), plp.empty_rect(), (0, 0, 0))
+
+@while_hovered(ws, obj)
+def click_check(w: plp.Workspace):
+    if w.input.mousebutton_down(plp.MouseButton.LEFT):
+        print("LMB down!")
+```
+
+'''
+
+__all__ = [
+    "ColorValue",
+    "RectValue",
+    "FRectValue",
+    "CoordinateValue",
+    "FCoordinateValue",
+    "Key",
+    "MouseButton",
+    "InputState",
+    "FRect",
+    "Rect",
+    "empty_rect",
+    "empty_frect",
+    "UIModifier",
+    "UIElement",
+    "Scene",
+    "init",
+    "Workspace",
+    "DATA_DIR",
+    "DEFAULT_ICON_PATH",
+    "__version__",
+    "enter_debug_mode",
+    "init",
+    "Log",
+    "LogWarning",
+    "LogError",
+    "InitializationError",
+    "InitializationWarning",
+    "Severity",
+    "log",
+    "UIPadding",
+    "UIOutline",
+    "UIBorderRadius",
+    "UIGradient",
+    "UIFont",
+    "UIPanel",
+    "UIScrollablePanel",
+    "UIText",
+    "UIButton",
+    "UITextbox",
+    "Event",
+    "create_event",
+    "on_start",
+    "on_update",
+    "on_quit",
+    "on_scene_change",
+    "on_modal_change",
+    "on_hover",
+    "on_unhover",
+    "while_hovered",
+    "on_hover_inclusive",
+    "on_unhover_inclusive",
+    "while_hovered_inclusive",
+]