# Visuele formulieren in de drie Atari Studios

TTBasic heeft zijn bestaande formulierontwerper. TTMicroPython Studio en
Pure C
Studio gebruiken de hieruit afgeleide gedeelde ontwerper in deze map. Ze
hebben
dezelfde gereedschappen en werken op kale TOS met klassieke GEM/AES/VDI.

## Bediening

- Python: File > New Form; Pure C: File > New Form project.
- Nieuw formulier: ook Ctrl+Shift+D in Python en Pure C.
- Bestaand ontwerp: Ctrl+D of F8, of View > Form designer.
- Kies links Button, Label, TextBox, CheckBox, Radio, ListBox of ComboBox.
  Klik vervolgens in het formulier. Maximaal zestien controls.
- Sleep een control om te verplaatsen; sleep het blokje rechtsonder om te
  vergroten. Pijlen verplaatsen acht pixels; Shift+pijlen wijzigen de
grootte.
- Rechts staan naam, tekst/titel, positie, afmetingen en eventhandler.
  Enabled, Visible, Checked, radiogroep en lijstitems zijn beschikbaar waar
  toepasselijk. Lijstitems worden met `|` gescheiden. Checked op een ListBox
  betekent MultiSelect. Op ST High wordt het eigenschappenpaneel compacter.
- F4 opent de geselecteerde eventhandler. F2 past toe en slaat op. F5 past
  toe en voert uit (Pure C compileert en linkt eerst). Ctrl+D/Code keert
terug
  naar de bron. Ctrl+Z maakt de laatste ontwerpwijziging ongedaan.
- Escape/sluitknop vraagt bij wijzigingen om toepassen, verwerpen of terug.
  Ctrl+pijlen en de pijltjes links verschuiven het werkvlak bij grote
vormen.

De ontwerper verandert een werkkopie. Toepassen genereert in een aparte
buffer;
bij ongeldige gegevens of te veel bronregels blijft de bestaande bron
behouden.
Toepassen is ook in de editor met undo/redo terug te draaien.

## Eigen code behouden

Python bewaart het model in `# @TTFORM`-commentaren; C in
`/* @TTFORM ... */`-commentaren. Het ontwerp wordt zonder uitvoeren van code
teruggelezen. Verander deze commentaren niet met de hand.

Bewerk de eventfuncties buiten het BEGIN/END-blok. Die blijven bij opnieuw
ontwerpen behouden. Ontbrekende events krijgen een lege functie. Het
beheerde
blok bevat de constructie van de GUI; wijzigingen daarin worden vervangen.
Python bouwt de GUI pas nadat de eventfuncties zijn gedefinieerd. Gebruik
Load
voor initialisatie die afhankelijk is van de controls.

Kies componentnamen vo?o?r de eerste keer toepassen. Het hernoemen van al
bestaande componenten wordt in deze eerste Python/C-versie geweigerd, zodat
referenties in eigen code niet ongemerkt stukgaan. TTBasic heeft hiervoor al
een uitgebreidere BASIC-specifieke hernoemfunctie.

## Python

`FORMDEMO.PY` toont alle zeven soorten controls. Het gegenereerde script
gebruikt
`gem` en draait in Studio, TTCON of TTPY met de bijbehorende runtime.
Controls gebruiken `text`, `enabled`, `visible`, `checked` en `group` waar
relevant, en `on_click(callback)` of `on_change(callback)`.

ListBox/ComboBox hebben `add_item(text)` en `list_index` (-1 is geen
selectie).
ListBox heeft `multi_select`, `selected(index)` en `set_selected(index,
bool)`.
De ComboBox is bewerkbaar; de pijl doorloopt de items. Een gesloten venster
bee?indigt de eventlus wanneer er geen andere vensters meer zijn.

## Pure C

`FORMS/FORMS.PCP` is een zelfstandig voorbeeldproject. De ontwerper kopieert
`C:\PCSTUDIO\FORMRT.H` naast de gegenereerde C-bron. Die header bevat de
kleine
GEM-runtime; er is geen afhankelijkheid van Studio, BASIC of MicroPython.
Pure C zelf en zijn standaard GEM/TOS-libraries blijven apart nodig.

De projectinstelling wordt GEM/.PRG. `F9` bouwt; `F5` bouwt en draait.
De gegenereerde `#define`-namen zijn indices in `form_controls`:

```c
void Button1_Click(int sender)
{
    (void)sender;
    strcpy(form_controls[Label2].text, "Geklikt!");
}
```

`form_controls[id]` heeft o.a. `text`, `checked`, `index`, `enabled`,
`visible`,
`group` en het MultiSelect-bitveld `selection`. `form_close()` bee?indigt de
lus.
Load/Closed ontvangen -1; controlcallbacks ontvangen de controlindex.
Het venster wordt na een callback opnieuw getekend. Escape of de sluitknop
sluit het formulier. De ComboBox-pijl doorloopt de items.

De headervoorziening schrijft Atari-CRLF via een tijdelijk bestand en
bewaart
de vorige header als FORMRT.HBK. Eigen bronbestanden behouden de
gebruikelijke
back-ups van de editor.

## Grenzen en bouwen

Ee?n beheerd formulier per bronbestand, maximaal zestien controls en 512
regels
van 159 tekens in Python/C. Ontwerptitels en teksten: afdrukbare ASCII,
maximaal
63 tekens. Lijstitems samen maximaal 63 tekens in het ontwerp; runtime
maximaal
32 items. Ontwerpformaat 120..600 bij 64..400 pixels; grote formulieren
kunnen
buiten de werkruimte van een klein scherm vallen. Geen RSC-import/export of
onderlinge bronimport tussen de drie programmeertalen. Dit is geen belofte
van
volledige gelijkheid van alle taalruntime-API's.

`python3 tools/sync_forms.py` kopieert FORM.C/H, DESIGN.C/H en FORMRT.H naar
beide
zelfstandig te bouwen bronbomen. Wijzig eerst deze gedeelde originelen.
`sh shared/forms/tests/test.sh` controleert generatie en model met
ASan/UBSan.
`python3 tools/check_forms_gui.py ttpython [st]` en dezelfde opdracht met
`purec-studio` bedienen de echte programma's op gei?soleerde Hatari-
schijven.
