====== TUI razvoj ======

Pregled razvoja terminalskega uporabniškega vmesnika (TUI) za WvdS FPC RAD Studio.

<note>TUI izrisovanje v WvdS dosega **kakovost podobno GUI**: brez utripanja, pravilna podpora Unicode, tematizacija, virtualizacija.</note>

===== Kaj je TUI? =====

Terminal User Interface (TUI) omogoča grafične vmesnike v terminalu:

  * **Tekstovna predstavitev** - Znaki namesto slikovnih pik
  * **Medplatformno** - Deluje na Windows Terminal, WezTerm, iTerm2, Linux Console
  * **Varčno z viri** - Idealno za strežnike, SSH, kontejnerje
  * **Dostopno** - Združljivo z bralniki zaslona

===== Kdaj uporabiti TUI =====

^ Primer uporabe ^ Priporočeno ^
| Administracija strežnikov | TUI |
| SSH orodja | TUI |
| Kontejnerji/Docker | TUI |
| CI/CD cevovodi | TUI |
| Namizna aplikacija z GUI | Desktop (LCL) |
| Spletna aplikacija | Web (pas2js) |
| Oboje (strežnik + namizje) | TUI + Desktop |

===== WVDS TUI standard =====

WVDS TUI standard se zgleduje po **Ratatui kakovosti** ali boljši:

==== Značilnosti kakovosti ====

^ Značilnost ^ Opis ^
| Brez utripanja | Dvojno medpomnenje, diferenčno izpiranje |
| Pravilna podpora Unicode | Široki znaki, emoji, kurzor zaveden grafemov |
| Tematizacija | Žetoni slogov, plastenje stanj |
| Virtualizacija | Učinkovito izrisovanje velikih količin podatkov |
| Odzivnost | Sidranje kot privzeto, stabilno ob spremembi velikosti |
| Podpora slik | Kitty/Sixel z nadomestno rešitvijo |

==== Pregled arhitekture ====

<code>
┌─────────────────────────────────────────────────────────────┐
│  PXAML (Markup)                                             │
├─────────────────────────────────────────────────────────────┤
│  Control Model (TWvdS*) - Ciljno neodvisen                  │
├─────────────────────────────────────────────────────────────┤
│  TUI Renderer - Ciljno specifičen                           │
├─────────────────────────────────────────────────────────────┤
│  Render Surface → CellBuffer → DiffEngine                   │
├─────────────────────────────────────────────────────────────┤
│  Terminal IO (ANSI Escape Sequences)                        │
└─────────────────────────────────────────────────────────────┘
</code>

===== Ključni koncepti =====

==== Ciljno neodvisni modeli ====

Modeli kontrol ne vsebujejo **nobene** terminalsko specifične logike:

<code pascal>
(* PRAVILNO - Ciljno neodvisno *)
TWvdSButton = class(TWvdSControl)
private
  FCaption: string;
  FOnClick: TNotifyEvent;
public
  property Caption: string read FCaption write SetCaption;
  property OnClick: TNotifyEvent read FOnClick write FOnClick;
end;

(* PREPOVEDANO - Terminalsko specifično v modelu *)
TWvdSButton = class(TWvdSControl)
  procedure WriteAnsiSequence;  (* PREPOVEDANO! *)
end;
</code>

==== Ciljno specifični izrisovalniki ====

Izrisovalniki rišejo model v CellBuffer:

<code pascal>
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;
</code>

==== Sidranje kot privzeto ====

Vsaka kontrola ima **privzeto** omogočeno sidranje:

<code>
Anchors: Left, Top, Right, Bottom

Privzeto: Left+Top (stabilna pozicija)
Left+Right: Širina se raztegne s staršem
Top+Bottom: Višina se raztegne s staršem
Vsa štiri: Pravokotnik se raztegne v obe smeri
</code>

===== Dokumentacija za TUI =====

^ Dokument ^ Vsebina ^
| [[.:tui-engine|TUI Engine]] | CellBuffer, DiffEngine, zmogljivosti terminala |
| [[.:tui-controls|TUI Controls]] | Implementacija kontrol, fokus, vnos |
| [[.:tui-layout|TUI Layout]] | Sidranje, odzivnost, prelomne točke |

===== Hiter začetek: Ustvarjanje TUI kontrole =====

==== 1. Enota modela (ciljno neodvisna) ====

<code pascal>
unit WvdS.UI.Controls.MyControl;

type
  TWvdSMyControl = class(TWvdSControl)
  private
    FValue: string;
  public
    property Value: string read FValue write SetValue;
  end;
</code>

==== 2. Enota TUI izrisovalnika ====

<code pascal>
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;
</code>

==== 3. Manifest paketa ====

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

===== Preverjanje =====

Vsaka TUI implementacija mora biti preverjena:

<code>
[ ] Brez utripanja pri ponavljajočem se ponovnem izrisovanju
[ ] Sprememba velikosti proizvede stabilen razpored
[ ] Kazalec TextEdit je stabilen pri širokih/kombiniranih znakih
[ ] Table/List izrisuje 10k vrstic z gladkim drsenjem
[ ] Slike se pravilno obnašajo glede na TerminalCaps
[ ] Fokus ostane stabilen skozi prerazporeditev
</code>

===== Glejte tudi =====

  * [[.:tui-engine|TUI Engine]]
  * [[.:tui-controls|TUI Controls]]
  * [[.:tui-layout|TUI Layout]]
  * [[.:targets|Gradbeni cilji]]
  * [[.:control-entwicklung|Razvoj kontrol]]