Inhaltsverzeichnis

Sviluppo TUI

Sviluppo TUI

Panoramica dello sviluppo Terminal UI (TUI) per WvdS FPC RAD Studio.

Il rendering TUI in WvdS raggiunge qualità simile alla GUI: flicker-free, Unicode corretto, themeable, virtualizzato.

Cos'è TUI?

Terminal User Interface (TUI) permette interfacce grafiche nel terminale:

Rappresentazione testuale - Caratteri invece di pixel
Cross-platform - Funziona su Windows Terminal, WezTerm, iTerm2, Linux Console
Efficiente - Ideale per server, SSH, container
Accessibile - Compatibile con screen reader

Quando usare TUI

Caso d'uso	Raccomandato
Amministrazione server	TUI
Tool basati su SSH	TUI
Container/Docker	TUI
Pipeline CI/CD	TUI
Applicazione desktop con GUI	Desktop (LCL)
Applicazione web	Web (pas2js)
Entrambi (server + desktop)	TUI + Desktop

Standard WVDS TUI

Lo standard WVDS TUI si orienta alla qualità Ratatui o superiore:

Caratteristiche qualità

Caratteristica	Descrizione
Flicker-free	Double buffering, flush basato su diff
Unicode corretto	Wide char, emoji, cursor grapheme-aware
Themeable	Token di stile, layering stati
Virtualizzato	Rendering efficiente grandi quantità dati
Responsive	Layout anchoring-first, stabile al resize
Supporto immagini	Kitty/Sixel con fallback

Panoramica architettura

┌─────────────────────────────────────────────────────────────┐
│  PXAML (Markup)                                             │
├─────────────────────────────────────────────────────────────┤
│  Control Model (TWvdS*) - Target-neutral                    │
├─────────────────────────────────────────────────────────────┤
│  TUI Renderer - Target-specific                             │
├─────────────────────────────────────────────────────────────┤
│  Render Surface → CellBuffer → DiffEngine                   │
├─────────────────────────────────────────────────────────────┤
│  Terminal IO (ANSI Escape Sequences)                        │
└─────────────────────────────────────────────────────────────┘

Concetti fondamentali

Model target-neutrali

I model dei controlli NON contengono logica specifica del terminale:

(* CORRETTO - Target-neutral *)
TWvdSButton = class(TWvdSControl)
private
  FCaption: string;
  FOnClick: TNotifyEvent;
public
  property Caption: string read FCaption write SetCaption;
  property OnClick: TNotifyEvent read FOnClick write FOnClick;
end;
 
(* VIETATO - Specifico terminale nel model *)
TWvdSButton = class(TWvdSControl)
  procedure WriteAnsiSequence;  (* VIETATO! *)
end;

Renderer target-specifici

I renderer disegnano il model nel CellBuffer:

TWvdSTUIButtonRenderer = class(TWvdSTUIRenderer)
public
  procedure Measure(AControl: TWvdSControl; AAvail: TSize): TSize; override;
  procedure Paint(AControl: TWvdSControl; ASurface: TRenderSurface); override;
  function HandleInput(AControl: TWvdSControl; AEvent: TInputEvent): Boolean; override;
end;

Anchoring come default

Ogni controllo ha l'anchoring attivato per default:

Anchors: Left, Top, Right, Bottom

Default: Left+Top (posizione stabile)
Left+Right: larghezza si espande con il parent
Top+Bottom: altezza si espande con il parent
Tutti e quattro: rect si espande in entrambe le direzioni

Documentazione TUI

Documento	Contenuto
TUI Engine	CellBuffer, DiffEngine, capability terminale
Controlli TUI	Implementazione controlli, focus, input
Layout TUI	Anchoring, responsive, breakpoint

Quickstart: Creare un controllo TUI

1. Unit Model (target-neutral)

unit WvdS.UI.Controls.MyControl;
 
type
  TWvdSMyControl = class(TWvdSControl)
  private
    FValue: string;
  public
    property Value: string read FValue write SetValue;
  end;

2. Unit TUI Renderer

unit WvdS.UI.TUI.Renderers.MyControl;
 
type
  TWvdSTUIMyControlRenderer = class(TWvdSTUIRenderer)
  public
    procedure Measure(AControl: TWvdSControl; AAvail: TSize): TSize; override;
    procedure Paint(AControl: TWvdSControl; ASurface: TRenderSurface); override;
  end;

3. Pack Manifest

{
  "id": "mycontrol",
  "renderers": {
    "tui": {
      "unit": "WvdS.UI.TUI.Renderers.MyControl",
      "class": "TWvdSTUIMyControlRenderer"
    }
  },
  "targetCaps": {
    "requires": ["keyboard"],
    "optional": ["mouse"]
  }
}

Verifica

Ogni implementazione TUI deve essere verificata:

[ ] Nessun flicker al repaint ripetuto
[ ] Resize produce layout stabile
[ ] Cursore TextEdit stabile con wide/combining char
[ ] Table/List renderizza 10k righe con scroll fluido
[ ] Immagini si comportano correttamente per TerminalCaps
[ ] Focus rimane stabile durante reflow