formular lesen (binär) und openspec für codex

openspec/changes/phase-4-steuerelemente/design.md

@@ -0,0 +1,114 @@
+# Design — Steuerelemente, Menüs, Dialoge
+
+## Context
+
+Siehe proposal.md — Why. Dieser Change setzt auf drei fertigen Stücken
+auf: dem Zellenpuffer aus Phase 3, der Ereignisschleife samt Mausquelle
+(`phase-4-ereignisschleife`) und dem Objektmodell
+(`phase-4-objektmodell`). Er ist der breiteste Change der Phase — 15
+Klassen, Menüs, Dialoge —, aber der mit den wenigsten offenen
+Architekturfragen.
+
+Die Forms-Referenz lässt drei Detailfragen offen, die hier beantwortet
+werden müssen: die Optik je Zustand, die Z-Reihenfolge bei Überlappung
+und die Reihenfolge gleichzeitig fälliger Timer.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Eine Darstellung, die im Zellenpuffer entsteht und deshalb mit dem
+  bestehenden Snapshot-Vergleich prüfbar ist.
+- Eingabebehandlung, die je Klasse an einer Stelle steht, statt über
+  Sonderfälle in der Schleife verteilt zu sein.
+
+**Non-Goals:**
+
+- Pixelgenaue Nachbildung der Originaloptik; maßgeblich sind Aufbau und
+  Zeichen, nicht der Farbton eines Schattens.
+- Ein Layoutalgorithmus. Steuerelemente stehen, wo ihre Koordinaten sie
+  hinstellen.
+
+## Decisions
+
+### D1 — Zeichnen ist eine Funktion des Zustands, kein Nebeneffekt
+
+Jede Klasse zeichnet sich vollständig aus ihren Eigenschaften in den
+Zellenpuffer. Es gibt keinen inkrementellen Zeichenpfad und kein
+Merken zuvor gezeichneter Bereiche.
+
+| Alternative | Warum nicht |
+|---|---|
+| Nur veränderte Bereiche neu zeichnen | Bei 80×25 Zellen ist das Neuzeichnen ohnehin billig; der Zustandsabgleich wäre die zweite Quelle der Wahrheit neben den Eigenschaften |
+
+Neu gezeichnet wird an den Zustellpunkten der Ereignisschleife, wenn
+eine Eigenschaft sich geändert hat — dieselbe Bedingung, die der
+Bildschirmpuffer heute schon für `present` nutzt.
+
+### D2 — Eingabe geht durch eine Kette, nicht durch eine Fallunterscheidung
+
+Ein Tastenereignis läuft: Menü (wenn offen) → modaler Dialog (wenn
+offen) → Access-Key des Formulars → fokussiertes Steuerelement →
+`Default`/`Cancel`-Schaltfläche → Formular. Jede Station nimmt das
+Ereignis an oder gibt es weiter. Für die Maus entsprechend: Menü →
+Dialog → Trefferprüfung über die Z-Reihenfolge → Formular.
+
+Die Kette ist die einzige Stelle, an der Vorrang entschieden wird; die
+Klassen selbst wissen nichts über einander.
+
+### D3 — Antworten auf die offenen Detailfragen der Forms-Referenz
+
+- **Optik je Zustand**: aus den Original-Screenshots abgeleitet und je
+  Klasse in der Forms-Referenz als Zeichenbild festgehalten, bevor
+  gezeichnet wird — sonst legt der erste Implementierungsversuch sie
+  stillschweigend fest.
+- **Z-Reihenfolge**: Reihenfolge der Erzeugung, später Erzeugtes liegt
+  oben; Steuerelement-Arrays nach Index. Das ist die Regel, die aus einer
+  `.FRM` reproduzierbar folgt.
+- **Gleichzeitig fällige Timer**: in aufsteigender Reihenfolge ihres
+  Namens im Formular, damit die Ausgabe eines Korpusprogramms nicht von
+  einer Hashreihenfolge abhängt.
+
+Alle drei werden in `docs/forms-referenz.md` als unsere Festlegung
+gekennzeichnet, nicht als Referenzverhalten ausgegeben.
+
+### D4 — Dialoge sind Formulare, keine Sonderfälle
+
+`MSGBOX` und `INPUTBOX$` bauen ein Formular mit Label und Schaltflächen
+und zeigen es modal über den Weg aus `phase-4-objektmodell` (Frame-Marke,
+D4 dort). Damit gelten Fokus, Access-Keys und Esc ohne Sonderbehandlung,
+und die Dialoge sind mit demselben Snapshot-Vergleich prüfbar wie jedes
+andere Formular.
+
+### D5 — Menü hält die Ereigniszustellung an
+
+Die Forms-Referenz nennt es für das Vorbild: Zeitereignisse und Trapping
+ruhen, solange ein Menü den Fokus hat. Umgesetzt wird das über den
+`STOP`-Zustand der Ereignissteuerung — kein neuer Mechanismus, sondern
+der vorhandene, vom Menü gesetzt und beim Schließen zurückgenommen.
+
+### D6 — Dateisystem-Steuerelemente werden plattformneutral abgebildet
+
+DriveListBox zeigt keine Laufwerksbuchstaben, sondern die Wurzeln bzw.
+Einhängepunkte der Plattform; DirListBox und FileListBox arbeiten auf
+Pfaden. `Pattern` bleibt das Muster des Vorbilds. Die Abweichung wird in
+der Sprachreferenz festgehalten.
+
+## Risks / Trade-offs
+
+- **Breite statt Tiefe** → 15 Klassen sind viel Fläche für Flüchtigkeit;
+  jede Klasse bekommt ihren eigenen Korpusnachweis, nicht nur einen
+  gemeinsamen Sammeltest.
+- **Vollständiges Neuzeichnen bei großen Terminals** → bei 200×60 sind es
+  12 000 Zellen je Anzeige; falls das messbar stört, greift die
+  Bedingung „nur bei Änderung" bereits heute, und ein Ausbau bleibt
+  möglich, ohne die Klassen anzufassen.
+- **Fremdprogramme scheitern aus unerwartetem Grund** → jeder Befund wird
+  festgehalten statt umgangen; er ist das eigentliche Ergebnis des
+  Kompatibilitätstests.
+
+## Open Questions
+
+- Ob die PictureBox als Container für OptionButton-Gruppen dieselbe
+  Fokuslogik wie der Frame braucht, zeigt der erste Korpusnachweis mit
+  gruppierten Optionsfeldern.