kiln.ui.text
Draws text using the configured font.

The last row clips the parent horizontally before ellipsizing the text.
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
return F.scene("kiln.ui.text", "Font, colour, wrapping and truncation", {
F.row('size = 18', function() ui.text("Handgloves 0123456789", { size = 18 }) end),
F.row('font = "Sans Bold"', function() ui.text("Handgloves 0123456789", { font = "Sans Bold", size = 18 }) end),
F.row('font = "Serif Italic"', function() ui.text("Handgloves 0123456789", { font = "Serif Italic", size = 18 }) end),
F.row('color = "#d79921"', function() ui.text("Handgloves 0123456789", { color = F.amber, size = 18 }) end),
F.row('wrap = "words", w = 240', function()
ui.box({ w = 240 }, function() ui.text("Text wraps at word boundaries inside this box.", { size = 18 }) end)
end, { h = 82 }),
F.row('clip + ellipsize = true', function()
ui.box({ w = 240, clip = { horizontal = true } }, function()
ui.text("A title longer than its container", { size = 18, ellipsize = true })
end)
end),
})
ui.text(str, cfg?)
Example
ui.box({ w = 180, clip = { horizontal = true } }, function()
ui.text("A title longer than its container", { ellipsize = true })
end)
Options
| Field | Type | Default | Behaviour |
|---|---|---|---|
color | colour | theme.fg | Text colour. |
size | number | theme.font_size | Font size in logical pixels. |
font | string | theme.font | Pango font description without a size. |
wrap | string | "words" | "words", "newlines" or "none". |
align | string | "left" | "left", "center" or "right". Aligns lines within the text box. |
line_height | number | 0 | Logical pixels per line. Zero uses the font height. |
ellipsize | boolean | false | Truncates at a horizontal clipping ancestor and adds an ellipsis. |
Text has no w, h, id or input handlers. Use a parent box for those fields.
For single-line placement, set the parent's align.
Fonts
ui.text("Handgloves", { font = "Sans Bold", size = 14 })
ui.text("Handgloves", { font = "Serif Italic" })
A size in font, such as "Sans Bold 14", raises an error. Set size
separately. Pango substitutes for an unavailable font family without an error.
The selected font is used for both measurement and rendering.
Truncation
ellipsize requires a horizontally clipping ancestor whose width is constrained
independently of the text. Without one, it has no effect and raises no error.
A horizontal clip leaves text at its full width, so the example stays on one
line even with wrap = "words".
The clip follows the ancestor's outer box. An ellipsis can therefore reach into its padding. Put the clip on an inner box to keep the text inside the padding.