Input

Pointer and keyboard input: clicks, drags and the wheel on a button, hover, scrolling containers, and typing into a textfield, including password fields whose keys never reach Lua. There is no key-handler property and no touch input; keys reach a config only through a focused textfield. A handler usually writes a named state, and the next pass shows the result.

local clicks = state("clicks", 0)

return panel {
    id = "bar",
    layer = "Top",
    anchor = { top = true },
    child = button {
        padding = 8,
        background = "#313244",
        on_click = function(rect, which)
            if which == "left" then clicks:set(clicks:get() + 1) end
        end,
        children = { text { content = clicks:map(function(n) return "Clicked " .. n end) } },
    },
}

Hit testing

Every pointer event asks which nodes lie under the pointer, from the surface down.

Pointer

Only a button takes clicks, drags and the wheel. For each event the innermost button with a handler for that event wins; a button without one is transparent, so a handle inside a draggable track leaves the track draggable.

Click. A press arms the click and the release fires it. Leaving the button and coming back before release still clicks; the pointer leaving the surface cancels. The click also cancels if the button’s laid-out box moved between press and release, so give press feedback with scale or translate rather than width or margin. A press on a textfield never clicks the button around it, and a link in a text (on_link) takes the click before any button around it.

Drag. A left press on an on_drag button calls "start" at once, so clicking a slider track also seeks. Every pointer motion on that surface then calls "move", wherever the pointer is. "end" comes on the left release, when the pointer leaves the surface, or when the surface closes. rect stays the box from the press for the whole drag. On release, "end" fires first and the click (if the button also has on_click) after it; a leave ends the drag and cancels the click.

Wheel. steps is positive away from the user (scroll up) and negative toward. One notch is 1; high-resolution wheels send fractions of a notch, and touchpads send distance divided by one notch’s 39 px. Horizontal motion never reaches on_wheel. The innermost on_wheel button or scroll container under the pointer takes the whole event, with no chaining to a parent.

local level = state("level", 0.5)
local function clamp(value) return math.max(0, math.min(1, value)) end

return panel {
    id = "bar",
    layer = "Top",
    anchor = { top = true },
    child = button {
        width = 200,
        height = 12,
        radius = 6,
        clip = "Rounded",
        background = "#45475a",
        -- A press is "start", so clicking the track also seeks.
        on_drag = function(rect, pointer, phase) level:set(clamp(pointer.x / rect.width)) end,
        on_wheel = function(_, steps) level:set(clamp(level:get() + steps * 0.05)) end,
        children = {
            rect {
                height = "Fill",
                background = "#89b4fa",
                width = level:map(function(value) return string.format("%d%%", math.floor(value * 100 + 0.5)) end),
            },
        },
    },
}

Hover

hover(name) returns a read-only boolean signal, false until the pointer first arrives. Bind it to a node’s hover and the engine writes it as the pointer moves; read the same signal anywhere else to react. The name is the identity: every hover("wifi") call returns the same signal, and it survives reloads.

local over = hover("wifi")

return panel {
    id = "bar",
    layer = "Top",
    anchor = { top = true },
    child = button {
        padding = 6,
        radius = 6,
        hover = over,
        background = over:map(function(on) return on and "#45475a" or "#313244" end),
        on_hover = function(inside) log.debug("wifi hovered:", inside) end,
        on_click = function() process.detach("nm-connection-editor", {}) end,
        children = { icon { name = "network-wireless-symbolic", size = 16 } },
    },
}

Scroll

scroll(name) returns a read-only signal holding a scroll offset in px, 0 at first. Bind it to the scroll property of a row, column or list and the wheel moves that container’s children. Like hover, the name is the identity and survives reloads.

Text fields

A textfield is a single-line text input. The engine holds what the user types (the draft); Lua sees it only through callbacks and cannot set it. The field with focus is the one keys go to. It has no size of its own, so give it width and height (nodes).

A field takes the keyboard only when both hold:

A press on the field focuses it and puts the caret under the pointer. autofocus focuses it without a press.

Selection and clipboard. Dragging or Shift+clicking with the pointer selects too. There is no clipboard in a field, and Tab does not move focus between fields; it only reaches on_navigate. Every key but Enter repeats while held.

Draft lifetime. Clicking elsewhere, or the surface losing the keyboard, stops typing but keeps the draft; clicking the field again resumes it. Enter and Escape clear it. An autofocus arm starts it empty. It is dropped when the field’s node leaves the tree or its surface closes.

local APPS = { "firefox", "foot", "nautilus", "pavucontrol", "thunderbird", "zed" }
local query = state("query", "")
local selected = state("selected", 1)
local LIST = scroll("results")
local open = state("launcher_open", true)

local results = query:map(function(needle)
    local found = {}
    for _, app in ipairs(APPS) do
        if fuzzy(app, needle) then found[#found + 1] = app end
    end
    return found
end)

local function pick(index)
    selected:set(index)
    LIST:reveal(index)
end

local search = textfield {
    width = "Fill",
    height = 32,
    placeholder = "Search apps",
    autofocus = true,
    on_change = function(text)
        query:set(text)
        pick(1)
    end,
    on_submit = function()
        local app = results:get()[selected:get()]
        if app then process.detach(app, {}) end
    end,
    -- First Escape clears the text; a second one, on an empty field, closes.
    on_cancel = function(cleared)
        if not cleared then open:set(false) end
    end,
    on_navigate = function(key)
        local step = ({ up = -1, down = 1 })[key]
        if step then pick(math.max(1, math.min(#results:get(), selected:get() + step))) end
    end,
}

local function app_row(app)
    return row {
        width = "Fill",
        padding = 6,
        background = computed({ results, selected }, function(found, index)
            return found[index] == app and "#45475a" or nil
        end),
        children = { text { content = app } },
    }
end

return panel {
    id = "launcher",
    layer = "Overlay",
    keyboard_interactivity = "OnDemand",
    width = 320,
    visible = open,
    child = column {
        width = "Fill",
        children = {
            search,
            list { width = "Fill", height = 120, scroll = LIST, source = results, itemfn = app_row, key = function(app) return app end },
        },
    },
}

Secure fields

secure_submit = { capability, action } turns a textfield into a password field. Its keys go to a native buffer and leave the Renderer as one message to that target; no Lua value ever holds the secret or its length.

return lock {
    id = "lock",
    child = column {
        width = "Fill",
        height = "Fill",
        align_h = "Center",
        align_v = "Center",
        spacing = 12,
        background = "#11111b",
        children = {
            textfield {
                width = 280,
                height = 40,
                placeholder = "Password",
                mask_character = "•",
                secure_submit = { capability = "lock", action = "authenticate" },
            },
            button {
                padding = 8,
                radius = 8,
                background = "#89b4fa",
                submit = true,
                children = { text { content = "Unlock", foreground = "#11111b" } },
            },
        },
    },
}

How do I…

Right-click menu. on_click reports the mouse button and the button’s rect, which is what a popup’s anchor_rect wants. The click is a pointer release, so the popup may take its grab. The menu hangs from the button, not the click point: no handler reports the pointer position of a click.

local menu_open = state("context_open", false)
local menu_at = state("context_at", { x = 0, y = 0, width = 1, height = 1 })

local function item(label, run)
    return button {
        width = "Fill",
        padding = 6,
        radius = 4,
        on_click = function()
            menu_open:set(false)
            run()
        end,
        children = { text { content = label } },
    }
end

local files = button {
    padding = 8,
    on_click = function(rect, which)
        if which == "right" then
            menu_at:set(rect)
            menu_open:set(true)
        else
            process.detach("nautilus", {})
        end
    end,
    children = { text { content = "Files" } },
}

return {
    panel { id = "bar", layer = "Top", anchor = { top = true }, child = files },
    popup {
        id = "files_menu",
        parent = "bar",
        anchor_rect = menu_at,
        anchor = "Bottom",
        gravity = "Bottom",
        visible = menu_open,
        on_dismiss = function() menu_open:set(false) end,
        child = column {
            width = 140,
            padding = 4,
            background = "#1e1e2e",
            children = {
                item("New window", function() process.detach("nautilus", { "--new-window" }) end),
                item("Downloads", function() process.detach("nautilus", { os.getenv("HOME") .. "/Downloads" }) end),
            },
        },
    },
}

Drag to reorder. Each row is an on_drag button in a keyed list. The drag keeps the row’s box from the press, so pointer.y divided by the row pitch counts the rows moved. The dragged row jumps slot by slot rather than following the pointer; to make it follow, also bind its translate to the drag offset. There is no drag-and-drop between surfaces or applications, and no drag image.

local items = state("order", { "Music", "Mail", "Files", "Terminal" })
local STEP = 32 -- row height 28 + spacing 4
local started_at = 1

local function index_of(name)
    for index, other in ipairs(items:get()) do
        if other == name then return index end
    end
end

local function row_for(name)
    return button {
        width = 200,
        height = 28,
        padding = 6,
        background = "#313244",
        cursor = "grab",
        on_drag = function(_, pointer, phase)
            if phase == "start" then
                started_at = index_of(name)
                return
            end
            -- `pointer` is relative to the row's box at the press, so the offset counts rows moved.
            local order = { table.unpack(items:get()) }
            local target = math.max(1, math.min(#order, started_at + math.floor(pointer.y / STEP)))
            local now = index_of(name)
            if target ~= now then
                table.insert(order, target, table.remove(order, now))
                items:set(order)
            end
        end,
        children = { text { content = name } },
    }
end

return panel {
    id = "bar",
    layer = "Top",
    anchor = { top = true },
    child = list { spacing = 4, source = items, itemfn = row_for, key = function(name) return name end },
}

Gotchas

See also: nodes (button, textfield, list), surfaces (keyboard_interactivity, popups, lock), signals (state the handlers write), animation (press and hover motion), capabilities (lock, polkit, network).

Source: pointer, wheel, keyboard, text fields, secure fields, hit testing, hover, scroll.