🖥️ GUI (Uživatelské rozhraní)

Grafické rozhraní CLua je postaveno na Terminal.GUI 2.4.4 a ovládá se z Lua přes vysokoúrovňové factory funkce definované v utils/elements.lua. Ty obalují nízkoúrovňové GUI.* C# volání a vracejí objekty prvků s metodami pro další manipulaci.

📐 XYWH — Pozice a velikost

Většina factory funkcí přijímá tabulku XYWH pro pozicování:

XYWH(x, y, šířka, výška)

local pos = XYWH(5, 2, 40, 10);

🪟 Okna (Window)

Okna jsou kontejnery nejvyšší úrovně. V jednu chvíli je viditelné vždy jen jedno okno.

local win = getWindow(name, visible, el)

local mainWin = getWindow("Hlavní menu", true, {});

Přepínání oken

setActiveWindow(win)   -- globální helper
win:SetActive()        -- metoda na objektu okna

Metody oken

🗂️ Frame (Rámeček)

Frame je ohraničený podkontejner uvnitř okna.

local frame = getFrame(parent, coors, name, el)

local panel = getFrame(mainWin, XYWH(1, 1, 38, 8), "Nastavení", {});

📜 Scrollbox

Scrollovatelný kontejner.

local box = getScrollbox(parent, coors, el)

🔘 Tlačítko (Button)

local btn = getButton(parent, coors, name, callback, el)

Callback může být:

• Funkce: zavolána přímo; el.params jsou předány jako argumenty
• String: vyhodnocen jako Lua v globálním scope při každém kliknutí

Použij "__self" uvnitř el.params pro referenci na samotný prvek tlačítka:

local btn = getButton(mainWin, XYWH(5, 5, 20, 1), "Spustit", mojeFunkce, {
    params = { "__self", "extraArg" }
});

Metoda tlačítka

btn:SetCallback(fn, ...)   -- změna callbacku po vytvoření

🏷️ Popisek (Label)

Statický textový prvek.

local lbl = getLabel(parent, coors, text, el)

local lbl = getLabel(mainWin, XYWH(2, 1, 30, 1), "Ahoj světe", {});
lbl:SetText("Aktualizovaný text");

📊 Progress Bar

local bar = getProgressBar(parent, coors, el)

Pozn: z XYWH se použijí pouze x, y a width.

bar:SetProgress(0.5);   -- hodnota mezi 0.0 a 1.0

☑️ Zaškrtávací políčko (Checkbox)

local cb = getCheckbox(parent, coors, text, el)

Pozn: z XYWH se použijí pouze x a y (velikost je automatická).

cb:SetChecked(true);
local stav = cb:GetChecked();   -- vrací boolean

🔵 Radio skupina (Radio Group)

local radio = getRadio(parent, coors, items, el)

local radio = getRadio(mainWin, XYWH(2, 3, 0, 0), {"Možnost A", "Možnost B", "Možnost C"}, {});
radio:SetRadioSelected(1);         -- vyber první možnost (indexováno od 1)
local sel = radio:GetRadioSelected();

✏️ Textové pole (TextField — jeden řádek)

local field = getTextField(parent, coors, text, el)

callback_keyup podporuje tokeny v obou režimech:

• String callback: tokeny se nahradí přímo v řetězci — %k (kód klávesy), %c (znak), %id (ID prvku)
• Function callback s el.params: použij token string v poli params — nahradí se skutečnými hodnotami před zavoláním funkce:
  • "k%" → kód klávesy (číslo)
  • "c%" → znak (string)
  • "id%" → ID prvku
  • "__self" → reference na samotný prvek

-- string callback s tokeny
local field = getTextField(mainWin, XYWH(2, 5, 30, 1), "", {
    callback_keyup = "print('klávesa: %k, znak: %c')"
});

-- function callback s více tokeny v params
local field2 = getTextField(mainWin, XYWH(2, 8, 30, 1), "", {
    callback_keyup = function(key, char, self) print("klávesa:", key, "znak:", char) end,
    params = { "k%", "c%", "__self" }
});

field:GetText();
field:SetText("nová hodnota");
field:SetReadOnly(true);

📝 Textová oblast (TextBox — více řádků)

local box = getTextBox(parent, coors, text, el)

callback_keyup podporuje tokeny v obou režimech: (stejné tokeny a params jako TextField)

• String callback: tokeny se nahradí přímo v řetězci — %k (kód klávesy), %c (znak), %id (ID prvku)
• Function callback s el.params: použij token string v poli params — nahradí se skutečnými hodnotami před zavoláním funkce:
  • "k%" → kód klávesy (číslo)
  • "c%" → znak (string)
  • "id%" → ID prvku
  • "__self" → reference na samotný prvek

local box = getTextBox(mainWin, XYWH(2, 5, 40, 10), "", { readOnly = true });
box:SetText("Nějaký obsah");

🔧 Společné metody prvků

Všechny prvky (kromě Window) dědí z ElementClass:

🗑️ Mazání prvků

Prvky lze za běhu odebrat z GUI:

GUI.DestroyElement(el.ID)       -- odstraní prvek a všechny jeho potomky
GUI.DestroyAllElements()        -- odstraní vše a vyčistí menu lištu

DestroyElement přijímá interní ID prvku (el.ID), rekurzivně odstraní všechny potomky a vyčistí zaregistrované callbacky. DestroyAllElements odstraní všechny prvky a vyčistí menu lištu, ale neresetuje Lua stav.

local lbl = getLabel(win, XYWH(2, 1, 30, 1), "Dočasné", {});
-- ... později:
GUI.DestroyElement(lbl.ID);

📋 Menu lišta

Horní menu lištu lze přizpůsobit z Lua:

GUI.AddMenuItem("_File", "_Export", "setActiveWindow(exportWin)");
GUI.UpdateMenuItem("_File", "_Export", "Nový popisek");
GUI.RemoveMenuItem("_File", "_Export");

Třetí argument je string Lua kódu, který se spustí při kliknutí na položku menu.

Pozn: AddMenuItem(...) je globální zkratka — lze volat bez prefixu GUI..

✍️ Příklad: Jednoduché okno s tlačítkem

local win = getWindow("Můj nástroj", true, {});

local lbl = getLabel(win, XYWH(2, 1, 30, 1), "Stiskni tlačítko:", {});

local btn = getButton(win, XYWH(2, 3, 20, 1), "Spustit makro", function()
    lbl:SetText("Probíhá...");
    -- práce zde
    lbl:SetText("Hotovo!");
end, {});

-- Registrace okna do menu lišty
GUI.AddMenuItem("_File", "_Můj nástroj", "setActiveWindow(win)");

-- Aktivace okna při startu
setActiveWindow(win);