[Times0]

Stacked on #10

Summary

Fourth of four stacked PRs for the 0.3.0 cleanup: the demo is now the living documentation, and the README is a short guide.

• Demo (src/PygameUIKit/demo.py). A 1100x720 window with a light background and a grid of titled cards. Each card has a one-line API caption.
  • Buttons: colors, outline, fixed width with align, and a button whose text changes on click.
  • Icons: IconButton, IconToggle (it animates the chart) and an ImageButton with hover_image and text.
  • Label: the three alignments within a width.
  • Slider: an integer slider and a float slider with step 0.05, both with show_value, plus a keyboard hint.
  • TextInput: placeholder, on_change, and on_submit (shows the submitted text).
  • Dropdown: recolors the chart and shows value and index.
  • BarChart: driven by a Randomize button, the IconToggle, the Dropdown and the R key. R is handled only when ui.handle_event returns False, so it is ignored while typing.
  • Event log: the last 8 callbacks, e.g. Slider.on_change(42). Continuous changes update a single line.
• Structure. A small Card dataclass (title, caption, rect, draw function) and a cell(column, row, columns) grid helper. The layout is one list in Demo.__init__, so adding a widget means adding a draw_<name> method and one Card. The Dropdown card is drawn last so its menu covers the cards below it.
• CLI. --frames N is kept. New: --screenshot PATH saves the last frame as a PNG and exits, using the dummy video driver by default, so no window opens.
• Library default. Label now defaults to black text instead of white (only 0.3 cleanup 2/4: Button, ImageButton, IconButton, IconToggle and Label #9 introduced the default; 0.2 required a color). This matches TextInput, Slider and BarChart, and white labels were invisible on light backgrounds. The CHANGELOG is updated.
• README. It shows the new screenshot (images/img.png, generated with --screenshot). "Use it" now has a runnable main-loop example (Group, the handle_event return value, update(dt), drawing each widget, dropdowns last), short notes on callbacks, colors and fonts, and a one-bullet reference per widget (constructor, properties, callbacks). Install, Try it and Develop are kept. The unreferenced images/logo.jpeg is removed.

Breaking changes

• Label's default color is "black" (it was "white" earlier in this unreleased stack).

How tested

uv run ruff check . && uv run ruff format --check . && uv run pytest && uv run pygameuikit-demo --frames 5 passes (81 tests). New tests/test_demo.py:

• runs the demo for a few frames
• clicks Randomize and the IconToggle through the demo's event handler and checks the event log; checks that R typed into the focused input doesn't reach the shortcut, and does after Escape
• writes a --screenshot to tmp_path and checks its size

I also checked the visuals by viewing the --screenshot output and a scripted interaction frame: buttons clicked, slider dragged, text typed and submitted, chart randomized, dropdown open with an option highlighted over the event log. I iterated on spacing until nothing overlapped or clipped. I also ran the README example headlessly.