textfield

A text input: a search box, a launcher query, a password, or with multiline a message box. The engine holds what the user types (the draft); Lua sees it through callbacks and sets it only with focus_target(name):set_text. Focus, editing keys, the draft’s lifetime and password fields are on input.

A launcher: the field filters a list as the user types, the arrow keys move a selection, Enter launches.

local apps = { "Firefox", "Files", "Terminal", "Text Editor", "Settings" }
local query = state("query", "")
local selected = state("selected", 1)

local matches = query:map(function(q)
    local out = {}
    for _, name in ipairs(apps) do
        if name:lower():find((q or ""):lower(), 1, true) then out[#out + 1] = name end
    end
    return out
end)

local launcher = column { width = 320, padding = 12, spacing = 8, background = "#1E1E2E", radius = 12, children = {
    rect { width = "fill", padding = { left = 10, right = 10 }, radius = 8, background = "#313244", children = {
        textfield {
            width = "fill",
            height = 36,
            font_size = 14,
            foreground = "#CDD6F4",
            placeholder = "Search…",
            autofocus = true,
            on_change = function(text) query:set(text); selected:set(1) end,
            on_key = function(key)
                if key.name == "Down" then selected:set(math.min(#matches:get(), selected:get() + 1))
                elseif key.name == "Up" then selected:set(math.max(1, selected:get() - 1)) end
            end,
            on_submit = function() print("launch", matches:get()[selected:get()]) end,
        },
    } },
    list {
        width = "fill",
        items = matches,
        key = function(name) return name end,
        each = function(name)
            return rect {
                width = "fill", padding = { left = 10, right = 10, top = 6, bottom = 6 }, radius = 8,
                background = computed({ matches, selected }, function(found, index)
                    return found[index] == name and "#45475A" or "#00000000"
                end),
                children = { text { content = name, foreground = "#CDD6F4" } },
            }
        end,
    },
} }

return { panel { id = "launcher", layer = "top", anchor = { top = true },
    keyboard_interactivity = "on_demand", child = launcher } }

The image shows the empty search field and unfiltered list. Typing updates the list through on_change. The panel needs keyboard_interactivity for the field to get keys (panel).

Properties

textfield takes the common properties, plus:

The field has no intrinsic width, so give it width; without height it is one line tall (font_size times line_height), or a multiline field’s rows. It draws one line of text and a caret, vertically centred (a multiline field: rows from the top), with the same typography properties as text, the draft, placeholder and mask alike, in the fonts chain unless font names a family. Plain fields use zwp_text_input_v3 for composition when the compositor offers it and text-input enters the field’s own surface. Raw keys stay active between compositions and are suppressed during pending or active composition. Preedit text is underlined; commits and surrounding deletions call on_change. Secure fields read wl_keyboard and never send their draft to an input method.

A field with none of on_change, on_submit and secure_submit never takes focus. The draft follows the node, so give the field a stable id when siblings before it come and go (identity).

Multiline

multiline = true wraps the draft at the field’s width. Return inserts a newline and Ctrl+Return submits; submit_key = "return" swaps them, with Shift+Return inserting the newline. The field grows from min_lines to max_lines rows; past that, or at a fixed height, its rows scroll to keep the caret in view, and the wheel scrolls them. Up and Down move by visual row, Home and End to its ends, Ctrl+Home and Ctrl+End to the text’s. Up on the first row and Down on the last reach on_key. Paste, input-method commits and set_text keep newlines; a secure_submit field cannot be multiline.

local reply = column { width = 280, padding = 10, background = "#1E1E2E", radius = 12, children = {
    textfield {
        width = "fill",
        font_size = 14,
        foreground = "#CDD6F4",
        placeholder = "Write a reply. Return sends it, Shift+Return starts a new line.",
        multiline = true,
        min_lines = 3,
        max_lines = 8,
        submit_key = "return",
        on_submit = function(text) print("send", text) end,
    },
} }

return { panel { id = "reply", layer = "top", anchor = { bottom = true },
    keyboard_interactivity = "on_demand", child = reply } }

How do I…

Gotchas

See also: input, list, text, surfaces: panel.

Source: vocabulary, content parsers, secure_submit, plain fields, focus.