252 lines
13 KiB
Markdown
252 lines
13 KiB
Markdown
# Forms-Referenz Terminal Basic
|
||
|
||
Rekonstruierte Referenz der Forms-Engine des Vorbilds (VBDOS 1.0) —
|
||
Grundlage für `tb-ui::forms` und den Formular-Designer. Primärquellen:
|
||
Original-Hilfedatei (dekodiert), `CONSTANT.BI`, Stringtabellen der
|
||
Original-Programme, Beispielprojekte. Aussagen ohne TODO sind daraus belegt.
|
||
Die zeilenweise Matrix mit Typ, Bereich, Vorgabe, Laufzeit-Schreibbarkeit
|
||
und Klassenquelle liegt im Change-Dokument
|
||
`openspec/changes/phase-4-objektmodell/klassen-und-eigenschaften.md`.
|
||
Als Beispiel-Gegenprobe dient `cout/vbdos` Commit
|
||
`1cdd2b32b829fe1721d0b6aecc433abc47a96fb6`; dessen binäre Formulare
|
||
`microsoft/check.frm`, `notepad.frm`, `qlbview.frm`, `seek.frm`,
|
||
`spindemo.frm`, `graphics/graphics.frm` und `misc/mentors/mentors.frm`
|
||
enthalten die dort ausgewiesenen Eigenschaften und Ereignisprozeduren.
|
||
|
||
## Koordinatenmodell
|
||
|
||
Einheit ist durchgängig die **Textzelle** (Spalte/Zeile), keine Twips.
|
||
`Left`/`Top` relativ zum Container, gültiger Bereich 0–254; `Height`/`Width`
|
||
für Controls 1–254, für Formulare bis Bildschirmgröße. `ScaleHeight`/
|
||
`ScaleWidth` (nur Form/PictureBox, read-only) = Innenmaß ohne Rahmen/Menü.
|
||
Maus-Koordinaten in Ereignissen sind SINGLE, aber in Zellen.
|
||
|
||
## Steuerelemente (exakte Klassennamen)
|
||
|
||
`CheckBox, ComboBox, CommandButton, DirListBox, DriveListBox, FileListBox,
|
||
Frame, HScrollBar, Label, ListBox, Menu, OptionButton, PictureBox, Spin, TextBox,
|
||
Timer, VScrollBar` — alle außer `Menu` über die Toolbox platzierbar
|
||
(Menüs entstehen im Menu Design Window). Default-Namen: `Check1`, `Combo1`,
|
||
`Command1`, `Dir1`, `Drive1`, `File1`, `Frame1`, `HScroll1`, `Label1`,
|
||
`List1`, `Option1`, `Picture1`, `Text1`, `Timer1`, `VScroll1`.
|
||
|
||
## Eigenschaften/Methoden/Ereignisse je Steuerelement
|
||
|
||
**Form** — Ereignisse: Click, DblClick, DragDrop, DragOver, GotFocus,
|
||
KeyDown, KeyPress, KeyUp, Load, LostFocus, MouseDown, MouseMove, MouseUp,
|
||
Paint, Resize, Unload. Methoden: CLS, DRAG, HIDE, LOAD, MOVE, PRINT,
|
||
PRINTFORM, REFRESH, SHOW, TEXTHEIGHT, TEXTWIDTH, UNLOAD. Eigenschaften:
|
||
AutoRedraw, BackColor, BorderStyle, Caption, ControlBox, CurrentX, CurrentY,
|
||
DragMode, Enabled, ForeColor, FormName, FormType, Height, Left, MaxButton,
|
||
MinButton, MousePointer, Parent, ScaleHeight, ScaleWidth, Tag, Top,
|
||
Visible, Width, WindowState.
|
||
|
||
**CommandButton** — Ereignisse: Click, DragDrop, DragOver, GotFocus,
|
||
KeyDown, KeyPress, KeyUp, LostFocus. Methoden: DRAG, MOVE, REFRESH,
|
||
SETFOCUS. Eigenschaften: BackColor, Cancel, Caption, CtlName, Default,
|
||
DragMode, Enabled, Height, Index, Left, MousePointer, Parent, TabIndex,
|
||
TabStop, Tag, Top, Value, Visible, Width. Darstellung nach Höhe:
|
||
1 = `<Text>`, 2 = einzeiliger Rahmen, ≥3 = Kasten; Mindestgröße 1×3.
|
||
|
||
**TextBox** — Ereignisse: Change, DragDrop, DragOver, GotFocus, KeyDown,
|
||
KeyPress, KeyUp, LostFocus. Methoden: DRAG, MOVE, REFRESH, SETFOCUS.
|
||
Eigenschaften: BackColor, BorderStyle, CtlName, DragMode, Enabled,
|
||
ForeColor, Height, Index, Left, MousePointer, MultiLine, Parent,
|
||
ScrollBars, SelLength, SelStart, SelText, TabIndex, TabStop, Tag, Text,
|
||
Top, Visible, Width.
|
||
|
||
**ListBox** — Ereignisse: Click, DblClick, DragDrop, DragOver, GotFocus,
|
||
Key*, LostFocus, Mouse*. Methoden: ADDITEM, DRAG, MOVE, REFRESH,
|
||
REMOVEITEM, SETFOCUS. Eigenschaften: BackColor, CtlName, DragMode, Enabled,
|
||
ForeColor, Height, Index, Left, List, ListCount, ListIndex, MousePointer,
|
||
Parent, Sorted, TabIndex, TabStop, Tag, Text, Top, Visible, Width.
|
||
|
||
**ComboBox** — wie ListBox plus Change, DropDown (Ereignisse), SelLength/
|
||
SelStart/SelText/Style/Text (Eigenschaften).
|
||
|
||
**CheckBox / OptionButton** — Ereignisse: Click (Option auch DblClick),
|
||
Drag*, GotFocus, Key*, LostFocus. Methoden: DRAG, MOVE, REFRESH, SETFOCUS.
|
||
Eigenschaften: BackColor, Caption, CtlName, DragMode, Enabled, ForeColor,
|
||
Height, Index, Left, MousePointer, Parent, TabIndex, TabStop, Tag, Top,
|
||
Value, Visible, Width.
|
||
|
||
**Frame** — nur DragDrop/DragOver; DRAG, MOVE, REFRESH (kein SetFocus);
|
||
Container für Gruppierung (OptionButton-Gruppen). `Index` und `TabIndex`
|
||
werden in den Originaldateien auch für Frames gespeichert.
|
||
|
||
**Label** — Ereignisse: Change, Click, DblClick, Drag*, Mouse*. Methoden:
|
||
DRAG, MOVE, REFRESH. Eigenschaften: zusätzlich Index, TabIndex, Alignment,
|
||
AutoSize, BorderStyle.
|
||
|
||
**HScrollBar/VScrollBar** — Ereignisse: Change, Drag*, GotFocus, Key*,
|
||
LostFocus (**kein** separates Scroll-Ereignis). Eigenschaften: zusätzlich
|
||
Attached (VBDOS-Spezifikum: am Formularrand angedockt; Laufzeit read-only),
|
||
LargeChange, Min, Max, SmallChange, Value.
|
||
|
||
**Spin** — Ereignisse: Custom(EventType), Drag*, GotFocus, Key*, LostFocus.
|
||
`Style` wählt vertikal/horizontal, `Interval` steuert die Wiederholung; `Value`
|
||
läuft zyklisch zwischen `Min` und `Max`. `BorderStyle`, `Width` und `Height`
|
||
sind zur Laufzeit schreibgeschützt.
|
||
|
||
**PictureBox** — Text-Zeichenfläche (PRINT/CLS aufs Control) und Container
|
||
für OptionButton-Gruppen. Ereignisse: Click, DblClick, Drag*, GotFocus,
|
||
Key*, LostFocus, Mouse*, Paint. Methoden: CLS, DRAG, MOVE, PRINT, REFRESH,
|
||
SETFOCUS, TEXTHEIGHT, TEXTWIDTH. Eigenschaften: zusätzlich Index, TabIndex,
|
||
TabStop, AutoRedraw, CurrentX, CurrentY, ScaleHeight, ScaleWidth.
|
||
|
||
**Timer** — Ereignis Timer, keine Methoden; Eigenschaften: CtlName, Enabled,
|
||
Index, Interval (0 = aus … 65 535 ms), Parent, Tag.
|
||
|
||
**Menu** — Ereignis Click; Eigenschaften Caption, Checked, CtlName, Enabled,
|
||
Index, Parent, Separator, Shortcut, Tag, Visible.
|
||
|
||
**DirListBox/DriveListBox/FileListBox** — Datei-Browser-Controls
|
||
(Path/Drive/FileName/Pattern/Archive/Hidden/Normal/ReadOnly/System;
|
||
Ereignisse u. a. Change, PathChange, PatternChange). Terminal Basic bildet
|
||
sie plattformneutral nach (Laufwerksliste → Wurzeln/Mounts).
|
||
|
||
## Standardwerte und Wertebereiche
|
||
|
||
| Eigenschaft | Bereich | Default |
|
||
|---|---|---|
|
||
| CheckBox.Value | 0 Unchecked · 1 Checked · 2 Grayed | 0 |
|
||
| OptionButton.Value | 0/−1 | 0 |
|
||
| CommandButton.Value | True löst Click aus | False |
|
||
| ComboBox.Style | 0 Dropdown · 1 Simple · 2 Dropdown List | 0 |
|
||
| BorderStyle (Form) | 0 None · 1 Fixed Single · 2 Sizable Single · 3 Fixed Double · 4 Sizable Double · 5 Fixed Solid · 6 Sizable Solid | 2 |
|
||
| BorderStyle (Control) | 0 None · 1 Single · 2 Double (nur Label/PictureBox) | Label 0; TextBox/PictureBox 1 |
|
||
| WindowState | 0 Normal · 1 Minimized · 2 Maximized | 0 |
|
||
| FormType | 0 Normal · 1 MDI-Container | 0 |
|
||
| Timer.Interval | 0–65 535 ms | 0 |
|
||
| ScrollBar Min/Max | −32 768…32 767 | 0 / 32 767 |
|
||
| Small-/LargeChange | 1…32 767 | 1 |
|
||
| TextBox.ScrollBars | 0 None · 1 H · 2 V · 3 Both | 0 |
|
||
| MultiLine/Sorted/Attached | Boolean, Laufzeit read-only | False |
|
||
| Alignment (Label) | 0 Left · 1 Right · 2 Center | 0 |
|
||
| DragMode | 0 Manual · 1 Automatic | 0 |
|
||
| MousePointer | 0–12 (Default, Block, Cross, I-Beam, …) | 0 |
|
||
| ForeColor/BackColor | 0–15 | 0 / 7 |
|
||
| Text (TextBox/ComboBox) | — | Entwurfszeit = CtlName |
|
||
| ListIndex | −1 = keine Auswahl | −1 |
|
||
|
||
## Zeichenbilder und Zustände
|
||
|
||
Die Originalquellen belegen Aufbau und Rahmenformen, enthalten aber keine
|
||
vollständige Screenshot-Reihe für jede Klasse und jeden Zustand. Die folgende
|
||
einheitliche Umsetzung ist deshalb **unsere Festlegung**: normal = die Werte
|
||
aus `ForeColor`/`BackColor`, fokussiert = Farbe 15 auf 1, deaktiviert = Farbe
|
||
8 auf 0. `&` kennzeichnet
|
||
nur den Access-Key und wird nicht ausgegeben. Die Beispiele zeigen jeweils
|
||
normal · fokussiert · deaktiviert; Inhalt wird auf die verfügbare Breite
|
||
gekürzt und der Rest mit Leerzeichen gefüllt.
|
||
|
||
| Klasse | normal | fokussiert | deaktiviert |
|
||
|---|---|---|---|
|
||
| CommandButton, Höhe 1 | `<OK>` | `<OK>` | `<OK>` |
|
||
| CommandButton, Höhe 2 | `┌OK──┐` / `└────┘` | ebenso | ebenso |
|
||
| CommandButton, Höhe ≥ 3 | `┌────┐` / `│ OK │` / `└────┘` | ebenso | ebenso |
|
||
| Label | `Text` | `Text` | `Text` |
|
||
| Frame | `┌ Titel ─┐` / `│ │` / `└────────┘` | ebenso | ebenso |
|
||
| CheckBox | `[ ] Text` | `[ ] Text` | `[ ] Text` |
|
||
| CheckBox, gewählt/grau | `[x] Text` / `[-] Text` | ebenso | ebenso |
|
||
| OptionButton | `( ) Text` | `( ) Text` | `( ) Text` |
|
||
| OptionButton, gewählt | `(•) Text` | `(•) Text` | `(•) Text` |
|
||
| TextBox | `┌──────┐` / `│Text │` / `└──────┘` | ebenso, Cursor an `SelStart` | ebenso, ohne Cursor |
|
||
| ListBox | `┌──────┐` / `│eins │` / `│zwei │` / `└──────┘` | ebenso, aktuelle Zeile in Fokusfarben | ebenso |
|
||
| ComboBox, Dropdown | `[Text ▼]` | ebenso in Fokusfarben | ebenso |
|
||
| ComboBox, Simple | `[Text ▼]` / `┌──────┐` / `│eins │` / `└──────┘` | ebenso in Fokusfarben | ebenso |
|
||
| HScrollBar | `◄──□──►` | ebenso in Fokusfarben | ebenso |
|
||
| VScrollBar | `▲` / `│` / `□` / `│` / `▼` | ebenso in Fokusfarben | ebenso |
|
||
| Spin | `▲` / `▼` oder `◄ ►` | ebenso in Fokusfarben | ebenso |
|
||
| PictureBox | `┌──────┐` / `│Text │` / `└──────┘` | ebenso in Fokusfarben | ebenso |
|
||
| DirListBox | `┌──────┐` / `│[dir] │` / `└──────┘` | ebenso, aktuelle Zeile in Fokusfarben | ebenso |
|
||
| DriveListBox | `[ / ▼]` | ebenso in Fokusfarben | ebenso |
|
||
| FileListBox | `┌──────┐` / `│a.bas │` / `└──────┘` | ebenso, aktuelle Zeile in Fokusfarben | ebenso |
|
||
| Menu | ` Datei Bearbeiten ` | gewählter Titel/Eintrag in Fokusfarben | Text in Farbe 8 |
|
||
| Timer | keine sichtbaren Zellen | keine sichtbaren Zellen | keine sichtbaren Zellen |
|
||
|
||
`BorderStyle = 0` unterdrückt den Rahmen von Label, TextBox und PictureBox;
|
||
`BorderStyle = 2` nutzt `╔═╗║╚╝`. Scrollbars erscheinen nur in den von
|
||
`ScrollBars` genannten Richtungen. Ein unsichtbares Steuerelement zeichnet
|
||
keine Zelle.
|
||
|
||
## Festgelegte Reihenfolgen
|
||
|
||
Die folgenden Regeln sind **unsere Festlegung**, nicht nachgewiesenes
|
||
Referenzverhalten:
|
||
|
||
- **Z-Reihenfolge:** Erzeugungsreihenfolge; später erzeugte Elemente liegen
|
||
oben. Bei Steuerelement-Arrays entscheidet bei sonst gleicher Position der
|
||
aufsteigende Index, sodass der höchste Index oben liegt. Gezeichnet wird von
|
||
unten nach oben, die Trefferprüfung läuft umgekehrt.
|
||
- **Timer-Reihenfolge:** Sind mehrere Timer am selben Zustellpunkt fällig,
|
||
werden ihre Ereignisse in aufsteigender, ASCII-unabhängig
|
||
großgeschriebener `CtlName`-Reihenfolge zugestellt. Mehrere verstrichene
|
||
Intervalle desselben Timers bleiben in zeitlicher Reihenfolge davor.
|
||
|
||
**Keine Default-Eigenschaften:** `Text1 = "x"` gibt es nicht — Zugriff
|
||
immer explizit (`Text1.Text`). „Default" ist nur die CommandButton-
|
||
Eigenschaft (Enter-Taste); „Cancel" analog für Esc.
|
||
|
||
## Ereignis-Signaturen
|
||
|
||
```basic
|
||
SUB Form_KeyDown (KeyCode AS INTEGER, Shift AS INTEGER)
|
||
SUB ctl_KeyPress ([Index AS INTEGER,] KeyAscii AS INTEGER)
|
||
SUB Form_MouseDown (Button AS INTEGER, Shift AS INTEGER, X AS SINGLE, Y AS SINGLE)
|
||
SUB Form_DragDrop (Source AS CONTROL, X AS SINGLE, Y AS SINGLE)
|
||
SUB Form_DragOver (Source AS CONTROL, X AS SINGLE, Y AS SINGLE, State AS INTEGER)
|
||
SUB Form_Unload (Cancel AS INTEGER) ' Cancel <> 0 verhindert Entladen
|
||
```
|
||
|
||
Shift-Bitfeld 1 Shift · 2 Ctrl · 4 Alt; Button 1 links · 2 rechts;
|
||
DragOver-State 0 Enter · 1 Leave · 2 Over. Bei Steuerelement-Arrays steht
|
||
`Index AS INTEGER` immer vorn. KeyAscii ist bei uns ein Unicode-Codepoint
|
||
(UTF-8-Abweichung); klassische KeyCode-Konstanten bleiben gültig
|
||
(Vorbild-Eigenheit: Entf = 127).
|
||
Ereignisse ohne eine der oben genannten Argumentfamilien haben keine
|
||
Parameter. Bei Arrays wird ausschließlich `Index AS INTEGER` vorangestellt;
|
||
die restliche Signatur bleibt unverändert.
|
||
|
||
## SCREEN-Objekt
|
||
|
||
Eigenschaften: ActiveControl, ActiveForm, AutoRedraw, ControlPanel,
|
||
Height, Width (Zeichen, read-only — bei uns die **aktuelle Terminalgröße**,
|
||
Abweichung: das Vorbild lieferte fest 25/43/50 × 80), MousePointer.
|
||
Methoden: HIDE, SHOW (alle sichtbaren Formulare ein-/ausblenden). `SCREEN.ControlPanel(0–17)`
|
||
konfiguriert Systemfarben/-effekte (AccessKey-/Desktop-/Menü-/Titel-
|
||
Farben, Schatten, 3D-Effekte, Desktop-Füllzeichen) — Konstanten in der
|
||
Konstanten-Include-Datei.
|
||
|
||
## Show/Hide/Load/Unload und Modalität
|
||
|
||
`form.SHOW [style%]`: **0 = modeless (Standard), 1 = modal**; lädt bei
|
||
Bedarf. Bei modal läuft der Code nach `SHOW` erst nach Schließen weiter.
|
||
Modal-Stacking-Regeln → Fehler 400–403 (u. a. „MDI form cannot be shown
|
||
modally"). `HIDE` setzt nur `Visible = False`; `LOAD`/`UNLOAD` mit
|
||
Load-/Unload-Ereignis (Cancel-Parameter). `LOAD/UNLOAD ctl(index%)` für
|
||
Steuerelement-Arrays (Entwurfszeit-Elemente sind nicht entladbar,
|
||
Fehler 362); deren Eigenschaften sind über `ctl(index%).Eigenschaft`
|
||
adressierbar und werden beim `LOAD` vom Entwurfszeit-Element 0 geklont.
|
||
|
||
## Menüsystem
|
||
|
||
Definition pro Formular im **Menu Design Window**, bis zu 6 Ebenen.
|
||
Felder: Caption (`&` Access-Key, `-` Separator), CtlName, Tag, Index,
|
||
Checked/Enabled/Visible/Separator, Shortcut-Dropdown. Regeln: Separatoren
|
||
nicht checked/disabled/mit Shortcut; Menütitel ohne Shortcut.
|
||
Menü-Steuerelement-Arrays sind möglich.
|
||
|
||
## Steuerelement-Arrays, Drag & Drop, Custom Controls
|
||
|
||
- **Control-Arrays:** gleiche CtlName + Index; Laufzeit-Erzeugung per
|
||
`LOAD ctl(index%)`.
|
||
- **Drag & Drop:** DragMode 0/1, Methode `DRAG action%` (0 Cancel ·
|
||
1 Begin · 2 Drop), Ereignisse DragDrop/DragOver mit `Source AS CONTROL`.
|
||
- **Custom Controls:** das Vorbild lud sie aus Quick-Libraries; für
|
||
Terminal Basic ist ein natives Erweiterungsmodell **Stufe 2** (PLAN.md).
|
||
|
||
## Offene Detailfragen
|
||
|
||
- `.FRM`-Textformat: exakte Serialisierung (siehe dateiformate.md)
|