xut 0.1.0__tar.gz

xut-0.1.0/API_SPEC_SHEET.md

@@ -0,0 +1,517 @@
+# XUT API Specification v1
+
+## Philosophy
+
+XUT is designed to be:
+
+* Extremely easy for beginners
+* Powerful for advanced users
+* Immediate-mode on the surface
+* Retained-mode under the hood
+
+## 1. Initialization
+
+```python
+import xut
+
+app = xut.App(theme="applesauce-mono")
+```
+
+### Theme Resolution Order
+
+1. `./applesauce-mono.xut`
+2. `./applesauce-mono/applesauce-mono.xut`
+3. Installed themes
+4. Default fallback theme
+
+### Theme Folder Structure
+
+```
+applesauce-mono/
+  applesauce-mono.xut
+  fonts/
+    Inter.ttf
+```
+
+
+## 2. Main Loop
+
+```python
+while app.running:
+    app.begin_frame()
+    # UI code here
+    app.end_frame()
+```
+
+### Stop App
+
+```python
+app.stop()
+```
+
+## 3. Core API Pattern
+
+All UI elements follow:
+
+* `id` (unique, internal)
+* `pos=(x, y)`
+* `size=(w, h)` (if applicable)
+* `z` (optional depth layer)
+* `rotation` (optional `float`, in degrees)
+* `font_size` (optional integer override)
+
+Most interactive elements return an `ElementHandle` that lets you mutate the element at any time — including after creation (live, mid-loop).
+
+4. UI Elements
+
+### Image
+
+```python
+img = app.image("logo", path="assets/logo.png", pos=(100, 100), size=(128, 128), rotation=0.0)
+```
+
+Returns: `ImageHandle`
+
+**Alternate (draw-only):**
+
+```python
+app.image("logo", path="assets/logo.png", pos=(100, 100), size=(128, 128))
+```
+
+**Using handle:**
+
+```python
+img.pos = (200, 120)
+img.size = (256, 256)
+img.rotation = 45.0
+```
+
+**Notes:**
+
+* Images are cached by id and path
+* Supports PNG/JPG
+* If size is omitted, uses original image size
+* Resizing uses smooth scaling
+
+### Button
+
+```python
+if app.button_clicked("confirm_btn", "Confirm", pos=(452, 640), size=(120, 40), rotation=0.0):
+    print("clicked")
+```
+
+Returns: `bool`
+
+Icon Button
+
+A button that renders an image icon instead of (or alongside) text.
+
+```python
+# Icon only
+if app.icon_button_clicked("save_btn", "icons/save.png", pos=(50, 50), size=(40, 40)):
+    print("save clicked")
+
+# Icon with text to the right
+if app.icon_button_clicked("open_btn", "icons/open.png", pos=(100, 50), size=(120, 36),
+                            text="Open", layout="text_right"):
+    print("open clicked")
+
+# Icon with text below
+if app.icon_button_clicked("home_btn", "icons/home.png", pos=(160, 50), size=(60, 60),
+                            text="Home", layout="text_below"):
+    print("home clicked")
+```
+
+Returns: `bool`
+
+### Layouts
+
+| layout      | description                      |
+|-------------|----------------------------------|
+| `icon_only` | Icon fills the button (default)  |
+| `text_right`| Icon on the left, text on the right |
+| `text_below`| Icon centred above, text below  |
+
+Advanced mode
+
+```python
+btn = app.icon_button("save_btn", "icons/save.png", rect=(50, 50, 40, 40))
+if btn.clicked:
+    print("save clicked")
+```
+
+Returns: `ElementHandle`
+
+Label
+
+```python
+app.label("Hello", pos=(100, 100), font_size=18, rotation=0.0)
+```
+
+For a named label you can mutate later, use `label_ex`:
+
+```python
+lbl = app.label_ex("status_lbl", "Ready", pos=(100, 100))
+# later in the loop:
+lbl.text = "Done!"
+lbl.pos  = (200, 150)
+lbl.font_size = 24
+```
+
+
+Icon Label
+
+A label that renders an icon image beside (or above) a text string.
+
+```python
+app.icon_label("status", "icons/ok.png", "Connected", pos=(100, 200))
+
+# Icon to the right of the text
+app.icon_label("warn", "icons/warning.png", "Low battery",
+               pos=(100, 240), icon_size=20, layout="icon_right")
+
+# Icon above the text
+app.icon_label("cloud", "icons/cloud.png", "Sync",
+               pos=(100, 280), icon_size=32, layout="icon_above")
+```
+
+Returns: `ElementHandle`
+
+### Layouts
+
+| layout     | description             |
+|------------|-------------------------|
+| `icon_left` | Icon then text (default)|
+| `icon_right`| Text then icon         |
+| `icon_above`| Icon above text        |
+
+Input
+
+```python
+text = app.input("username", pos=(100, 200), size=(300, 40), placeholder="Enter name")
+```
+
+Returns: `str`
+
+Slider
+
+```python
+value = app.slider("volume", pos=(100, 300), size=(300, 16))
+```
+
+Returns: `float` (0.0 - 1.0)
+
+Checkbox
+
+```python
+checked = app.checkbox("enable", "Enable feature", pos=(100, 350))
+```
+
+Returns: `bool`
+
+Radio
+
+```python
+selected = app.radio("sync", "Sync to cloud", pos=(100, 400))
+```
+
+Returns: `bool`
+
+Toggle
+
+A sliding switch for boolean values.
+
+```python
+on = app.toggle("power", pos=(100, 450), size=(44, 24))
+```
+
+Returns: `bool`
+
+Progress Bar
+
+```python
+app.progress(0.7, pos=(100, 500), size=(300, 10))
+```
+
+Dropdown
+
+```python
+selected = app.dropdown("role", ["Standard", "Admin", "Guest"], pos=(100, 550), size=(300, 40))
+```
+
+Returns: `str`
+
+Divider
+
+```python
+app.divider(pos=(100, 600), size=(300, 1))
+```
+
+
+Panel
+
+```python
+app.panel("main_panel", "Main Interface", pos=(130, 150), size=(764, 478))
+```
+
+Window
+
+```python
+app.window("main_window", "My App", pos=(100, 60), size=(824, 648))
+```
+
+Tabs
+
+Horizontal navigation bar.
+
+```python
+active = app.tabs("settings_tabs", ["General", "Audio", "Network"], pos=(130, 110), size=(300, 35))
+```
+
+Returns: `int` (active index)
+
+Scrollbar
+
+Vertical or horizontal track for scrolling.
+
+```python
+scroll = app.scrollbar("main_scroll", pos=(875, 120), size=(12, 498))
+```
+
+Returns: `float` (0.0 - 1.0)
+
+## 5. Internal Behavior
+
+### Element Persistence
+
+* Elements are stored by id
+* Persist across frames
+* Automatically reused
+
+### Event Handling
+
+* Higher `z` gets priority
+* Stops propagation on interaction
+* Rotated elements maintain correct hitboxes
+
+### Rendering Order
+
+Sorted by `z` (low → high)
+
+## 6. Element State
+
+Each element may expose:
+
+* `clicked` (one frame)
+* `hovered`
+* `pressed`
+* `value`
+* `rotation`
+* `font_size`
+
+## 7. Advanced Mode (Optional)
+
+```python
+btn = app.button("confirm_btn", "Confirm", rect=(452, 640, 120, 40))
+if btn.clicked:
+    print("clicked")
+```
+
+
+8. Live Element Mutation
+
+All element-creating calls (button, label_ex, window, panel, icon_button,
+icon_label, …) return an ElementHandle. You can also retrieve a handle
+for any already-created element with app.get(id).
+
+h = app.get("my_button")
+
+
+### ElementHandle properties
+
+| property  | type  | description                              |
+|-----------|-------|------------------------------------------|
+| `pos`     | `(x, y)` | Get / set position                   |
+| `size`    | `(w, h)` | Get / set size                       |
+| `z`       | `int` | Get / set render / event layer       |
+| `text`    | `str` | Get / set displayed text or label    |
+| `value`   | `float` | Get / set slider or progress value (0.0–1.0) |
+| `rotation`| `float` | Get / set element rotation in degrees|
+| `font_size`| `int` | Get / set element font size override |
+| `clicked` | `bool` | Read — True on the frame clicked     |
+| `hovered` | `bool` | Read — True while mouse is over      |
+| `pressed` | `bool` | Read — True while held               |
+
+Example — move and relabel a button live
+
+btn = app.button_clicked("ok_btn", "OK", pos=(100, 100), size=(80, 32))
+
+handle = app.get("ok_btn")
+if handle:
+    handle.pos  = (200, 300)   # move it
+    handle.size = (120, 40)    # resize it
+    handle.z    = 20           # bring it forward
+    handle.text = "Confirm"    # relabel it
+    handle.rotation = 15.0     # tilt it
+
+
+Changes take effect on the next frame — the element is already cached and
+will be drawn with the new values without re-creation.
+
+9. Theme System
+
+### Load Theme by Name
+
+```python
+app.set_theme("dark-pro")
+```
+
+Clears all cached elements; they are recreated on the next frame with the new theme.
+
+### Live Theme Reload (Hot-Reload)
+
+```python
+# Call this whenever you want to pick up on-disk changes to the .xut file
+app.reload_theme()
+```
+
+
+Useful during development: edit your .xut file in any text editor and call
+reload_theme() (e.g. on a keypress) to see the result immediately without
+restarting the app.
+
+while app.running:
+    app.begin_frame()
+
+    for event in pygame.event.get():
+        if event.type == pygame.KEYDOWN and event.key == pygame.K_r:
+            app.reload_theme()   # R to hot-reload
+
+    # ... draw UI ...
+    app.end_frame()
+
+
+Theme Features
+
+Hex colors
+
+Variable references
+
+Global values
+
+Font loading from /fonts
+
+Brightness modifiers
+
+10. Window Title and Icon
+
+### Set Window Title
+
+```python
+app.set_window_title("My New Title")
+```
+
+Can be called at any time, including inside the main loop.
+
+### Set Window Icon
+
+```python
+app.set_window_icon("assets/myicon.png")
+```
+
+Falls back to `icon.png` next to the xut package if path is None or missing. Can also be passed at construction time:
+
+```python
+app = xut.App(theme="applesauce-mono", icon="assets/myicon.png")
+```
+
+
+## 11. Shortcuts
+
+```python
+if app.shortcut("ctrl+s"):
+    save()
+```
+
+Returns `True` on the single frame the key combination is pressed — identical in feel to `button_clicked`.
+
+#### Modifier tokens
+
+| token          | key            |
+|----------------|----------------|
+| `ctrl`         | Control        |
+| `shift`        | Shift          |
+| `alt`          | Alt / Option   |
+| `meta` / `cmd` / `super` | Meta / Cmd / Win |
+
+**Named keys:** `space`, `enter`, `escape` / `esc`, `tab`, `backspace`, `delete` / `del`, `insert`, `home`, `end`, `pageup`, `pagedown`, `up`, `down`, `left`, `right`, `f1`–`f15`
+
+Single letters and digits work directly: `"a"`, `"1"`, etc.
+
+**Examples:**
+
+```python
+if app.shortcut("ctrl+s"):       save()
+if app.shortcut("ctrl+z"):       undo()
+if app.shortcut("ctrl+shift+z"): redo()
+if app.shortcut("f5"):           refresh()
+if app.shortcut("escape"):       close_modal()
+```
+
+
+## 12. Example
+
+```python
+import xut
+
+app = xut.App("applesauce-mono", title="Settings", icon="assets/icon.png")
+
+# Keep a live handle so we can mutate the window later
+win = app.window("main", "Settings", pos=(100, 60), size=(800, 600))
+
+while app.running:
+    app.begin_frame()
+
+    app.window("main", "Settings", pos=(100, 60), size=(800, 600))
+
+    # Tabs for navigation
+    active_tab = app.tabs("nav", ["General", "Graphics", "Audio"], pos=(120, 100), size=(300, 30))
+
+    # Icon button
+    if app.icon_button_clicked("save_btn", "icons/save.png",
+                                pos=(20, 20), size=(40, 40)):
+        app.set_window_title("Saved!")
+
+    # Named label that can be mutated
+    status = app.label_ex("status", "Idle", pos=(80, 28))
+
+    if app.button_clicked("confirm", "Confirm", pos=(450, 600), size=(120, 40), rotation=5.0):
+        status.text = "Confirmed"
+        print("Saved!")
+
+    # Shortcuts — same feel as button_clicked
+    if app.shortcut("ctrl+s"):
+        status.text = "Saved"
+    if app.shortcut("ctrl+z"):
+        status.text = "Undo"
+    if app.shortcut("r"):
+        app.reload_theme()
+
+    username = app.input("user", pos=(200, 200), size=(300, 40))
+
+    volume = app.slider("vol", pos=(200, 300), size=(300, 16))
+    app.progress(volume, pos=(200, 330), size=(300, 10))
+    
+    # New Toggle feature
+    is_active = app.toggle("active_state", pos=(200, 360), size=(44, 24))
+
+    # Hot-reload theme on R key
+    import pygame
+    for event in pygame.event.get():
+        if event.type == pygame.KEYDOWN and event.key == pygame.K_r:
+            app.reload_theme()
+
+    app.end_frame()
+```
+
+End of Spec

xut-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+
+
+Copyright 2026 - 2030 Yixuan Xu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.