# UI System

SimVX provides a set of UI controls and layout containers for building game interfaces. All widgets are rendered via the engine's Vulkan backend — no external GUI toolkit required.

## Controls

All controls inherit from `Control`, which provides rect-based layout, mouse interaction, and focus management.

### Label

```python
from simvx.core import Label

label = Label(text="Score: 0", font_size=24)
label.position = Vec2(10, 10)
root.add_child(label)
```

### Button

```python
from simvx.core import Button

btn = Button(text="Start Game")
btn.pressed.connect(start_game)
root.add_child(btn)
```

### TextEdit

```python
from simvx.core import TextEdit

edit = TextEdit(placeholder="Enter name...")
edit.text_changed.connect(lambda text: print(text))
root.add_child(edit)
```

### Slider

```python
from simvx.core import Slider

slider = Slider(min_value=0, max_value=100, value=50)
slider.value_changed.connect(lambda v: print(f"Volume: {v}"))
root.add_child(slider)
```

### ProgressBar

```python
from simvx.core import ProgressBar

bar = ProgressBar(min_value=0, max_value=100, value=75)
root.add_child(bar)
```

## Containers

Containers automatically arrange their children.

### HBoxContainer / VBoxContainer

```python
from simvx.core import HBoxContainer, VBoxContainer, Button

menu = VBoxContainer(separation=10)
menu.add_child(Button(text="New Game"))
menu.add_child(Button(text="Load Game"))
menu.add_child(Button(text="Settings"))
root.add_child(menu)
```

### GridContainer

```python
from simvx.core import GridContainer

grid = GridContainer(columns=3, h_separation=5, v_separation=5)
for i in range(9):
    grid.add_child(Button(text=str(i + 1)))
```

### MarginContainer

```python
from simvx.core import MarginContainer

margin = MarginContainer(
    margin_left=20, margin_right=20,
    margin_top=10, margin_bottom=10,
)
margin.add_child(Label(text="Padded content"))
```

## Theming

`Theme` controls colours, fonts, and sizing for all widgets. Colours are `(r, g, b, a)` floats in 0.0–1.0 range.

```python
from simvx.core.ui import get_theme

theme = get_theme()
theme.colours["accent"] = (0.3, 0.6, 1.0, 1.0)
theme.colours["bg"] = (0.15, 0.15, 0.15, 1.0)
theme.sizes["font_size"] = 18
```

Individual widgets can override theme colours via `ThemeColour` descriptors:

```python
btn = Button(text="Delete")
btn.bg_colour = (0.8, 0.2, 0.2, 1.0)  # Override theme
btn.bg_colour = None                    # Revert to theme default
```

Default colour keys include: `bg`, `bg_light`, `bg_dark`, `text`, `text_disabled`, `accent`, `accent_hover`, `accent_pressed`, `border`, `focus`, `btn_bg`, `btn_hover`, `btn_pressed`, `error`, `warning`, `success`.

## API Reference

See {py:mod}`simvx.core.ui` for the complete UI API.