C API

Schedule a one-shot callback after a millisecond delay and return its timer ID. An active event loop runs it on the main thread. KUI does not free user_data; keep it valid while waiting and during the callback. The timer needs no clearing after it fires.

Shut down platform services after the event loop ends and handles have been released in the standard lifecycle.

Wait for an event or timeout; a negative timeout_seconds waits indefinitely.

Bind a document to a script engine on the main thread so scripts can operate on it. Keep the document valid while the binding is used. Returns NOT_SUPPORTED when scripting is disabled.

Create a Lua script engine handle to be released with kui_script_engine_release. Returns NOT_SUPPORTED when scripting is disabled in the build or an engine cannot be created.

Evaluate Lua source with an optional source name; NULL uses <eval>. Check out_success for script success and read errors from the caller buffer. Retrying evaluates the source again, so a side-effecting script is not a harmless two-call query. Returns NOT_SUPPORTED when scripting is disabled.

Execute scripts in the bound document on the main thread. Requires a valid engine and relevant document binding. Returns NOT_SUPPORTED when scripting is disabled.

Release and destroy a script engine handle exactly once. Detach any window borrowing the engine and stop further calls before destruction.

Set a script error callback receiving error text, source, line number, and user_data. A NULL fn clears it. Callback text is temporarily borrowed and must be copied if needed later. Returns NOT_SUPPORTED when scripting is disabled.

Unbind the document from a script engine on the main thread. Returns NOT_SUPPORTED when scripting is disabled.

Get a static description of a status code; the result is never NULL, allocates nothing and needs no release. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Register a named window event listener and optionally receive its ID. A nonzero once flag makes it run once. The callback event is borrowed, valid only during that callback, and must not be released or saved for later.

Clear the explicit window frame radius setting. Requires a valid window handle.

Invoke the window close operation; the uniquely owned handle still needs release according to its lifecycle.

Create a uniquely owned window from KuiWindowProps. It is already visible on return. Zero-initialize properties for defaults; opacity=0 means 1.0. Hide immediately to configure off-screen. Release the handle exactly once.

Read the window device pixel ratio.

Read the listening port of the window DevTools server. Returns NOT_FOUND when that window has no DevTools server.

Read the window DevTools connection URL. UTF-8 output uses the caller buffer: query with NULL/0, then allocate out_len+1; the length excludes NUL. Insufficient capacity returns BUFFER_TOO_SMALL and the required length; positive capacity still receives a truncated NUL-terminated result.

Get a counted reference to the window-owned document and release it when done. This reference can keep the document alive after window release. A window cannot attach an external document.

Get the borrowed operating-system window identifier: HWND on Windows, NSWindow* on macOS or X11 Window on Linux. This adds no ownership beyond the uniquely owned window.

Read the window position coordinates.

Read the window width and height.

Read the window title. UTF-8 output uses the caller buffer: query with NULL/0, then allocate out_len+1; the length excludes NUL. Insufficient capacity returns BUFFER_TOO_SMALL and the required length; positive capacity still receives a truncated NUL-terminated result.

Hide the specified window.

Read whether the window is maximized.

Read whether the window is minimized.

Read whether the window is currently visible.

Maximize the window.

Minimize the window.

Replace the window resize callback; pass NULL to clear it. The callback receives width, height and user_data.

Destroy the uniquely owned window; this is not a reference-count decrement. Call exactly once per window handle. Previously obtained counted document references can keep the document alive.

Remove a window listener using its event name and listener ID. The ID must be paired with its event type.

Remove every listener registered under one window event name.

Resize the actual operating-system window width and height.

Restore the window to its normal state.

Enable or disable always-on-top behavior for the window.

Set the window frame corner radius. The radius must be nonnegative, and window must be a valid uniquely owned window handle.

Set whether a frameless window can be resized. window is uniquely owned and must remain valid; it is not a reference-counted object that can be copied and released repeatedly.

Set the window opacity.

Set the window position coordinates.

Associate a borrowed script engine with a window on the main thread. NULL detaches it. The window does not take ownership of the handle; keep the engine valid while the window uses it. Returns NOT_SUPPORTED when scripting is disabled.

Set the window title. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Read the flag indicating whether the window should close.

Show the specified window.

Start window DevTools on the supplied port and report whether it started through out_started.