PlayPy 0.1.0

PlayPy is a lightweight UI toolkit built off pygame designed to make building apps on python easier.

PlayPy (0.1.0)

PlayPy is a lightweight UI toolkit built off pygame designed to make building apps on python easier. It provides a small scene-based workspace, UI elements, style modifiers, and decorator-based event hooks.

Requirements

• Python >=3.11
• pygame >=2.6.1

Installation

To install PlayPy, Enter the following to the terminal:

pip install playpy

This should automatically install PlayPy to your computer to be used in any python projects

Core Concepts

Workspace

Workspace owns the window, render loop, input state, scene stack, and modal stack.

Key methods:

• run() starts the loop
• quit() stops the loop
• set_scene(scene) replaces the current scene
• push_scene(scene) / pop_scene() stacks scenes
• push_modal(element) / pop_modal() / clear_modals() manages overlays

Layout Values

PlayPy uses two rectangle value types:

• FRectValue(x, y, w, h) Relative scale (fraction of parent rectangle).
• RectValue(x, y, w, h) Absolute pixel offsets applied on top of scale.

Final element rect = scale * parent_size + offset.

Parenting

Any UIElement can contain children. Assigning parent wires it automatically:

child.parent = parent

Or use helpers:

parent.add_child(child)

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)
• UIOutline(color, width, edge_type)
• UIBorderRadius(radius)
• UIGradient(start_color, end_color, direction)
• UIFont(font_path=None, font_size=None, bold=None, italic=None, antialias=None)

Attach/remove/get:

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)
• @on_update(target)
• @on_quit(target)
• @on_scene_change(target)
• @on_modal_change(target)
• @create_event(target)(condition) for custom conditions

Example:

@plp.on_update(ws)
def tick(w: plp.Workspace):
    if plp.pg.K_ESCAPE in w.input.key_downs:
        w.quit()

Scene and Modal Behavior

• If a modal is active, input is only routed to the modal tree
• 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
• mouse_buttons_pressed, mouse_downs, mouse_ups
• mouse_pos, mouse_wheel
• text_input
• dt, runtime, quit