Phase 5: IDE-Rahmen implementieren, synchronisieren und archivieren

docs/ide-bedienung.md

@@ -0,0 +1,164 @@
+# 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.