MenuItem és TextRenderer dokumentáció

doc/TextRenderer.md

@@ -0,0 +1,218 @@
+# TextRenderer
+
+A `TextRenderer` osztály egy egyszerű, karakterenként gépelődő (typewriter effektusú) szövegmegjelenítő. A szöveget sprite-okként tárolja és rendereli, támogatja a sortörést meghatározott szélesség esetén, valamint speciális karakterek kezelését egyedi `display()` függvényeken keresztül.
+
+---
+
+## Konstruktor
+
+```python
+TextRenderer(x, y, width=None)
+```
+
+Új szövegmegjelenítőt hoz létre.
+
+### Paraméterek
+
+- `x` (`int`) - A szöveg kezdő X koordinátája.
+- `y` (`int`) - A szöveg kezdő Y koordinátája.
+- `width` (`int | None`) - Opcionális maximális szélesség pixelekben. Túllépés esetén automatikus sortörés történik.
+
+### Attribútumok
+
+- `sprites` - A renderelendő karaktersprite-ok listája.
+- `base_x` - Kezdő X koordináta.
+- `base_y` - Kezdő Y koordináta.
+- `width` - Maximális szövegszélesség.
+- `text` - A megjelenítendő szöveg.
+- `textptr` - Az aktuálisan feldolgozott karakter indexe.
+- `x` - Aktuális rajzolási pozíció X tengelyen.
+- `y` - Aktuális rajzolási pozíció Y tengelyen.
+
+---
+
+## `reset(text)`
+
+```python
+reset(text)
+```
+
+Visszaállítja a renderelőt alapállapotba, és új szöveget tölt be.
+
+### Paraméterek
+
+- `text` (`str`) - A megjelenítendő szöveg.
+
+### Működés
+
+- Törli az összes korábbi sprite-ot.
+- Visszaállítja a rajzolási pozíciót a kezdőkoordinátákra.
+- Nullázza a karaktermutatót (`textptr`).
+
+### Példa
+
+```python
+renderer.reset("Helló világ!")
+```
+
+---
+
+## `amend(text)`
+
+```python
+amend(text)
+```
+
+Hozzáfűz további szöveget a már meglévő szöveghez.
+
+### Paraméterek
+
+- `text` (`str`) - A hozzáfűzendő szöveg.
+
+### Példa
+
+```python
+renderer.reset("Helló")
+renderer.amend(" világ!")
+```
+
+Eredmény:
+
+```text
+Helló világ!
+```
+
+---
+
+## `type_tick()`
+
+```python
+type_tick()
+```
+
+Egyetlen karakter feldolgozását végzi el. A függvény elsősorban gépelési animációk megvalósítására használható.
+
+### Visszatérési érték
+
+```python
+bool
+```
+
+- `True` - a teljes szöveg feldolgozása befejeződött.
+- `False` - még vannak feldolgozatlan karakterek.
+
+### Működés
+
+1. Lekéri az aktuális karakterhez tartozó definíciót a `texttable` szótárból.
+2. Ismeretlen karakter esetén a `'?'` definíciót használja.
+3. Látható karakter esetén:
+   - kivágja a megfelelő textúrát a font atlaszból,
+   - létrehozza a sprite adatait,
+   - hozzáadja azokat a `sprites` listához.
+4. Ha a megadott szélesség elfogyott:
+   - új sorba lép,
+   - az Y koordinátát 13 pixellel csökkenti.
+5. Nem látható karakter esetén meghívja a karakter:
+
+```python
+display(renderer)
+```
+
+metódusát.
+
+### Példa
+
+```python
+while not renderer.type_tick():
+    pass
+```
+
+---
+
+## `type_all()`
+
+```python
+type_all()
+```
+
+A teljes szöveget azonnal feldolgozza.
+
+### Működés
+
+A `type_tick()` függvényt hívja ismételten addig, amíg minden karakter feldolgozásra nem kerül.
+
+### Példa
+
+```python
+renderer.reset("Szia!")
+renderer.type_all()
+```
+
+A teljes szöveg egyetlen frame alatt elkészül.
+
+---
+
+## `render()`
+
+```python
+render()
+```
+
+Kirajzolja az összes létrehozott karaktersprite-ot.
+
+### Működés
+
+A `sprites` listán végighaladva minden karakterhez meghívja:
+
+```python
+arcade.draw_texture_rect()
+```
+
+függvényt pixelpontos (`pixelated=True`) rendereléssel.
+
+### Példa
+
+```python
+def on_draw(self):
+    arcade.start_render()
+    renderer.render()
+```
+
+---
+
+# Tipikus használat
+
+## Gépelési effekt
+
+```python
+renderer = TextRenderer(10, 100, width=200)
+
+renderer.reset(
+    "Ez egy hosszabb szöveg, amely több sorba törhet."
+)
+
+renderer.type_tick()
+
+renderer.render()
+```
+
+## Azonnali megjelenítés
+
+```python
+renderer = TextRenderer(10, 100)
+
+renderer.reset("Helló világ!")
+renderer.type_all()
+
+renderer.render()
+```
+
+---
+
+# Megjegyzések
+
+- Az osztály nem hoz létre külön `Sprite` objektumot minden karakterhez, hanem csak a szükséges textúrát és pozíciót tárolja.
+- Ismeretlen karakter esetén automatikusan a `'?'` karakter kerül megjelenítésre.
+- A sortörés kizárólag a megadott `width` túllépésekor történik.
+- Speciális vezérlőkarakterek létrehozhatók `visible=False` karakterdefiníciókkal.
+- Ezek a karakterek tetszőleges működést valósíthatnak meg a `display(renderer)` metóduson keresztül.