Lua scripting

How to use it

Lua scripting is optional and controlled by KUI_ENABLE_SCRIPTING. Read _VERSION from the delivered runtime for its version. One build's verified version does not apply to all platforms. KUI does not provide a browser JavaScript runtime.

Integration and limits

Define parameters, errors and object ownership when bridging interface scripts to native code. Execute trusted application scripts, and do not concatenate external input into executable code. Return host asynchronous work to the UI thread before touching the interface.

Attach scripting to a window

After loading HTML, create a ScriptEngine, bind the document, execute script tags and associate it with the window. The caller owns the returned unique_ptr and keeps it alive while the window uses it. If ScriptEngine::create returns null, check whether scripting is included in the runtime.

std::unique_ptr<kui::ScriptEngine> attachScripts(kui::Window& window) {
    auto engine = kui::ScriptEngine::create();
    if (!engine) return nullptr;
    engine->bindDocument(window.document());
    engine->executeScripts();
    window.setScriptEngine(engine.get());
    return engine;
}

Query elements and handle events

This script needs an action button and an output element in the page. Use colon syntax for object methods; textContent is a property. Do not treat references to removed elements as permanent handles.

local count = 0
local button = document:getElementById("action")
local output = document:getElementById("output")
button:addEventListener("click", function(event)
    count = count + 1
    output.textContent = "Clicks: " .. tostring(count)
end)

Window functions and form values

window.innerWidth(), window.innerHeight() and window.devicePixelRatio() use dot-call syntax. document:body() uses a colon. Read current input through its value property, treating default values and checked/defaultChecked separately. Similar names do not establish complete browser-script equivalence.

print(_VERSION)
print(window.innerWidth(), window.innerHeight())
local input = document:getElementById("name")
if input then print(input.value) end

• Lua API catalogue →
• Lua examples →

Animation, timers and observers

The scripting surface includes setTimeout, setInterval, requestAnimationFrame, Promise, JSON and DOM observers. Stop continuous animation when hidden or no longer needed. Consult each API for listener return values and removal rules on document, Element and window.

• Timer APIs →
• Observer APIs →

Attach and clean up scripting

Loading HTML alone does not perform every scripting integration step. Use an SDK with scripting support.

1. Load a document containing a text/lua script.
2. Create and check ScriptEngine, then bindDocument and executeScripts.
3. Associate it with window->setScriptEngine and keep the engine alive through the event loop.
4. Detach it from the window and unbindDocument on exit; avoid script references to a destroyed document.

When scripts do not run

Use the symptom to narrow the cause before editing.

Start with a runnable lesson

The Forge Library lesson reads input, saves, updates a counter and restores a name. C++ manages the window and engine; the UI feedback lives in the Lua source.

• Hands-on Lua lesson →
• Download Lua project →