Metadata-Version: 2.4
Name: xut
Version: 0.1.0
Summary: Modern UI, out of the box.
Project-URL: Homepage, https://github.com/Lightingdev/xut
Author-email: Yixuan Xu <xuyixuan370@gmail.com>
License: MIT
License-File: LICENSE
Keywords: gamedev,imgui,pygame,ui
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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

```bash
pip install xut
```

### Basic Setup

```python
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

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

Stop the app anytime:

```python
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

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

---

### 🔘 Button

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

---

### 🧷 Icon Button

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

Layouts:

* `icon_only`
* `text_right`
* `text_below`

---

### 🏷 Label

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

Mutable label:

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

---

### 🧾 Input

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

---

### 🎚 Slider

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

---

### ☑ Checkbox / Toggle

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

---

### 📊 Progress

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

---

### 📂 Dropdown

```python
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:

```python
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

```python
app.set_theme("dark-pro")
```

### Hot Reload

```python
app.reload_theme()
```

Perfect for live editing your `.xut` files.

---

## 🪟 Window Control

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

---

## ⌨️ Shortcuts

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

Supports:

* `ctrl`, `shift`, `alt`, `cmd`
* Letters, numbers
* Function keys
* Arrow keys

---

## ⚡ Example

```python
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.**
