Skip to main content

core

core is the raw native surface of the compositor: 58 functions across core.*, core.client.*, core.input.*, and core.output.*. Everything the stdlib does (layout, widgets, focus, rules) is built by calling these.

note

core.* is the raw native boundary the stdlib is built on. Configs should prefer the object model (client, tag, screen, layer, notification) and kiln.*, but everything here is reachable from config code and over IPC. The subset stock widgets may use is listed under Writable by a config.

-- readback over IPC: where did the first bar land? Bars carry the
-- indexed id form, { name, index }.
local b = core.box({ "bar", 1 })
print(b.x, b.y, b.width, b.height)

core.*​

Declare​

These build the Clay element tree and error outside a frame or lock handler ("declare primitives are only callable inside the frame handler"). Normally only the stdlib's frame handler calls them; kiln.ui nodes compile down to these.

FunctionDescription
core.open(decl)Open a Clay element. decl is a raw Clay declaration table: id, layout (sizing, padding, childGap, childAlignment, layoutDirection), backgroundColor, cornerRadius, aspectRatio, image, floating (incl. clipTo = "none" or "attached_parent"), clip, border. Must be balanced by core.close(). Errors: a custom, text, overlayColor, transition or userData key raises "unsupported drawing feature"; a non-finite or out-of-range number raises (sizes and radii must be non-negative, percent in 0..1, padding and gap at most 65535, zIndex in -32768..32767); an id already declared this frame raises "duplicate element id" and the frame is dropped.
core.close()Close the innermost open element. Errors without a matching core.open.
core.text(str, cfg)Declare a text leaf. cfg fields: textColor, fontId (an id from core.font; 0 is the default font), fontSize (default 16), letterSpacing, lineHeight, wrapMode, textAlignment, ellipsize.
core.font(desc)Intern a Pango font description ("Sans Bold", "Monospace") to the id a text declaration carries as fontId. The same description always returns the same id. A size in desc raises; pass size on the text cfg. Callable outside a frame, unlike the declare primitives; ui.text calls it through a cache for its font cfg.
core.surface(handle, decl?)Place the client’s surface tree as a self-closing leaf to display client content. Without decl it grows in both axes. The element id derives from the handle, so the key is stable across frames. Declaring the same handle twice in one frame is an error.

Readback​

Coordinates and output selection are defined under geometry and units. core.hits takes global coordinates; core.box returns output-local coordinates.

core.box lets a widget turn a pointer position into a value without doing layout arithmetic; kiln.widgets.slider reads its solved track this way. Before the first solve it returns nil.

FunctionDescription
core.hits(screen, x, y)Element ids under a layout point on the screen named screen, innermost first, as { { name = ..., index = ... }, ... } (max 32), from the last solve. The liveness test: only elements the live tree put under the point answer.
core.box(id)The solved box of an element as { x, y, width, height }, half-up-rounded integers. id is a string or { name, index }. Callable any time: inside the frame handler it reads the previous solve (boxes are only rewritten when the solve ends). Clay's element map is persistent, so an id that left the tree keeps answering with its final box; nil only for an id never declared, or before the first solve. Not a liveness test, use core.hits for that.
core.screenshot(screen, path?)Read the screen's composed scene into the image cache and return the cache key (usable as an image source). With path, also write a PNG there. nil on a stale screen name or failed readback.
core.output.list()Output enumeration, see core.output.* below.

Handlers​

One of each; setting again replaces. The stdlib owns all three, so a config never calls these unless it is replacing stdlib behavior wholesale.

FunctionDescription
core.set_frame_handler(fn(screen, w, h))The declare pass: called per dirty screen, builds that screen's tree with the declare primitives.
core.set_event_handler(fn(ev))Receives every origin event.
core.set_lock_handler(fn(screen, w, h))The declare pass for the native lockscreen while locked.

Control​

FunctionDescription
core.dirty(screen?)Mark one screen (by name) or every screen dirty, scheduling a re-solve.
core.tick(screen, on)Arm or disarm that output's frame clock. While on, the core keeps a frame scheduled and delivers frame::tick with the true delta each cycle; easing and delta clamping are Lua's job.
core.set_key_bindings(chords)Replace the whole consume set: { { mods = {"alt"}, key = "Return" }, ... }. Mod names: shift, ctrl, alt, super. The core consumes exactly these chords; every other key forwards to the focused client. Locked modifiers (NumLock, CapsLock) are ignored in the match. Errors on an unknown key name.
core.timer(ms, fn)One-shot timer; returns a numeric id. ms <= 0 fires on the next loop turn.
core.timer_cancel(id)Disarm a pending timer. A fired or unknown id no-ops.
core.quit()Terminate the compositor. Deferred to the event loop, so it works even at config load time.
core.replay()Re-emit the map fact for every live client. The reload verb: after Lua drops its client model, the compositor is the only one that still knows what is on screen.
core.set_idle_timeout(ms)Arm the idle timer for ms of no input (delivers idle events); nil or 0 disarms.
core.image_reload(path)Drop the cached decode so the next declare re-reads the file. The only image invalidation; marking dirty afterwards is the caller's job.
core.inspector(screen)Whether the Clay debug inspector is up on that screen. screen is a name, as everywhere in core; kiln.inspector is the one that takes a screen object.
core.inspector(screen, on)Show or hide it. Returns the state after the call, read back from Clay: the panel can close itself from its own header button, so the answer is never a stored copy. Desktop screens only; the lockscreen cannot be inspected.
core.inspector(screen, cfg)Optional enabled and width in px (default 400, range 0-16384). Width is process-wide. Any other key raises "unsupported inspector style option". Changing state during a declare raises "inspector cannot change during declaration".
core.inspector_scroll(screen, dx, dy)Feed the panel a wheel delta for its next solve. Routed by Lua only when the hits under the cursor name the panel, so it never has to decide whether a scroll was meant for the inspector.
core.inspector_scroll(screen)The tree pane's current y offset.

Spawn​

FunctionDescription
core.spawn(cmd)Fork and exec. cmd is an argv table (via execvp) or a string (via sh -c); anything else errors.
core.spawn_with_token(cmd)Like spawn, but mints an xdg-activation token first and hands it to the child via XDG_ACTIVATION_TOKEN, so the launched client can raise itself as user-initiated.
core.spawn_pipe(cmd)Spawn with stdout and stderr piped back. Returns an id; each raw chunk arrives as a spawn::out event (fd 1 or 2), then one spawn::exit after both streams hit EOF and the child is reaped (code is the exit status, or 128 plus the signal). Line framing is Lua's job.

Lock​

FunctionDescription
core.lock()Engage the native lockscreen. Returns false if a lock (native or external) is already active.
core.unlock()Disengage the native lockscreen. Refused (returns false) unless the last core.authenticate request reported success; the gate is enforced natively, so Lua cannot unlock without a verified password.
core.authenticate(password)Starts a PAM check in a worker and returns a request id, or nil when it cannot start (not natively locked, or a check already running). The result arrives as a session authenticated event (id, success, reason); on success, core.unlock() is allowed.

Notify, tray, and layer plumbing​

FunctionDescription
core.notify_closed(id, reason)Send NotificationClosed on the bus. reason is the protocol integer; the core does not check whether the id ever named anything.
core.notify_action(id, key)Send ActionInvoked for a pressed notification action. Whether the notification then closes is Lua's call, made with notify_closed.
core.tray_activate(service, kind, a?, b?)Forward one method call to a tray item (activate, scroll, and so on).
core.layer_configure(handle, w, h)Answer a layer::map or layer::commit fact with a size. The only configure path a layer surface has.

core.client.*​

All but focused take the numeric client handle (the handle field from client events).

FunctionDescription
core.client.focus(handle?)Give keyboard focus; nil defocuses everything.
core.client.focused()The handle of the surface that holds keyboard focus, or nil.
core.client.configure(handle, w, h)Send a size to the client.
core.client.close(handle)Polite close request (the client may ignore it).
core.client.kill(handle)Force kill the client's process.
core.client.set_activated(handle, on)Set the activated (focused-look) state.
core.client.set_fullscreen_hint(handle, on)Tell the client it is fullscreen. Presentation only; geometry stays Lua's.
core.client.set_maximized_hint(handle, on)Tell the client it is maximized.
core.client.set_tiled_hint(handle, edges)Set the tiled-edges hint (bitmask).
core.client.set_suspended(handle, on)Tell the client it is not visible, so it can stop drawing.
core.client.set_minimized_hint(handle, on)Tell the client it is minimized.
core.client.set_output_mirror(handle, name?)Set foreign-toplevel output membership to one named output; nil or an unknown name leaves all memberships. This does not change wl_surface output membership.

core.input.*​

FunctionDescription
core.input.grab_pointer(on)Hand the cursor to Lua policy, or return it. While on, pointer events keep flowing to the event handler and none reach clients.
core.input.grab_keyboard(on)While on, keys keep entering the event queue and none reaches a client, so a Lua grabber reads them ahead of bindings. The core tracks no grabber and no stack; the claim is Lua's.
core.input.set_cursor(name)Set the cursor image by xcursor name.
core.input.set_cursor_theme(name?, size?)Swap the xcursor theme. nil name restores the environment default; size defaults to 24.
core.input.set_keymap{rules, model, layout, variant, options}One whole-keymap replacement applied to every keyboard, no readback. The compose table is built from the locale, not the keymap, so it survives untouched.
core.input.set_repeat(rate, delay)Key repeat rate (per second) and delay (ms) on every keyboard.
core.input.set_numlock(on)Set the locked NumLock modifier on every keyboard (Wayland starts with it cold).
core.input.set_pointer{tap_to_click, natural_scrolling, left_handed, accel_speed, accel_profile, scroll_method, click_method}libinput config over every pointer device. A nil field is left untouched; a device that does not support a field ignores it. No per-device targeting.

core.output.*​

FunctionDescription
core.output.list()Enumerate outputs (max 16). Returns { { name, width, height, refresh, scale, x, y, enabled, modes = { { width, height, refresh }, ... } }, ... }; refresh is in millihertz. A non-desktop output (a VR headset) also carries non_desktop = true and starts disabled. Enumeration is discovery; runtime changes arrive as output events, not from re-reading this.
core.output.set_mode(name, w, h, refresh?)Set the output mode. refresh is in mHz (60000 for 60 Hz); omitted or 0 picks the first advertised mode of that size. A size with no advertised timing is rejected.
core.output.set_scale(name, f)Set the output scale factor.
core.output.set_position(name, x, y)Move the output in the global layout.
core.output.set_enabled(name, on)Enable or disable the output.
core.output.set_adaptive_sync(name, on)Toggle adaptive sync (VRR).

See also​