TerminalBasic/docs/ide-referenz.md

# IDE-Referenz Terminal Basic

Rekonstruierte UX-Spezifikation der IDE des Vorbilds (VBDOS 1.0, 1992) —
Grundlage für `tb-ide` (Phase 5). Quellen: Original-Hilfedatei (dekodiert),
README des Originalpakets, Screenshots (Pixelanalyse), Sekundärliteratur.
Konfidenz je Abschnitt vermerkt; `TODO` = offen. Konkrete Farbquellen und
Kontrastanpassungen: siehe Abschnitt 4a.

Die IDE besteht im Vorbild aus zwei Programmen: der **Programmierumgebung**
und dem separaten **Form Designer** (eigene Menüleiste, Wechsel über
„Event Procedures"/F12 bzw. View→Form). Terminal Basic bildet beides in
**einem** Prozess ab, behält aber die zwei Modi mit identischer Bedienung.

## 1. Menüstruktur (Konfidenz: sicher)

Menüleiste der Umgebung: **File Edit View Search Run Debug Options Window**,
**Help** rechtsbündig. Form-Designer-Modus: **File Edit View Tools Options
Window Help**. `───` = Separator, `•` = Toggle-Markierung.

- **File (Alt+F):** New Project / Open Project… / Save Project ─── New Form /
  New Module… / Add File… / Remove File… / Save File / Save File As… ───
  Load Text… / Save Text… ─── Print… / Shell ─── Exit **Alt+F4**
- **Edit (Alt+E):** Undo **Ctrl+Z** ─── Cut **Ctrl+X** / Copy **Ctrl+C** /
  Paste **Ctrl+V** / Clear **Del** ─── New Sub… / New Function… /
  Event Procedures… **F12**
- **View (Alt+V):** Code… **F2** / Form… **Shift+F12** ─── Next Statement /
  Output Screen **F4** ─── Included File / •Included Lines
  *(Designer-Modus: … ─ Menu Bar **F10** / Grid Lines)*
- **Search (Alt+S):** Find… / Selected Text **Ctrl+\\** / Repeat Last Find
  **F3** / Change…
- **Run (Alt+R):** Start **Shift+F5** / Restart / Continue **F5** / Pause (Ctrl+Break) /
  Modify COMMAND$… ─── Make EXE File… / Make Library… ─── Set Start-up File…
- **Debug (Alt+D):** Add Watch… / Instant Watch… **Shift+F9** / Watchpoint… /
  Delete Watch… / Delete All Watch ─── •Trace On / •History On ───
  Toggle Breakpoint **F9** / Clear All Breakpoints / •Break on Errors /
  Set Next Statement
- **Options (Alt+O):** Display… / Set Paths… / Right Mouse… / Save… /
  •Syntax Checking (Einstellungen persistent)
- **Window (Alt+W):** New Window / Arrange All ─── Calls / Debug / Help /
  Immediate / Output / Project ─── Liste offener Code-Fenster (• = aktiv)
  *(Designer-Modus: Color Palette / Menu Design Window / Toolbox / Help /
  •Form: … )*
- **Help (Alt+H):** Index / Contents ─── Keyboard ─── Topic: **F1** /
  Using Help **Shift+F1** / Tutorial ─── About…

Bedienung: **Alt** (oder F11) aktiviert die Menüleiste, hervorgehobene
Buchstaben wählen, Esc bricht ab, „…" kündigt Dialog an.

## 2. Fensterverwaltung (Konfidenz: sicher)

- MDI-artig: alle Fenster/Dialoge sind Kinder der IDE-Fläche. Titelleiste
  mit Control-Menü-Box links, Minimieren/Maximieren rechts, Rahmen,
  Scrollbalken; Code-Fenster nummeriert („[1] Untitled").
- Tasten: **F6/Ctrl+F6** nächstes, **Shift+F6** vorheriges Fenster,
  **Ctrl+F4** schließen, **Ctrl+F7** verschieben, **Ctrl+F8** Größe,
  **Ctrl+F9** minimieren, **Ctrl+F10** maximieren, **Ctrl+F5**
  wiederherstellen, **Alt+Minus** Control-Menü; „Arrange All" kachelt.
- Control-Menü (Restore, Move, Size, Minimize, Maximize, Close): fensterlokal
  für alle Fensterarten gleich, per Alt+Minus oder Klick auf „[≡]" des aktiven
  Fensters. Es hängt am Symbol: linke Spalte gleich Symbolspalte, bevorzugt
  direkt unter der Titelzeile; fehlt dort Platz (z. B. minimiertes Fenster am
  unteren Rand), klappt es nach oben bis an die Titelzeile; am rechten Rand
  rückt es nur so weit nach links, dass es in die Arbeitsfläche passt. Die
  Menüleiste zeigt dabei keinen ausgewählten Titel.
- **Project Window** (Start: rechts angedockt): Buttons „Form"/„Code"
  (Enter öffnet, „Form" wechselt in den Designer) + Modulliste (.FRM/.BAS).
- **Immediate Window** über Alt+W,I — nicht permanent sichtbar (anders als QB).
- **Debug Window** (read-only: Watches/Watchpoints), **Output Window**
  (Ausgabebildschirm als Fenster; **F4** = echter Vollbild-Output),
  **Calls**- und **Help**-Fenster.

## 3. Form Designer (Konfidenz: sicher)

- **Toolbox** links; Einträge: Check Box, Combo Box, Command Button,
  Dir List, Drive List, File List, Frame, HScrollBar, Label, List Box,
  Option Button, Picture Box, Text Box, Timer, VScrollBar (identisch als
  Tools-Menü).
- Platzieren: Doppelklick auf Toolbox-Eintrag oder Tool wählen + auf der
  Form aufziehen; **Sizing Handles** (■ an den Ecken); Verschieben per Drag.
  Tastatur: Pfeile = 1 Zelle verschieben, **Ctrl+Pfeile** = 5 Zellen,
  **Shift+Pfeile** = Größe, **Tab/Shift+Tab** = Control-Wechsel;
  Mehrfachauswahl mit Strg+Klick (nur Maus). Raster: View→Grid Lines.
- **Properties Bar oben** statt Eigenschaftsfenster:
  `Property: [Caption]↓  Value: […]↓ │ Spalte,Zeile │ BxH`.
  **F2** springt in die Value-Box; **F10** toggelt Menüleiste ↔ Properties
  Bar (nur eine sichtbar). Keine Statuszeile im Designer.
- **Menu Design Window** (Alt+W,M): Caption (`&` = Access-Key, `-` =
  Separator), CtlName, Tag, Index; Checked/Enabled/Visible/Separator;
  Shortcut-Dropdown; Outlining-Buttons (Ebene/Reihenfolge, Einfügen,
  Löschen, Done).
- **Color Palette** (Alt+W,C): ForeColor/BackColor wählen, Farbe per Drag
  auf die Form ziehen.

## 4. Farbschema (Konfidenz: sicher für belegte Elemente)

| Element | Farben (DOS-Palette) |
|---|---|
| Menüleiste | Schwarz (0) auf Hellgrau (7) |
| Desktop | Füllzeichen ▒, Hellgrau (7) auf Schwarz (0); Füllzeichen einstellbar |
| Code-Fenster | Hellgrau/Weiß auf **Blau (1)** |
| Titelleiste aktiv | **Weiß (15) auf Magenta (5)** — VBDOS-Spezifikum |
| Rahmen/Scrollbalken | Schwarz auf Hellgrau (7) |
| Project Window/Dialoge | Schwarz auf Hellgrau (7); Fokus-Button mit weißem Doppelrahmen; Deaktiviertes Dunkelgrau (8); Listenauswahl Weiß auf Schwarz |
| Statuszeile | Schwarz auf **Cyan (3)** |

Alles über **Options→Display** je „User-Interface Element" umkonfigurierbar
(Fore-/Background aus 16 Farben, Desktop-Füllzeichen, Tabweite).
Laufzeit-Defaults kompilierter Programme weichen ab (Titel Weiß auf Schwarz).

## 4a. Farbabbildung und Kontrast (Phase 6)

Die DOS-Farbnummern in Options→Display bleiben erhalten. IDE, Formularvorschau
und BASIC-Ausgabe verwenden dieselbe feste klassische RGB-Palette. Jede
Farbe wird als 24-Bit-Vorder-/Hintergrundwert ausgegeben, unabhängig von
`TERM`, `COLORTERM`, `NO_COLOR` oder der ANSI-Palette des Terminalprofils.
Es gibt keinen Rückfall auf Index- oder Profilfarben. Die globale
Terminalpalette wird nicht verändert; gespeichert werden weiterhin
DOS-Farbnummern, und BASIC bestimmt seine eigenen ForeColor/BackColor-Werte.

Beispielwerte: Codehintergrund `#0000AA`, Codeschrift `#AAAAAA`, aktiver
Titel `#FFFFFF` auf `#AA00AA`. DOS-Farbe 6 ist Braun (`#AA5500`).
Fensterflächen werden vor dem Zeichnen geleert, damit Desktop-Füllzeichen
und Inhalte verdeckter Fenster keine scheinbar helleren Hintergründe erzeugen.

Die Ausgabe setzt einen Terminalemulator mit 24-Bit-Farbunterstützung voraus.
Fehlende RGB-Unterstützung bleibt ein offener Zielbefund. Transparenz,
Farbfilter und Inaktivitätsdimmung sind nachgelagerte Emulatorfunktionen;
sie werden für die visuelle Farbprüfung getrennt protokolliert.

### Referenzfundstellen

Die folgenden Originalprogramm-Ansichten wurden am 07.09.2026 visuell
abgeglichen; die Beschreibung des Archivs ist keine Quelle für die genaue
Palette. Ansichten belegen Flächen und Rollen, keine heutige Terminalausgabe.

- [Code View: Code, Run-Menü, Projekt und Status](https://winworldpc.com/screenshot/c39439e2-80a2-c692-222e-11c3a4e284a2/207ae280-a231-57c3-b111-c3a4c2a90f70)
- [Form View: Designer, Properties, Werkzeuge und Palette](https://winworldpc.com/screenshot/c39439e2-80a2-c692-222e-11c3a4e284a2/1865c3a7-0957-c3b1-11c3-a4c2a90f7054)
- [About: Dialog, aktiver Titel und Fokusrahmen](https://winworldpc.com/screenshot/c39439e2-80a2-c692-222e-11c3a4e284a2/0de2809a-6fc3-b757-c3b1-11c3a4c2a90f)

| Rolle | Beobachtung im Vorbild | Terminal Basic / Anpassung |
|---|---|---|
| Code | Helle Schrift auf dunklem Blau | DOS 7 auf 1; Auswahl invertiert dasselbe Paar |
| Aktiver Titel / Dialogtitel | Weiß auf Magenta | DOS 15 auf 5; dunkles Magenta, kein Pastellrosa |
| Inaktives Projekt / Rahmen | Schwarz auf Grau | DOS 0 auf 7; aktive Fenster zusätzlich mit Doppelrahmen |
| Menü, Projekt, Dialog | Schwarz auf Grau; Auswahl hell auf Schwarz | DOS 0 auf 7, Auswahl 15 auf 0 |
| Status | Schwarz auf Cyan | DOS 0 auf 3 |
| Designer-Werkzeuge | Schwarz auf Cyan | DOS 0 auf 3 |
| Properties Bar | Helle Schrift auf Cyan | Bewusste Kontrastanpassung: Schwarz auf Cyan |
| Fokusrahmen und Sizing Handles | Teilweise Weiß auf Grau | Schwarzer Doppelrahmen; schwarze Handle-Zeichen auf Gelb |
| Deaktivierte Beschriftungen | Nicht ausreichend durch diese Ansichten belegt | Lesbares Schwarz auf Grau, Menüs zusätzlich `×` und kursiv |
| Hilfe und Debuggermarkierungen | In diesen Ansichten nicht belegt | Dunkelblaue Hilfetitel/Links auf Grau; Fokus Weiß auf Blau; Breakpoints Weiß auf Rot, Ausführungszeile Schwarz auf Gelb |

Die Standardpaare müssen bei RGB-Ausgabe mindestens 4,5:1
Textkontrast erreichen; notwendige nichttextuelle Fokusmarkierungen mindestens
3:1. Die Zelltests prüfen auch Rahmen und Handles auf mindestens 4,5:1
gegen ihren eigenen Hintergrund. Benutzerauswahl in Display bleibt frei;
bestehende Optionsdateien werden nicht umgeschrieben. BASIC-Ausgabe und
Formularvorschau behalten ihre programmbestimmten Farbattribute, während
Designer-Werkzeuge und Handles die IDE-Farben verwenden.

Die sRGB-Kontrastberechnung ergibt für die wichtigsten Standardpaare:

| Rolle | RGB-Kontrast |
|---|---|
| Code / Hilfelink | 5,72:1 |
| Aktiver Titel | 6,38:1 |
| Menü / Dialog / deaktivierter Text | 9,04:1 |
| Status / Werkzeuge | 7,33:1 |
| Auswahl | 21,00:1 |
| Linkfokus / Debugger | 13,29:1 |
| Breakpoint | 7,75:1 |
| Ausführung / Handle | 19,69:1 |

### Prüffolge für Change 05

Je Pflichtzelle Windows amd64/Windows Terminal, macOS arm64/Terminal.app,
Linux amd64/xterm, Linux amd64/VTE, Linux arm64/xterm und Linux arm64/VTE:

1. Revision und Executable-Prüfsumme, OS-/Terminalversion, Profil,
   `TERM`/`COLORTERM`, `NO_COLOR`, Transparenz und Dimmung protokollieren.
   Mit einem frischen Optionsverzeichnis sowie einer Kopie der vorhandenen
   Optionen prüfen; echte Benutzeroptionen dabei erhalten.
2. `tests/compat/datarohtext.bas` öffnen. Unmarkierten Editor und Ctrl+A-Auswahl
   erfassen, anschließend mit F6 ins Projekt wechseln. Erwartet: dunkles
   Blau, lesbare Auswahl, unterscheidbare aktive/inaktive Rahmen und Titel.
3. Run-Menü einschließlich deaktiviertem Eintrag, Options→Display und einen
   Exportdialog mit ungültiger Eingabe öffnen. Erwartet: lesbare Mnemonics,
   Fokusfelder, deaktivierte Texte und Fehlerhinweise.
4. F1-Hilfe öffnen, mit Tab einen Link fokussieren. F9-Breakpoint setzen und
   mit F5 bis zum Halt laufen. Erwartet: lesbare Überschriften und Links,
   sichtbare Breakpoint-/Ausführungsmarkierungen.
5. Neue Form anlegen, Toolbox und Palette öffnen, Control auswählen und
   Größe ändern. Erwartet: cyanfarbene Werkzeuge/Properties, lesbare 16
   Farbbeschriftungen und Handles; ForeColor/BackColor der Vorschau bleiben
   unabhängig vom IDE-Theme.
6. Dieselben Ansichten mit absichtlich abweichender ANSI-Palette prüfen.
   RGB-Farben von IDE und BASIC-Ausgabe müssen stabil bleiben. Transparenz und
   Inaktivitätsdimmung getrennt ein-/ausschalten und Abweichungen als
   Emulatorverhalten dokumentieren. Auch ohne `COLORTERM`, mit `TERM=vt100`
   und mit `NO_COLOR=1` muss die Anwendung dieselben RGB-Werte ausgeben.
7. Options ändern, speichern und neu starten; Auswahl muss erhalten sein.
   IDE beenden: globale Palette und normale Shell-Anzeige müssen erhalten sein.

Pro Schritt Soll/Ist, Bild-/Transkriptbezug und gegebenenfalls Befund führen.
Headless-Zelltests ersetzen diese visuellen Zielnachweise nicht. Die
vollständige Matrix ist noch offen; die Originalansichten oben sind keine
bestandenen TerminalBasic-Zielprüfungen.

## 5. Editor-Verhalten (Konfidenz: sicher; Keyword-Großschreibung: wahrscheinlich)

- **Syntax Checking** (Toggle, Standard an): beim Verlassen der Zeile wird
  geprüft (Fehlerdialog), formatiert (Leerzeichen, Keywords groß) und die
  Zeile sofort in ausführbare Form übersetzt. Für Terminal Basic heißt das:
  zeilenweise Inkrementalübersetzung ist Teil des Editors (passt zur
  Instant-Compile-Anforderung).
- **DECLARE**-Prototypen werden beim Speichern automatisch erzeugt;
  DEFtype-Zeilen werden automatisch in neue Prozeduren übernommen.
- Tastatur: CUA (Ctrl+X/C/V/Z, Einfg, Pos1/Ende) **plus** WordStar-Chords
  (Ctrl+Q…, Ctrl+Y Zeile löschen, Bookmarks Ctrl+K,0–3 / Ctrl+Q,0–3).
  Prozedurnavigation **Shift+F2/Ctrl+F2**.

## 6. Run/Debug-Tasten (Konfidenz: sicher)

**Shift+F5** Start · **F5** Continue · **F4** Output-Screen-Toggle ·
**F7** bis Cursor · **F8** Single Step · **F10** Procedure Step ·
**F9** Breakpoint · **Shift+F9** Instant Watch · **Shift+F8/Shift+F10**
History rückwärts/vorwärts (bei History On) · **F12** Event Procedures.
Break-Modus: Immediate Window akzeptiert `PRINT`, Zuweisungen,
Prozeduraufrufe, `ERROR n`; „Set Next Statement" verlegt die Ausführung.
„Break on Errors" stoppt im Fehlerhandler.

## 7. Hilfe (Konfidenz: sicher)

**F1** kontextsensitiv (auch rechte Maustaste, konfigurierbar),
**Shift+F1** Using Help. Hyperlinks als ◄Thema►, Tab/Shift+Tab springt,
Enter folgt, **Alt+F1** zurück (20 Ebenen), Ctrl+F1 nächstes Topic,
Esc schließt. Hilfe im eigenen Fenster; Index, Contents, Keyboard-Guide,
Tutorial. → Terminal Basic: Hilfeinhalt sind die Markdown-Dokumente aus
`docs/` (Sprach- und Bibliotheksreferenz, Ist-Stand der Implementierung),
gerendert im Help-Fenster mit dynamischem Umbruch nach Fenstergröße;
Navigation wie im Vorbild (F1 kontextsensitiv, Tab/Enter, Alt+F1 zurück).

## 8. Statuszeile (Konfidenz: sicher; Caps/Num: unklar)

Unterste Zeile, Schwarz auf Cyan. Links kontextabhängige Shortcuts in
spitzen Klammern (`<Shift+F1=Help> <F6=Window> <F2=Code> <F5=Run>
<F8=Step>`), per Mausklick auslösbar. Rechts `Zeile:Spalte`
(`00001:001`). TODO: Caps/Num-Anzeige.

## 9. Start (Konfidenz: wahrscheinlich)

„Log-On Screen" (Begrüßung, Version, Copyright), danach leeres Projekt:
Code-Fenster „[1] Untitled", Project Window „Untitled". Kein
Survival-Guide-Dialog, kein Easy/Full-Menüs-Konzept. TODO: Splash vs. Dialog.

## 10. Interpreter vs. Compiler (Konfidenz: sicher)

Die Umgebung führt P-Code-übersetzte Zeilen sofort aus; der separate
Compiler erzeugt native EXEs (wahlweise standalone oder mit Runtime-Modul).
Nur die Umgebung hat: Immediate Window, Watches/Watchpoints, Breakpoints,
Stepping, History-Trace, Set Next Statement, automatische Bereichs-/
Überlaufprüfungen. → Terminal Basic: `tb` (IDE) und `tbc`
(Standalone-Compiler) teilen sich dieselbe TBVM, damit es — anders als im
Vorbild — **keine** Verhaltensunterschiede zwischen IDE-Lauf und
kompiliertem Programm gibt (dokumentierte Abweichung, gewollt).

## Übernahme-Entscheidungen für Terminal Basic

1. Menüstruktur, Tastenbelegung, Fensterverwaltung und Farbschema werden
   originalgetreu übernommen (inkl. Magenta-Titelleiste, Options→Display).
2. Umgebung und Form Designer werden ein Prozess mit zwei Modi; der
   F12/Shift+F12-Wechsel bleibt erhalten.
3. Zeilenweises Syntax-Checking mit Formatierung/Normalisierung ist
   Editor-Standard (abschaltbar wie im Vorbild).
4. IDE-Lauf und `tbc`-Kompilat verhalten sich identisch (gleiche TBVM).
5. MS-DOS-spezifische Toolbox-Controls (Dir/Drive/File List) werden als
   plattformneutrale Datei-Browser-Controls nachgebildet.
6. **Dynamische Terminalgröße** (2026-09-02): die IDE nutzt das gesamte
   Terminal — Desktop, Fensterverwaltung und Formulare passen sich an;
   Mindestgröße 80×25, darunter nur ein Hinweis (btop-artig).