# ide-oberflaeche Specification

## Purpose

Definiert den bedienbaren Terminalrahmen der IDE mit zwei Arbeitsmodi, gemeinsamen Befehlen, Fenstern, Dialogen und beständigen Benutzereinstellungen.

## Requirements

### Requirement: Start und zwei Arbeitsmodi
Die IDE SHALL mit Versions-/Copyright-Begrüßung und anschließend einem leeren Projekt mit Codefenster „[1] Untitled“ und rechts angeordnetem Project Window starten. Programmierumgebung und Designer SHALL im selben Prozess arbeiten. Die Umgebung SHALL File/Edit/View/Search/Run/Debug/Options/Window und rechts Help zeigen; der Designer File/Edit/View/Tools/Options/Window/Help. Der Designer SHALL eine Properties Bar statt einer Statuszeile besitzen.

#### Scenario: Erster Start
- **WHEN** die IDE ohne Projekt gestartet wird
- **THEN** ist das leere Codefenster direkt bedienbar und das Project Window sichtbar; die Begrüßung blockiert keine Eingabe

### Requirement: Einheitliche Menü- und Befehlsbedienung
Alle Befehle aus docs/ide-referenz.md SHALL im jeweils beschriebenen Menü erscheinen. Alt oder F11 SHALL die Menüleiste aktivieren, Mnemonics auswählen und Esc abbrechen; mit „…“ bezeichnete Befehle SHALL einen Dialog öffnen. Menü, Kürzel und anklickbarer Statushinweis SHALL dieselbe Aktion auslösen. Kontextuell unzulässige Befehle SHALL deaktiviert und ihr Grund erkennbar sein.

#### Scenario: Modusabhängige Funktionstaste
- **WHEN** F10 im Designer und danach im pausierten Programmiermodus gedrückt wird
- **THEN** wechselt es im Designer zwischen Menü- und Properties Bar und löst im Programmiermodus den Prozedurschritt aus

#### Scenario: Vollständige Eingabeverteilung
- **WHEN** Ctrl+C im Editor, F11 zur Menüaktivierung und F12 im Formularkontext gedrückt werden
- **THEN** werden Kopieren, Menüaktivierung und Event Procedures ausgelöst, ohne als BASIC-Abbruch oder verlorene Taste behandelt zu werden

### Requirement: MDI-Fenster und Fokus
Fenster SHALL Titelleiste, Control-Menü, Rahmen und bei Bedarf Scrollbalken erhalten. New Window SHALL eine zusätzliche Ansicht erzeugen; Arrange All SHALL geöffnete Fenster kacheln. F6/Ctrl+F6, Shift+F6, Ctrl+F4, Ctrl+F7/F8/F9/F10/F5 und Alt+Minus SHALL Wechseln, Schließen, Verschieben, Skalieren, Minimieren, Maximieren, Wiederherstellen und Control-Menü bedienen. Die Window-Liste SHALL das aktive Codefenster markieren. Projektbuttons Form/Code und Enter SHALL die entsprechende Ansicht öffnen.

Das Control-Menü SHALL für alle Fensterarten (Code, Projekt, Output/Run, Immediate, Debug, Calls, Hilfe, Toolbox, Palette, Menüdesign) nach derselben Regel fensterlokal erscheinen. Es SHALL sich nur für das aktive Fenster öffnen, per Alt+Minus und per Klick auf das Control-Menü-Symbol `[≡]` identisch. Der Aufklappbereich SHALL an das Symbol angehängt sein: seine linke Spalte SHALL der Spalte des Symbols in der Titelleiste des aktuellen Fensterrechtecks entsprechen (normal, maximiert oder minimiert), und er SHALL bevorzugt unmittelbar unter der Titelzeile beginnen. Reicht der Platz unterhalb bis zur Statuszeile nicht aus, SHALL der Aufklappbereich stattdessen nach oben aufklappen, sodass seine unterste Zeile unmittelbar über der Titelzeile endet. Reicht der Platz rechts nicht aus, SHALL er nur so weit nach links verschoben werden, dass er in die Arbeitsfläche passt und die Symbolspalte weiterhin überdeckt. Der Aufklappbereich SHALL stets vollständig innerhalb der Arbeitsfläche zwischen Menüleiste und Statuszeile liegen und MUST NOT die Titelzeile des eigenen Fensters überdecken. Ein offenes Control-Menü MUST NOT einen Titel der Menüleiste hervorheben oder als Menüleistenauswahl gelten; Auf/Ab, Enter, Mnemonics und Esc SHALL die Einträge bedienen, Esc und ein Klick außerhalb SHALL das Control-Menü schließen und den Fokus im Fenster belassen.

#### Scenario: Fenster wiederherstellen
- **WHEN** ein Codefenster verschoben, skaliert, minimiert, maximiert und wiederhergestellt wird
- **THEN** bleiben Dokument, Cursor und vorherige Normalgeometrie erhalten und alle Bedienelemente erreichbar

#### Scenario: Dialogfokus
- **WHEN** ein modaler Dialog geöffnet und anschließend abgebrochen wird
- **THEN** empfängt nur der Dialog die Eingaben und danach erhält das vorher aktive Fenster den Fokus zurück

#### Scenario: Control-Menü am Fenstersymbol
- **WHEN** ein beliebiges Fenster (etwa Run, Code oder Projekt) aktiv ist, unter seiner Titelzeile genug Platz besteht und der Benutzer Alt+Minus drückt oder auf `[≡]` in dessen Titelleiste klickt
- **THEN** erscheint das Control-Menü mit Restore, Move, Size, Minimize, Maximize und Close direkt unterhalb der Titelzeile, mit linker Spalte gleich der Symbolspalte, kein Titel der Menüleiste ist hervorgehoben, und Esc schließt es, ohne den Fokus zu ändern

#### Scenario: Control-Menü klappt nach oben
- **WHEN** das aktive Fenster minimiert am unteren Rand liegt oder so weit nach unten verschoben wurde, dass das Control-Menü unterhalb der Titelzeile nicht mehr in die Arbeitsfläche passt
- **THEN** öffnet sich das Control-Menü oberhalb der Titelzeile, seine unterste Zeile grenzt an die Titelzeile, seine linke Spalte ist die Symbolspalte, und alle Einträge liegen innerhalb der Arbeitsfläche

#### Scenario: Control-Menü am rechten Rand und bei maximiertem Fenster
- **WHEN** das aktive Fenster so weit rechts liegt, dass das Control-Menü über die Arbeitsfläche hinausragen würde, oder das Fenster maximiert ist
- **THEN** wird das Control-Menü nur so weit nach links gerückt, dass es in die Arbeitsfläche passt und die Symbolspalte weiterhin überdeckt; bei maximiertem Fenster öffnet es sich unter der Titelzeile des maximierten Rechtecks

#### Scenario: Gleiche Regel für alle Fensterarten
- **WHEN** nacheinander Code-, Projekt-, Output-, Immediate-, Debug- und Hilfefenster aktiviert und ihr Control-Menü geöffnet wird
- **THEN** ergibt sich die Position jedes Menüs ausschließlich aus dem aktuellen Rechteck und der Titelzeile des jeweils aktiven Fensters nach derselben Anheft- und Aufklappregel

### Requirement: Farben und Statusanzeige
Die IDE SHALL das anhand belegter VBDOS-Ansichten dokumentierte Farbschema aus docs/ide-referenz.md verwenden, insbesondere dunkelblaue Codefläche mit heller Schrift, weiße aktive Titel auf dunklem Magenta, graue Menüs und schwarze Statusschrift auf Cyan. Alle IDE-Farben SHALL als feste 24-Bit-RGB-Werte ausgegeben werden, unabhängig von TERM, COLORTERM, NO_COLOR und der ANSI-Palette. Ein Rückfall auf Index- oder Profilfarben MUST NOT erfolgen; die IDE MUST NOT die globale Terminalpalette verändern. Fensterflächen SHALL vor dem Zeichnen vorhandene Desktopzeichen und verdeckte Fensterinhalte löschen, sodass unbeschriebene Fläche und Texthintergrund dieselbe Farbe besitzen. Die Statuszeile SHALL kontextuelle klickbare Kürzel und Zeile/Spalte im Format 00001:001 zeigen. Display SHALL Vorder-/Hintergrund aus 16 Farben, Desktop-Füllzeichen und Tabweite ändern können. Bestehende gespeicherte Farbauswahlen SHALL gültig bleiben und MUST NOT stillschweigend überschrieben werden.

#### Scenario: Farben ändern
- **WHEN** der Benutzer Titelhintergrund, Desktopzeichen und Tabweite im Display-Dialog ändert
- **THEN** erscheinen die Änderungen in der IDE, während die Farbvorgaben des ausgeführten BASIC-Programms unverändert bleiben

#### Scenario: Abweichende ANSI-Palette
- **WHEN** die IDE mit Standardoptionen auf einem Terminal mit expliziter Farbausgabe und einer pastellfarbenen ANSI-Palette gestartet wird
- **THEN** bleiben Codefläche dunkelblau, Code lesbar und aktive Titel weiß auf dunklem Magenta; das Terminalprofil und die Farben nach Verlassen der IDE werden nicht verändert

#### Scenario: Bestehende Einstellungen laden
- **WHEN** eine vorhandene Optionsdatei mit angepassten DOS-Farbnummern geladen wird
- **THEN** bleiben die gewählten Nummern sowie alle weiteren Einstellungen erhalten und gelten über dieselbe definierte IDE-Farbabbildung

#### Scenario: Keine Farbfähigkeit gemeldet
- **WHEN** die IDE ohne COLORTERM, mit TERM=vt100 oder NO_COLOR=1 startet
- **THEN** gibt sie unverändert absolute RGB-Werte aus, insbesondere Codehintergrund #0000AA und Titelhintergrund #AA00AA

#### Scenario: Freie Fensterfläche
- **WHEN** der Desktop ein Füllzeichen enthält oder sich Fenster überdecken und im Editor Text eingegeben, markiert und die Auswahl aufgehoben wird
- **THEN** bleiben unbeschriebene Fensterzellen echte Leerzeichen in der jeweiligen Fensterfarbe ohne Desktopmuster oder verdeckte Inhalte

### Requirement: Beständige und validierte Optionen
Options SHALL Display, Set Paths, Right Mouse, Save und Syntax Checking anbieten. Syntax Checking SHALL anfangs aktiv sein. Rechtsklick SHALL konfigurierbar Kontext-Hilfe auslösen. Explizites Save SHALL die Optionen benutzerbezogen speichern; fehlerhafte oder unbekannte Konfiguration SHALL mit verständlicher Diagnose und benutzbaren Vorgaben behandelt werden.

#### Scenario: Neustart mit Optionen
- **WHEN** Optionen gespeichert und die IDE aus einem anderen Arbeitsverzeichnis neu gestartet wird
- **THEN** gelten die gespeicherten Werte weiterhin, ohne Projektdateien als Konfigurationsspeicher zu benutzen

### Requirement: Terminalgröße und Wiederherstellung
Die IDE SHALL die aktuelle Terminalfläche nutzen und auf Größenänderungen reagieren. Unter 80×25 SHALL ausschließlich ein Mindestgrößenhinweis erscheinen, ohne Dokumente oder Sitzung zu verlieren. Normaler Exit und Fehlerabbruch SHALL Terminalmodus und Cursor wiederherstellen.

#### Scenario: Verkleinern und zurück
- **WHEN** ein Terminal mit offenen Dokumenten unter 80×25 schrumpft und anschließend wieder wächst
- **THEN** kehrt die bedienbare Oberfläche mit erhaltenen Dokumenten und erreichbaren Fenstern zurück

### Requirement: Vollständige Exportdialoge mit getrennter Erzeugung
Run→Make EXE File und Run→Make Library SHALL bereits in Phase 5 bedienbare Dialoge für Artefaktart, Zielsystem/-architektur und Ausgabepfad öffnen. Mit Phase 6 SHALL die Ziele als natives eigenständiges Executable mit nativer Runtime in tbrt beziehungsweise portable P-Code-Bibliothek `.tbl` beschrieben sein. System-/Architekturwahl SHALL nur für EXE erforderlich sein; Make Library SHALL ohne native Zielvorlage verfügbar sein, sobald sein Backend vorhanden ist. Die Dialoge SHALL Eingaben prüfen, Überschreibkonflikte behandeln und Zustände für Erzeugung, Erfolg, Fehler und Abbruch darstellen können. Die tatsächliche Erzeugung SHALL erst mit dem Backend aus Phase 6 verfügbar sein; bis dahin SHALL nur die Erzeugungsaktion mit einem verständlichen Verfügbarkeitsgrund gesperrt sein. Die IDE MUST NOT einen Export vortäuschen oder ein bloßes TBC-Kompilat als natives Artefakt ausgeben.

#### Scenario: Dialoge vor dem Erzeugungsbackend
- **WHEN** beide Make-Befehle ohne verfügbares Erzeugungsbackend über Menü oder Tastatur geöffnet werden
- **THEN** lassen sich die zur Artefaktart passenden Angaben (EXE-Zielsystem/-architektur und Ausgabepfad, für TBL der Ausgabepfad) bearbeiten und validieren; die fehlende Erzeugung wird erklärt und keine Zieldatei geschrieben

#### Scenario: Fehlerhafte Ausgabeangaben
- **WHEN** ein leerer oder unzulässiger Ausgabepfad beziehungsweise ein bestehendes Ziel ohne Überschreibentscheidung angegeben wird
- **THEN** zeigt der Dialog den Eingabefehler oder die notwendige Entscheidung und behält die übrigen Angaben

#### Scenario: Ergebnisdarstellung über die vorbereitete Übergabe
- **WHEN** die Exportanbindung im Oberflächentest Erzeugung, Erfolg, Fehler und Abbruch mit demselben gültigen Auftrag zurückmeldet
- **THEN** zeigt die IDE jeweils den passenden Zustand mit Ziel beziehungsweise Diagnose und erhält die Projektdokumente; der Test behauptet keine tatsächliche native Dateierzeugung

#### Scenario: Verfügbares Erzeugungsbackend
- **WHEN** ein gültiger Auftrag bei verfügbarem Backend tatsächlich erfolgreich erzeugt wird
- **THEN** zeigt der Dialog den bestätigten Erfolg mit dem passenden EXE- oder TBL-Zielartefakt und erhält die Projektdokumente

### Requirement: Lesbare UI-Zustände
Im Standardtheme SHALL jedes dargestellte IDE-Text-/Hintergrundpaar mindestens 4,5:1 Kontrast nach sRGB-Relativluminanz besitzen, einschließlich Auswahl, Hilfelinks, Fehlermeldungen und deaktivierter Beschriftungen. Zur Bedienung notwendige nichttextuelle Fokus-/Rahmenmarkierungen SHALL gegenüber angrenzenden Flächen mindestens 3:1 erreichen. Aktive/inaktive, ausgewählte, deaktivierte und Debuggerzustände SHALL zusätzlich durch Rahmen, Zeichen oder Text erkennbar bleiben. Benutzerdefinierte Farbkombinationen und programmgesteuerte BASIC-Farben sind von den Standardtheme-Grenzwerten ausgenommen.

#### Scenario: Auswahl und Fensterwechsel
- **WHEN** Text markiert, zwischen Code und Projekt gewechselt und ein Menü oder Dialog geöffnet wird
- **THEN** bleiben Schrift und Fokus in allen beteiligten Zuständen lesbar; die Standardfarbpaare und erforderlichen Markierungen erfüllen die Kontrastgrenzen

#### Scenario: Hilfe, Debugger und Designer
- **WHEN** ein Hilfelink fokussiert, ein Breakpoint oder die aktuelle Ausführungszeile angezeigt und ein Designer-Control ausgewählt wird
- **THEN** bleiben Inhalt, jeweilige Markierung und Beschriftungen unterscheidbar und erfüllen die Standardtheme-Kontrastgrenzen

### Requirement: Belegter Theme-Abgleich
Der Theme-Abgleich SHALL nachvollziehbare VBDOS-Referenzfundstellen und zugeordnete IDE-Ansichten für Editor, aktive/inaktive Titel, Menüs, Projekt, Dialoge, Status, Hilfe und Designer dokumentieren. Nicht belegte Details SHALL als solche und bewusste Abweichungen für Kontrast als Anpassungen gekennzeichnet sein. Die reale Darstellung SHALL in der Plattformmatrix für Windows Terminal, Terminal.app sowie xterm und VTE auf beiden Linux-Architekturen mit Revision, Terminalversion und Farbprofil geprüft werden. Fehlende visuelle Nachweise MUST offen bleiben.

#### Scenario: Farbnummern stimmen, Darstellung weicht ab
- **WHEN** ein Render-Test die erwarteten Farbnummern liefert, der reale Terminalnachweis aber blasse oder unlesbare Standardfarben zeigt
- **THEN** bleibt der Theme-Befund offen, bis Ursache, Korrektur beziehungsweise belegte Terminalgrenze und erneute betroffene Abnahme dokumentiert sind