diff options
| -rw-r--r-- | resources/default-config.kdl | 7 | ||||
| -rw-r--r-- | wiki/Configuration:-Debug-Options.md | 13 | ||||
| -rw-r--r-- | wiki/Configuration:-Key-Bindings.md | 174 | ||||
| -rw-r--r-- | wiki/_Sidebar.md | 1 |
4 files changed, 188 insertions, 7 deletions
diff --git a/resources/default-config.kdl b/resources/default-config.kdl index 60848297..b4148bd8 100644 --- a/resources/default-config.kdl +++ b/resources/default-config.kdl @@ -469,16 +469,9 @@ binds { Alt+Print { screenshot-window; } // The quit action will show a confirmation dialog to avoid accidental exits. - // If you want to skip the confirmation dialog, set the flag like so: - // Mod+Shift+E { quit skip-confirmation=true; } Mod+Shift+E { quit; } // Powers off the monitors. To turn them back on, do any input like // moving the mouse or pressing any other key. Mod+Shift+P { power-off-monitors; } - - // This debug bind will tint all surfaces green, unless they are being - // directly scanned out. It's therefore useful to check if direct scanout - // is working. - // Mod+Shift+Ctrl+T { toggle-debug-tint; } } diff --git a/wiki/Configuration:-Debug-Options.md b/wiki/Configuration:-Debug-Options.md index 0f9fd06e..13cfe3ca 100644 --- a/wiki/Configuration:-Debug-Options.md +++ b/wiki/Configuration:-Debug-Options.md @@ -125,3 +125,16 @@ debug { enable-color-transformations-capability } ``` + +### `toggle-debug-tint` Key Binding + +This one is not a debug option, but rather a key binding. + +It will tint all surfaces green, unless they are being directly scanned out. +It's therefore useful to check if direct scanout is working. + +``` +binds { + Mod+Shift+Ctrl+T { toggle-debug-tint; } +} +``` diff --git a/wiki/Configuration:-Key-Bindings.md b/wiki/Configuration:-Key-Bindings.md new file mode 100644 index 00000000..411c5b0f --- /dev/null +++ b/wiki/Configuration:-Key-Bindings.md @@ -0,0 +1,174 @@ +### Overview + +Key bindings are declared in the `binds {}` section of the config. + +> [!NOTE] +> This is one of the few sections that *does not* get automatically filled with defaults if you omit it, so make sure to copy it from the default config. + +Each bind is a hotkey followed by one action enclosed in curly brackets. +For example: + +``` +binds { + Mod+Left { focus-column-left; } +} +``` + +The hotkey consists of modifiers separated by `+` signs, followed by an XKB key name in the end. + +Valid modifiers are: + +- `Ctrl` or `Control`; +- `Shift`; +- `Alt`; +- `Super` or `Win`; +- `ISO_Level3_Shift` or `Mod5`---this is the AltGr key on certain layouts; +- `Mod`. + +`Mod` is a special modifier that is equal to `Super` when running niri on a TTY, and to `Alt` when running niri as a nested winit window. +This way, you can test niri in a window without causing too many conflicts with the host compositor's key bindings. +For this reason, most of the default keys use the `Mod` modifier. + +> [!TIP] +> To find an XKB name for a particular key, you may use a program like [`wev`](https://git.sr.ht/~sircmpwn/wev). +> +> Open it from a terminal and press the key that you want to detect. +> In the terminal, you will see output like this: +> +> ``` +> [14: wl_keyboard] key: serial: 757775; time: 44940343; key: 113; state: 1 (pressed) +> sym: Left (65361), utf8: '' +> [14: wl_keyboard] key: serial: 757776; time: 44940432; key: 113; state: 0 (released) +> sym: Left (65361), utf8: '' +> [14: wl_keyboard] key: serial: 757777; time: 44940753; key: 114; state: 1 (pressed) +> sym: Right (65363), utf8: '' +> [14: wl_keyboard] key: serial: 757778; time: 44940846; key: 114; state: 0 (released) +> sym: Right (65363), utf8: '' +> ``` +> +> Here, look at `sym: Left` and `sym: Right`: these are the key names. +> I was pressing the left and the right arrow in this example. + +Binds can also have a cooldown, which will rate-limit the bind and prevent it from repeatedly triggering too quickly. + +``` +binds { + Mod+T cooldown-ms=500 { spawn "alacritty"; } +} +``` + +This is mostly useful for the scroll bindings. + +### Scroll Bindings + +You can bind mouse wheel scroll ticks using the following syntax. +These binds will change direction based on the `natural-scroll` setting. + +``` +binds { + Mod+WheelScrollDown cooldown-ms=150 { focus-workspace-down; } + Mod+WheelScrollUp cooldown-ms=150 { focus-workspace-up; } + Mod+WheelScrollRight { focus-column-right; } + Mod+WheelScrollLeft { focus-column-left; } +} +``` + +Similarly, you can bind touchpad scroll "ticks". +Touchpad scrolling is continuous, so for these binds it is split into discrete intervals based on distance travelled. + +These binds are also affected by touchpad's `natural-scroll`, so these example binds are "inverted", since niri has `natural-scroll` enabled for touchpads by default. + +``` +binds { + Mod+TouchpadScrollDown { spawn "wpctl" "set-volume" "@DEFAULT_AUDIO_SINK@" "0.02+"; } + Mod+TouchpadScrollUp { spawn "wpctl" "set-volume" "@DEFAULT_AUDIO_SINK@" "0.02-"; } +} +``` + +Both mouse wheel and touchpad scroll binds will prevent applications from receiving any scroll events when their modifiers are held down. +For example, if you have a `Mod+WheelScrollDown` bind, then while holding `Mod`, all mouse wheel scrolling will be consumed by niri. + +### Actions + +Every action that you can bind is also available for programmatic invocation via `niri msg action`. +Run `niri msg action` to get a full list of actions along with their short descriptions. + +Here are a few actions that benefit from more explanation. + +#### `spawn` + +Run a program. + +`spawn` accepts a path to the program binary as the first argument, followed by arguments to the program. +For example: + +``` +binds { + // Run alacritty. + Mod+T { spawn "alacritty"; } + + // Run `wpctl set-volume @DEFAULT_AUDIO_SINK@ 0.1+`. + XF86AudioRaiseVolume { spawn "wpctl" "set-volume" "@DEFAULT_AUDIO_SINK@" "0.1+"; } +} +``` + +Currently, niri *does not* use a shell to run commands, which means that you need to manually separate arguments. + +``` +binds { + // Correct: every argument is in its own quotes. + Mod+T { spawn "alacritty" "-e" "/usr/bin/fish"; } + + // Wrong: will interpret the whole `alacritty -e /usr/bin/fish` string as the binary path. + Mod+T { spawn "alacritty -e /usr/bin/fish"; } + + // Wrong: will pass `-e /usr/bin/fish` as one argument, which alacritty won't understand. + Mod+T { spawn "alacritty" "-e /usr/bin/fish"; } +} +``` + +This also means that you cannot expand environment variables or `~`. +If you need this, you can run the command through a shell manually. + +``` +binds { + // Wrong: no shell expansion here. These strings will be passed literally to the program. + Mod+T { spawn "grim" "-o" "$MAIN_OUTPUT" "~/screenshot.png"; } + + // Correct: run this through a shell manually so that it can expand the arguments. + // Note that the entire command is passed as a SINGLE argument, + // because shell will do its own argument splitting by whitespace. + Mod+T { spawn "sh" "-c" "grim -o $MAIN_OUTPUT ~/screenshot.png"; } + + // You can also use a shell to run multiple commands, + // use pipes, process substitution, and so on. + Mod+T { spawn "sh" "-c" "notify-send clipboard \"$(wl-paste)\""; } +} +``` + +As a special case, niri will expand `~` to the home directory *only* at the beginning of the program name. + +``` +binds { + // This will work: one ~ at the very beginning. + Mod+T { spawn "~/scripts/do-something.sh"; } +} +``` + +#### `quit` + +Exit niri after showing a confirmation dialog to avoid accidentally triggering it. + +``` +binds { + Mod+Shift+E { quit; } +} +``` + +If you want to skip the confirmation dialog, set the flag like so: + +``` +binds { + Mod+Shift+E { quit skip-confirmation=true; } +} +``` diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md index 014a8b91..e1781b9d 100644 --- a/wiki/_Sidebar.md +++ b/wiki/_Sidebar.md @@ -9,6 +9,7 @@ * [Overview](./Configuration:-Overview.md) * [Input](./Configuration:-Input.md) * [Outputs](./Configuration:-Outputs.md) +* [Key Bindings](./Configuration:-Key-Bindings.md) * [Window Rules](./Configuration:-Window-Rules.md) * [Animations](./Configuration:-Animations.md) * [Debug Options](./Configuration:-Debug-Options.md) |