Surfaces

A surface is a top-level Wayland object that holds one node tree. shell.lua returns one surface or a list of them, and every other node lives under some surface’s child. This page holds the rules all four roles share; each role has its own page.

An instance is one mapped copy of a declared surface; its id keys the retained scene and names the surface in mantle log (glossary).

A 32 px bar on every output that pushes windows down by its height and prints the output’s connector name:

local bar = panel {
    id = "bar",
    layer = "top",
    anchor = { top = true, left = true, right = true },
    height = 32,
    exclusive_zone = true,
    child = function(output)
        return row {
            width = "fill",
            height = "fill",
            padding = { left = 8, right = 8 },
            background = "#1e1e2e",
            children = {
                rect {
                    align_v = "center",
                    padding = { left = 10, right = 10, top = 3, bottom = 3 },
                    radius = 10,
                    background = "#313244",
                    children = { text { content = output, font_weight = 700, foreground = "#89b4fa" } },
                },
            },
        }
    end,
}

return { bar }

Properties every role takes

Every surface takes id (required), one child node and, except lock, visible; each role’s page has their table. The root is itself a box node, so it also takes the common and box node properties, except those that place a node in a parent (below): its own background, radius, padding, border_*, paint and animate. Any other key is refused, and the error names the closest accepted one or, with none close, lists them all.

The surface root

The root has no parent, so a few node properties mean something else on it:

Reload and structural fields

The returned list is re-read on every reload. Each surface is matched to the last evaluation by its fingerprint, the fields that the protocol fixes when the object is created.

Per-output child

child = function(output) is for panel and lock, the roles with one instance per output. It runs with that instance’s connector name ("DP-1") on the first pass, and again only when the surface root resolves again: a signal the function or the root’s own properties read is written, or a reload (what a node reads again). Bind signals to properties inside it rather than reading them with :get(), and key per-output state by name: state("wallpaper_" .. output, ...). Returning nil leaves that output’s instance empty. A window, popup or output = "active" panel has no output name and refuses a function child. Example: per-output wallpaper.

Reset on close

Named state keeps its value while a surface is hidden, so a reopened menu shows what it showed last. List the state a panel, window or popup owns in reset_on_close to start it fresh instead: when the surface stops being shown, each state goes back to its declared initial and each scroll to the top.

local open = state("picker_open", true)
local query = state("picker_query", "")
local list_scroll = scroll("picker_list")

return panel {
  id = "picker",
  layer = "overlay",
  visible = open,
  reset_on_close = { query, list_scroll },
  child = textfield { width = 300, height = 32, on_change = function(text) query:set(text) end },
}

A textfield’s draft is the engine’s and is not state; it follows its own lifetime.

Input region

A surface takes pointer input only where its content is solid; everywhere else clicks, hover and focus-follows-mouse pass through to what is below. The engine rebuilds this region on every pass.

A claiming box that clips its children ends the walk there; one that does not also claims the descendants sticking out of it, each cut to any clipping ancestor. visible = false subtrees claim nothing. To make an empty area catch clicks, put a rect { width = "fill", height = "fill", on_click = ... } there (click outside to close).

How do I…

Gotchas

See also: nodes, paint, input, signals, runtime, CLI.

Source: surface parsing, accepted properties, fingerprints, instances, function child and root size, input region, reload and hotplug.