# TTMicroPython Studio 0.1 ? handleiding

## Installatie

Kopieer `TTPY` uit de distributie naar `C:\TTPY`. Start `TTPYST.PRG` voor
Studio of `TTCON.PRG` voor een los consolevenster. Je hebt tijdens gebruik
geen Pure C, compiler, MiNT, Linux of moderne computer nodig. De voorbeelden
gebruiken korte TOS-bestandsnamen; houd alle `.PY`-bestanden bij elkaar.

De map `Schijf-C/TTPY` is in deze werkomgeving alvast ingericht. TT BASIC
staat in zijn eigen map en is niet vervangen. Er is geen autostart of
desktopconfiguratie aangepast.

## Studio

Links zie je de `.PY`-bestanden in de huidige map. In het midden staat de
editor, onderaan de uitvoer met een Python-prompt. Klik een bestandsnaam aan
om dat bestand te laden. Een sterretje bij de naam betekent dat de editor
wijzigingen heeft die nog niet zijn opgeslagen.

De bestandenlijst is een mapweergave, geen projectmanifest. Imports volgen
de normale Python-syntaxis. Scripts zoeken ook naast het uitgevoerde bestand
naar modules. `GEMDEMO.PY` gebruikt bijvoorbeeld `from COUNTER import
Counter`.

| Toets | Studio |
| --- | --- |
| Ctrl+N | Nieuw Python-bestand; kies een nieuwe naam met `.PY`. |
| Ctrl+O | Bestaand Python-bestand openen. |
| Ctrl+S | Opslaan. De vorige versie wordt `.BAK`; schrijven gebeurt eerst
via `.PNW`. |
| Ctrl+Z | Laatste editorbewerking ongedaan maken. |
| Ctrl+R of F5 | De huidige editorinhoud uitvoeren, ook als die nog niet is
opgeslagen. |
| Ctrl+L | Wisselen tussen editor en console-invoer. |
| Tab in de editor | Spaties invoegen tot de volgende stap van vier. |
| Tab in console-invoer | Terug naar de editor. |
| Escape of Ctrl+C tijdens uitvoering | Python onderbreken met
KeyboardInterrupt. |
| F1 | Toetsenoverzicht. |
| Ctrl+Q | Afsluiten; bij niet opgeslagen editorwijzigingen wordt eerst
gevraagd. |

Pijltjes, Home, End, Page Up/Down, Backspace, Delete en Enter werken in de
editor. Enter neemt inspringing over; na een dubbele punt voegt hij vier
spaties toe. Horizontaal en verticaal schuiven volgt de cursor.

Opslaan bewaart de vorige schijfversie als `.BAK`. Bij een niet afgehandeld
oud `.PNW`-bestand weigert Studio een nieuwe save, zodat dat bestand eerst
bekeken kan worden. Bestanden die te groot zijn voor de editor worden
geweigerd; de huidige editorinhoud blijft behouden. CRLF wordt bij laden
naar LF omgezet en tabs worden naar Python-equivalente stappen van acht
spaties uitgebreid. Bij nieuwe invoer gebruikt Tab vier spaties.

## Een zichtbare Python-console

Bij `>>>` kun je direct een Python-opdracht of uitdrukking intypen:

```python
answer = 6 * 7
answer
```

De tweede opdracht toont `42`. Variabelen en functies blijven tussen
opdrachten beschikbaar. Een Python-fout toont een traceback en bee?indigt de
opdracht; daarna kun je verder werken met gewone variabelen uit dezelfde
sessie.

Bij een meerregelig blok wordt de prompt `...`. Bijvoorbeeld:

```python
def twice(x):
    return x * 2

```

Na de lege regel kun je `twice(answer)` uitvoeren. Ook haakjes die op een
volgende regel worden gesloten worden herkend. Met pijl omhoog/omlaag blader
je door de laatste 24 niet-lege invoerregels. Links/rechts/Home/End en
Backspace/Delete bewerken de invoerregel.

Escape of Ctrl+C annuleert invoer of onderbreekt een lopende berekening. Na
een KeyboardInterrupt blijft de console bruikbaar. De menuoptie Clear
console wist alleen de zichtbare uitvoer.

**Run source begint een nieuwe Python-sessie.** De variabelen van het
uitgevoerde script blijven daarna in de console beschikbaar. Zo kun je na
het sluiten van het GEM-voorbeeld `counter.value` opvragen. Een nieuwe Run
wist de oude namespace.

## Los consolevenster

`TTCON.PRG` bevat dezelfde interpreter, maar toont alleen de console. Het
heeft een eigen GEM-venster en werkt ook in ST Low op een
320?200-kleurenscherm.

- Ctrl+N of New: een nieuwe Python-sessie; oude variabelen verdwijnen.
- Ctrl+K of Clear: zichtbare uitvoer wissen.
- Escape/Ctrl+C: invoer annuleren of uitvoering onderbreken.
- F1: hulp.
- Ctrl+Q of `exit()`/`quit()`: afsluiten.

Dit is een Python-REPL, geen algemene TOS- of Unix-shell. Onder kale TOS
zijn Studio en het losse consoleprogramma afzonderlijke toepassingen; de
console binnen Studio draait in hetzelfde programma als de editor.

## GEM vanuit Python

De publieke 0.1-module heet `gem` en biedt:

```python
import gem

window = gem.Window('Mijn Python-app', 360, 180)
label = gem.Label(window, 'Hallo Atari!', 16, 16, 300, 24)
button = gem.Button(window, 'Klik hier', 16, 64, 160, 32)

def clicked(sender):
    label.text = 'De knop werkt!'
    print('Klik ontvangen')

button.on_click(clicked)
window.show()
gem.run()
```

De vijf ondersteunde classes zijn `Window`, `Button`, `Label`, `TextBox` en
`CheckBox`. Naast `Window(title, width, height)` gebruiken de controls
`Control(window, text, x, y, width, height)`. Posities zijn relatief aan het
werkgebied van hun Window. Een control moet binnen zijn oudervenster passen.

- `.text` leest of wijzigt de tekst.
- `.checked` leest of wijzigt de stand van een CheckBox.
- `.on_click(handler)` verbindt een procedure met de klik; die ontvangt het
control als `sender`.
- `.on_change(handler)` kan bij een TextBox worden gebruikt; wijzigingen
door toetsenbordinvoer sturen dat event.
- `window.show()` opent het venster; `window.close()` sluit het.
- `gem.run()` verwerkt gebeurtenissen tot alle geopende Python-vensters
gesloten zijn, of `gem.exit()` wordt gevraagd.
- `gem.alert('Een melding')` toont een klassieke GEM-melding met OK. Er is
een grens van vijf regels van 38 tekens. GEM-scheidingstekens worden veilig
vervangen.

De C-port houdt verwijzingen naar de levende controls en callbacks vast voor
de garbage collector. Een niet opgevangen fout of een nieuwe sessie ruimt de
Python-vensters op. Oude controlobjecten uit een opgeruimde GUI zijn daarna
niet opnieuw te gebruiken.

Het uitgebreidere voorbeeld `GEMDEMO.PY` laat een TextBox, CheckBox, knop,
label en sluitknop zien. De klikprocedure voert ook een expliciete GC-ronde
uit, zodat deze koppeling in de tests wordt gecontroleerd.

## Scripts vanuit een tekstshell uitvoeren

Als je al een TOS-shell gebruikt:

```text
C:\TTPY\TTPY.TOS C:\TTPY\MAIN.PY
```

Zonder argument probeert het programma `MAIN.PY` in de huidige werkmap.
`TTPY.TOS` voert een script uit; de interactieve vensterconsole is
`TTCON.PRG`. De distributie bevat zelf geen algemene TOS-shell.

## Grenzen van deze versie

- Python-heap: vast 2 MiB. Meer totaal RAM vergroot de Python-heap nog niet
automatisch.
- Editor: 512 regels van maximaal 159 bytes per regel. Console-invoer:
maximaal 158 tekens per regel en ongeveer 8 KiB per meerregelig blok.
- Bestandenlijst: maximaal 32 `.PY`-bestanden in de huidige map.
- Uitvoerlog: laatste 128 regels; weergave is beperkt tot de zichtbare
vensterruimte. Er is nog geen logscrollbar.
- GEM: maximaal 48 objecten in de port, naast de vensterlimieten van AES.
Tekst is maximaal 127 bytes; weergave gebruikt de klassieke Atari-letterset.
- Bestandslezer voor scripts/imports: maximaal 1 MiB per bestand.
- Nog geen debugger of uitgebreide projectbestanden. Code completion,
tekstselectie, intern klembord en undo/redo zijn beschikbaar in de editor.
- Nog geen `os`, netwerk, pip, Tkinter, Qt of CPython-extensies.
`open()`/bestands-I/O is toegevoegd in de ontwikkelbuild; zie het nieuwe
hoofdstuk.
- Dit is MicroPython, geen volledige implementatie van de nieuwste CPython-
release. Welke standaardfuncties aanwezig zijn hangt van de portconfiguratie
af.

Studio vraagt minimaal 640?400 en meldt dat bij een te klein scherm. Gebruik
de losse console op een lage resolutie. Vier MiB is het geteste minimum voor
deze build met voorbeelden; het is geen garantie dat ieder Python-programma
in die configuratie past. Een fysieke hardwaretest staat nog open.

## Inklapbare panelen (ontwikkelversie, 8 november 2026)

In Studio klapt Ctrl+L de Python-console in of uit. Je kunt ook op
`- Console` / `+ Console` rechtsboven klikken, of op `[-]` in de consolekop.
Bij openen gaat de invoerfocus naar de console; bij sluiten naar de editor.
Variabelen, geschiedenis, nog niet uitgevoerde invoer en een half ingevoerd
Python-blok blijven behouden. Run source maakt de uitvoerconsole zichtbaar.

Ctrl+B klapt het projectpaneel (de bestandenlijst naast het script) in of
uit.
Met de muis klik je op `- PROJECT` of de overblijvende `+` linksboven.
Het View-menu biedt beide schakelaars. De editor gebruikt de vrijgekomen
breedte en hoogte. Dit werkt ook op ST High, 640x400 monochroom.
De losse TTCON.PRG blijft een volledig consolevenster.

Deze functies horen bij de panelen-proefversie, niet bij de oorspronkelijke
0.1-downloads op de website. De keuzes gelden voor de huidige sessie.

## Bestanden met open() (ontwikkelversie)

`open()` en `io.open()` leveren echte TOS-bestandsobjecten. Tekstmodi geven
Strings terug; binaire modi geven bytes terug. `with` sluit bij normale
afloop
en bij een exception. Ook `close()` is beschikbaar en mag herhaald worden.

```python
with open("DATA.TXT", "w", encoding="utf-8") as f:
    f.write("Hallo Atari\n")
with open("DATA.TXT") as f:
    for line in f:
        print(line.rstrip())
with open("DATA.BIN", "wb") as f:
    f.write(bytes([0, 128, 255]))
```

Modi: `r` (standaard), `w` (nieuw/leegmaken), `a` (altijd toevoegen),
optioneel
`b` of `t` en `+`. Voorbeelden: `rb`, `wb`, `r+b`, `w+b`, `a+b`.
Methoden: `read`, `readinto`, `readline`, `readlines`, `write`, `seek`,
`tell`,
`flush`, `close`, plus iteratie en contextbeheer. `read()` zonder aantal
leest
het resterende bestand in het Python-geheugen; lees grote bestanden in
blokken.

Tekst is UTF-8; `encoding="utf-8"` of `"utf8"` is optioneel. Tekst lezen
normaliseert CRLF en CR naar LF; tekst schrijven zet LF om naar Atari CRLF.
Binaire modi bewaren alle bytes exact. Seek/tell gebruiken native
byteposities,
ook bij tekst; seek naar 0 of een eerder verkregen tell-positie is het
veiligst.
Paden zijn relatief aan de actuele TOS-werkmap, niet automatisch aan de plek
van het script. Gebruik absolute paden als dat nodig is en Atari 8.3-namen.

Er zijn maximaal 16 gelijktijdig open bestanden. GC sluit vergeten
bestanden;
alle resterende bestanden sluiten ook bij het beeindigen/resetten van een
Python-sessie. Gebruik with voor tijdig sluiten en foutmeldingen.
Ontbrekende
bestanden, verkeerde toegang en schijffouten geven OSError; ongeldige modi
en
I/O na close geven ValueError. Dit is geen volledige CPython-IO: andere
encodings, buffering/newline/errors-parameters, x-modus, fileno en
uitgebreide
bestandsattributen worden niet aangeboden. `os`, netwerk en pip blijven
buiten
deze port. Zie FILEDEMO.PY. De oorspronkelijke 0.1-download is ongewijzigd.

De streammethoden volgen de MicroPython-stream-API:
https://docs.micropython.org/en/latest/library/io.html


### Editor: undo/redo, zoeken/vervangen en blokken

Zie [de editorhandleiding](editor-nl.md) voor Ctrl+Z/Y, Ctrl+F/H, F6,
selectie
en Tab/Shift+Tab. Deze functies zijn ook bereikbaar via Bewerken/Edit.


### F-strings (build 13 november 2026)

F-strings zijn ingeschakeld in Studio, de interactieve console en de script-
CLI. Je kunt expressies, objectvelden en methoden direct in een tekst
opnemen:

```python
gem.alert(f'{counter.add()},{name.text}')
```

`counter.add()` verhoogt de teller; gebruik `counter.value` om alleen de
huidige waarde te tonen. Ook `f'{counter.value:03d}'`, `f'{1.25:.2f}'`, `!r`
en dubbele accolades (`{{` en `}}`) worden ondersteund. Het voorbeeld
`FSTRING.PY` gebruikt `COUNTER.PY` en toont de melding via een knop.
Herstart Studio/console na vervanging van de programmabestanden; oudere
builds ondersteunen deze syntax niet.


### Code completion in de Python-editor (14 november 2026)

- **Ctrl+Spatie** of **Edit ? Complete** opent de voorstellen. Na een punt
verschijnt de lijst automatisch.
- Typ verder om te filteren; **pijltjes omhoog/omlaag** of PageUp/PageDown
kiezen een voorstel. **Enter**, **Tab** of een muisklik voegt de naam in.
**Esc** sluit de lijst.
- De regel onder de lijst toont een korte signature of typehint. Alleen de
naam wordt ingevoegd; voeg zelf de haakjes en argumenten toe. Invoegen
vervangt het hele woord onder de cursor en is e?e?n undo-stap, ook na
opslaan.

Voorbeelden: `gem.al` ? `alert`, `name.te` ? `text`, `counter.ad` ? `add`.
De hulp herkent Python-sleutelwoorden en gangbare ingebouwde functies, de
publieke API van `gem`, `gc`, `sys` en `game`, eenvoudige toewijzingen,
functieparameters, eigen klassen/methoden en velden op `self`. Ook aliassen
en directe lokale imports zoals `from COUNTER import Counter` worden
gelezen. Het programma en gei?mporteerde modules worden daarbij nooit
uitgevoerd.

Dit is een beperkte bronindex, geen volledige Python-typechecker: dynamische
typen, overerving, complexe expressies en onherkenbare terugkeertypen worden
niet geraden. Maximaal acht directe lokale modules met een 8.3-bestandsnaam,
256 symbolen en 64 voorstellen; gei?mporteerde bestanden moeten binnen 512
regels van 159 tekens passen. Aanvullen gebeurt buiten strings en
commentaar; ook de inhoud van f-strings blijft buiten de index. Underscore-
leden zijn beschikbaar via Ctrl+Spatie na een underscore. De losse console
krijgt in deze versie geen completion.

De tijdelijke bronindex wordt na het aanvullen vrijgegeven. Studio wordt
voor distributie gestript van linkersymbolen, zodat het programma met de
aanvulhulp op een DD-diskette blijft passen.

## Visuele formulierontwerper (forms-preview, 16 november 2026)

File > New Form maakt een nieuw visueel formulier. Ctrl+D of F8 opent het
ontwerp opnieuw. Plaats controls met de gereedschappen links; rechts bewerk
je eigenschappen en eventnamen. F4: eventcode, F2: toepassen en opslaan,
F5: toepassen en uitvoeren. Eigen eventfuncties buiten het @TTFORM
BEGIN/END-
blok blijven behouden. Zie FORMS.TXT en FORMDEMO.PY in de nieuwe
distributie.
Bestaande componentnamen hernoemen is in deze eerste versie beperkt; kies
namen voor de eerste keer toepassen. De oudere downloads hebben geen
ontwerper.
