windows

Open toplevel windows with title, app ID, workspace, output and state flags.

list {
    source = mantle.windows:map(function(windows)
        return windows and windows.windows or {}
    end),
    key = function(window) return window.id end,
    itemfn = function(window)
        return button {
            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 or wlr-foreign-toplevel backend.

Field	Type	Description
`source`	`string`	`"niri"`, `"hyprland"`, or `"wlr_foreign_toplevel"`.
`windows`	`WindowEntry[]`	Sorted by `workspace_id`, then backend order; windows without one last.

`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.
`workspace_id?`	`integer`	`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.

Backend

niri and Hyprland share the workspaces reader; any other compositor needs zwlr_foreign_toplevel_manager_v1 (backend table).

Backend	Reports	Writes
niri	`floating`	`focus`, `close`
Hyprland	`floating`, `fullscreen`, `maximized`	`focus`, `close`, `set_fullscreen`, `set_maximized`
wlr foreign-toplevel	`fullscreen`, `maximized`, `minimized`	Every action

A flag a backend does not report is nil; an action it lacks is logged at debug level and dropped.

Gotchas

Trap	Fix
`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.

Source: supervisor/src/capabilities/windows/

Keyboard shortcuts