# Touchscreen UI Toolkit Evaluation

Raspberry Pi 4B, official 7" (800×480) or Waveshare 5" (720×720) DSI/HDMI
touch displays. Requirements: faders, meters, mute/solo, routing matrix,
plugin chain, touch gestures, DPI-aware layout.

## Candidates

### LVGL (Light and Versatile Graphics Library)
- **Type**: C library, embedded-first, Python bindings via `lvgl` package
- **RPi support**: Native framebuffer + SDL2/KMS backends, no X11 required
- **Touch**: Native input device support (libinput/evdev), multi-touch, gestures
- **DPI**: Pixel-based (px), no automatic scaling — manual math required
- **Widgets**: Sliders, buttons, labels, charts, tables — good but basic
- **Performance**: ⭐⭐⭐⭐⭐ — C rendering, 30-60 FPS on RPi 4
- **Python ergonomics**: ⭐⭐ — Python bindings are auto-generated, not idiomatic;
  callbacks are C-style, error messages opaque; limited docs for Python usage
- **Verdict**: Best performance, but Python API is friction-heavy. Good for C
  projects. Too much pain for a Python codebase.

### GTK 3/4
- **Type**: C library, GObject introspection for Python (`PyGObject`)
- **RPi support**: Requires X11 or Wayland compositor — adds RAM overhead
- **Touch**: Mouse-emulated touch; not natively touch-optimized
- **DPI**: CSS-based theming, but DPI scaling is complex on small screens
- **Widgets**: Very rich (sliders, buttons, tree views, notebooks)
- **Performance**: ⭐⭐ — X11/Wayland overhead, not optimized for embedded
- **Python ergonomics**: ⭐⭐⭐ — GObject patterns leak through; verbose
- **Verdict**: Desktop toolkit forced onto embedded. Heavy, poor touch UX.
  Best for desktop companion apps, not the primary mixer UI.

### SDL2
- **Type**: C library, Python via `PySDL2`
- **RPi support**: Framebuffer/KMSDRM backends, no X11 required
- **Touch**: Raw input events only — no gesture recognition built in
- **DPI**: None — raw pixels, manual scaling required
- **Widgets**: None — you build every widget from primitives (rects, lines, text)
- **Performance**: ⭐⭐⭐⭐ — low-level, fast rendering
- **Python ergonomics**: ⭐ — no widgets, no layout engine, no theme system.
  Building a mixer UI in raw SDL2 means writing a UI toolkit from scratch.
- **Verdict**: Great for games, terrible for complex UIs. Too much boilerplate.

### Kivy (selected)
- **Type**: Python-native UI framework, OpenGL ES 2.0 backend
- **RPi support**: Native RPi support via `kivy-rpi`; framebuffer or X11 backends;
  works with official 7" and Waveshare displays out of the box
- **Touch**: First-class multi-touch, gesture recognition (swipe, pinch, long-press),
  mouse fallback for development
- **DPI**: `dp()` and `sp()` (density-independent pixels/scaled pixels) —
  automatic scaling across 5" / 7" / desktop displays
- **Widgets**: Sliders, buttons, toggles, labels, layouts, screens, tabbed panels
- **Performance**: ⭐⭐⭐ — OpenGL-accelerated; 30-60 FPS on RPi 4 for
  typical mixer UI complexity; GPU handles rendering, CPU free for DSP
- **Python ergonomics**: ⭐⭐⭐⭐⭐ — Pure Python, declarative KV language or
  programmatic widget construction; natural fit for the existing Python codebase
- **Verdict**: Best balance of performance, touch UX, and Python ergonomics.
  Purpose-built for multi-touch interfaces. DPI-aware by default. Rich widget
  set plus easy custom widget creation for faders/meters.

## Decision: Kivy

| Criterion | LVGL | GTK | SDL2 | Kivy |
|-----------|------|-----|------|------|
| Touch UX | ★★★★ | ★★ | ★ | ★★★★★ |
| Performance | ★★★★★ | ★★ | ★★★★ | ★★★ |
| Python API | ★★ | ★★★ | ★ | ★★★★★ |
| DPI scaling | ★ | ★★★ | ★ | ★★★★★ |
| Widget richness | ★★★ | ★★★★★ | ★ | ★★★★ |
| RPi setup | ★★★★ | ★★ | ★★★ | ★★★★ |

Kivy is the clear winner for a Python-project building a touch-optimized mixer
UI on Raspberry Pi. The DPI-aware layout system means the same code works on
5" and 7" displays without manual scaling math. Multi-touch and gestures
come free. Custom widgets (faders, meters, knobs) are straightforward to
build on Kivy's Canvas primitives.

### Installation (RPi)
```bash
sudo apt install python3-kivy  # system package, includes RPi deps
# or
pip3 install kivy  # + manual SDL2/OpenGL deps
```

### Development (desktop)
```bash
pip3 install kivy
# Run with: python3 main_touch.py
# Mouse works as touch fallback
```