xut 0.1.0

Modern UI, out of the box.

XUT — Simple. Powerful. Instant UI.

XUT is a modern UI toolkit designed to feel effortless for beginners while staying insanely powerful for advanced users. It combines the simplicity of immediate-mode APIs with the performance and flexibility of retained-mode systems under the hood.

---

✨ Philosophy

• Beginner-friendly, zero friction
• Powerful and scalable
• Immediate-mode on the surface
• Retained-mode internally

---

🚀 Getting Started

Installation

pip install xut

Basic Setup

import xut

app = xut.App(theme="applesauce-mono")

---

🎨 Themes

Resolution Order

XUT automatically resolves themes in this order:

1. ./applesauce-mono.xut
2. ./applesauce-mono/applesauce-mono.xut
3. Installed themes
4. Default fallback

Theme Structure

applesauce-mono/
  applesauce-mono.xut
  fonts/
    Inter.ttf

Features

• Hex colors
• Variables
• Global values
• Font loading
• Brightness modifiers
• Hot-reload support 🔥

---

🔁 Main Loop

while app.running:
    app.begin_frame()
    # UI here
    app.end_frame()

Stop the app anytime:

app.stop()

---

🧠 Core Concepts

All UI elements share a unified API:

• id (unique identifier)
• pos=(x, y)
• size=(w, h) (if applicable)
• z (layer depth)
• rotation (degrees)
• font_size

Most elements return a handle, allowing real-time updates — even after creation.

---

🧩 UI Elements

🖼 Image

img = app.image("logo", path="assets/logo.png", pos=(100, 100), size=(128, 128))
img.rotation = 45

---

🔘 Button

if app.button_clicked("btn", "Click Me", pos=(100, 100), size=(120, 40)):
    print("clicked")

---

🧷 Icon Button

app.icon_button_clicked("save", "icons/save.png", pos=(50, 50), size=(40, 40))

Layouts:

• icon_only
• text_right
• text_below

---

🏷 Label

app.label("Hello", pos=(100, 100))

Mutable label:

lbl = app.label_ex("status", "Ready", pos=(100, 100))
lbl.text = "Done!"

---

🧾 Input

text = app.input("username", pos=(100, 200), size=(300, 40))

---

🎚 Slider

value = app.slider("volume", pos=(100, 300), size=(300, 16))

---

☑ Checkbox / Toggle

app.checkbox("enable", "Enable", pos=(100, 350))
app.toggle("power", pos=(100, 400))

---

📊 Progress

app.progress(0.7, pos=(100, 500), size=(300, 10))

---

📂 Dropdown

app.dropdown("role", ["User", "Admin"], pos=(100, 550), size=(300, 40))

---

🧱 Layout Components

• panel()
• window()
• tabs()
• scrollbar()
• divider()

---

⚙️ Element Handles (🔥 Powerful)

Every element can be modified live:

btn = app.button_clicked("ok", "OK", pos=(100, 100), size=(80, 32))

handle = app.get("ok")
handle.pos = (200, 300)
handle.text = "Confirm"
handle.rotation = 15

Properties

Property	Description
pos	Position
size	Size
z	Layer
text	Label text
value	Numeric value
rotation	Rotation
font_size	Font override
clicked	Clicked this frame
hovered	Mouse over
pressed	Mouse held

---

🧠 Internal Behavior

Persistence

• Elements are cached by id
• Automatically reused every frame

Rendering

• Sorted by z
• Proper hitboxes (even rotated)

Events

• Top layer gets priority
• Stops propagation on interaction

---

🎨 Theme Control

Change Theme

app.set_theme("dark-pro")

Hot Reload

app.reload_theme()

Perfect for live editing your .xut files.

---

🪟 Window Control

app.set_window_title("My App")
app.set_window_icon("assets/icon.png")

---

⌨️ Shortcuts

if app.shortcut("ctrl+s"):
    save()

Supports:

• ctrl, shift, alt, cmd
• Letters, numbers
• Function keys
• Arrow keys

---

⚡ Example

import xut

app = xut.App("applesauce-mono", title="Settings")

while app.running:
    app.begin_frame()

    active = app.tabs("tabs", ["General", "Audio"], pos=(100, 100), size=(300, 30))

    if app.button_clicked("save", "Save", pos=(100, 200), size=(120, 40)):
        app.set_window_title("Saved!")

    if app.shortcut("ctrl+s"):
        print("Saved via shortcut")

    app.end_frame()

---

💡 Why XUT?

• No boilerplate
• No layout headaches
• Real-time mutation
• Hot-reload themes
• Works great for tools, apps, and even full desktop environments 👀

---

🧪 Status

XUT is actively evolving. Expect rapid improvements, new elements, and deeper customization.

---

🧡 Contributing

Ideas, feedback, and contributions are welcome.

---

📄 License

MIT

---

Build fast. Iterate faster. Ship instantly.