196 lines
9.9 KiB
Markdown
196 lines
9.9 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, 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.
|
||
|
||
**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, Tag, Visible (Shortcut nur zur Entwurfszeit).
|
||
|
||
**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 |
|
||
|
||
**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
|
||
|
||
- Exakte Optik je Steuerelement-Zustand (normal/fokussiert/deaktiviert):
|
||
aus den Original-Screenshots ableiten (Phase 4)
|
||
- Z-Reihenfolge/Überlappung: Verhalten bei überlappenden Controls
|
||
- Timer-Reihenfolge bei mehreren gleichzeitig fälligen Timern
|
||
- `.FRM`-Textformat: exakte Serialisierung (siehe dateiformate.md)
|