C API

Execute a NUL-terminated CDP JSON command directly on the main thread and copy its JSON response. A short response buffer is truncated and reports the required length. Calling again executes the command again, so account for side effects.

Inject a key-down, key-up, or character event into the focused element on the main thread only. key is the semantic name, code is an optional physical code, text supplies character input, and is_auto_repeat marks a held-key repeat.

Inject a mouse move, press, release, or wheel event into a document on the main thread only. Coordinates are viewport-relative CSS pixels. Modifier bits are Alt=1, Ctrl=2, Meta=4, Shift=8; deltas apply to wheel events only.

Query the box model of the element matching a selector on the main thread only. Write 32 floats: eight each for content, padding, border, and margin, plus width and height in CSS pixels. No match returns NOT_FOUND.

Add CSS stylesheet source to the document; call on the main thread. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Get a counted reference to the document body element and release it when done.

Clear document stylesheets; call on the main thread.

Create a standalone document and return one counted reference to release when done. This does not attach the document to a window.

Create a document element by tag name and return a counted reference to release. Creation does not itself insert it into the DOM. Call on the main thread. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Check whether a tag is defined in the document custom element registry. Returns NOT_SUPPORTED when the registry is unavailable.

Define a custom element tag and connected, disconnected, and observed-attribute callbacks on the main thread. Observed attribute names are copied during registration. Callback elements and text are borrowed; retain the element or copy text before keeping them. Returns NOT_SUPPORTED without a registry.

Read an extension last, maximum, and total tick/paint times and invocation counts by tag name. Time fields are milliseconds. Returns NOT_SUPPORTED without an extension manager.

Invoke a target extension element method on the main thread with typed arguments and a maximum result count. Release the returned result handle; inspect it separately for the extension invocation status. A missing extension manager returns NOT_SUPPORTED.

Check whether the document has loaded a DOM element extension for a tag name. Returns NOT_SUPPORTED when no extension manager is available.

Reset performance statistics in the document extension manager. Returns NOT_SUPPORTED without an extension manager.

Find a document element by ID. The caller must release the returned element reference; lookup results follow the same reference-counting rule as constructors. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Get a counted reference to the document head element and release it when done.

Initialize document DOM element extensions from a directory on the main thread and optionally report the loaded count. Returns NOT_SUPPORTED when the extension manager is unavailable. This uses the kuiext element extension protocol.

Load document content from an HTML source string; DOM mutation must run on the main thread. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Load an HTML document from the supplied file path; DOM mutation must run on the main thread. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Write a document to a PDF path on the main thread with metadata, page dimensions in points, font rasterization, and outline options. out_written reports whether writing succeeded. A windowless document temporarily receives a headless rendering backend; unavailable backends return NOT_SUPPORTED.

Find the first document element matching a CSS selector; the returned counted reference must be released. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Find all document elements matching a selector, writing handles into a caller-provided array and reporting the count. Release every element reference actually returned. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Drop a document reference; only the last reference destroys the object. NULL is an error, and the released reference must not be used. Reference operations are atomic and safe from any thread.

Add a document reference. Pair each retain with release; reference operations are atomic and safe from any thread.

Get a counted reference to the document root element and release it when done.

Register an event-type listener and return its ID. The callback runs during main-thread dispatch and may mutate the DOM. evt is borrowed only during the callback: never store or release it. The caller manages user_data. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Append a child element to its parent. The caller still releases its own element references. Mutate the DOM on the main thread.

Blur the element; call on the main thread.

Read the child-element count, excluding text and other non-element nodes.

Add the supplied token to the class list; call on the main thread. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Check whether the class list contains the supplied token. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Remove the supplied token from the class list; call on the main thread. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Toggle the presence of the supplied class token; call on the main thread. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Dispatch a synthetic event at the element through the normal capture/bubble path. The element must be attached to a document or INVALID_ARG is returned. Optional out_not_canceled is 1 if no listener prevents the default. No mouse coordinates or key state are carried. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Get a counted reference to the first child element, skipping non-element nodes; release it when done.

Focus the element; call on the main thread.

Read the value of the named element attribute. 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. 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 bounding rectangle of a laid-out element on the main thread, preserving subpixel geometry. A document that has never been laid out may return zero sizes successfully.

Read the element full class-name string. 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.

Read client metrics for the padding box: left/top are border widths, and width/height exclude rendered scrollbars. All four values use floor(x+0.5). Individual outputs may be omitted, but not all of them. Read on the main thread after layout; a never-laid-out document may return zero values successfully.

Read the element ID. 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.

Read the serialized element innerHTML. 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.

Read border-box position and size relative to the offset parent. All four values use floor(x+0.5); use the bounding rectangle for subpixel geometry. Outputs may be omitted individually, but not all at once. Read on the main thread after layout; a never-laid-out document may return zero values successfully.

Read the current scroll offsets and full scrollable extent. left/top remain fractional, while width/height use floor(x+0.5). Individual outputs may be omitted, but not all of them. Read on the main thread after layout; a never-laid-out document may return zero values successfully.

Read the serialized value of a property in the element inline declaration. An unset property returns KUI_ERR_NOT_FOUND. color:red may serialize as #ff0000; the output need not match the input text. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length.

Count the properties actually set in the element inline declaration for inspection and enumeration.

Read an inline declaration property name by index. Enumeration indices may change as soon as the declaration is modified. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length.

Read the serialized text of the complete inline style declaration, corresponding to the style attribute value. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length.

Read the element tag name. 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.

Read the element textContent. 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.

Check whether the element has the named attribute. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Get a counted reference to the last child element, skipping non-element nodes; release it when done.

Get a counted reference to the next sibling element, skipping non-element nodes; release it when done.

Get a counted reference to the parent element and release it when done.

Position an element relative to an anchor on the main thread using placement and optional flip, viewport clamping, offset, and viewport margin settings. Both element handles must be valid.

Get a counted reference to the previous sibling element, skipping non-element nodes; release it when done.

Find the first matching element within this element query scope; release the returned counted reference. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Find all matching elements within this element query scope, writing to the caller handle array and reporting the count. Release each counted reference actually returned. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Release one element reference. Other references can keep an element alive after DOM removal. Release each reference exactly once and do not reuse it; atomic reference operations are safe from any thread.

Remove the element from its DOM tree. Existing handles keep it alive through reference counting. Call on the main thread.

Remove a named element attribute; call on the main thread. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Remove a child from the supplied parent. A missing child returns NOT_FOUND; existing counted references can keep it alive. Call on the main thread.

Remove one listener using both event name and listener ID. IDs are scoped by event type, so an ID alone is ambiguous. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Remove every listener registered on the element for the supplied event name. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Remove one property from the element inline style declaration on the main thread.

Add an extra element reference. Ordinary handle-returning functions already provide one, so they need no extra retain. Pair every retain with release; atomic reference operations are safe from any thread.

Scroll the element by dx/dy; call on the main thread.

Set a named element attribute value; call on the main thread. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Replace the element class-name string; call on the main thread. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Replace the element innerHTML with HTML source; mutate the DOM on the main thread. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Set the element absolute left/top scroll position; call on the main thread.

Set one inline style declaration on the main thread. A nonzero important flag marks it !important. This changes the element own declaration.

Set the complete element inline style declaration from CSS text on the main thread.

Set the element textContent; mutate the DOM on the main thread. Input strings use UTF-8 and explicit byte lengths; length 0 means strlen. Required names, selectors, paths and source text must not be NULL.

Check whether the specified inline declaration is marked !important and return the result as an integer.

Read a dragged file path by index. Non-drag events or missing DataTransfer return NOT_SUPPORTED; an out-of-range index returns NOT_FOUND. Copy needed information before the event callback ends. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length.

Read the file count in a drag event DataTransfer. A non-drag event or missing DataTransfer returns NOT_SUPPORTED. The event is borrowed only for its callback.

Get a counted reference to the current event target element and release it when done. evt is valid only during the current callback and must not be stored or released.

Read the event bubbles, cancelable and defaultPrevented flags. evt is valid only during the current callback and must not be stored or released.

Get a counted reference to the event target element and release it when done. A non-element target, such as a text node, returns NOT_FOUND. evt is valid only during the current callback and must not be stored or released.

Read the current event type name. 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. evt is valid only during the current callback and must not be stored or released.

Read the runtime tag of a borrowed event to distinguish base, mouse, wheel, pointer, keyboard, focus, input, and drag events. Access the event only while its callback remains active.

Read the physical key code of a keyboard event, such as KeyA. Non-keyboard events return KUI_ERR_NOT_SUPPORTED. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length. The event is borrowed only within its callback; do not save or release it.

Read the semantic key name of a keyboard event, such as a, Enter, or ArrowUp. Non-keyboard events return KUI_ERR_NOT_SUPPORTED. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length. The event is borrowed only within its callback; do not save or release it.

Read Ctrl, Shift, Alt, and Meta states from a keyboard event. Unneeded outputs may be NULL. Non-keyboard events return KUI_ERR_NOT_SUPPORTED. The event is borrowed only within its callback; do not save or release it.

Read the KuiCMouseButton value of a mouse event. Non-mouse events return KUI_ERR_NOT_SUPPORTED. The event is borrowed for the current callback only; do not retain or release it.

Read mouse client coordinates relative to the viewport; a non-mouse event returns NOT_SUPPORTED. evt is valid only during the current callback and must not be stored or released.

Read mouse offset coordinates relative to the target padding box; a non-mouse event returns NOT_SUPPORTED. evt is valid only during the current callback and must not be stored or released.

Read mouse page coordinates including scroll offsets; a non-mouse event returns NOT_SUPPORTED. evt is valid only during the current callback and must not be stored or released.

Prevent the default action during the current event callback. evt is valid only during the current callback and must not be stored or released.

Stop further propagation during the current event callback. evt is valid only during the current callback and must not be stored or released.

Read the number of values actually returned by an extension invocation for indexed access.

Read the error text stored in an extension invocation result. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length.

Read the extension method invocation status code. It is distinct from the KuiStatus returned by the result accessor itself.

Copy an extension string result by index. An out-of-range index returns NOT_FOUND; a non-string result returns NOT_SUPPORTED. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length.

Read an extension result type and scalar fields by index. An out-of-range index returns NOT_FOUND. For strings, string_len reports the length and string_value is NULL; copy the text with get_string.

Release an extension invocation result handle exactly once. Read any needed values and error text before release.

Read the loaded library runtime version, which can differ from the compile-time version macros.

Cancel all pending asynchronous requests belonging to this client.

Create an HTTP client handle for synchronous or asynchronous requests. Release it with kui_http_client_release when finished.

Fetch a URL asynchronously and call back on completion. The callback may run on a worker thread and must not mutate the DOM directly. It owns and must release the response handle. Allocation failure may pass NULL; the callback must not throw.

Fetch a URL synchronously, blocking until completion or timeout. Release the returned response handle separately. KUI_OK means the ABI call completed; inspect the response for HTTP status and network errors.

Release and destroy an HTTP client handle exactly once. Do not start further requests through the released handle.

Set the HTTP client User-Agent string. The UTF-8 pointer must be non-NULL; zero len reads through the NUL terminator.

Copy raw response body bytes, which may contain NUL. Query the required byte count, then allocate need+1 bytes. The current bridge also writes a terminating NUL; the body length excludes that terminator.

Read the HTTP response Content-Type string. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length.

Read the HTTP response network error string to inspect and display the reason for a failed request. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length.

Read the HTTP response status code. Check the error text separately for transport failures.

Release an HTTP response handle exactly once. The caller owns responses returned synchronously and responses received by asynchronous callbacks.

Query whether a Lottie resource has finished loading as 0 or 1. complete checks LoadState::Complete, not whether playback has ended. Non-Lottie elements return NOT_SUPPORTED.

Read a Lottie animation natural width and height. One output may be omitted, but not both. Non-Lottie elements return NOT_SUPPORTED.

Pause animation of a Lottie element on the main thread. Non-Lottie elements return NOT_SUPPORTED.

Request playback of a Lottie element on the main thread. Non-Lottie elements return NOT_SUPPORTED.

Set a Lottie element source on the main thread. src must be non-NULL; non-Lottie elements return NOT_SUPPORTED.

Read a media element current playback time in seconds. Non-media elements return NOT_SUPPORTED.

Read the media resource duration in seconds. Non-media elements return NOT_SUPPORTED.

Read whether a media element is muted as 0 or 1. Non-media elements return NOT_SUPPORTED.

Read the integer network-state enum value of a media element. Non-media elements return NOT_SUPPORTED.

Read whether a media element is paused as 0 or 1. Non-media elements return NOT_SUPPORTED.

Read the integer ready-state enum value of a media element. Non-media elements return NOT_SUPPORTED.

Read a media element current volume. Non-media elements return NOT_SUPPORTED.

Query whether media capability is available for a media element, returning 0 or 1. Non-media elements return NOT_SUPPORTED. Availability does not establish successful resource playback.

Pause a media element on the main thread. Non-media elements return NOT_SUPPORTED.

Request playback of a media element on the main thread. A non-media element returns NOT_SUPPORTED; actual playback also depends on the media backend and resource state.

Set whether a media element displays playback controls on the main thread. A nonzero enabled flag enables them. Non-media elements return NOT_SUPPORTED.

Set a media element playback position in seconds on the main thread. Non-media elements return NOT_SUPPORTED.

Set a media element muted state on the main thread. A nonzero muted flag mutes it. Non-media elements return NOT_SUPPORTED.

Set a media element source on the main thread. src must be non-NULL, and non-media elements return NOT_SUPPORTED.

Set a media element volume on the main thread. Non-media elements return NOT_SUPPORTED. Value handling follows the media element implementation.

Clear a timeout or interval task by timer ID.

Copy text from the system clipboard into a caller-owned buffer. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length.

Read a monitor bounds, work area, scale, and primary flag by index. Write its name into a caller-owned UTF-8 buffer. A missing index returns NOT_FOUND. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length.

Read the current monitor count to determine the range for indexed monitor queries.

Read the current operating system name into a caller-owned buffer. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length.

Read the current operating system version string into a caller-owned buffer. For UTF-8 output, query the length with NULL/0, then allocate need+1. The length excludes the terminating NUL; a short buffer returns BUFFER_TOO_SMALL and reports the full required length.

Read the primary monitor bounds, work area, scale and primary flag.

Read the primary monitor physical size. Either width or height may be omitted, but both outputs cannot be NULL.

Check whether the system clipboard currently contains text and return the result as an integer.

Initialize process-wide platform services before creating GUI windows and running the event loop.

Open a file picker with title, default path, filters, and multiple-selection options. Supply a valid output buffer for this one-shot operation; the header recommends 32768 bytes on Windows. Cancellation returns NOT_FOUND. Do not probe with an empty buffer and then reopen.

Process pending events and return immediately, for embedding in a host that owns its event loop.

Request that the platform event loop quit with the supplied exit code.

Schedule a callback once when the event loop next becomes idle. It runs on the main thread; KUI does not free user_data.

Run the blocking platform event loop until quit is requested, returning the exit code through the output parameter.

Open a save-file dialog and return the chosen path. Supply a valid output buffer in this one-shot operation; 32768 bytes is recommended on Windows. Cancellation returns NOT_FOUND. The returned path does not itself save file contents.

Open a folder picker with a title and copy the selected path. Provide a valid buffer for the one-shot operation; 32768 bytes is recommended on Windows. Cancellation returns NOT_FOUND.

Write UTF-8 text to the system clipboard. text must be non-NULL; a zero len reads through the NUL terminator.

Enable or disable the platform behavior that opens DevTools with F12.

Schedule a repeating callback at a millisecond interval and return its ID; clear it explicitly. Callbacks run on the main thread only while the event loop is active. The caller owns user_data and must keep it alive at least until the timer is cleared.