windows
Open toplevel windows with title, app ID, workspace, output and state flags.
list {
items = mantle.windows:map(function(windows)
return windows.windows
end),
key = function(window) return window.id end,
each = function(window)
return rect {
on_click = function() mantle.windows:focus(window.id) end,
children = {
text { content = window.title, foreground = window.focused and "#89B4FA" or "#CDD6F4" },
},
}
end,
}
State
mantle.windows:get() returns WindowsState, nil before the first push. A field marked ? may be absent.
mantle.windows payload; nil with no niri, Hyprland, sway, mango or wlr-foreign-toplevel
backend.
| Field | Type | Description |
|---|---|---|
source | string | "niri", "hyprland", "sway", "mango", or "wlr_foreign_toplevel". |
windows | WindowEntry[] | Sorted by numeric workspace_id, then Hyprland named ones. Windows with a non-numeric id (sway names such as 1:web, mango’s DP-1:3) or none come last, in backend order. |
WindowEntry
One toplevel window. nil optional fields are ones the backend does not report.
| Field | Type | Description |
|---|---|---|
app_id | string | Wayland app_id (Hyprland’s class); empty when unset. |
floating? | boolean | Whether the window floats rather than tiles; nil on wlr. |
focused | boolean | Whether the window has keyboard focus. |
fullscreen? | boolean | Whether the window is fullscreen; nil on niri. |
id | string | Opaque, backend-shaped id for the windows actions; compare it, never parse it. |
maximized? | boolean | Whether the window is maximized; nil on niri. |
minimized? | boolean | Whether the window is minimized; nil except on wlr. |
output? | string | Connector name; nil when unknown. On wlr, the earliest-entered output the window is still on. |
title | string | Window title; empty when unset. |
urgent | boolean | Whether the window is asking for attention; always false on wlr, which has no such state. |
workspace_id? | string | WorkspaceEntry.id; nil on wlr and on Hyprland special workspaces. |
Actions
Call each as mantle.windows:<action>(arguments...); ? marks an argument you may omit.
| Action | Arguments | Description |
|---|---|---|
focus | id: string | Focuses a window. |
close | id: string | Asks the compositor to close the window. |
set_fullscreen | id: string, fullscreen: boolean | Sets fullscreen on or off; no-op on niri. |
set_minimized | id: string, minimized: boolean | Sets minimized on or off; wlr only. |
set_maximized | id: string, maximized: boolean | Sets maximized on or off; no-op on niri, sway and mango. |
move_to_workspace | id: string, workspace_id: string | Moves a window to a workspace. |
Backend
niri, Hyprland, sway and mango share the workspaces reader; any other compositor needs
zwlr_foreign_toplevel_manager_v1 (backend table).
| Backend | Reports | Writes |
|---|---|---|
| niri | floating | focus, close, move_to_workspace |
| Hyprland | floating, fullscreen, maximized | focus, close, set_fullscreen, set_maximized, move_to_workspace |
| sway | floating, fullscreen | focus, close, set_fullscreen, move_to_workspace |
| mango | floating, fullscreen, maximized, minimized | focus, close, set_fullscreen |
| wlr foreign-toplevel | fullscreen, maximized, minimized | focus, close, set_fullscreen, set_minimized, set_maximized |
A mango window’s workspace_id is its lowest tag on its output (nil on the special tag).
A flag a backend does not report is nil; an action it lacks is logged at debug level and dropped.
On Hyprland, a window’s id also feeds capture { window = id }.
Gotchas
| Trap | Fix |
|---|---|
window.app_id is a class on sway | Xwayland windows have no app_id; sway reports their X11 class instead |
if window.fullscreen == false never matches on niri | The flag is nil there. Test truthiness, or branch on source |
output is nil for a window on a monitor plugged in after startup | wlr binds outputs once, at connect. Restart the Supervisor after a hotplug if a dock sorts by output |
See also: workspaces for the focused window and per-output workspaces.