Surfaces & Views

A surface is a named UI view (like a page). You can maintain multiple surfaces and switch between them for multi-page UIs.

Creating Surfaces

local main = ss.ui.surface("main")
local settings = ss.ui.surface("settings")

Activating a Surface

Only the active surface is rendered on a given physical screen:

ss.ui.activate("main")
-- later...
ss.ui.activate("settings")

You can keep writing to inactive surfaces — they will display the latest state when activated.

Screen Index

For multi-screen setups, provide a screen index:

local ui = ss.ui.surface("main", 1)  -- Second screen

Querying Size

local size = ui:size()
if size then
    print("Screen: " .. size.w .. "x" .. size.h)
end

Clearing a Surface

ui:clear()  -- Remove all elements from this surface

Multi-Page UI Pattern

local pages = {}
pages.main = ss.ui.surface("main")
pages.settings = ss.ui.surface("settings")

-- Build each page
-- ... (create elements on each surface)

-- Navigation buttons
pages.main:element({
    id = "go_settings", type = "button",
    rect = { unit = "px", x = 10, y = 10, w = 100, h = 30 },
    props = { text = "Settings" },
    on_click = function() ss.ui.activate("settings") end
})

pages.settings:element({
    id = "go_back", type = "button",
    rect = { unit = "px", x = 10, y = 10, w = 100, h = 30 },
    props = { text = "Back" },
    on_click = function() ss.ui.activate("main") end
})

ss.ui.activate("main")
pages.main:commit()
pages.settings:commit()