icon
A square icon from the desktop icon theme, or from a file path. Use it for app icons, status
glyphs and tray items. Symbolic (SVG) icons take a tint. For photos and artwork at their own aspect
ratio, use an image.
The focused window’s icon and title. mantle.applications maps a
window’s app_id to its desktop entry, whose icon is a theme name:
local focused_icon = computed({ mantle.applications, mantle.workspaces }, function(apps, workspaces)
local client = workspaces.active_client
if client == nil then return "" end
local index = apps.by_app_id[client.app_id] or apps.by_app_id[string.lower(client.app_id)]
return index and apps.entries[index].icon or ""
end, "")
local app_badge = row {
spacing = 8, padding = { left = 8, right = 12, top = 6, bottom = 6 }, radius = 8, background = "#313244",
children = {
icon { name = focused_icon, size = 20, align_v = "center" },
text { content = mantle.workspaces:map(function(w)
return w.active_client and w.active_client.title or ""
end, ""), max_width = 200, elide = "end", align_v = "center", foreground = "#CDD6F4" },
},
}
return app_badge
Properties
icon takes the common properties, plus:
| Property | Type | Default | Behaviour |
|---|---|---|---|
name | string|Bound | "" | An icon theme name ("firefox", "audio-volume-high-symbolic"), looked up at the drawn size, or an image path (absolute, or ~/ under $HOME), used as is. "" or a name the theme lacks draws nothing |
size | number|Bound | 12 | The box is size × size px; not range-checked |
foreground | Color|Bound | The file’s own colours | Colour for the SVG’s currentColor (CSS color), which tints symbolic icons; a -symbolic icon with no currentColor is recoloured whole, hard-coded fills included. Full-colour icons ignore it |
An explicit width or height overrides that axis of the square; the icon draws at the shorter
side, centred.
The theme is the desktop portal’s org.gnome.desktop.interface icon-theme (what
gsettings set org.gnome.desktop.interface icon-theme writes), else gtk-icon-theme-name from
$XDG_CONFIG_HOME/gtk-4.0/settings.ini, else gtk-3.0/settings.ini, else hicolor. A
change through the portal redraws every icon at once; a settings.ini edit shows after a shell
restart. Files load as PNG, JPEG, WebP, GIF, ICO, BMP, SVG or SVGZ.
How do I…
| Task | Answer |
|---|---|
| Show an app’s icon | The example above |
| Tint a symbolic icon | foreground = "#CDD6F4" on a -symbolic name |
| Show a tray item’s icon | name = item.icon_name or item.icon_path: both spellings work (tray) |
| Show a notification’s app icon | name = notification.app_icon (notifications) |
| Make an icon button | Give the icon an on_click, or put it in a rect with padding and on_click for a bigger target |
| Put a badge on an icon | Layer them in a rect |
Gotchas
| Trap | Fix |
|---|---|
| An icon draws nothing | The theme and its fallbacks lack the name; mantle log warns once with the theme. Check /usr/share/icons/<theme>, or pass an absolute path or ~/ under $HOME |
foreground does not change a colour icon | Only SVGs that use currentColor (symbolic icons) take it |
| The wrong theme’s icons appear | Set the theme with gsettings set org.gnome.desktop.interface icon-theme <theme> (needs xdg-desktop-portal with a GTK or GNOME backend). Without the portal, set gtk-icon-theme-name in settings.ini and restart the shell |
| An icon is smaller than its box | It draws at the shorter side of width/height. Keep them equal, or use size alone |
| An icon given as a relative path draws nothing | A relative name is a theme name. Use mantle.config_dir .. "/icons/x.svg" |
See also: image, capabilities.
Source: vocabulary, content parsers, theme lookup, decode, icon draw.