kiln.ui.scroll
Clips a column and moves it in response to wheel input.

Both columns contain twelve entries. Wheel over either viewport in the Lua example to scroll.
Show Lua
Save the Lua file as /tmp/kiln-figure.lua, then run:
kiln-client eval 'dofile("/tmp/kiln-figure.lua")'
It opens on the focused screen and closes after two minutes. To close it early:
kiln-client eval 'if kiln_reference_figure then kiln_reference_figure.stop() end'
local kiln = require("kiln")
local ui, widgets = kiln.ui, kiln.widgets
if kiln_reference_figure then kiln_reference_figure.stop() end
local F = {
bg = "#282828", fg = "#ebdbb2", panel = "#32302f", slot = "#504945",
muted = "#bdae93", amber = "#d79921", blue = "#83a598", green = "#b8bb26",
width = 940, label_width = 300,
}
function F.text(text, cfg)
cfg = cfg or {}
cfg.color = cfg.color or F.fg
cfg.font = cfg.font or "Sans"
cfg.size = cfg.size or 19
ui.text(text, cfg)
end
function F.block(text, cfg)
cfg = cfg or {}
ui.box({ w = cfg.w or 72, h = cfg.h or 30, color = cfg.color or F.blue,
radius = 4, align = "center" }, function()
F.text(text, { color = F.bg, size = 16 })
end)
end
function F.row(label, draw, opts)
opts = opts or {}
return function()
ui.row({ w = "grow", gap = 20, align = { y = "center" } }, function()
ui.box({ w = F.label_width }, function()
F.text(label, { font = "monospace", size = 17, color = F.muted })
end)
ui.box({ w = "grow", h = opts.h or 44, pad = opts.pad or 6,
radius = 8, border = { width = 1, color = F.slot },
align = { y = "center" } }, draw)
end)
end
end
function F.scene(title, subtitle, rows, opts)
opts = opts or {}
local s = screen.focused or screen.all()[1]
assert(s, "a screen is required")
local popup = ui.popup {
id = "kiln-reference-figure", screen = s, w = F.width, pad = 28, gap = 12,
color = F.bg, fit = false, band = opts.band,
fn = function()
F.text(title, { size = 36, font = "Sans Bold" })
F.text(subtitle, { size = 21, color = F.muted })
ui.box({ h = 6 })
for _, row in ipairs(rows) do row() end
end,
}
local figure = { popup = popup, screen = s }
function figure.stop()
popup:destroy()
if figure.timer then core.timer_cancel(figure.timer); figure.timer = nil end
if kiln_reference_figure == figure then kiln_reference_figure = nil end
if figure.cleanup then figure.cleanup() end
end
kiln_reference_figure = figure
figure.timer = core.timer(120000, figure.stop)
popup:show(s)
return figure
end
function F.clients(count)
local result = {}
for _, c in ipairs(client.all()) do
if c.mapped and not c.override_redirect then result[#result + 1] = c end
end
assert(#result >= count, "open " .. count .. " clients before running this figure")
return result
end
function F.client_scene(title, subtitle, rows, opts)
local previous = kiln.declare_clients
local replacement = function() end
kiln.declare_clients = replacement
local figure = F.scene(title, subtitle, rows, opts)
figure.cleanup = function()
if kiln.declare_clients == replacement then kiln.declare_clients = previous end
kiln.dirty()
end
return figure
end
local function entries()
for i = 1, 12 do
ui.box({ h = 28, w = "grow", color = i % 2 == 0 and F.panel or nil, pad = { x = 8 } }, function()
F.text("Entry " .. i, { size = 18 })
end)
end
end
return F.scene("kiln.ui.scroll", "The viewport clips a taller column; wheel input changes its offset", {
F.row('h = 84, 12 entries', function()
ui.scroll({ id = "scroll-short", w = "grow", h = 84, step = 28 }, entries)
end, { h = 100 }),
F.row('h = 168, 12 entries', function()
ui.scroll({ id = "scroll-tall", w = "grow", h = 168, step = 28 }, entries)
end, { h = 184 }),
})
ui.scroll(cfg, children)
Example
ui.scroll({ id = "history", w = 240, h = 160, step = 24 }, function()
for i = 1, 20 do
ui.text("Entry " .. i)
end
end)
Options
| Field | Type | Default | Behaviour |
|---|---|---|---|
id | element ID | required | Stable viewport ID. |
w | sizing | "fit" | Viewport width. |
h | sizing | "fit" | Viewport height. Constrain it to produce overflow. |
color | colour | nil | Viewport background. |
pad | padding | 0 | Viewport padding. |
step | number | 40 | Logical pixels per unit of ev.dy. |
Behaviour
children declares inside a column with w = "grow" and h = "fit".
The constructor accepts only the fields above. It installs its own on_scroll
and clips vertically; horizontal scrolling is not supported.
Offsets are stored per output and viewport ID. The solved content height limits
the offset. A string ID reserves id .. ":content" for the column. A
{ name, index } ID reserves { name .. ":content", index }.