wibox.widget.imagebox
Shows one image. Without a size from forced_width, forced_height or an ancestor, the box is the image's own size. With a size on one axis the image scales to it, keeping its aspect; with both, it fits inside.

Each row sets one property. The outline is the box the widget was given.
Show Lua
Save this as /tmp/widget-imagebox.lua, then run:
somewm-client eval 'dofile("/tmp/widget-imagebox.lua")'
It opens the figure on your focused screen and closes after two minutes. Every row is the same Cairo-drawn 64 by 40 image with one property set.
-- 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.imagebox: one 64x40 image drawn with Cairo, shown at several sizes.
local cairo = require("lgi").cairo
local img = cairo.ImageSurface.create(cairo.Format.ARGB32, 64, 40)
local cr = cairo.Context(img)
cr:set_source(gears.color(F.blue)); cr:rectangle(0, 0, 64, 40); cr:fill()
cr:set_source(gears.color(F.amber)); cr:arc(20, 20, 14, 0, 2 * math.pi); cr:fill()
cr:set_source(gears.color(F.green)); cr:rectangle(40, 8, 18, 24); cr:fill()
local function image(extra)
local t = { image = img, widget = wibox.widget.imagebox }
for k, v in pairs(extra or {}) do t[k] = v end
return t
end
return F.scene("wibox.widget.imagebox", "A 64x40 image, resized or not, aligned, clipped", {
F.row('image = surface (own size)', image(), { fit = true }),
F.row('forced_height = 80', image { forced_height = 80 }, { fit = true }),
F.row('forced_width = 200, forced_height = 60', image { forced_width = 200, forced_height = 60 }, { fit = true }),
F.row('resize = false', image { resize = false }, { h = 80 }),
F.row('upscale = false', image { upscale = false }, { h = 80 }),
F.row('halign = "right", valign = "bottom"', image { halign = "right", valign = "bottom" }, { h = 80 }),
F.row('clip_shape = gears.shape.circle', image { clip_shape = gears.shape.circle, forced_height = 80 }, { fit = true }),
})
Download the Lua file. To close it early:
somewm-client eval 'if somewm_reference_figure then somewm_reference_figure.stop() end'
Constructor: wibox.widget.imagebox(image, resize_allowed, clip_shape, ...). Upstream page.
local icon = wibox.widget {
image = beautiful.awesome_icon,
forced_height = 16,
widget = wibox.widget.imagebox,
}
Properties
| Property | Type | Default | What it does | In SomeWM |
|---|---|---|---|---|
image | string, surface, handle or nil | nil | A file path (PNG, SVG and what gears.surface loads), a Cairo image surface, or an rsvg handle. nil shows nothing and takes no space. | An image with no size, such as an SVG handle without dimensions, warns once and is left out. |
resize | boolean | true | Scale the image to the box. false draws it at its own size, cut at the box. | |
upscale | boolean | resize | Allow scaling up. | |
downscale | boolean | resize | Allow scaling down. | |
halign | "left", "center", "right" | "center" | Where the image sits when the box is wider. | |
valign | "top", "center", "bottom" | "center" | Where the image sits when the box is taller. | |
clip_shape | function | gears.shape.rectangle | A gears.shape the image is clipped to. Extra constructor arguments go to it. | |
max_scaling_factor | number | 0 | Largest scale allowed; 0 means no limit. | |
horizontal_fit_policy | string | "auto" | How the width is used: "auto", "none", "fit", "repeat", "reflect", "pad". | Any value but "auto" warns once and draws as "auto". |
vertical_fit_policy | string | "auto" | The same for the height. | Same. |
scaling_quality | string | "good" | Scaling filter: "fast", "good", "best", "nearest", "bilinear". | Not applied. The renderer picks the filter. |
stylesheet | string | "" | CSS applied to an SVG, as text or a file path. | |
dpi | number or table | 96 | DPI an SVG is rendered at. | |
source_height | number | The image's own height. Read only. |
Setting a property emits property::<name>.
Gone in SomeWM 2.1: auto_dpi and source_width. The output's scale applies. An imagebox with no size on either axis is the image's own size and can overflow a layout; see the compatibility list.
Methods
| Method | What it does |
|---|---|
:set_image(image) | Sets image and returns true, or false when the file could not be loaded. |
:set_clip_shape(shape, ...) | Sets clip_shape with arguments for the shape function. |
The common properties, methods and signals apply.