A Bar from Scratch
A kiln bar is not a window or a surface. It is a container of nodes in the screen's one layout tree. The stock frame lays out bars and the workarea in one Clay column, so clients are never placed under a bar.
Prerequisites
A config you can edit and reload (see Basics). Snippets assume:
local kiln = require("kiln")
local ui = kiln.ui
local widgets = kiln.widgets
local th = kiln.theme
1. The smallest possible bar
Bars are registered per screen, inside the added handler. Replace the
default config's screen.on("added") block with this one (adding a second
handler would give you a second bar and a sixth tag):
screen.on("added", function(s)
tag.new { name = "1", screen = s, layout = kiln.layout.tile }
ui.bar(s, { edge = "top" }, function()
widgets.clock()
end)
end)
Reload. You get a 32 px bar across the top with a clock. ui.bar(s, cfg, fn)
appends the bar to the screen and marks it dirty; everything about its content
is the fn, and everything about its container is the cfg, which is
ordinary element cfg plus edge. What you did not write, the frame fills in
as defaults: a row direction because the edge is horizontal, theme.bar_height
for the height, 8 px of padding along the bar, a 6 px gap between cells,
vertical centering, theme.bg behind it all.
ui.bar appends. Registering it anywhere that runs repeatedly (or pasting it
twice over IPC) stacks a second bar. Keep it inside screen.on("added") and
apply changes with kiln.reload(), which rebuilds the bar list cleanly.
2. The declare function
The fn you passed is a declare function. It runs again on every dirty frame
of that screen, and each run states the bar's entire content from scratch.
When the screen is marked dirty (tag selected, client mapped, title changed),
fn runs again and declares the whole bar.
That is why widgets.clock() can be one line: it declares today's text, and a
timer aligned to the minute rollover marks the screen dirty when the text
would change. See Frames and dirty.
Inside a top or bottom bar, your cells are laid out left to right; a left or
right bar lays them out top to bottom. The bar's body is a ui.row or
ui.column built from the bar's own cfg.
3. Add a taglist and push the clock right
ui.bar(s, { edge = "top" }, function()
widgets.taglist(s)
ui.spacer()
widgets.clock()
end)
widgets.taglist(s) declares one pressable cell per tag, highlighted with
theme.accent when the tag is selected; pressing one views it. ui.spacer()
is exactly ui.box({ w = "grow" }): an empty node the solver hands the
leftover room, pushing everything after it to the right edge.
4. Tasklist, layoutbox, systray
ui.bar(s, { edge = "top" }, function()
widgets.taglist(s)
widgets.layoutbox(s)
widgets.tasklist(s)
ui.spacer()
widgets.systray()
widgets.clock()
end)
widgets.layoutbox(s)shows the selected tag's layout name; pressing it cycles to the next layout.widgets.tasklist(s, cfg?)declares one row per visible client: icon, title, accent when focused, press to focus (and restore, if minimized). Which clients it lists and how wide each row grows are configurable; see the widgets reference.widgets.systray(cfg?)shows status-notifier tray items;size(default 18) sets the icon size. Press activates an item, scrolling forwards the wheel.
Press mod+shift+i to open Clay's debug inspector over the running desktop.
Your bar is in there as a row of nodes, and clicking one shows the box the
solver gave it: width, height, sizing mode, padding, alignment. This is the
fastest way to understand ui.spacer(), because you can watch it report
whatever width was left over. See Inspect the Live Element
Tree.
5. Style it
The bar cfg is element cfg, so styling a bar is the same vocabulary as
styling any box: h for the bar's height, color, gap, pad, and the
rest. What you leave unset falls to a documented default, filled per frame;
the ui reference lists every bar field and its
default.
ui.bar(s, { edge = "bottom", h = 24, color = "#101014", gap = 10 },
function()
widgets.taglist(s)
ui.spacer()
widgets.clock()
end)
The defaults are read from kiln.theme each frame, so a theme edit restyles
every bar that left the field unset; see Theming.
6. Center the clock on the screen
Two spacers center a cell in the leftover space, so a growing tasklist pushes it right. Split the bar into three 33.33% regions instead:
ui.bar(s, { edge = "top" }, function()
ui.row({ w = "33.33%", h = "grow", gap = 6,
clip = { horizontal = true },
align = { y = "center" } }, function()
widgets.taglist(s)
widgets.tasklist(s)
end)
ui.row({ w = "33.33%", h = "grow", align = "center" }, function()
widgets.clock()
end)
ui.row({ w = "33.33%", h = "grow", gap = 6,
align = { x = "right", y = "center" } }, function()
widgets.systray()
widgets.layoutbox(s)
end)
end)
Two things make this hold at any tasklist width. A percent child is sized
unconditionally, so the middle third's center is the bar's center no matter
what the sides contain; "grow" regions would only stay equal until one
side's content outgrew its share. And the left region clips, so an overfull
tasklist truncates at its own third instead of pushing into the middle.
Check it in the inspector: the three regions report a third each, clients
open or not.
7. Turn it sideways
edge = "left" reserves workarea on the left, uses a ui.column, and takes
its width from theme.bar_height.
ui.bar(s, { edge = "left" }, function()
widgets.layoutbox(s)
ui.spacer()
ui.box({ w = 16, h = 16, color = th.accent, radius = 8 })
end)
ui.spacer() grows along the column, so it pushes later cells down. Cells
that assume a wide bar (the tasklist's ellipsized titles, the clock's text)
are a poor fit for a 32 px wide column; vertical bars usually carry glyphs.
8. Your own cells: row, box, text
Every stock cell is built from primitives you can use directly:
ui.box(cfg, children?), ui.row(cfg, children?), ui.column(cfg, children?), and the ui.text(str, cfg?) leaf. A launcher button; add this
inside your bar function:
ui.box({
id = "launch-btn", color = th.accent, radius = 4, pad = { x = 8 },
align = "center",
on_press = function() kiln.spawn("fuzzel") end,
}, function()
ui.text("run", { color = th.bg, size = 12 })
end)
Give interactive cells a stable id; it keys the press handler frame to
frame. The cfg fields (w, h, dir, pad, gap, align, color,
radius, border, on_press, on_hover, on_scroll, and more) are the
same on every container: see the ui reference.
Because the whole bar re-declares each frame, live state is just Lua read in place:
ui.text(client.focus and (client.focus.title or "") or "", { size = 12 })
No subscription needed for facts that already dirty the screen (focus, title, tags all do). For your own data sources and timers, see Widgets.
Complete example
local kiln = require("kiln")
local ui = kiln.ui
local widgets = kiln.widgets
local th = kiln.theme
screen.on("added", function(s)
tag.new { name = "one", screen = s, layout = kiln.layout.tile }
tag.new { name = "two", screen = s, layout = kiln.layout.fair }
s.tags[1]:view()
ui.bar(s, { edge = "top", h = 28, color = th.bg }, function()
ui.row({ w = "33.33%", h = "grow", gap = 6,
clip = { horizontal = true },
align = { y = "center" } }, function()
widgets.taglist(s)
ui.box({
id = "launch-btn", color = th.accent, radius = 4,
pad = { x = 8 }, align = "center",
on_press = function() kiln.spawn("fuzzel") end,
}, function()
ui.text("run", { color = th.bg, size = 12 })
end)
widgets.tasklist(s)
end)
ui.row({ w = "33.33%", h = "grow", align = "center" }, function()
ui.box({
id = "clock", color = th.bg2, radius = 4, pad = { x = 8 },
align = "center",
on_hover = ui.tooltip(function()
return os.date("%A %d %B %Y")
end),
}, widgets.clock)
end)
ui.row({ w = "33.33%", h = "grow", gap = 6,
align = { x = "right", y = "center" } }, function()
widgets.systray()
widgets.layoutbox(s)
end)
end)
end)
The clock uses ui.tooltip, which returns an on_hover handler. The default
config's bar also adds the launcher glyph, the backdrop and a clipped right
region.