0.3 cleanup 2/4: Button, ImageButton, IconButton, IconToggle and Label

CHANGELOG.md

@@ -8,8 +8,13 @@
 - Every `handle_event` returns `True` when it consumed the event (button presses and clicks, slider drags, clicks and typing in a focused text input, open-dropdown interactions). `Group.handle_event` stops at the first widget that consumes an event and returns whether one did.
 - `Group` now sets the mouse cursor after each `MOUSEMOTION`: the `cursor` of the hovered widget (hand for buttons, sliders and dropdowns; I-beam for text inputs), otherwise the arrow. Widgets no longer change the cursor themselves.
 - A focused text input sees mouse clicks first, so clicking another widget still unfocuses it.
-- Export `Group`, `Widget` and all widget classes from the top-level package (`from PygameUIKit import ButtonText, Slider`). Submodules remain importable.
+- Export `Group`, `Widget` and all widget classes from the top-level package (`from PygameUIKit import Button, Slider`). Submodules remain importable.
 - Remove `Group.draw`, which drew every widget at the same position.
+- Replace the eight button classes with four: `Button` (rounded text button), `ImageButton`, `IconButton` and `IconToggle`. All click on a left press and release inside the button, cancel on window focus loss, and expose `pressed`.
+- `Button` sizes itself to its text (or a fixed `width` with `align`), derives hover and pressed shades from `color`, picks black or white text for contrast unless `text_color` is given, and defaults to `border_radius=6` and `padding=(16, 8)`. `outline_color` draws a 2 px outline. `button.text` is a property that resizes the button.
+- `Label(text, color="white", *, font=None, align="left")` draws exactly at (x, y); `draw(surface, x, y, width=None)` aligns the text within `width`. Setting `text` or `color` re-renders only when the value changes.
+- `IconButton`'s clickable area and hover backdrop are the icon plus `padding` on each side, starting at (x, y).
+- Add `utils.shade(color, amount)`; `utils.best_contrast_color` uses perceived brightness and returns a `pygame.Color`.
 - Remove the duplicate root `src/demo.py` and `src/assets/`; the packaged `pygameuikit-demo` is the demo.
 
 ### Upgrading from 0.2
@@ -24,6 +29,16 @@
 - Button `on_hover()`/`on_unhover()` hooks and Slider `on_hover()`/`on_unhover()` are removed; read `hovered` instead.
 - Widgets no longer call `pygame.mouse.set_cursor`; route `MOUSEMOTION` events through a `Group` to get cursor changes.
 - Overlapping widgets in a `Group` no longer all react to the same click; only the first one that consumes it does.
+- Buttons take `on_click` (second positional argument or keyword) instead of `onclick_f`; reassign `button.on_click` instead of calling `connect()`. `clicked` → `pressed`.
+- `ButtonText(text, onclick_f, rect_color=..., font_color=..., fixed_width=..., text_align=...)` → `Button(text, on_click, color=..., text_color=..., width=..., align=...)`. `change_text(text)` → `button.text = text`.
+- `ButtonRect(w, h, color, onclick_f)` → `Button(text, on_click, color=..., width=w)` (the height follows the font and `padding`), or an `ImageButton` showing a filled `pygame.Surface((w, h))`.
+- `ButtonImage(image, onclick_f, hover_image)` → `ImageButton(image, on_click, hover_image=...)`.
+- `ButtonImageText(image, onclick_f, text, text_color, font, image_hover, text_offset)` → `ImageButton(image, on_click, hover_image=..., text=..., text_color=..., font=...)`; text is centered and `text_offset` is removed.
+- `ButtonPngIcon(image, onclick_f, hover_color, opacity, inflate)` → `IconButton(image, on_click, hover_color=..., hover_alpha=int(opacity * 255), padding=inflate // 2)`. The icon is now drawn at (x + padding, y + padding).
+- `ButtonTwoStates(image_default, image_click, onclick_f)` → `IconToggle(image_off, image_on, on_change)`; `on_change` receives the new `value` (bool) and `state` (1/2) → `value` (False/True).
+- `ButtonThreadImage` and `ButtonThreadText` are removed. Set `button.text` (or `image_button.image`) from your own state each frame instead, e.g. `button.text = "Searching..." if thread.is_alive() else "Find match"`.
+- `Label(text, font_color, font, text_align, bounding_rect)` → `Label(text, color, font=..., align=...)`. Pass the bounding width to `draw(surface, x, y, width)` instead of `bounding_rect`; the `TextAlignment` enum is removed (use `"left"`, `"center"`, `"right"`). Labels no longer add 10 px of padding: draw at `(x + 10, y + 10)` for the old placement. `label.render_text()` and `label.text_surface` → `label.surface` (re-rendered automatically).
+- `utils.make_surface_darker` is removed; use `utils.shade` for colors.
 
 ## 0.2.0
 

README.md

@@ -28,19 +28,13 @@ uv installs Python and dependencies automatically. The demo is also included in
 
 ```python
 import pygame
-from PygameUIKit import Group, button
+from PygameUIKit import Button, Group
 
 pygame.init()
 screen = pygame.display.set_mode((640, 360))
 clock = pygame.time.Clock()
 ui = Group()
-hello = button.ButtonText(
-    "Say hello",
-    lambda: print("Hello!"),
-    rect_color=(85, 145, 92),
-    border_radius=8,
-    ui_group=ui,
-)
+hello = Button("Say hello", lambda: print("Hello!"), color=(85, 145, 92), ui_group=ui)
 
 running = True
 while running:
@@ -62,11 +56,14 @@ pygame.quit()
 
 Add widgets with `ui_group=ui`, forward each event once, and call `ui.update(dt)` with seconds. `ui.handle_event(event)` returns `True` when a widget consumed the event (for example a button click or typing into a focused text input), so you can skip your own handling for it. The group also sets the mouse cursor for the hovered widget. Draw each widget at your chosen position. Sliders accept `draw(screen, x, y, width, height)`; charts use the same layout arguments. Draw dropdowns last so their menus appear above other widgets.
 
-- `button`: text, image, icon, toggle, and thread-status buttons.
+- `Button("Play", on_click, color="seagreen")`: rounded text button sized to its text; set `text` to relabel it. Options: `width` and `align`, `outline_color`, `border_radius`, `padding`, `text_color` (black or white for contrast by default).
+- `ImageButton(image, on_click, hover_image=None, text="")`: an image, optionally with centered text.
+- `IconButton(icon, on_click)`: an icon with a translucent backdrop on hover.
+- `IconToggle(icon_off, icon_on, on_change)`: switches icons on click and calls `on_change(value)`; read or set `value`.
 - `slider.Slider(min, max, step)`: `get_value()` and `connect(callback)`.
 - `combobox.ComboBox(["One", "Two"])`: `get_value()` and `add_action(index, callback)`.
 - `text_input.TextInput(placeholder="Name")`: `get_text()` and `set_text(text)`.
-- `label.Label("Hello", "white")`: update the `text` property.
+- `Label("Hello", "white")`: draws at exactly (x, y); `draw(screen, x, y, width)` aligns it within `width` using `align="left" | "center" | "right"`. Set `text` to change it.
 - `barchart.BarChart([10, 20, 30])`: `change_value(index, value)`; accepts non-negative values.
 
 Text inputs use Pygame's `TEXTINPUT` events for Unicode text and `KEYDOWN` for editing. Forward both through `Group`; don't also forward the same events separately to the input. Pass a custom `pygame.font.Font` if you need a particular font or character set.

src/PygameUIKit/__init__.py

@@ -2,16 +2,7 @@
 
 from . import barchart, button, combobox, label, slider, text_input, utils, widget
 from .barchart import BarChart
-from .button import (
-    ButtonImage,
-    ButtonImageText,
-    ButtonPngIcon,
-    ButtonRect,
-    ButtonText,
-    ButtonThreadImage,
-    ButtonThreadText,
-    ButtonTwoStates,
-)
+from .button import Button, IconButton, IconToggle, ImageButton
 from .combobox import ComboBox
 from .label import Label
 from .slider import Slider
@@ -20,16 +11,12 @@
 
 __all__ = [
     "BarChart",
-    "ButtonImage",
-    "ButtonImageText",
-    "ButtonPngIcon",
-    "ButtonRect",
-    "ButtonText",
-    "ButtonThreadImage",
-    "ButtonThreadText",
-    "ButtonTwoStates",
+    "Button",
     "ComboBox",
     "Group",
+    "IconButton",
+    "IconToggle",
+    "ImageButton",
     "Label",
     "Slider",
     "TextInput",