Keybindings and actions

Nothing here is hard-coded. Every entry in the default table below is an ordinary [binds] line you can change, and every drag verb is an ordinary [mouse] line. Super+Shift+? shows the live list on screen.

Contents: defaults · actions · modes · mouse · gestures · the desktop strip · the launcher

Default bindings

These are also the built-ins fwm falls back on when [binds] is missing or unusable, so they work on a machine with no config at all.

Windows

Layout

Desktops and camera

Everything else

Actions

Any of these can be bound in [binds], in a [mode.*], in [mouse], in [gestures], or run from a script with fwmctl dispatch <action>. An unknown action is reported when the config loads rather than doing nothing when pressed.

Windows

Layout and desktops

World

Interface

Monitors

Escapes

Giving a key to an external shell

A Wayland client cannot see a key it is not focused for, so an outside launcher can never answer Super+Space by itself: the compositor has to hand the press over. global: is that handover, over hyprland-global-shortcuts-v1, which Quickshell exposes as its GlobalShortcut type.

The client registers a named action and says nothing about keys — which keys reach it stays fwm’s decision:

GlobalShortcut { appid: "quickshell"; name: "launcher"; onPressed: /* ... */ }

[binds]
"super+space" = "global:quickshell:launcher"   # instead of "launcher"

Binding the key away from launcher is what makes this replace fwm’s own launcher rather than sit beside it. Nothing has registered the name yet — the shell is not running — and the key does nothing but say so in the log.

Modes (submaps)

A second keymap you step into, so single keys can mean something. While a mode is active it owns the keyboard: its binds fire, Escape leaves, and every other key does nothing rather than reaching the application underneath — which is what makes a bare g safe to bind.

[mode.physics]
enter  = "super+o"
"g"    = "cycle_gravity"
"c"    = "calm_all"
"r"    = "spin_all"

One-shot by default: the first action drops you back. sticky = true keeps the mode open until Escape, for something you mean to repeat. The tray shows the mode’s name while it is active. Up to 8 modes.

Mouse drags

[mouse]
"super+left"       = "move"
"super+shift+left" = "move_nocollide"
"super+right"      = "resize"
"super+ctrl+left"  = "twist"

Buttons are left, right, middle, side, extra; modifiers are matched exactly. The five verbs are the ones only a drag can express, and what they mean depends on the desktop’s mode:

Anything else in the value is an ordinary action, fired once on press. A bind with no modifier eats that button from every client — allowed, but know that you did it.

Gestures

[gestures]
sensitivity    = 1.0
natural        = true
"swipe3+left"  = "pan_desktop"
"swipe3+right" = "pan_desktop"
"swipe3+up"    = "launcher"
"swipe4+left"  = "move_to_view:prev"

swipe<2..5>+left|right|up|down and pinch<2..5>+in|out, with the same action vocabulary plus pan_desktop — which only makes sense as a gesture: it hands the camera to your fingers and pans live, settling on a desktop when they lift. Bind it to both horizontal directions; it is one gesture.

A finger count with nothing bound is passed through untouched, so pinch-to-zoom in a browser still works.

Keys inside the desktop strip

expo (Super+A) takes the keyboard while it is up:

Windows can be dragged between cards with the mouse, and clicking a card enters that desktop.

Keys inside the launcher

Type to filter, ↑/↓ (or Tab / Shift+Tab) to move, Return to run, Backspace to erase, Escape to close. The launcher owns the keyboard while it is open, for the same reason the strip does.