Widgets
ui.widget{fn, every=, watch=} arms a timer and signal listeners that mark
screens dirty, and returns fn for your bar function to call.
kiln.widgets provides stock widgets such as the taglist and clock.
Prerequisites
A bar of your own (see A bar from scratch). Snippets assume:
local kiln = require("kiln")
local ui = kiln.ui
local widgets = kiln.widgets
local th = kiln.theme
Build widgets once, at config load (top level of your rc), never inside a bar
function. ui.widget{ every = n } arms a recurring timer when it is called;
calling it inside a declare function would arm a new timer every frame.
1. A seconds clock with every
The built-in widgets.clock() redraws on the minute. For seconds you need a
faster cadence:
local seconds_clock = ui.widget {
every = 1,
function()
ui.text(os.date("%H:%M:%S"), { size = 12 })
end,
}
The spec's first positional entry (or a fn field) is the declare function;
every = 1 marks every screen dirty each second. Call seconds_clock()
inside your existing bar function:
seconds_clock()
Reload. The clock appears in the bar and updates every second.
2. External data: a battery reader with spawn.watch
kiln.spawn.watch(cmd, interval, cb) runs a command, passes each output line to cb, and runs it again interval seconds after it exits:
local stats = { battery = nil }
kiln.spawn.watch("cat /sys/class/power_supply/BAT0/capacity", 30,
function(line)
stats.battery = tonumber(line)
kiln.dirty()
end)
local battery = ui.widget {
function()
ui.text(stats.battery and (stats.battery .. "%") or "n/a", { size = 12 })
end,
}
Add battery() to your bar and reload. It shows the charge percentage, or n/a if no BAT0 is found. Adjust the path if your battery has a different name, such as BAT1.
The callback saves the reading and calls kiln.dirty() to redraw. The widget needs no every timer.
spawn.watch returns a handle with :stop(). Reload stops watches and drops
their callbacks, but running children continue until they exit. See
pipe and watch lifetime.
3. Reacting to signals with watch
watch wires object signals to redraws. Entries are "Class::signal" where
the class is one of the globals (client, screen, tag, layer,
notification). Focus and title changes already redraw the screen; a
property of your own does not. Writing any unknown key on a client stores it
and emits property::<key>, so a mark flag set from a key becomes a
watchable signal:
kiln.key { mods = { "mod" }, key = "b", desc = "toggle mark", group = "client",
press = kiln.focused(function(c) c.mark = not c.mark end) }
local marked = ui.widget {
watch = { "client::property::mark" },
function()
local n = 0
for _, c in ipairs(client.all()) do
if c.mark then n = n + 1 end
end
ui.text(n .. " marked", { size = 12, color = th.muted })
end,
}
Add marked() to your bar, reload, and press mod+b on a few windows. The
count follows each press. Listeners are registered once per signal name; see
the signals reference.
4. Keyed lists with ui.each
ui.each(items, key, declare) declares a cell per item. Give each item a stable key to preserve its handler and state when the list is reordered:
local function note_key(n)
return "note:" .. n.seq
end
local notification_chips = ui.widget {
watch = { "notification::added", "notification::dismissed" },
function()
ui.each(notification.all(), note_key, function(n, id, st)
ui.box({
id = id, color = th.accent, radius = 3, pad = { x = 6 },
on_press = function() n:dismiss() end,
}, function()
ui.text(n.title or "", { size = 12 })
end)
end)
end,
}
Wire the chips into your bar, reload, and send yourself a notification:
kiln-client eval 'require("kiln").notify { title = "hello" }'
A chip labelled "hello" appears in the bar. Click it to dismiss the notification and remove the chip.
declare(item, id, st) receives a per-key state table st that survives
across frames as long as the key is still declared, then vanishes with it.
Define the key function at module level, not inline: the state store is
scoped by the key function's identity.
5. A stock meter
Add a progress bar with widgets.progress:
widgets.progress({ id = "meter", value = 0.42,
w = { "grow", max = 100 }, h = 8 })
Drop that line into your bar function and reload: a thin 100 px track appears with the left 42 percent filled in the accent color.
Pass the current value on each frame. See the form widgets reference for configuration options.
Complete example
A battery meter, wired end to end:
local kiln = require("kiln")
local ui = kiln.ui
local widgets = kiln.widgets
local th = kiln.theme
local stats = { battery = nil }
kiln.spawn.watch("cat /sys/class/power_supply/BAT0/capacity", 30,
function(line)
stats.battery = tonumber(line)
kiln.dirty()
end)
local battery = ui.widget {
function()
local pct = stats.battery
if pct == nil then
ui.text("no battery", { size = 12, color = th.muted })
return
end
ui.row({ gap = 6, align = { y = "center" } }, function()
ui.text(pct .. "%", { size = 12 })
widgets.progress({ id = "bat", value = pct / 100,
w = { "grow", max = 100 }, h = 8,
color = pct < 20 and th.urgent or th.accent })
end)
end,
}
screen.on("added", function(s)
tag.new { name = "1", screen = s, layout = kiln.layout.tile }
ui.bar(s, { edge = "top" }, function()
widgets.taglist(s)
ui.spacer()
battery()
widgets.clock()
end)
end)
Reload. The meter shows the charge and changes color below 20%. Without a battery, it displays "no battery".