Input

Put input policy in ~/.config/aqueous/input.toml. The sidecar overlays matching wm.toml input and gesture values, and changes apply to connected devices and devices added later.

Change your keyboard layout

Open Settings → Aqueous → Input → Keyboard and enter an XKB code: de for German or us,de for both layouts. Set grp:alt_shift_toggle in XKB options to switch with Alt+Shift. Validate and Apply & save, then test both layouts in a text editor before entering a password.

To edit the file instead, update the existing [input] table in input.toml:

[input]
xkb_layout = "us,de"
xkb_options = "grp:alt_shift_toggle"

Save for automatic reload, or run aqueousctl session reload --json. Restore the previous layout/options to undo. This changes the session keymap, not the greeter, interface language or IME; see language choices.

Set touchpad tapping and scrolling

Open Settings → Aqueous → Input → Pointer and touchpad. Change the touchpad’s tapping or natural scrolling, Validate and Apply & save. Test tapping and two-finger scrolling in an application. In TOML, use [input.touchpad].tap and natural_scroll; other controls are listed below.

If the saved setting has no effect, check the loaded configuration and helper status. Keep the policy in one file. Focus behavior controls pointer-driven focus separately from tapping and scrolling.

Keyboard and focus

[input]
focus_follows_mouse = false
mouse_follows_focus = false
focus_new_windows = false
raise_on_focus = true
raise_on_focus_delay_ms = 0
num_lock_state = true

xkb_layout = "us,de"
xkb_variant = ""
xkb_options = "caps:escape,grp:alt_shift_toggle"
repeat_rate = 40
repeat_delay = 400

• focus_follows_mouse focuses the pointer target immediately, except where a scrolling layout configures its own dwell delay.
• mouse_follows_focus moves the pointer into a newly focused window after keyboard navigation, activation, or automatic focus changes. It defaults to false. Pointer-originated focus, grabs, and drags leave the pointer in place; a pointer already over the target’s visible content also stays put. Output navigation still moves the pointer when this setting is disabled.
• focus_new_windows focuses a newly admitted focusable window after its output/workspace rule is resolved. Inactive-workspace and non-focusable X11 arrivals do not steal focus.
• raise_on_focus persistently raises a stacking/freeform window after the optional delay.
• num_lock_state sets Num Lock on physical keyboards (default false). An explicit value overrides wm.toml and changes apply to connected keyboards on reload. Reloading an unchanged value preserves manual Num Lock toggles.
• repeat_rate is characters per second; zero disables repeat.
• repeat_delay is milliseconds before repeat begins.

Empty or omitted XKB values use xkbcommon defaults. Multiple layouts and variants use xkbcommon’s comma-separated grammar.

Physical keyboard events are queued through the seat. Internal bindings get the first opportunity to consume a press; otherwise an input-method grab, legacy binding protocol, or focused client receives it. A consumed press owns its corresponding release even if modifiers change.

Mouse and touchpad

Device sections are overrides. Omit a field to keep libinput’s device default.

[input.mouse]
accel_profile = "flat"
accel_speed = 0.0
natural_scroll = false
left_handed = false
middle_emulation = false
dwt = false

[input.touchpad]
accel_profile = "adaptive"
accel_speed = 0.0
natural_scroll = true
tap = true
dwt = true
left_handed = false
middle_emulation = false
click_method = "clickfinger"
scroll_method = "two-finger"

Accepted values are:

• accel_profile: flat or adaptive.
• accel_speed: -1.0 through 1.0.
• click_method: clickfinger or button-areas.
• scroll_method: two-finger, edge, or no-scroll.
• Boolean switches: natural_scroll, tap, dwt, left_handed, and middle_emulation.

Tap, click, and scroll-method configuration is applied only to devices detected as touchpads.

Gestures

Gesture bindings use <kind>_<fingers>_<direction> and the same verbs as custom keyboard bindings:

[gestures]
swipe_3_left = "builtin:focus_workspace_down"
swipe_3_right = "builtin:focus_workspace_up"
pinch_4_in = "builtin:toggle_start_menu"

Swipes accept left, right, up, and down; pinches accept in and out. Finger counts are positive integers. The value may be builtin:<action>, set_layout:<id-or-slot>, or spawn:<command>. A matching gesture is consumed by Aqueous; unmatched gestures continue through the normal client path.

Pointer interactions and constraints

Normal clicks use scene hit-testing. The configured primary modifier intercepts window-management drags before client delivery. Client drag-and-drop temporarily suppresses focus-follows-pointer so wlroots can own its pointer and keyboard grabs without focus changes underneath it.

The untrap_pointer binding releases an active relative-pointer constraint while held and restores it on release. This is useful for games without permanently disabling pointer locking.

Scrolling-layout wheel navigation uses the primary modifier to move by column and the primary modifier plus Alt to move within a column. Natural-scroll settings reverse those directions consistently. Configure or disable these actions with wheel_scroll_left/right/up/down; see wheel bindings.

Touchscreen limits

Touch input and client drag-and-drop do not support native window move/resize requests from a touchscreen or pen. Use a mouse, touchpad or keyboard window actions instead. Touchpad swipe bindings are separate from touchscreen window drags.

Tablets

Map a tablet’s absolute pen input to one output with repeated [[input.tablet]] rules in input.toml. Each tablet can use a different output while the mouse cursor remains independent. Pen pressure, tilt, proximity, tip and buttons continue through tablet-v2.

aqueousctl input devices --json
aqueousctl input generate-config --device DEVICE_ID --id drawing-pen --output OUTPUT

Replace DEVICE_ID and OUTPUT with values from discovery. Generation prints TOML by default; add --write ~/.config/aqueous/input.toml to update the file. See Tablets for Kamvas/Intuos setup, persistent matching, full-desktop or disabled modes, and troubleshooting.

Mouse/touchpad acceleration settings apply to pointer devices, not pens. Unconfigured tablets retain the existing desktop mapping behavior. Configured tablets wait for their assigned output when it is unavailable.

Input methods and virtual devices

At the protocol layer Aqueous supports tablet v2, text-input v3, input-method v2 and input popups, relative pointers, pointer gestures, virtual keyboards, and virtual pointers. These standard interfaces allow drawing tablets, on- screen keyboards, IMEs, accessibility tools, and test/automation clients to participate in normal seat focus. These protocols do not install or configure the tools themselves.

Accessibility and input-method readiness

Task	Current limits
Keyboard-only desktop	Use Aqueous bindings and Pearl’s launcher, dock and Settings navigation; check login and locking with your bindings.
Screen reader, including Orca	Full speech and lock-screen support is unconfirmed.
Magnification	Pearl’s font and cursor settings help visibility; they do not provide a desktop magnifier.
IME or on-screen keyboard	Install and configure a separate service; protocol support alone does not provide a working setup.

Keep a working input method available during setup. Check composition and candidate windows in your apps, and check navigation, speech and password privacy through locking and unlocking. Report the tool, version and failed step.

Trackpoints and legacy pointer values

[input.trackpoint] is accepted and retained, but the current libinput application path classifies every non-touchpad pointer as a mouse. Put effective trackpoint policy under [input.mouse] for now.

Legacy global acceleration remains available:

[input]
pointer_acceleration = false
pointer_acceleration_factor = 0.0

Per-device profile and speed take precedence. Prefer the device sections in a new configuration.

Keep input policy in one file

Explicit tracking makes most sidecar values safe to clear, including focus and raising fields. Legacy global pointer values and some empty XKB strings retain compatibility merge behavior. Defining input policy in one file keeps that precedence unambiguous.