TerminalBasic/docs/ide-bedienung.md

# Terminal Basic IDE bedienen

`cargo run -p tb-ide -- [Projekt.mak|Modul.bas|Formular.frm]` startet die IDE.
Ohne Datei erscheint ein neues Projekt mit `[1] Untitled` und dem Project
Window rechts. Versions- und Copyright-Begrüßung blockieren keine Eingabe.
Bei bereits vorhandener `Untitled.bas` bekommt das neue Dokument einen
freien Namen. Es wird beim Start keine Datei angelegt.

Das Terminal muss mindestens 80×25 Zellen haben. Darunter erscheint nur
der Größenhinweis; Dokumente, Fokus und Fensterzustand bleiben erhalten.
Beim Vergrößern werden die Fenster wieder innerhalb der Terminalfläche
dargestellt. Normales Beenden und Fehlerpfade stellen Raw Mode, Cursor,
Mausmodus und Alternate Screen zurück.

## Menüs, Fenster und Dialoge

- Alt plus Menübuchstabe oder F11 öffnet die Menüleiste. Pfeile wählen
  Menü/Eintrag, Enter führt aus; der unterstrichene Buchstabe wählt direkt.
  Esc bricht ab. F11 ist die Alternative, wenn das Terminal Alt allein
  nicht meldet. Menüs sind auch anklickbar, Help steht rechts.
- File enthält Projekt- und Dateiaktionen einschließlich New Form,
  New Module, Add/Remove File, Save File/As, Load/Save Text und Exit.
  Run → Set Start-up File speichert eine Auswahl oder den bisherigen Standard.
- Dialoge binden Tastatur und Maus an sich. Tab/Shift+Tab wechselt das Feld,
  Links/Rechts ändert Auswahlwerte, Leertaste schaltet Kästchen. Textfelder
  unterstützen Cursor, Pos1/Ende, Backspace/Entf und Ctrl+A zum Ersetzen.
  Enter/OK übernimmt, Esc/Abbrechen verwirft den Dialog.
- F2 in einem Dateipfad öffnet die Dateiauswahl. Links/Rechts wählt einen
  Eintrag, Enter öffnet ein Verzeichnis oder übernimmt eine Datei. Esc
  kehrt zum vorherigen Dialog mit dessen Angaben zurück. Neue Dateinamen
  lassen sich direkt ins Pfadfeld schreiben.
- F6/Ctrl+F6 bzw. Shift+F6 wechselt Fenster. Ctrl+F4 schließt eine Ansicht;
  Dokument und Änderungen bleiben im Projektmodell erhalten. Alt+Minus
  oder die Control-Menü-Box öffnet die Fensterbefehle.
- Ctrl+F7 verschiebt und Ctrl+F8 skaliert mit Pfeilen (Ctrl+Pfeile: fünf
  Zellen); Enter bestätigt, Esc stellt die vorige Geometrie wieder her.
  Ctrl+F9 minimiert, Ctrl+F10 maximiert, Ctrl+F5 stellt die Normalgeometrie
  wieder her. Window → Arrange All kachelt, New Window öffnet eine weitere
  Ansicht desselben Dokuments. Die Window-Liste markiert die aktive Ansicht.
- Im Project Window wählen Pfeile das Mitglied; Enter öffnet Code oder
  Formular entsprechend dem Dateityp. Form/Code-Buttons öffnen die gewählte
  Ansicht. View → Code/Form bietet zusätzlich einen Auswahldialog.
- Die Umgebung zeigt unten anklickbare Tastenkürzel und `00001:001` als
  Zeile/Spalte. Der Designer besitzt stattdessen die Properties Bar.
  F10 wechselt dort zwischen Menü- und Properties Bar, F2 fokussiert Value.
  Die fachliche Formularbearbeitung folgt in Change 05.

## Speichern und Wechseln

Save File nutzt den bestehenden Pfad; neue Dateien, Importziele und
Speicherkonflikte öffnen den Speicherdialog. Save Project zeigt Projektziel
und Dokumentziele mit separaten Überschreibentscheidungen. Eine Änderung
eines Pfades allein autorisiert kein Überschreiben einer vorhandenen Datei.
Binäre FRM-Originale bleiben auch mit gesetzter Überschreibentscheidung
geschützt; für bearbeitete Importe ist ein anderes Textziel erforderlich.

Beim Projektwechsel und Beenden stehen Abbrechen, Speichern und Verwerfen
zur Auswahl. Abbrechen ist vorausgewählt. Bei einem Teilspeicherfehler
bleibt der Dialog mit allen Angaben offen: erfolgreich gespeicherte Dateien
sind gespeichert, übrige Änderungen bleiben erhalten; die IDE schließt
nicht. Die MAK-Datei wird zuletzt geschrieben. Details stehen in
[Dateiformate](dateiformate.md#bearbeitete-dokumente-und-speichern).

Load Text fügt am Cursor als eine Undo-Aktion ein; Save Text exportiert im
Rahmen den gesamten Code. Der Dokumentvertrag unterstützt bereits
Auswahlexport; die Auswahlbedienung gehört zum Editor-Change 03. Remove
File löscht keine Datei; beim Entfernen der Startdatei ist die Wahl eines
Ersatzes oder des bisherigen Standards ausdrücklich im Dialog enthalten.

## Display und Benutzereinstellungen

Options → Display bietet Vorder- und Hintergrund (0–15) für Menü, Desktop,
Code, aktiven Titel, Rahmen, Dialog/Projekt und Status. Default ist Schwarz
auf Hellgrau für Menüs/Dialogs, Hellgrau auf Blau für Code, Weiß auf Magenta
für aktive Titel und Schwarz auf Cyan für den Status. Desktop: `▒`,
Hellgrau auf Schwarz; Tabweite: 8. Ein Desktopzeichen muss genau eine
Terminalzelle belegen, Tabweite liegt zwischen 1 und 32. Änderungen gelten
sofort für die IDE; BASIC-Laufzeitfarben bleiben unabhängig.

Set Paths verwaltet Quellen-, Ausgabe- und Include-Verzeichnisse. Mehrere
Includes werden mit `|` getrennt; relative Optionspfade werden beim
Übernehmen relativ zum Projektverzeichnis absolut aufgelöst. Das Include
neben der Quelldatei hat Vorrang vor Suchverzeichnissen. Right Mouse
schaltet Kontext-Hilfe per Rechtsklick (Default an); die Hilfefunktion
folgt in Change 07. Syntax Checking ist zunächst an; dessen fachliche
Editorwirkung folgt in Change 03.

Erst Options → Save… / OK schreibt die versionierte Benutzerdatei:

| System | Pfad |
| --- | --- |
| Unix mit absolutem XDG_CONFIG_HOME | `$XDG_CONFIG_HOME/TerminalBasic/options.ini` |
| macOS ohne XDG_CONFIG_HOME | `$HOME/Library/Application Support/TerminalBasic/options.ini` |
| anderes Unix ohne XDG_CONFIG_HOME | `$HOME/.config/TerminalBasic/options.ini` |
| Windows | `%APPDATA%/TerminalBasic/options.ini` |

Die Datei ist unabhängig vom Arbeitsverzeichnis. Ungültige Werte erhalten
eine Diagnose und behalten die Vorgabe; unbekannte Schlüssel werden mit
Hinweis ignoriert. Unbekannte Versionen/ungültige Textkodierung verwenden
Defaults. Schreibfehler erhalten die aktuellen, ungespeicherten Optionen.
Externe Änderungen der Optionsdatei werden vor dem Ersetzen erkannt.

## Native Exporte: UI in Phase 5, Erzeugung in Phase 6

Run → Make EXE File… (Alt+R, E) und Make Library… (Alt+R, L) öffnen
vollständig bedienbare Dialoge. Artefaktart ist das native eigenständige
Executable bzw. die native Systembibliothek. Zielsystem (Linux/macOS/Windows)
und Architektur (x86_64/aarch64) sind auswählbar; Vorgabe ist das laufende
Zielsystem. Ausgabepfad und Überschreibentscheidung werden je Auftrag
erfasst. Die Auswahl ist noch keine Zusage einer vom Backend unterstützten
Kombination; die Phase-6-Plattformmatrix bestätigt die tatsächlichen Ziele.

Prüfen/Enter validiert die Angaben und schützt Projektdatei, geöffnete
Dokumente und binäre FRM-Originale. Leere/ungültige Pfade, fehlende
Zielverzeichnisse, bestehende Ziele ohne Zustimmung und `.tbc` als natives
Ziel ergeben eine Diagnose; die anderen Angaben bleiben erhalten.

Nur **Erzeugen** ist bis Phase 6 gesperrt, mit dem Hinweis „Native
Erzeugung folgt in Phase 6“. Ein Produktionsaufruf schreibt keine Datei
und meldet keinen erfundenen Erfolg. Der vorbereitete Auftrag trägt
Projektidentität und Revisionsstand, Artefakt, Zielsystem, Architektur,
Pfad und Überschreibentscheidung. Die UI kann zu diesem Auftrag Laufend,
Erfolg, Fehler und Abbruch darstellen. Oberflächentests speisen diese
Ergebnisse kontrolliert ein; sie belegen keine native Erzeugung.

Die tatsächliche Erzeugung und reale Backend-Anbindung, native Formate,
Library-Symbole/Aufrufvertrag und der native Verbraucher-Nachweis stehen
explizit in [PLAN.md, Phase 6](../PLAN.md). Ein umbenanntes TBC erfüllt
keines der beiden Exportziele.

## Befehlsabdeckung nach Change 02

Alle Referenzbefehle sind in ihrer Menüfolge vorhanden. Fachbefehle der
folgenden Changes sind sichtbar deaktiviert und zeigen einen
Verfügbarkeitsgrund; ihre Kürzel gelangen nicht versehentlich an BASIC.
Ctrl+C im Editor ist Kopieren (Fachfunktion 03), bei laufendem Programm mit
Output-Fokus wird Ctrl+C an den Programmeingabepfad weitergereicht.

| Bereich | Rahmenaktion jetzt | Fachaktion im Folgechange |
| --- | --- | --- |
| File | New/Open/Save Project, New Form/Module, Add/Remove File, Save File/As, Load/Save Text, Exit | Print/Shell: 04 |
| Edit | Undo über Dokumentaktionen; einfacher Texteinstieg | Cut/Copy/Paste/Clear, New Sub/Function: 03; Event Procedures: 05 |
| View | Code/Form-Auswahl, Designer Menu Bar/Value-Fokus | Included File/Lines: 03; Output Screen: 04; Grid Lines: 05; Next Statement: 06 |
| Search | Vollständiges Menü und Kürzelzuordnung | Find, Selected Text, Repeat Last Find, Change: 03 |
| Run | Set Start-up File und beide Make-Dialoge | Start/Restart/Continue/COMMAND$ und Startup-Ausführungswirkung: 04; native Erzeugung: Phase 6 |
| Debug | Vollständiges Menü und Kürzelzuordnung, einschließlich F7/F8/F9/F10 und History | Watches, Watchpoints, Trace, History, Breakpoints, Break on Errors, Set Next Statement: 06 |
| Options | Display, Set Paths, Right Mouse, Save, Syntax Checking | Syntaxwirkung: 03; Kontext-Hilfe: 07 |
| Window | New Window, Arrange All, Calls/Debug/Help/Immediate/Output/Project, aktive Codeliste, alle Fensterkürzel | Output-Inhalt: 04; Debug/Calls/Immediate-Inhalte: 06; Hilfeinhalt: 07 |
| Designer Tools/Window | Tools-Menü, Formliste und gemeinsamer Fenster-/Modusrahmen | Controls/Toolbox, Color Palette, Menu Design Window: 05 |
| Help | Vollständiges Menü, About und Help-Fensterrahmen | Index, Contents, Keyboard, Topic, Using Help, Tutorial: 07 |

Der einfache Texteinstieg ist noch kein abgeschlossener Editor: Navigation,
Selektion, Zwischenablage, Syntaxprüfung und inkrementelles Übersetzen
werden in 03 vollständig umgesetzt. Die gesamte Phase-5-Abnahme erfolgt
erst in Change 08.

## Reproduzierbarer Testpfad

`cargo test -p tb-ide` prüft denselben `App::handle(Event)`-Dispatcher und
dieselbe `App::render`-Funktion wie der Terminalprozess mit
`ratatui::TestBackend`. Die Tests bedienen Menü, Tastatur, Dialog und Maus;
sie prüfen Fokus, Dokumente, Fenster, sichtbare Texte und Farben. Dieser
Pfad steht den Folgechanges zur Verfügung. `TerminalGuard` prüft zusätzlich
Normalende, Fehlerende und teilweise fehlgeschlagene Initialisierung.