Skip to main content

Widget conventions

Load the module with local widgets = require("kiln").widgets.

Declaration and state​

Call drawing functions inside a bar, layout or declare hook. Each call declares elements for the current frame. It does not return a persistent widget object. layoutlist is an exception: call it from an input handler to open a menu.

The caller stores form values. A slider calls changed(value); a toggle calls press(ev). Update your value in that callback. The slider dirties its screen; other callbacks that change plain Lua state must call kiln.dirty().

Only fields listed on each widget's page are read. Widgets do not forward an arbitrary element cfg. Wrap one in a UI box to add padding, clipping, a border or a pointer handler.

Runnable example​

The form example opens progress, separator, toggle and slider widgets in one popup. Save it as /tmp/kiln-forms.lua and load it in a running Kiln session:

kiln-client eval 'dofile("/tmp/kiln-forms.lua")'

The toggle and slider update local Lua values. Escape closes the popup. Loading the file again replaces the previous example. To remove it:

kiln-client eval 'if kiln_reference_forms then kiln_reference_forms:destroy(); kiln_reference_forms = nil end'
Show Lua
local kiln = require("kiln")
local ui, widgets = kiln.ui, kiln.widgets
local muted, volume = false, 0.6

if kiln_reference_forms then kiln_reference_forms:destroy() end

kiln_reference_forms = ui.popup {
id = "kiln-reference-forms",
w = 440, pad = 20, gap = 16,
color = kiln.theme.bg, radius = 8,
border = { width = 1, color = kiln.theme.accent },
keys = { Escape = "close" },
fn = function()
ui.text("Form widgets", { size = 20 })
ui.text("progress: value = 0.6, h = 8")
widgets.progress { value = 0.6, h = 8 }
widgets.separator { color = kiln.theme.muted }
ui.row({ w = "grow", align = { y = "center" } }, function()
ui.text("toggle: " .. (muted and "on" or "off"))
ui.spacer()
widgets.toggle {
id = "reference-mute", on = muted,
press = function()
muted = not muted
kiln.dirty()
end,
}
end)
ui.text(string.format("slider: value = %.2f", volume))
widgets.slider {
id = "reference-volume", value = volume, w = "grow",
changed = function(value) volume = value end,
}
ui.text("Press Escape to close", { color = kiln.theme.muted })
end,
}
kiln_reference_forms:show()

IDs​

IDs must be unique within an output's declaration. A duplicate rejects the frame. Slider and toggle IDs must be strings because their child IDs are made by concatenation. Progress and separator accept the ordinary element ID forms.

Stock bar and client widgets derive IDs from screens, tags and clients. Calling the same widget twice for the same object in one output can duplicate those IDs.

Handler table​

taglist, tasklist and layoutbox accept on:

CallbackArgumentsBehaviour
press(item, ev)Receives the tag, client or selected tag. Return truthy to suppress the default press action; nil or false allows it.
scroll(ev)Receives wheel input. No default scroll action.

ev carries the button or wheel delta and modifier state. Pointer coordinates are global logical coordinates. The default press actions do not restrict the mouse button.

Replacing a widget​

Assign the replacement to kiln.widgets, for example kiln.widgets.titlebar = function(c, focused) ... end. Stock callers read that table, so the replacement also applies inside the client composite. Reload resets titlebar; other replacements remain unless your config changes them. See reload state.

API available to widgets​

Every stock widget uses only API a config can reach with the same spelling. make check runs scripts/widget-lint.sh, which rejects any name outside this list (beyond ui.* and kiln.widgets itself):

NameWhat a widget uses it for
core.boxRead back an element's solved box. The slider uses it to convert pointer positions into values.
core.dirtyMark a screen dirty so the next frame redeclares.
core.timer, core.timer_cancelOne-shot timer and its cancel; the clock arms one per minute rollover.
core.tray_activateForward a press or scroll to a status-notifier item.
core.input.set_cursorSet the pointer image; the resize handles set the edge cursors.
kiln.themeColors and metrics. The same table state.theme names inside the stdlib.
clientThe client global: client.focus, the properties a row draws.
screen.allThe screen list.
kiln.icon, kiln.layout, kiln.systrayIcon resolution, the layout registry, the tray registry.
kiln.keygrabber, kiln.mousegrabberGrabs. The widgets reach them through require("kiln.grab"), the module both names come from.
note

core.box returns nil until the element has been solved once, so a widget that reads its own box needs a stable id; widgets.slider errors without one.