keyboard
Lock keys, the active layout and the keyboard backlight.
rect {
on_click = function()
local keyboard = mantle.keyboard:get()
if keyboard and keyboard.layout_count > 1 then
mantle.keyboard:switch_layout((keyboard.active_layout_index + 1) % keyboard.layout_count)
end
end,
children = {
text {
content = mantle.keyboard:map(function(keyboard)
return keyboard.active_layout .. (keyboard.caps_lock and " ⇪" or "")
end, ""),
},
},
}
State
mantle.keyboard:get() returns KeyboardState, nil before the first push. A field marked ? may be absent.
mantle.keyboard’s payload. Lock keys read false when no source resolves.
| Field | Type | Description |
|---|---|---|
active_layout | string | Layout display name, e.g. "English (US)"; empty before the compositor answers or without one. |
active_layout_index | integer | 0-based position of the active layout, as switch_layout takes it. |
backlight_percent? | integer | Keyboard backlight, 0 to 100, or nil without a backlight device or readable level. Refreshes on hardware hotkeys and set_backlight only, not on other software writes. |
caps_lock | boolean | Caps Lock is on. |
layout_count | integer | Configured layout count; below 2 there is nothing to switch. |
num_lock | boolean | Num Lock is on. |
scroll_lock | boolean | Scroll Lock is on. |
Actions
Call each as mantle.keyboard:<action>(arguments...); ? marks an argument you may omit.
| Action | Arguments | Description |
|---|---|---|
set_backlight | percent: number | Sets the keyboard backlight, 0 to 100, fractions allowed; values outside clamp to it. |
switch_layout | index: integer | Switches to the 0-based configured layout index. |
Backend
| Part | Source | Without it |
|---|---|---|
| Lock keys | EV_LED events from the first /dev/input device with a Caps Lock LED; a replugged keyboard is reopened | sysfs *::capslock, *::numlock, *::scrolllock polled every 250 ms; with none of those, false |
| Backlight | Reads sysfs *::kbd_backlight, writes through logind’s SetBrightness | backlight_percent = nil; set_backlight is logged and ignored |
| Layout | The event stream workspaces reads: niri’s layout events, Hyprland’s devices for the keyboard marked main (the one typed on last), sway’s GET_INPUTS for the first keyboard that lists layouts, or mango’s keyboardlayout name | active_layout = "", layout_count = 0; switch_layout is logged and ignored. On mango only active_layout is set, so layout_count stays 0 and switch_layout is ignored |
The first push comes when keyboard starts, with whatever layout the compositor has reported.
Gotchas
| Trap | Fix |
|---|---|
caps_lock changes up to 250 ms after the key | The Supervisor cannot read /dev/input, so it polls sysfs. Add the user to the input group |
backlight_percent misses a change another program made | It refreshes only on hardware hotkeys and set_backlight. Change it through set_backlight |
switch_layout on niri with an index above 255 does nothing | niri takes a u8; the call is logged and dropped |
See also: brightness for the screen backlight.