Skip to main content

Data Widgets

kiln has no canvas or drawing API, and bar meters do not need one. The standard forms (a progress bar, a slider, a toggle) ship on kiln.widgets as controlled widgets: your config owns the value, the widget draws it. The data lives in plain Lua variables; a shell command polled by kiln.spawn.watch updates them and marks the screen dirty, and the next frame declares the new numbers. Shapes with no stock widget are built from ui.box; the history graph below is an example.

Snippets assume the standard config preamble:

local kiln = require("kiln")
local ui = kiln.ui
local widgets = kiln.widgets
local th = kiln.theme
note

Widget state is ordinary Lua. Changing a local variable draws nothing by itself; call kiln.dirty() after every update so the next frame renders it. See frames and dirty.

Feeding data: kiln.spawn.watch​

kiln.spawn.watch(cmd, interval, cb) runs a command, feeds each output line to your callback, and re-runs it interval seconds after it exits. A memory fraction, polled every 5 seconds:

local mem = 0

kiln.spawn.watch("free -b", 5, function(line)
local total, used = line:match("^Mem:%s+(%d+)%s+(%d+)")
if total ~= nil then
mem = tonumber(used) / tonumber(total)
kiln.dirty()
end
end)

The returned handle has a :stop() if you ever need to cancel the poll.

A progress bar​

widgets.progress is the track-and-fill pair, drawn from whatever value you pass:

-- inside the bar function:
widgets.progress({ id = "mem-bar", value = mem, w = 120 })

It is two boxes, a track and a fill sized to value. The reference lists its options.

A history graph​

A graph is a row of thin grow boxes whose heights come from a ring buffer. Give each sample a monotonic sequence number so its identity is stable as it slides left, and declare the row through ui.each, keyed by that number:

local cpu_hist, cpu_seq = {}, 0
local prev_idle, prev_total
local SAMPLES = 30

kiln.spawn.watch("head -1 /proc/stat", 2, function(line)
local n = {}
for v in line:gmatch("%d+") do n[#n + 1] = tonumber(v) end
local idle, total = n[4] + (n[5] or 0), 0
for _, v in ipairs(n) do total = total + v end
if prev_total ~= nil and total > prev_total then
cpu_seq = cpu_seq + 1
cpu_hist[#cpu_hist + 1] = {
seq = cpu_seq,
value = 1 - (idle - prev_idle) / (total - prev_total),
}
if #cpu_hist > SAMPLES then table.remove(cpu_hist, 1) end
kiln.dirty()
end
prev_idle, prev_total = idle, total
end)

local function cpu_graph(id, height)
ui.row({
id = id, w = SAMPLES * 4, h = height, gap = 1,
align = { y = "bottom" }, color = th.bg2, radius = 3,
}, function()
ui.each(cpu_hist, function(sample)
return "cpu-sample:" .. sample.seq
end, function(sample, sid)
ui.box({
id = sid, w = "grow",
h = math.max(1, math.floor(sample.value * height)),
color = th.accent,
})
end)
end)
end

align = { y = "bottom" } pins the columns to the baseline, so they rise like a bar chart. ui.each derives each column's id from the sample's own key, never from its array position, which is the rule for any dynamic list.

A slider​

widgets.slider is a progress bar that writes back: press or drag anywhere on the track and changed receives the new 0 to 1 value. id is required: the slider reads its own solved box. The drag ends when the button that started it is released. Wired to volume:

local vol = 0.5

-- inside the bar function:
widgets.slider({ id = "vol-slider", w = 100, value = vol,
changed = function(f)
vol = f
kiln.spawn(string.format(
"wpctl set-volume @DEFAULT_AUDIO_SINK@ %d%%",
math.floor(f * 100 + 0.5)))
end })

The slider holds no copy of the value: it draws value and reports through changed. The fill shows value as of the last declare. To track volume changed outside kiln, add a kiln.spawn.watch on wpctl get-volume @DEFAULT_AUDIO_SINK@ that writes vol.

A toggle​

widgets.toggle is the same contract for a boolean: on in, press out. Do-not-disturb, backed by the notification module's own switch:

-- inside the bar function:
widgets.toggle({ id = "dnd-toggle",
on = notification.suspended,
press = function()
notification.suspended = not notification.suspended
kiln.dirty()
end })

Complete example​

The meters assembled into a bar. The watchers and helpers above sit at the top level of your config; the bar function only declares:

screen.on("added", function(s)
tag.new { name = "main", screen = s }

ui.bar(s, { edge = "top", h = 28, color = th.bg }, function()
widgets.taglist(s)
ui.spacer()
ui.text("cpu", { size = 12, color = th.muted })
cpu_graph("cpu-graph", 18)
ui.text("mem", { size = 12, color = th.muted })
widgets.progress({ id = "mem-bar", value = mem, w = 120 })
ui.text("vol", { size = 12, color = th.muted })
widgets.slider({ id = "vol-slider", w = 100, value = vol,
changed = function(f)
vol = f
kiln.spawn(string.format(
"wpctl set-volume @DEFAULT_AUDIO_SINK@ %d%%",
math.floor(f * 100 + 0.5)))
end })
widgets.toggle({ id = "dnd-toggle",
on = notification.suspended,
press = function()
notification.suspended = not notification.suspended
kiln.dirty()
end })
widgets.clock()
end)
end)

See also​