Dokumentace CLua

🔧 Pomocné funkce

CLua poskytuje sadu globálních pomocných funkcí a rozšíření definovaných v utils/utils.lua. Jsou dostupné automaticky ve všech skriptech.

🎨 Barevné funkce

Používají se kdekoliv, kde se přijímá barevná hodnota (např. formátování XLSX, GUI).

RGB(r, g, b)            -- {red, green, blue}
RGBA(r, g, b, a)        -- {red, green, blue, alpha}
GRAY(v)                 -- RGB(v,v,v)
GRAYA(v, a)             -- šedá s průhledností
BLACK()                 -- RGB(0,0,0)
BLACKA(a)               -- černá s průhledností
WHITE()                 -- RGB(255,255,255)
WHITEA(a)               -- bílá s průhledností

GetHexColor(rgb)        -- převede RGB tabulku na string "#rrggbb"

local c = RGB(255, 128, 0)
print(GetHexColor(c))   -- "#ff8000"

Pozn: CLua GUI prvky ani tabulky XLSX nepracují s alfa kanálem, jakákoliv hodnota bude ignorována.

Více o barvách v rámci GUI v kartě Barvy & Schémata.

📐 Konstruktor XYWH

Vytvoří tabulku souřadnic/velikosti pro pozicování GUI prvků.

XYWH(x, y, šířka, výška)   -- vrátí {X, Y, W, H}

🔀 switch

Vzor switch/case pro Lua:

switch(hodnota) {
    [1] = function() print("jedna") end,
    [2] = function() print("dva") end,
    default = function() print("jiné") end,
}

🛡️ safeCall

Obalí volání funkce v xpcall s debug.traceback jako error handlerem. Vrátí true/výsledek při úspěchu, nebo false/traceback při chybě.

local ok, result = safeCall(mojeFunkce, arg1, arg2)
if not ok then
    print("Chyba:", result)
end

⏱️ Časové funkce

clock           -- alias pro os.clock (CPU čas v sekundách)

getTime(t)      -- zformátuje časovou hodnotu (z os.clock) jako čitelný string

🐛 Debug pomocník

debugTracker    -- alias pro debug.traceback
                -- zachován před uzamčením sandboxu (debug knihovna je jinak vypnutá)

🔤 Rozšíření stringu

Rozšíření přidaná do standardní string knihovny:

Funkce	Popis
`string.trim(s)`	Odstraní mezery ze začátku a konce
`string.rtrim(s)`	Odstraní mezery pouze z konce
`string.ctrim(s)`	Sloučí vnitřní mezery na jednu
`string.startswith(s, prefix)`	Vrátí `true` pokud `s` začíná na `prefix`

local s = "  hello world  "
print(s:trim())               -- "hello world"
print(s:startswith("  he"))   -- true

K dispozici jsou také dva globální pomocníci pro práci se stringy:

Tab(n)              -- vrátí string n mezer (pro odsazení)
StripParnt(str)     -- odstraní obsah v závorkách [...] (včetně vnořených)

print(Tab(4) .. "položka")                           -- "    položka"
print(StripParnt("foo [bar] baz [x[y]z] end"))       -- "foo  baz  end"

📦 Rozšíření tabulky

Rozšíření přidaná do standardní table knihovny:

Funkce	Popis
`table.contains(tbl, val)`	Vrátí `true` pokud `val` je v tabulce
`table.removeValue(tbl, val)`	Odstraní první výskyt `val`
`table.diff(tblA, tblB)`	Odstraní z `tblA` všechny hodnoty, které jsou v `tblB`
`table.copytable(orig)`	Hluboká kopie tabulky
`table.serialize(val, name, ...)`	Serializuje hodnotu do Lua string reprezentace

local t = {1, 2, 3, 4, 5}
table.diff(t, {2, 4})
-- t je nyní {1, 3, 5}

🔢 Rozšíření matiky

Rozšíření přidaná do standardní math knihovny:

Funkce	Popis
`math.odd(n)`	Vrátí `true` pokud je `n` liché
`math.even(n)`	Vrátí `true` pokud je `n` sudé
`math.sign(n)`	Vrátí `-1`, `0` nebo `1` podle znaménka `n`
`math.div(a, b)`	Celočíselné dělení
`math.round(n)`	Zaokrouhlí na nejbližší celé číslo
`math.trunc(n)`	Ořízne směrem k nule
`math.minmax(val, min, max)`	Omezí `val` na rozsah `min`–`max`
`math.roundup`	Alias pro originální built-in `math.sign` (v tomto Lua buildu funguje jako roundup)

⚙️ Makro utility

Pomocné utility pro sledování průběhu maker a formátování stringů. Definovány v utils/macros_utils.lua.

Progress controller

Slouží k ovládání GUI okna s průběhem — podporuje až 3 progress bary.

local prog = newProgress(
    winElement,              -- Window    (z getWindow)
    titleLblElement,         -- Label     (z getLabel)
    { lbl1, lbl2, lbl3 },    -- 3 Label prvky          (z getLabel)
    { bar1, bar2, bar3 },    -- 3 ProgressBar prvky    (z getProgressBar)
    doneBtnElement,          -- Button    (z getButton)
    cancelBtnElement         -- Button    (z getButton)
)

Parametr	Typ	Popis
`window`	Window element	Okno průběhu (`getWindow`)
`mainLabel`	Label element	Hlavní titulkový label (`getLabel`)
`processLabels`	tabulka 3 Label prvků	Jeden label procesu na každý bar (`getLabel`)
`progressBars`	tabulka 3 ProgressBar prvků	Tři progress bary (`getProgressBar`)
`returnButton`	Button element	Tlačítko "Hotovo" (`getButton`)
`cancelButton`	Button element	Tlačítko "Zrušit" (`getButton`)

Metoda	Popis
`prog:Init(title, bar1, bar2, bar3)`	Inicializuje; zobrazí/skryje každý bar (`true`/`false`)
`prog:SetTitle(title)`	Aktualizuje titulkový label
`prog:SetRange(barID, maxValue)`	Nastaví maximální hodnotu pro bar (pro automatické škálování)
`prog:SetProces(barID, text)`	Nastaví text procesu u daného baru
`prog:SetProgres(barID, value)`	Nastaví průběh (auto-škáluje: `value / maxValue`)
`prog:SetButtonVissible(done, cancel)`	Zobrazí/skryje tlačítka návratu a zrušení

prog:Init("Exportuji...", true, false, false);
prog:SetRange(1, celkemRadku);

for i = 1, celkemRadku do
    prog:SetProces(1, "Řádek " .. i);
    prog:SetProgres(1, i);
end

prog:SetButtonVissible(true, false);

📋 ListClass

Jednoduchý indexovaný seznam s automatickým sledováním ID. Definován v utils/lists.lua.

local list = ListClass.Make(useShift)

Pokud je useShift true, smazané položky se automaticky kompaktují (posunou); jinak zůstávají mezery.

Každá přidaná položka automaticky dostane dvě pole:

item.inList — reference na seznam, do kterého patří
item.inListID — její index v seznamu

Metoda	Popis
`list:Add(item)`	Přidá položku na konec; vrátí položku
`list:Set(id, item)`	Nastaví položku na konkrétní index
`list:Get(id)`	Získá položku podle indexu
`list:GetLast()`	Získá poslední položku
`list:Delete(item)`	Odstraní položku podle reference
`list:DeleteID(id)`	Odstraní položku podle indexu
`list:FindFree()`	Najde první volný (`nil`) slot
`list:FindUsed(start)`	Najde první obsazený slot od `start`
`list:Trim()`	Odstraní prázdné konce; kompaktuje pokud je nastaven `useShift`

local list = ListClass.Make(true);

local a = list:Add({ name = "Alpha" });
local b = list:Add({ name = "Beta" });

print(b.inListID)       -- 2
list:Delete(a);
print(list:Get(1).name) -- "Beta" (posunuto)