Custom Layouts
A layout in kiln is not an object or a class. It is one function:
function my_layout(clients, area, tag)
-- declare cells for the clients
end
Kiln calls the first selected tag's layout inside the workarea container.
clients contains eligible tiled clients from all selected tags, deduplicated
in selection order. tag supplies the first selected tag's parameters.
See membership and visibility.
Declare UI containers and a kiln.widgets.client(c) for
each client to display. Clay solves their geometry.
1. The smallest layout
A vertical stack: one column, every client a growing cell.
local kiln = require("kiln")
local ui = kiln.ui
local function stack(cs, area, t)
if #cs == 0 then
return
end
local gap = (t and t.gap) or kiln.theme.gap
ui.column({ w = "grow", h = "grow", gap = gap }, function()
for _, c in ipairs(cs) do
kiln.widgets.client(c)
end
end)
end
Two things every layout should copy from this:
- Guard the empty case. An empty
"grow"container is not invisible to the solver: it is a sibling that takes its share of space. Declaring one next to real cells hands half the screen to a hole. - Read the gap from the tag with a theme fallback, so per-tag
t.gapoverrides work.
kiln.widgets.client(c) declares the full client frame (client content, titlebar and border). Sizing accepts numbers (pixels), "grow", "fit", and percent strings like "60%".
2. A two-column layout
Split the client list in half, one column each side:
local function twocol(cs, area, t)
if #cs == 0 then
return
end
local gap = (t and t.gap) or kiln.theme.gap
local half = math.ceil(#cs / 2)
ui.row({ w = "grow", h = "grow", gap = gap }, function()
ui.column({ w = "grow", h = "grow", gap = gap }, function()
for i = 1, half do
kiln.widgets.client(cs[i])
end
end)
if #cs > half then
ui.column({ w = "grow", h = "grow", gap = gap }, function()
for i = half + 1, #cs do
kiln.widgets.client(cs[i])
end
end)
end
end)
end
The second column is only declared when it has clients, for the empty-container reason above. With one client, the layout degrades to a single full column automatically.
3. Read the tag's parameters
Layouts take their knobs from plain tag properties. The stock layouts read master_width_factor (default 0.5), master_count (1), column_count (1), gap (theme default), and carousel_width (0.5). Writing any of them redraws the screen, so a keybinding that nudges master_width_factor reshapes your layout live with no extra wiring.
To make the left column's width configurable, size it with a percent string derived from the factor, the same way the stock tile does. In twocol, compute the width and pass it to the first column (the complete example has the whole function):
local f = (t and t.master_width_factor) or 0.5
-- The percent form only makes sense when both columns exist.
local left_w = #cs > half and (f * 100) .. "%" or "grow"
-- ...
ui.column({ w = left_w, h = "grow", gap = gap }, function()
Now mod bindings that adjust t.master_width_factor (see the keybindings tutorial) drive your layout too.
4. The model: how the stock tile works
The stock tile, simplified:
local function tile(cs, area, t)
if #cs == 0 then
return
end
local f = (t and t.master_width_factor) or 0.5
local n = math.min((t and t.master_count) or 1, #cs)
local gap = (t and t.gap) or kiln.theme.gap
local stacked = #cs > n
ui.row({ w = "grow", h = "grow", gap = gap }, function()
-- The master run: a percent-width column while a stack exists,
-- the whole area when it does not.
ui.column({ w = stacked and (f * 100) .. "%" or "grow",
h = "grow", gap = gap }, function()
for i = 1, n do
kiln.widgets.client(cs[i])
end
end)
-- The stack, only when non-empty.
if stacked then
ui.column({ w = "grow", h = "grow", gap = gap }, function()
for i = n + 1, #cs do
kiln.widgets.client(cs[i])
end
end)
end
end)
end
5. Register it
Assign the function to a tag:
tag.new { name = "code", screen = s, layout = twocol }
or at runtime:
screen.focused.selected_tag.layout = twocol
To include it in the layout cycle (kiln.layout.next, the layoutbox press, mod+space style bindings), set the cycle list; it is yours to override:
kiln.layout.list = {
kiln.layout.tile,
twocol,
kiln.layout.max,
kiln.layout.floating,
}
kiln.layout.name(fn) only knows the built-in families, so the stock kiln.widgets.layoutbox shows ? for a custom layout, and kiln.widgets.layoutlist has no label for it. If you want a name in your bar, render your own indicator, for example t.layout == twocol and "twocol" or kiln.layout.name(t.layout).
6. When you need area, and when you do not
Most layouts never touch the area argument: sizing with "grow" and percent strings lets the solver do all division, and that is the recommended default. area is { x, y, width, height }, the box your layout's container fills, for the cases that genuinely need pixel arithmetic:
- fixed pixel column widths (the stock
carouselcomputes its strip offset fromarea.width) - centered floats sized relative to the workarea (the stock
magnifiersizes its focused float asarea.width * f)
area comes from the previous frame's solve, so it is one frame stale after a bar or gap change; the first frame falls back to the whole screen. Use area only where pixel arithmetic is unavoidable.
Complete example
local kiln = require("kiln")
local ui = kiln.ui
local function twocol(cs, area, t)
if #cs == 0 then
return
end
local f = (t and t.master_width_factor) or 0.5
local gap = (t and t.gap) or kiln.theme.gap
local half = math.ceil(#cs / 2)
local left_w = #cs > half and (f * 100) .. "%" or "grow"
ui.row({ w = "grow", h = "grow", gap = gap }, function()
ui.column({ w = left_w, h = "grow", gap = gap }, function()
for i = 1, half do
kiln.widgets.client(cs[i])
end
end)
if #cs > half then
ui.column({ w = "grow", h = "grow", gap = gap }, function()
for i = half + 1, #cs do
kiln.widgets.client(cs[i])
end
end)
end
end)
end
screen.on("added", function(s)
tag.new { name = "main", screen = s, layout = twocol }
s.tags[1]:view()
end)