# Forms-Referenz Terminal Basic

Rekonstruierte Referenz der Forms-Engine des Vorbilds (VBDOS 1.0) —
Grundlage für `tb-ui::forms` und den Formular-Designer. Primärquellen:
Original-Hilfedatei (dekodiert), `CONSTANT.BI`, Stringtabellen der
Original-Programme, Beispielprojekte. Aussagen ohne TODO sind daraus belegt.
Die zeilenweise Matrix mit Typ, Bereich, Vorgabe, Laufzeit-Schreibbarkeit
und Klassenquelle liegt im Change-Dokument
`openspec/changes/phase-4-objektmodell/klassen-und-eigenschaften.md`.
Als Beispiel-Gegenprobe dient `cout/vbdos` Commit
`1cdd2b32b829fe1721d0b6aecc433abc47a96fb6`; dessen binäre Formulare
`microsoft/check.frm`, `notepad.frm`, `qlbview.frm`, `seek.frm`,
`spindemo.frm`, `graphics/graphics.frm` und `misc/mentors/mentors.frm`
enthalten die dort ausgewiesenen Eigenschaften und Ereignisprozeduren.

## Koordinatenmodell

Einheit ist durchgängig die **Textzelle** (Spalte/Zeile), keine Twips.
`Left`/`Top` relativ zum Container, gültiger Bereich 0–254; `Height`/`Width`
für Controls 1–254, für Formulare bis Bildschirmgröße. `ScaleHeight`/
`ScaleWidth` (nur Form/PictureBox, read-only) = Innenmaß ohne Rahmen/Menü.
Maus-Koordinaten in Ereignissen sind SINGLE, aber in Zellen.

## Steuerelemente (exakte Klassennamen)

`CheckBox, ComboBox, CommandButton, DirListBox, DriveListBox, FileListBox,
Frame, HScrollBar, Label, ListBox, Menu, OptionButton, PictureBox, TextBox,
Timer, VScrollBar` — alle außer `Menu` über die Toolbox platzierbar
(Menüs entstehen im Menu Design Window). Default-Namen: `Check1`, `Combo1`,
`Command1`, `Dir1`, `Drive1`, `File1`, `Frame1`, `HScroll1`, `Label1`,
`List1`, `Option1`, `Picture1`, `Text1`, `Timer1`, `VScroll1`.

## Eigenschaften/Methoden/Ereignisse je Steuerelement

**Form** — Ereignisse: Click, DblClick, DragDrop, DragOver, GotFocus,
KeyDown, KeyPress, KeyUp, Load, LostFocus, MouseDown, MouseMove, MouseUp,
Paint, Resize, Unload. Methoden: CLS, DRAG, HIDE, LOAD, MOVE, PRINT,
PRINTFORM, REFRESH, SHOW, TEXTHEIGHT, TEXTWIDTH, UNLOAD. Eigenschaften:
AutoRedraw, BackColor, BorderStyle, Caption, ControlBox, CurrentX, CurrentY,
DragMode, Enabled, ForeColor, FormName, FormType, Height, Left, MaxButton,
MinButton, MousePointer, Parent, ScaleHeight, ScaleWidth, Tag, Top,
Visible, Width, WindowState.

**CommandButton** — Ereignisse: Click, DragDrop, DragOver, GotFocus,
KeyDown, KeyPress, KeyUp, LostFocus. Methoden: DRAG, MOVE, REFRESH,
SETFOCUS. Eigenschaften: BackColor, Cancel, Caption, CtlName, Default,
DragMode, Enabled, Height, Index, Left, MousePointer, Parent, TabIndex,
TabStop, Tag, Top, Value, Visible, Width. Darstellung nach Höhe:
1 = `<Text>`, 2 = einzeiliger Rahmen, ≥3 = Kasten; Mindestgröße 1×3.

**TextBox** — Ereignisse: Change, DragDrop, DragOver, GotFocus, KeyDown,
KeyPress, KeyUp, LostFocus. Methoden: DRAG, MOVE, REFRESH, SETFOCUS.
Eigenschaften: BackColor, BorderStyle, CtlName, DragMode, Enabled,
ForeColor, Height, Index, Left, MousePointer, MultiLine, Parent,
ScrollBars, SelLength, SelStart, SelText, TabIndex, TabStop, Tag, Text,
Top, Visible, Width.

**ListBox** — Ereignisse: Click, DblClick, DragDrop, DragOver, GotFocus,
Key*, LostFocus, Mouse*. Methoden: ADDITEM, DRAG, MOVE, REFRESH,
REMOVEITEM, SETFOCUS. Eigenschaften: BackColor, CtlName, DragMode, Enabled,
ForeColor, Height, Index, Left, List, ListCount, ListIndex, MousePointer,
Parent, Sorted, TabIndex, TabStop, Tag, Text, Top, Visible, Width.

**ComboBox** — wie ListBox plus Change, DropDown (Ereignisse), SelLength/
SelStart/SelText/Style/Text (Eigenschaften).

**CheckBox / OptionButton** — Ereignisse: Click (Option auch DblClick),
Drag*, GotFocus, Key*, LostFocus. Methoden: DRAG, MOVE, REFRESH, SETFOCUS.
Eigenschaften: BackColor, Caption, CtlName, DragMode, Enabled, ForeColor,
Height, Index, Left, MousePointer, Parent, TabIndex, TabStop, Tag, Top,
Value, Visible, Width.

**Frame** — nur DragDrop/DragOver; DRAG, MOVE, REFRESH (kein SetFocus);
Container für Gruppierung (OptionButton-Gruppen). `Index` und `TabIndex`
werden in den Originaldateien auch für Frames gespeichert.

**Label** — Ereignisse: Change, Click, DblClick, Drag*, Mouse*. Methoden:
DRAG, MOVE, REFRESH. Eigenschaften: zusätzlich Index, TabIndex, Alignment,
AutoSize, BorderStyle.

**HScrollBar/VScrollBar** — Ereignisse: Change, Drag*, GotFocus, Key*,
LostFocus (**kein** separates Scroll-Ereignis). Eigenschaften: zusätzlich
Attached (VBDOS-Spezifikum: am Formularrand angedockt; Laufzeit read-only),
LargeChange, Min, Max, SmallChange, Value.

**PictureBox** — Text-Zeichenfläche (PRINT/CLS aufs Control) und Container
für OptionButton-Gruppen. Ereignisse: Click, DblClick, Drag*, GotFocus,
Key*, LostFocus, Mouse*, Paint. Methoden: CLS, DRAG, MOVE, PRINT, REFRESH,
SETFOCUS, TEXTHEIGHT, TEXTWIDTH. Eigenschaften: zusätzlich Index, TabIndex,
TabStop, AutoRedraw, CurrentX, CurrentY, ScaleHeight, ScaleWidth.

**Timer** — Ereignis Timer, keine Methoden; Eigenschaften: CtlName, Enabled,
Index, Interval (0 = aus … 65 535 ms), Parent, Tag.

**Menu** — Ereignis Click; Eigenschaften Caption, Checked, CtlName, Enabled,
Index, Parent, Separator, Tag, Visible (Shortcut nur zur Entwurfszeit).

**DirListBox/DriveListBox/FileListBox** — Datei-Browser-Controls
(Path/Drive/FileName/Pattern/Archive/Hidden/Normal/ReadOnly/System;
Ereignisse u. a. Change, PathChange, PatternChange). Terminal Basic bildet
sie plattformneutral nach (Laufwerksliste → Wurzeln/Mounts).

## Standardwerte und Wertebereiche

| Eigenschaft | Bereich | Default |
|---|---|---|
| CheckBox.Value | 0 Unchecked · 1 Checked · 2 Grayed | 0 |
| OptionButton.Value | 0/−1 | 0 |
| CommandButton.Value | True löst Click aus | False |
| ComboBox.Style | 0 Dropdown · 1 Simple · 2 Dropdown List | 0 |
| BorderStyle (Form) | 0 None · 1 Fixed Single · 2 Sizable Single · 3 Fixed Double · 4 Sizable Double · 5 Fixed Solid · 6 Sizable Solid | 2 |
| BorderStyle (Control) | 0 None · 1 Single · 2 Double (nur Label/PictureBox) | Label 0; TextBox/PictureBox 1 |
| WindowState | 0 Normal · 1 Minimized · 2 Maximized | 0 |
| FormType | 0 Normal · 1 MDI-Container | 0 |
| Timer.Interval | 0–65 535 ms | 0 |
| ScrollBar Min/Max | −32 768…32 767 | 0 / 32 767 |
| Small-/LargeChange | 1…32 767 | 1 |
| TextBox.ScrollBars | 0 None · 1 H · 2 V · 3 Both | 0 |
| MultiLine/Sorted/Attached | Boolean, Laufzeit read-only | False |
| Alignment (Label) | 0 Left · 1 Right · 2 Center | 0 |
| DragMode | 0 Manual · 1 Automatic | 0 |
| MousePointer | 0–12 (Default, Block, Cross, I-Beam, …) | 0 |
| ForeColor/BackColor | 0–15 | 0 / 7 |
| Text (TextBox/ComboBox) | — | Entwurfszeit = CtlName |
| ListIndex | −1 = keine Auswahl | −1 |

**Keine Default-Eigenschaften:** `Text1 = "x"` gibt es nicht — Zugriff
immer explizit (`Text1.Text`). „Default" ist nur die CommandButton-
Eigenschaft (Enter-Taste); „Cancel" analog für Esc.

## Ereignis-Signaturen

```basic
SUB Form_KeyDown (KeyCode AS INTEGER, Shift AS INTEGER)
SUB ctl_KeyPress ([Index AS INTEGER,] KeyAscii AS INTEGER)
SUB Form_MouseDown (Button AS INTEGER, Shift AS INTEGER, X AS SINGLE, Y AS SINGLE)
SUB Form_DragDrop (Source AS CONTROL, X AS SINGLE, Y AS SINGLE)
SUB Form_DragOver (Source AS CONTROL, X AS SINGLE, Y AS SINGLE, State AS INTEGER)
SUB Form_Unload (Cancel AS INTEGER)   ' Cancel <> 0 verhindert Entladen
```

Shift-Bitfeld 1 Shift · 2 Ctrl · 4 Alt; Button 1 links · 2 rechts;
DragOver-State 0 Enter · 1 Leave · 2 Over. Bei Steuerelement-Arrays steht
`Index AS INTEGER` immer vorn. KeyAscii ist bei uns ein Unicode-Codepoint
(UTF-8-Abweichung); klassische KeyCode-Konstanten bleiben gültig
(Vorbild-Eigenheit: Entf = 127).
Ereignisse ohne eine der oben genannten Argumentfamilien haben keine
Parameter. Bei Arrays wird ausschließlich `Index AS INTEGER` vorangestellt;
die restliche Signatur bleibt unverändert.

## SCREEN-Objekt

Eigenschaften: ActiveControl, ActiveForm, AutoRedraw, ControlPanel,
Height, Width (Zeichen, read-only — bei uns die **aktuelle Terminalgröße**,
Abweichung: das Vorbild lieferte fest 25/43/50 × 80), MousePointer.
Methoden: HIDE, SHOW (alle sichtbaren Formulare ein-/ausblenden). `SCREEN.ControlPanel(0–17)`
konfiguriert Systemfarben/-effekte (AccessKey-/Desktop-/Menü-/Titel-
Farben, Schatten, 3D-Effekte, Desktop-Füllzeichen) — Konstanten in der
Konstanten-Include-Datei.

## Show/Hide/Load/Unload und Modalität

`form.SHOW [style%]`: **0 = modeless (Standard), 1 = modal**; lädt bei
Bedarf. Bei modal läuft der Code nach `SHOW` erst nach Schließen weiter.
Modal-Stacking-Regeln → Fehler 400–403 (u. a. „MDI form cannot be shown
modally"). `HIDE` setzt nur `Visible = False`; `LOAD`/`UNLOAD` mit
Load-/Unload-Ereignis (Cancel-Parameter). `LOAD/UNLOAD ctl(index%)` für
Steuerelement-Arrays (Entwurfszeit-Elemente sind nicht entladbar,
Fehler 362); deren Eigenschaften sind über `ctl(index%).Eigenschaft`
adressierbar und werden beim `LOAD` vom Entwurfszeit-Element 0 geklont.

## Menüsystem

Definition pro Formular im **Menu Design Window**, bis zu 6 Ebenen.
Felder: Caption (`&` Access-Key, `-` Separator), CtlName, Tag, Index,
Checked/Enabled/Visible/Separator, Shortcut-Dropdown. Regeln: Separatoren
nicht checked/disabled/mit Shortcut; Menütitel ohne Shortcut.
Menü-Steuerelement-Arrays sind möglich.

## Steuerelement-Arrays, Drag & Drop, Custom Controls

- **Control-Arrays:** gleiche CtlName + Index; Laufzeit-Erzeugung per
  `LOAD ctl(index%)`.
- **Drag & Drop:** DragMode 0/1, Methode `DRAG action%` (0 Cancel ·
  1 Begin · 2 Drop), Ereignisse DragDrop/DragOver mit `Source AS CONTROL`.
- **Custom Controls:** das Vorbild lud sie aus Quick-Libraries; für
  Terminal Basic ist ein natives Erweiterungsmodell **Stufe 2** (PLAN.md).

## Offene Detailfragen

- Exakte Optik je Steuerelement-Zustand (normal/fokussiert/deaktiviert):
  aus den Original-Screenshots ableiten (Phase 4)
- Z-Reihenfolge/Überlappung: Verhalten bei überlappenden Controls
- Timer-Reihenfolge bei mehreren gleichzeitig fälligen Timern
- `.FRM`-Textformat: exakte Serialisierung (siehe dateiformate.md)