TerminalBasic/openspec/specs/ereignissteuerung/spec.md

# ereignissteuerung Specification

## Purpose

Die Ereignissteuerung bestimmt, woher Ereignisse kommen, wann ein
laufendes Programm sie zu sehen bekommt und wie es darauf reagiert:
Ereignisquellen (Tastatur, Maus, Zeit, benutzerdefiniert) und ihre
Warteschlange, die abschließende Liste der
Zustellpunkte, die Maskierung je Quelle und global, sowie die Zustellung
als `GOSUB` in das laufende Programm. Sie ist die gemeinsame Grundlage
der klassischen Ereignis-Traps und späterer Forms-Ereignisse.

## Requirements

### Requirement: Ereignisquellen mit Zeit vom Host
Die Laufzeit SHALL Ereignisse aus vier Quellen führen: Tastatur, Maus,
Zeit und benutzerdefinierte Ereignisse. Die Zeit SHALL vom Host bezogen
werden;
die Laufzeit MUST NOT für die Ereigniszustellung selbst auf die
Systemuhr zugreifen. Ein Host ohne Terminal MUST die Zeit frei stellen
können, sodass zeitgesteuerte Programme ohne Wartezeit und mit
reproduzierbarem Ergebnis prüfbar sind.

Auch Wartefristen der VM SHALL ausschließlich von der Hostzeit abhängen. Ein Host mit stehender virtueller Zeit MUST NOT durch reale verstrichene Zeit eine Frist scheinbar erreichen.

#### Scenario: Zeitgesteuerter Trap ohne echte Wartezeit
- **WHEN** ein Testhost die Zeit um 5 Sekunden vorstellt und ein Programm `ON TIMER(5) GOSUB Marke` mit `TIMER ON` aktiv hat
- **THEN** wird der Trap zugestellt, ohne dass der Test tatsächlich wartet

#### Scenario: Wiederholter Lauf liefert dasselbe Ergebnis
- **WHEN** dasselbe zeitgesteuerte Korpusprogramm zweimal mit demselben Zeitverlauf ausgeführt wird
- **THEN** ist die Ausgabe beide Male identisch

#### Scenario: Stehende virtuelle Zeit
- **WHEN** ein Host während SLEEP seine Zeit unverändert hält
- **THEN** endet SLEEP nicht wegen realer Zeit; eine vom Host gemeldete Frist oder ein zugestelltes Ereignis beendet das Warten

### Requirement: Mausereignisse in Zellenkoordinaten
Die Darstellungsschicht SHALL Mausereignisse der Ausführungsumgebung an
die Laufzeit weitergeben: Drücken, Loslassen und Bewegung, jeweils mit
gedrückter Taste, Umschaltzustand und Position. Die Position SHALL in
Zellen des Textbildschirms angegeben werden, gezählt wie bei `LOCATE`,
also 1-basiert. Ereignisse außerhalb der aktuellen Bildschirmfläche MUST
verworfen werden. Die Reihenfolge zwischen Maus- und Tastenereignissen
SHALL der Reihenfolge ihres Eintreffens entsprechen. Solange kein
Verbraucher ein Mausereignis annimmt, MUST es am Zustellpunkt verworfen
werden, damit die Warteschlange nicht unbegrenzt wächst.

Die Reihenfolge SHALL bis zur beobachtbaren Ausführung der zugehörigen Handler erhalten bleiben; getrennte Quellarten MUST NOT nachträglich nach ihrer Art umgeordnet werden.

#### Scenario: Position als Zelle
- **WHEN** in der linken oberen Ecke der Darstellungsfläche die linke Maustaste gedrückt wird
- **THEN** trägt das Ereignis Zeile 1 und Spalte 1

#### Scenario: Reihenfolge bleibt erhalten
- **WHEN** eine Taste gedrückt und danach die Maus geklickt wird
- **THEN** liefert die Warteschlange erst das Tasten-, dann das Mausereignis

#### Scenario: Ereignis außerhalb der Fläche
- **WHEN** ein Mausereignis eine Position außerhalb der aktuellen Bildschirmgröße nennt
- **THEN** wird es verworfen und erreicht die Warteschlange nicht

#### Scenario: Kein Verbraucher, keine Anhäufung
- **WHEN** ein Programm ohne Verbraucher für Mausereignisse läuft und die Maus dauerhaft bewegt wird
- **THEN** wächst die Warteschlange nicht über ihre Grenze und das Programm läuft unverändert weiter

#### Scenario: Taste vor Maus bis zum Handler
- **WHEN** eine Taste vor einem Mausklick eintrifft und beide Handler eine Kennung anhängen
- **THEN** steht die Tastenkennung vor der Mauskennung

#### Scenario: Maus vor Taste bis zum Handler
- **WHEN** ein Mausklick vor einer Taste eintrifft
- **THEN** wird zuerst der Maushandler wirksam

### Requirement: Abschließende Liste der Zustellpunkte
Ereignisse SHALL ausschließlich an folgenden Punkten zugestellt werden
— das Vorbild prüft die Ereignismarke „before executing the next
statement":
an einer Anweisungsgrenze, bei `DOEVENTS`, während `SLEEP` und vor einer
blockierenden Eingabe. Zwischen zwei Zustellpunkten MUST NOT ein
Trap-Handler beginnen; insbesondere MUST NOT eine Anweisung in ihrer
Mitte unterbrochen werden. Ein zugestelltes Ereignis SHALL ein laufendes
`SLEEP` beenden.

Forms-Ereignisse SHALL auch während SLEEP an dessen bestehenden Zustellpunkten verarbeitet werden. Eine für das Menü geltende Zustellsperre SHALL an jedem Zustellpunkt gleichermaßen gelten.

#### Scenario: Keine Zustellung innerhalb einer Anweisung
- **WHEN** ein Ereignis fällig wird, während eine mehrteilige Anweisung ausgewertet wird
- **THEN** läuft die Anweisung zu Ende und der Handler beginnt erst an der folgenden Anweisungsgrenze

#### Scenario: SLEEP endet durch Ereignis
- **WHEN** ein Programm `SLEEP 60` ausführt und nach 2 Sekunden ein aktiver Trap fällig wird
- **THEN** wird der Handler ausgeführt und `SLEEP` kehrt danach zurück, ohne die vollen 60 Sekunden abzuwarten

#### Scenario: DOEVENTS stellt zu
- **WHEN** ein anstehendes Ereignis vorliegt und `DOEVENTS` ausgewertet wird
- **THEN** läuft der zugehörige Handler, bevor `DOEVENTS` einen Wert liefert

#### Scenario: Forms-Timer beendet SLEEP
- **WHEN** während SLEEP ein aktiver Forms-Timer fällig wird
- **THEN** läuft dessen Handler und SLEEP kehrt danach zurück

### Requirement: Maskierung je Quelle mit drei Zuständen
Jede Ereignisquelle SHALL drei Zustände kennen. `ON` stellt Ereignisse
zu. `OFF` verwirft sie; ein während `OFF` eingetretenes Ereignis MUST
NOT nachträglich zugestellt werden, und ein zuvor unter `STOP` gemerktes
Ereignis MUST von `OFF` verworfen werden. `STOP` merkt höchstens ein
anstehendes Ereignis und stellt es beim nächsten `ON` zu. Ohne
vorangehende `ON …`-Trap-Definition MUST eine Steueranweisung wirkungslos
bleiben, aber keinen Fehler auslösen.

#### Scenario: OFF verwirft
- **WHEN** `TIMER OFF` gilt, die Frist verstreicht und danach `TIMER ON` ausgeführt wird
- **THEN** wird kein Handler ausgeführt

#### Scenario: STOP merkt genau eines
- **WHEN** `KEY(1) STOP` gilt, F1 dreimal gedrückt wird und danach `KEY(1) ON` ausgeführt wird
- **THEN** läuft der Handler genau einmal

#### Scenario: OFF verwirft das unter STOP Gemerkte
- **WHEN** `TIMER STOP` gilt, die Frist verstreicht, danach `TIMER OFF` und dann `TIMER ON` ausgeführt werden
- **THEN** läuft kein Handler

### Requirement: EVENT klammert Abschnitte ohne Ereignisprüfung
`EVENT OFF` SHALL die Ereignisprüfung für den folgenden Abschnitt
abschalten, `EVENT ON` sie wieder einschalten; die beiden klammern einen
Abschnitt, in dem keine Ereignisse erkannt werden müssen. Ein dritter
Zustand MUST NOT bestehen: `EVENT STOP` ist im Vorbild nicht
dokumentiert und MUST namentlich abgewiesen werden. Der Schalter SHALL
die Zustände der einzelnen Quellen überlagern, ohne sie zu verändern:
nach `EVENT ON` gilt für jede Quelle wieder ihr eigener Zustand.
Ereignisse, die während `EVENT OFF` eintreten, MUST NOT nachträglich
zugestellt werden.

#### Scenario: Klammer überlagert Einzelzustand
- **WHEN** `TIMER ON` gilt und danach `EVENT OFF` ausgeführt wird
- **THEN** wird kein Zeit-Trap zugestellt, und nach `EVENT ON` wird wieder zugestellt, ohne dass `TIMER ON` erneut nötig ist

#### Scenario: EVENT STOP gibt es nicht
- **WHEN** ein Modul `EVENT STOP` enthält
- **THEN** wird es namentlich abgewiesen

### Requirement: Zustellung als GOSUB ohne Wiedereintritt
Ein zugestelltes Ereignis SHALL das `GOSUB`-Ziel seines Traps ausführen
und danach an die unterbrochene Stelle zurückkehren; der unterbrochene
Zustand (aufrufende Prozedur, Schleifen, Variablen) MUST erhalten
bleiben. Beim Eintritt in den Handler SHALL für seine eigene Quelle
selbsttätig `STOP` wirken, sodass keine rekursiven Traps entstehen; das
`RETURN` SHALL für sie selbsttätig `ON` ausführen — es sei denn, im
Handler wurde ausdrücklich `OFF` für diese Quelle ausgeführt, dann bleibt
sie aus. Ein `RETURN label` aus einem Handler MUST erlaubt sein.

#### Scenario: Rückkehr in die unterbrochene Schleife
- **WHEN** ein Trap während einer `FOR`-Schleife zugestellt wird
- **THEN** läuft die Schleife nach `RETURN` mit unverändertem Zählerstand weiter

#### Scenario: Kein Wiedereintritt
- **WHEN** ein Zeit-Trap läuft und die nächste Frist während des Handlers verstreicht
- **THEN** wird der Handler nicht erneut betreten, sondern das Ereignis nach `RETURN` einmal zugestellt

#### Scenario: OFF im Handler überlebt das RETURN
- **WHEN** ein Handler `TIMER OFF` ausführt und danach `RETURN` erreicht
- **THEN** bleibt die Quelle aus und kein weiterer Zeit-Trap wird zugestellt

### Requirement: Getrappte Tasten verlassen den Eingabestrom
Eine Taste, für die ein aktiver `ON KEY`-Trap besteht, SHALL dem Trap
zugestellt werden und MUST NOT zusätzlich über `INKEY$`, `INPUT`,
`LINE INPUT` oder `INPUT$` sichtbar werden. Bei `OFF` oder `STOP` der
Quelle SHALL die Taste dem normalen Eingabestrom erhalten bleiben.

Unter STOP SHALL die Taste normal lesbar bleiben und zugleich höchstens ein Ereignis für das spätere ON gemerkt werden.

#### Scenario: Getrappte Taste erscheint nicht bei INKEY$
- **WHEN** `ON KEY(1) GOSUB Marke` mit `KEY(1) ON` gilt und F1 gedrückt wird
- **THEN** läuft der Handler und ein anschließendes `INKEY$` liefert den leeren String

#### Scenario: Nicht getrappte Taste bleibt im Strom
- **WHEN** derselbe Trap mit `KEY(1) OFF` gilt und F1 gedrückt wird
- **THEN** liefert `INKEY$` die Sondertastenfolge für F1

#### Scenario: STOP merkt und erhält Eingabe
- **WHEN** unter KEY(1) STOP F1 gedrückt, per INKEY$ gelesen und danach KEY(1) ON ausgeführt wird
- **THEN** liefert INKEY$ die Sondertastenfolge und der Handler läuft nach ON genau einmal

### Requirement: Benutzerdefiniertes Ereignis
`SetUEvent` SHALL ein benutzerdefiniertes Ereignis auslösen, das über
`ON UEVENT GOSUB` und die Steueranweisung `UEVENT` denselben Regeln für
Maskierung und Zustellung unterliegt wie die übrigen Quellen.

#### Scenario: SetUEvent löst den Handler aus
- **WHEN** `ON UEVENT GOSUB Marke` mit `UEVENT ON` gilt und `SetUEvent` aufgerufen wird
- **THEN** läuft der Handler am nächsten Zustellpunkt genau einmal

### Requirement: Reihenfolge bei mehreren fälligen Ereignissen
Sind an einem Zustellpunkt mehrere Ereignisse fällig, SHALL genau eines
zugestellt werden; die übrigen bleiben anstehend und werden an
folgenden Zustellpunkten zugestellt. Die Reihenfolge SHALL festgelegt
und dokumentiert sein, sodass sie über Läufe hinweg gleich bleibt.

#### Scenario: Zwei gleichzeitig fällige Traps
- **WHEN** an einem Zustellpunkt ein Zeit- und ein Tasten-Trap zugleich fällig sind
- **THEN** läuft zuerst genau ein Handler und der andere am nächsten Zustellpunkt

### Requirement: Fehler in einem Handler
Ein Laufzeitfehler in einem Trap-Handler SHALL der geltenden
Fehlerbehandlung unterliegen. `RESUME` und `RESUME NEXT` SHALL sich auf
die Anweisung im Handler beziehen, nicht auf die unterbrochene
Anweisung.

#### Scenario: Fehler im Handler erreicht den Handler des Moduls
- **WHEN** ein Trap-Handler eine Anweisung mit Laufzeitfehler ausführt und ein modulweiter `ON ERROR GOTO`-Handler gesetzt ist
- **THEN** wird dieser Handler betreten und `ERL` nennt die Zeile im Trap-Handler

### Requirement: Signal-Trap auf Betriebssystemsignalen
`ON SIGNAL(n%) GOSUB` und die Steueranweisung `SIGNAL(n%)` SHALL
denselben Regeln für Maskierung, Zustellung und Wiedereintritt
unterliegen wie die übrigen Quellen. `n%` SHALL auf
Betriebssystemsignale abgebildet werden, und zwar ausschließlich auf die
Menge, die auf allen Zielplattformen besteht: 1 auf den
Unterbrechungswunsch (`SIGINT`), 2 auf den Beendigungswunsch
(`SIGTERM`). Ein anderer Wert MUST namentlich abgewiesen werden — zur
Übersetzungszeit, wenn er konstant ist, sonst mit Laufzeitfehler 5. Ein
Signal MUST NOT im Signalkontext verarbeitet werden; es SHALL über den
Host als Ereignis in die Warteschlange gelangen. Die Abweichung zur
OS/2-gebundenen Quelle des Vorbilds SHALL in der Sprachreferenz
ausgewiesen sein.

#### Scenario: Signal-Trap folgt der Maskierung
- **WHEN** `ON SIGNAL(1) GOSUB Marke` mit `SIGNAL(1) STOP` gilt und ein `SIGINT` eintrifft
- **THEN** läuft der Handler erst nach `SIGNAL(1) ON`, und zwar genau einmal

#### Scenario: Unzulässige Signalnummer
- **WHEN** ein Modul `ON SIGNAL(7) GOSUB Marke` enthält
- **THEN** wird es namentlich abgewiesen und die Meldung nennt den zulässigen Bereich

#### Scenario: Signal ohne Trap bleibt Abbruch
- **WHEN** ein `SIGINT` eintrifft, ohne dass ein `SIGNAL(1)`-Trap aktiv ist
- **THEN** bleibt es beim bisherigen Abbruchverhalten

#### Scenario: SIGTERM wird zugestellt
- **WHEN** SIGNAL(2) ON gilt und ein SIGTERM über den Host eintrifft
- **THEN** wird das Ziel von ON SIGNAL(2) GOSUB am nächsten erlaubten Zustellpunkt ausgeführt