Skip to main content
Version: 2.2 (dev)

wibox.widget.textbox

Shows one string of text. Set text for plain text or markup for a Pango markup subset (<b>, <i>, <u>, <s>, <span foreground=... background=...>). The box takes the text's size unless an ancestor sizes it; a textbox with no text takes no size.

local clock = wibox.widget {
text = "12:00",
font = "DejaVu Sans Bold 11",
halign = "center",
widget = wibox.widget.textbox,
}
clock.text = os.date("%H:%M")

Textbox properties: text, markup, halign, valign, ellipsize and font, each in an outlined slot

Each row sets one property. The outline is the box the widget was given, so you can see where the text sits in it and where it was cut.

Show Lua

Save this as /tmp/widget-textbox.lua, then run:

somewm-client eval 'dofile("/tmp/widget-textbox.lua")'

It opens the figure on your focused screen and closes after two minutes. Every row is a stock textbox with one property set; the labels and slots are stock widgets too.

-- Shared canvas for the SomeWM widget reference figures, in the style of the
-- 2.1.0 announcement diagrams: the session's theme colors and font family
-- with gruvbox fallbacks, a bold title and a muted subtitle, rounded cards
-- with one-pixel borders, 28 px margins, an ontop popup that closes itself.
--
-- generate.sh concatenates this file ahead of each scene and publishes the
-- result next to the PNG, so a reader can run the same file:
-- somewm-client eval 'dofile("/tmp/figure.lua")'
-- The scene calls F.scene(title, subtitle, rows). This file defines the
-- global F instead of returning a module because the concatenation is one
-- chunk with no package path.

local awful = require("awful")
local beautiful = require("beautiful")
local gears = require("gears")
local wibox = require("wibox")

if _G.somewm_reference_figure then _G.somewm_reference_figure.stop() end

F = {}

F.bg = beautiful.bg_normal or "#282828"
F.fg = beautiful.fg_normal or "#ebdbb2"
F.panel = "#32302f"
F.slot = "#504945"
F.muted = "#bdae93"
F.amber = "#d79921"
F.blue = "#83a598"
F.green = "#b8bb26"
F.family = (beautiful.font or "sans 10"):gsub("%s+%d+%.?%d*$", "")
F.font = F.family .. " 14"
F.font_bold = F.family .. " Bold 14"
F.mono = "monospace 13"

F.width = 940
F.label_width = 300
F.slot_height = 44

function F.rounded(cr, w, h)
gears.shape.rounded_rect(cr, w, h, 8)
end

-- A line of text in the figure's own font. size is in points.
function F.text(text, size, color, bold)
return wibox.widget {
markup = '<span foreground="' .. (color or F.fg) .. '">'
.. gears.string.xml_escape(text) .. '</span>',
font = F.family .. (bold and " Bold " or " ") .. size,
widget = wibox.widget.textbox,
}
end

-- A textbox in the figure font, for rows that show text. extra overrides
-- properties, which is how a row demonstrates one of them.
function F.label(text, extra)
local t = { text = text, font = F.font, widget = wibox.widget.textbox }
for k, v in pairs(extra or {}) do t[k] = v end
return t
end

-- A solid block of a given size and color, for layout figures.
function F.block(w, h, color, text)
return {
text and {
text = text, font = F.mono, halign = "center", valign = "center",
widget = wibox.widget.textbox,
} or nil,
forced_width = w,
forced_height = h,
bg = color,
fg = F.bg,
shape = F.rounded,
widget = wibox.container.background,
}
end

-- One row: the property value in monospace, then the widget in a rounded
-- slot outlined in F.slot. The outline is the box the widget is given plus
-- opts.pad on each side (6 unless the scene needs the edge). opts.w and
-- opts.h size the slot; opts.fit lets it take the widget's own size.
function F.row(label, widget, opts)
opts = opts or {}
local slot = {
{ widget, margins = opts.pad or 6, widget = wibox.container.margin },
border_width = 1,
border_color = F.slot,
shape = F.rounded,
widget = wibox.container.background,
}
if not opts.fit then
slot.forced_width = opts.w or (F.width - 56 - F.label_width - 20)
slot.forced_height = opts.h or F.slot_height
elseif opts.h then
slot.forced_height = opts.h
end
return {
{
markup = '<span foreground="' .. F.muted .. '">' .. gears.string.xml_escape(label) .. '</span>',
font = F.mono,
ellipsize = "none",
forced_width = F.label_width,
widget = wibox.widget.textbox,
},
{
slot,
halign = "left",
valign = "center",
widget = wibox.container.place,
},
spacing = 20,
layout = wibox.layout.fixed.horizontal,
}
end

-- Build the figure as a centered popup on the primary screen, so every
-- capture comes from the same output and scale. It stays until
-- stop() runs or two minutes pass. Returns a message; generate.sh reads the
-- geometry from _G.somewm_reference_figure.popup once it has a size.
function F.scene(title, subtitle, rows)
local target = screen.primary
local contents = wibox.layout.fixed.vertical()
contents.spacing = 12
contents:add(F.text(title, 27, F.fg, true))
contents:add(F.text(subtitle, 16, F.muted))
contents:add(wibox.widget { forced_height = 6, widget = wibox.container.background })
for _, r in ipairs(rows) do contents:add(wibox.widget(r)) end

local popup = awful.popup {
screen = target,
visible = true,
ontop = true,
input_passthrough = true,
bg = F.bg,
fg = F.fg,
minimum_width = F.width,
maximum_width = F.width,
placement = awful.placement.centered,
widget = { contents, margins = 28, widget = wibox.container.margin },
}
local state = { popup = popup, screen = target }
_G.somewm_reference_figure = state
function state.stop()
popup.visible = false
if state.timer then state.timer:stop() end
if _G.somewm_reference_figure == state then _G.somewm_reference_figure = nil end
end
state.timer = gears.timer.start_new(120, function() state.stop(); return false end)
return title .. " figure opened on screen " .. target.index
end
-- wibox.widget.textbox: text and markup, alignment, ellipsize, font.
local long = "A long line of text that does not fit in the slot it was given, so it is cut"
return F.scene("wibox.widget.textbox", "One string of text, aligned, cut or wrapped, in a font", {
F.row('text = "Hello"', F.label("Hello")),
F.row('markup = "<b>Bold</b> ..."', { markup = "<b>Bold</b> <i>italic</i> <span foreground='#83a598'>blue</span>", font = F.font, widget = wibox.widget.textbox }),
F.row('halign = "left"', F.label("left", { halign = "left" })),
F.row('halign = "center"', F.label("center", { halign = "center" })),
F.row('halign = "right"', F.label("right", { halign = "right" })),
F.row('valign = "top"', F.label("top", { valign = "top" }), { h = 64 }),
F.row('valign = "bottom"', F.label("bottom", { valign = "bottom" }), { h = 64 }),
F.row('ellipsize = "end" (default)', F.label(long), { w = 360 }),
F.row('ellipsize = "none"', F.label(long, { ellipsize = "none" }), { w = 360, h = 72 }),
F.row('font = "sans Bold 14"', F.label("Bold 14", { font = F.font_bold })),
F.row('font = "monospace 18"', F.label("monospace 18", { font = "monospace 18" }), { h = 64 }),
})

Download the Lua file. To close it early:

somewm-client eval 'if somewm_reference_figure then somewm_reference_figure.stop() end'

Constructor: wibox.widget.textbox(text, ignore_markup). text is interpreted as markup unless ignore_markup is true. Upstream page.

Properties​

PropertyTypeDefaultWhat it doesIn SomeWM
textstring""The text, shown as is. \n starts a new line.
markupstringself.textThe text with Pango markup. Invalid markup is an error; use set_markup_silently to get a return value instead.The first font in the markup is used for the whole text. Color, alpha, background, underline and strikethrough spans draw. Other attributes, such as a size or weight that changes mid-text, warn once and are not drawn.
fontstringbeautiful.fontA Pango font description, such as "DejaVu Sans Bold 11". The number is the size in points.A description without a size warns once and draws nothing.
halign"left", "center", "right""left"Horizontal position of the text inside the box.
valign"top", "center", "bottom""center"Vertical position of the text inside the box.
ellipsize"end", "none", "start", "middle""end"What happens when the text is wider than the box."end" keeps one line per \n and cuts the line with an ellipsis. "none" wraps at words. "start" and "middle" warn once and behave as "end". AwesomeWM wraps and then ellipsizes at the bottom; SomeWM does one or the other.
wrap"word", "char", "word_char""word_char"Where a wrapped line breaks.Lines always break at words. "char" warns once.
justifybooleanfalseStretch wrapped lines to the box width.Not applied. Warns once.
indentnumber0Indent of the first line in points, negative for a hanging indent.Not applied. Warns once.
line_spacing_factornumber or nilnilLine height as a factor of the font's, nil for the font's own.Not applied. Warns once.

Setting a property emits property::<name>. The text color is the fg of the nearest background container or of the wibox; a fg that is not a solid color warns once and draws the text transparent.

Methods​

MethodReturnsWhat it does
:set_markup_silently(markup)true, or false, errorSets markup and reports invalid markup instead of raising.
:get_preferred_size(s)width, heightThe size the text takes on screen s when nothing limits its width, in whole pixels.
:get_preferred_size_at_dpi(dpi)width, heightThe same at a given DPI, measured on the primary screen.
wibox.widget.textbox.get_markup_geometry(markup, s, font){x, y, width, height}The preferred size of markup in font without creating a visible textbox.

Gone in SomeWM 2.1: get_height_for_width and get_height_for_width_at_dpi. Let the container size the text, or give the container a width. See the compatibility list.

The common properties, methods and signals apply: forced_width, forced_height, visible, opacity, buttons, mouse signals.