From dc93f1c1fd7b67e2da5af2ffada732b9ddeb2d6a Mon Sep 17 00:00:00 2001 From: Kent Daleng Date: Sun, 17 Aug 2025 16:05:41 +0200 Subject: github wiki replacement / mkdocs-docs (#2147) * Add wiki based on mkdocs * wording fixes * fix github bg color on narrow * Fix left sidebar section headers being bigger than pages * fix hover accent * fix list rendering on fractional layout * fix videos * fix automatic full links * remove redundant commented css * improve dark mode contrast * update pygments for better child node coloring * update logo * remove blank lines * add systemd language hint --------- Co-authored-by: Ivan Molodetskikh --- wiki/Application-Issues.md | 90 --- wiki/Configuration:-Animations.md | 412 ---------- wiki/Configuration:-Debug-Options.md | 353 --------- wiki/Configuration:-Gestures.md | 96 --- wiki/Configuration:-Input.md | 379 --------- wiki/Configuration:-Introduction.md | 150 ---- wiki/Configuration:-Key-Bindings.md | 375 --------- wiki/Configuration:-Layer-Rules.md | 193 ----- wiki/Configuration:-Layout.md | 553 ------------- wiki/Configuration:-Miscellaneous.md | 298 ------- wiki/Configuration:-Named-Workspaces.md | 47 -- wiki/Configuration:-Outputs.md | 219 ------ wiki/Configuration:-Overview.md | 1 - wiki/Configuration:-Switch-Events.md | 47 -- wiki/Configuration:-Window-Rules.md | 915 ---------------------- wiki/Development:-Animation-Timing.md | 46 -- wiki/Development:-Design-Principles.md | 30 - wiki/Development:-Developing-niri.md | 76 -- wiki/Development:-Fractional-Layout.md | 34 - wiki/Development:-Redraw-Loop.md | 22 - wiki/Example-systemd-Setup.md | 76 -- wiki/FAQ.md | 65 -- wiki/Floating-Windows.md | 16 - wiki/Gestures.md | 93 --- wiki/Getting-Started.md | 187 ----- wiki/Home.md | 5 - wiki/IPC.md | 75 -- wiki/Important-Software.md | 46 -- "wiki/Layer\342\200\220Shell-Components.md" | 5 - wiki/Nvidia.md | 55 -- wiki/Overview.md | 104 --- wiki/Packaging-niri.md | 123 --- wiki/Screencasting.md | 136 ---- wiki/Tabs.md | 35 - wiki/Workspaces.md | 61 -- wiki/Xwayland.md | 159 ---- wiki/_Sidebar.md | 39 - wiki/examples/close_custom_shader.frag | 147 ---- wiki/examples/open_custom_shader.frag | 128 --- wiki/examples/resize_custom_shader.frag | 211 ----- wiki/img/RedrawState-dark.drawio.png | 3 - wiki/img/RedrawState-light.drawio.png | 3 - wiki/img/block-out-from-screencast.png | 3 - wiki/img/border-radius-clip.png | 3 - wiki/img/border.png | 3 - wiki/img/clip-to-geometry.png | 3 - wiki/img/different-corner-radius.png | 3 - wiki/img/focus-ring.png | 3 - wiki/img/geometry-corner-radius.png | 3 - wiki/img/gradients-default.png | 3 - wiki/img/gradients-oklch.png | 3 - wiki/img/gradients-relative-to-workspace-view.png | 3 - wiki/img/layer-block-out-from-screencast.png | 3 - wiki/img/opacity-popup.png | 3 - wiki/img/simple-egl-border-with-background.png | 3 - wiki/img/simple-egl-border-without-background.png | 3 - wiki/img/struts.png | 3 - wiki/img/workspaces-dark.drawio.svg | 442 ----------- wiki/img/workspaces-dark.png | 3 - wiki/img/workspaces-light.drawio.svg | 426 ---------- wiki/img/workspaces-light.png | 3 - 61 files changed, 7027 deletions(-) delete mode 100644 wiki/Application-Issues.md delete mode 100644 wiki/Configuration:-Animations.md delete mode 100644 wiki/Configuration:-Debug-Options.md delete mode 100644 wiki/Configuration:-Gestures.md delete mode 100644 wiki/Configuration:-Input.md delete mode 100644 wiki/Configuration:-Introduction.md delete mode 100644 wiki/Configuration:-Key-Bindings.md delete mode 100644 wiki/Configuration:-Layer-Rules.md delete mode 100644 wiki/Configuration:-Layout.md delete mode 100644 wiki/Configuration:-Miscellaneous.md delete mode 100644 wiki/Configuration:-Named-Workspaces.md delete mode 100644 wiki/Configuration:-Outputs.md delete mode 100644 wiki/Configuration:-Overview.md delete mode 100644 wiki/Configuration:-Switch-Events.md delete mode 100644 wiki/Configuration:-Window-Rules.md delete mode 100644 wiki/Development:-Animation-Timing.md delete mode 100644 wiki/Development:-Design-Principles.md delete mode 100644 wiki/Development:-Developing-niri.md delete mode 100644 wiki/Development:-Fractional-Layout.md delete mode 100644 wiki/Development:-Redraw-Loop.md delete mode 100644 wiki/Example-systemd-Setup.md delete mode 100644 wiki/FAQ.md delete mode 100644 wiki/Floating-Windows.md delete mode 100644 wiki/Gestures.md delete mode 100644 wiki/Getting-Started.md delete mode 100644 wiki/Home.md delete mode 100644 wiki/IPC.md delete mode 100644 wiki/Important-Software.md delete mode 100644 "wiki/Layer\342\200\220Shell-Components.md" delete mode 100644 wiki/Nvidia.md delete mode 100644 wiki/Overview.md delete mode 100644 wiki/Packaging-niri.md delete mode 100644 wiki/Screencasting.md delete mode 100644 wiki/Tabs.md delete mode 100644 wiki/Workspaces.md delete mode 100644 wiki/Xwayland.md delete mode 100644 wiki/_Sidebar.md delete mode 100644 wiki/examples/close_custom_shader.frag delete mode 100644 wiki/examples/open_custom_shader.frag delete mode 100644 wiki/examples/resize_custom_shader.frag delete mode 100644 wiki/img/RedrawState-dark.drawio.png delete mode 100644 wiki/img/RedrawState-light.drawio.png delete mode 100644 wiki/img/block-out-from-screencast.png delete mode 100644 wiki/img/border-radius-clip.png delete mode 100644 wiki/img/border.png delete mode 100644 wiki/img/clip-to-geometry.png delete mode 100644 wiki/img/different-corner-radius.png delete mode 100644 wiki/img/focus-ring.png delete mode 100644 wiki/img/geometry-corner-radius.png delete mode 100644 wiki/img/gradients-default.png delete mode 100644 wiki/img/gradients-oklch.png delete mode 100644 wiki/img/gradients-relative-to-workspace-view.png delete mode 100644 wiki/img/layer-block-out-from-screencast.png delete mode 100644 wiki/img/opacity-popup.png delete mode 100644 wiki/img/simple-egl-border-with-background.png delete mode 100644 wiki/img/simple-egl-border-without-background.png delete mode 100644 wiki/img/struts.png delete mode 100644 wiki/img/workspaces-dark.drawio.svg delete mode 100644 wiki/img/workspaces-dark.png delete mode 100644 wiki/img/workspaces-light.drawio.svg delete mode 100644 wiki/img/workspaces-light.png (limited to 'wiki') diff --git a/wiki/Application-Issues.md b/wiki/Application-Issues.md deleted file mode 100644 index c02a820b..00000000 --- a/wiki/Application-Issues.md +++ /dev/null @@ -1,90 +0,0 @@ -### Electron applications - -Electron-based applications can run directly on Wayland, but it's not the default. - -For Electron > 28, you can set an environment variable: -```kdl -environment { - ELECTRON_OZONE_PLATFORM_HINT "auto" -} -``` - -For previous versions, you need to pass command-line flags to the target application: -``` ---enable-features=UseOzonePlatform --ozone-platform-hint=auto -``` - -If the application has a [desktop entry](https://specifications.freedesktop.org/menu-spec/latest/menu-add-example.html), you can put the command-line arguments into the `Exec` section. - -### VSCode - -If you're having issues with some VSCode hotkeys, try starting `Xwayland` and setting the `DISPLAY=:0` environment variable for VSCode. -That is, still running VSCode with the Wayland backend, but with `DISPLAY` set to a running Xwayland instance. -Apparently, VSCode currently unconditionally queries the X server for a keymap. - -### WezTerm - -> [!NOTE] -> Both of these issues seem to be fixed in the nightly build of WezTerm. - -There's [a bug](https://github.com/wezterm/wezterm/issues/4708) in WezTerm that it waits for a zero-sized Wayland configure event, so its window never shows up in niri. To work around it, put this window rule in the niri config (included in the default config): - -```kdl -window-rule { - match app-id=r#"^org\.wezfurlong\.wezterm$"# - default-column-width {} -} -``` - -This empty default column width lets WezTerm pick its own initial width which makes it show up properly. - -There's [another bug](https://github.com/wezterm/wezterm/issues/6472) in WezTerm that causes it to choose a wrong size when it's in a tiled state, and prevent resizing it. -Niri puts windows in the tiled state with [`prefer-no-csd`](./Configuration:-Miscellaneous.md#prefer-no-csd). -So if you hit this problem, comment out `prefer-no-csd` in the niri config and restart WezTerm. - -### Ghidra - -Some Java apps like Ghidra can show up blank under xwayland-satellite. -To fix this, run them with the `_JAVA_AWT_WM_NONREPARENTING=1` environment variable. - -### rofi-wayland - -There's a bug in rofi-wayland that prevents it from accepting keyboard input on niri with errors in the output. -It's been fixed in rofi, but [the fix had not been released yet](https://github.com/davatorium/rofi/discussions/2008). - -### Fullscreen games - -Some video games, both Linux-native and on Wine, have various issues when using non-stacking desktop environments. -Most of these can be avoided with Valve's [gamescope](https://github.com/ValveSoftware/gamescope), for example: - -```sh -gamescope -f -w 1920 -h 1080 -W 1920 -H 1080 --force-grab-cursor --backend sdl -- -``` - -This command will run ** in 1080p fullscreen—make sure to replace the width and height values to match your desired resolution. -`--force-grab-cursor` forces gamescope to use relative mouse movement which prevents the cursor from escaping the game's window on multi-monitor setups. -Note that `--backend sdl` is currently also required as gamescope's default Wayland backend doesn't lock the cursor properly (possibly related to https://github.com/ValveSoftware/gamescope/issues/1711). - -Steam users should use gamescope through a game's [launch options](https://help.steampowered.com/en/faqs/view/7D01-D2DD-D75E-2955) by replacing the game executable with `%command%`. -Other game launchers such as [Lutris](https://lutris.net/) have their own ways of setting gamescope options. - -Running X11-based games with this method doesn't require Xwayland as gamescope creates its own Xwayland server. -You can run Wayland-native games as well by passing `--expose-wayland` to gamescope, therefore eliminating X11 from the equation. - -### Steam - -On some systems, Steam will show a fully black window. -To fix this, navigate to Settings -> Interface (via Steam's tray icon, or by blindly finding the Steam menu at the top left of the window), then **disable** GPU accelerated rendering in web views. -Restart Steam and it should now work fine. - -If you do not want to disable GPU accelerated rendering you can instead try to pass the launch argument `-system-composer` instead. - -Steam notifications don't run through the standard notification daemon and show up as floating windows in the center of the screen. -You can move them to a more convenient location by adding a window rule in your niri config: - -```kdl -window-rule { - match app-id="steam" title=r#"^notificationtoasts_\d+_desktop$"# - default-floating-position x=10 y=10 relative-to="bottom-right" -} -``` diff --git a/wiki/Configuration:-Animations.md b/wiki/Configuration:-Animations.md deleted file mode 100644 index 2400f568..00000000 --- a/wiki/Configuration:-Animations.md +++ /dev/null @@ -1,412 +0,0 @@ -### Overview - -Niri has several animations which you can configure in the same way. -Additionally, you can disable or slow down all animations at once. - -Here's a quick glance at the available animations with their default values. - -```kdl -animations { - // Uncomment to turn off all animations. - // You can also put "off" into each individual animation to disable it. - // off - - // Slow down all animations by this factor. Values below 1 speed them up instead. - // slowdown 3.0 - - // Individual animations. - - workspace-switch { - spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001 - } - - window-open { - duration-ms 150 - curve "ease-out-expo" - } - - window-close { - duration-ms 150 - curve "ease-out-quad" - } - - horizontal-view-movement { - spring damping-ratio=1.0 stiffness=800 epsilon=0.0001 - } - - window-movement { - spring damping-ratio=1.0 stiffness=800 epsilon=0.0001 - } - - window-resize { - spring damping-ratio=1.0 stiffness=800 epsilon=0.0001 - } - - config-notification-open-close { - spring damping-ratio=0.6 stiffness=1000 epsilon=0.001 - } - - screenshot-ui-open { - duration-ms 200 - curve "ease-out-quad" - } - - overview-open-close { - spring damping-ratio=1.0 stiffness=800 epsilon=0.0001 - } -} -``` - -### Animation Types - -There are two animation types: easing and spring. -Each animation can be either an easing or a spring. - -#### Easing - -This is a relatively common animation type that changes the value over a set duration using an interpolation curve. - -To use this animation, set the following parameters: - -- `duration-ms`: duration of the animation in milliseconds. -- `curve`: the easing curve to use. - -```kdl -animations { - window-open { - duration-ms 150 - curve "ease-out-expo" - } -} -``` - -Currently, niri only supports four curves: - -- `ease-out-quad` Since: 0.1.5 -- `ease-out-cubic` -- `ease-out-expo` -- `linear` Since: 0.1.6 - -You can get a feel for them on pages like [easings.net](https://easings.net/). - -#### Spring - -Spring animations use a model of a physical spring to animate the value. -They notably feel better with touchpad gestures, because they take into account the velocity of your fingers as you release the swipe. -Springs can also oscillate / bounce at the end with the right parameters if you like that sort of thing, but they don't have to (and by default they mostly don't). - -Due to springs using a physical model, the animation parameters are less obvious and generally should be tuned with trial and error. -Notably, you cannot directly set the duration. -You can use the [Elastic](https://flathub.org/apps/app.drey.Elastic) app to help visualize how the spring parameters change the animation. - -A spring animation is configured like this, with three mandatory parameters: - -```kdl -animations { - workspace-switch { - spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001 - } -} -``` - -The `damping-ratio` goes from 0.1 to 10.0 and has the following properties: - -- below 1.0: underdamped spring, will oscillate in the end. -- above 1.0: overdamped spring, won't oscillate. -- 1.0: critically damped spring, comes to rest in minimum possible time without oscillations. - -However, even with damping ratio = 1.0, the spring animation may oscillate if "launched" with enough velocity from a touchpad swipe. - -> [!WARNING] -> Overdamped springs currently have some numerical stability issues and may cause graphical glitches. -> Therefore, setting `damping-ratio` above `1.0` is not recommended. - -Lower `stiffness` will result in a slower animation more prone to oscillation. - -Set `epsilon` to a lower value if the animation "jumps" at the end. - -> [!TIP] -> The spring *mass* (which you can see in Elastic) is hardcoded to 1.0 and cannot be changed. -> Instead, change `stiffness` proportionally. -> E.g. increasing mass by 2× is the same as decreasing stiffness by 2×. - -### Animations - -Now let's go into more detail on the animations that you can configure. - -#### `workspace-switch` - -Animation when switching workspaces up and down, including after the vertical touchpad gesture (a spring is recommended). - -```kdl -animations { - workspace-switch { - spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001 - } -} -``` - -#### `window-open` - -Window opening animation. - -This one uses an easing type by default. - -```kdl -animations { - window-open { - duration-ms 150 - curve "ease-out-expo" - } -} -``` - -##### `custom-shader` - -Since: 0.1.6 - -You can write a custom shader for drawing the window during an open animation. - -See [this example shader](./examples/open_custom_shader.frag) for a full documentation with several animations to experiment with. - -If a custom shader fails to compile, niri will print a warning and fall back to the default, or previous successfully compiled shader. -When running niri as a systemd service, you can see the warnings in the journal: `journalctl -ef /usr/bin/niri` - -> [!WARNING] -> -> Custom shaders do not have a backwards compatibility guarantee. -> I may need to change their interface as I'm developing new features. - -Example: open will fill the current geometry with a solid gradient that gradually fades in. - -```kdl -animations { - window-open { - duration-ms 250 - curve "linear" - - custom-shader r" - vec4 open_color(vec3 coords_geo, vec3 size_geo) { - vec4 color = vec4(0.0); - - if (0.0 <= coords_geo.x && coords_geo.x <= 1.0 - && 0.0 <= coords_geo.y && coords_geo.y <= 1.0) - { - vec4 from = vec4(1.0, 0.0, 0.0, 1.0); - vec4 to = vec4(0.0, 1.0, 0.0, 1.0); - color = mix(from, to, coords_geo.y); - } - - return color * niri_clamped_progress; - } - " - } -} -``` - -#### `window-close` - -Since: 0.1.5 - -Window closing animation. - -This one uses an easing type by default. - -```kdl -animations { - window-close { - duration-ms 150 - curve "ease-out-quad" - } -} -``` - -##### `custom-shader` - -Since: 0.1.6 - -You can write a custom shader for drawing the window during a close animation. - -See [this example shader](./examples/close_custom_shader.frag) for a full documentation with several animations to experiment with. - -If a custom shader fails to compile, niri will print a warning and fall back to the default, or previous successfully compiled shader. -When running niri as a systemd service, you can see the warnings in the journal: `journalctl -ef /usr/bin/niri` - -> [!WARNING] -> -> Custom shaders do not have a backwards compatibility guarantee. -> I may need to change their interface as I'm developing new features. - -Example: close will fill the current geometry with a solid gradient that gradually fades away. - -```kdl -animations { - window-close { - custom-shader r" - vec4 close_color(vec3 coords_geo, vec3 size_geo) { - vec4 color = vec4(0.0); - - if (0.0 <= coords_geo.x && coords_geo.x <= 1.0 - && 0.0 <= coords_geo.y && coords_geo.y <= 1.0) - { - vec4 from = vec4(1.0, 0.0, 0.0, 1.0); - vec4 to = vec4(0.0, 1.0, 0.0, 1.0); - color = mix(from, to, coords_geo.y); - } - - return color * (1.0 - niri_clamped_progress); - } - " - } -} -``` - -#### `horizontal-view-movement` - -All horizontal camera view movement animations, such as: - -- When a window off-screen is focused and the camera scrolls to it. -- When a new window appears off-screen and the camera scrolls to it. -- After a horizontal touchpad gesture (a spring is recommended). - -```kdl -animations { - horizontal-view-movement { - spring damping-ratio=1.0 stiffness=800 epsilon=0.0001 - } -} -``` - -#### `window-movement` - -Since: 0.1.5 - -Movement of individual windows within a workspace. - -Includes: - -- Moving window columns with `move-column-left` and `move-column-right`. -- Moving windows inside a column with `move-window-up` and `move-window-down`. -- Moving windows out of the way upon window opening and closing. -- Window movement between columns when consuming/expelling. - -This animation *does not* include the camera view movement, such as scrolling the workspace left and right. - -```kdl -animations { - window-movement { - spring damping-ratio=1.0 stiffness=800 epsilon=0.0001 - } -} -``` - -#### `window-resize` - -Since: 0.1.5 - -Window resize animation. - -Only manual window resizes are animated, i.e. when you resize the window with `switch-preset-column-width` or `maximize-column`. -Also, very small resizes (up to 10 pixels) are not animated. - -```kdl -animations { - window-resize { - spring damping-ratio=1.0 stiffness=800 epsilon=0.0001 - } -} -``` - -##### `custom-shader` - -Since: 0.1.6 - -You can write a custom shader for drawing the window during a resize animation. - -See [this example shader](./examples/resize_custom_shader.frag) for a full documentation with several animations to experiment with. - -If a custom shader fails to compile, niri will print a warning and fall back to the default, or previous successfully compiled shader. -When running niri as a systemd service, you can see the warnings in the journal: `journalctl -ef /usr/bin/niri` - -> [!WARNING] -> -> Custom shaders do not have a backwards compatibility guarantee. -> I may need to change their interface as I'm developing new features. - -Example: resize will show the next (after resize) window texture right away, stretched to the current geometry. - -```kdl -animations { - window-resize { - custom-shader r" - vec4 resize_color(vec3 coords_curr_geo, vec3 size_curr_geo) { - vec3 coords_tex_next = niri_geo_to_tex_next * coords_curr_geo; - vec4 color = texture2D(niri_tex_next, coords_tex_next.st); - return color; - } - " - } -} -``` - -#### `config-notification-open-close` - -The open/close animation of the config parse error and new default config notifications. - -This one uses an underdamped spring by default (`damping-ratio=0.6`) which causes a slight oscillation in the end. - -```kdl -animations { - config-notification-open-close { - spring damping-ratio=0.6 stiffness=1000 epsilon=0.001 - } -} -``` - -#### `screenshot-ui-open` - -Since: 0.1.8 - -The open (fade-in) animation of the screenshot UI. - -```kdl -animations { - screenshot-ui-open { - duration-ms 200 - curve "ease-out-quad" - } -} -``` - -#### `overview-open-close` - -Since: 25.05 - -The open/close zoom animation of the [Overview](./Overview.md). - -```kdl -animations { - overview-open-close { - spring damping-ratio=1.0 stiffness=800 epsilon=0.0001 - } -} -``` - -### Synchronized Animations - -Since: 0.1.5 - -Sometimes, when two animations are meant to play together synchronized, niri will drive them both with the same configuration. - -For example, if a window resize causes the view to move, then that view movement animation will also use the `window-resize` configuration (rather than the `horizontal-view-movement` configuration). -This is especially important for animated resizes to look good when using `center-focused-column "always"`. - -As another example, resizing a window in a column vertically causes other windows to move up or down into their new position. -This movement will use the `window-resize` configuration, rather than the `window-movement` configuration, to keep the animations synchronized. - -A few actions are still missing this synchronization logic, since in some cases it is difficult to implement properly. -Therefore, for the best results, consider using the same parameters for related animations (they are all the same by default): - -- `horizontal-view-movement` -- `window-movement` -- `window-resize` diff --git a/wiki/Configuration:-Debug-Options.md b/wiki/Configuration:-Debug-Options.md deleted file mode 100644 index f2d38de0..00000000 --- a/wiki/Configuration:-Debug-Options.md +++ /dev/null @@ -1,353 +0,0 @@ -### Overview - -Niri has several options that are only useful for debugging, or are experimental and have known issues. -They are not meant for normal use. - -> [!CAUTION] -> These options are **not** covered by the [config breaking change policy](./Configuration:-Introduction.md#breaking-change-policy). -> They can change or stop working at any point with little notice. - -Here are all the options at a glance: - -```kdl -debug { - preview-render "screencast" - // preview-render "screen-capture" - enable-overlay-planes - disable-cursor-plane - disable-direct-scanout - restrict-primary-scanout-to-matching-format - render-drm-device "/dev/dri/renderD129" - force-pipewire-invalid-modifier - dbus-interfaces-in-non-session-instances - wait-for-frame-completion-before-queueing - emulate-zero-presentation-time - disable-resize-throttling - disable-transactions - keep-laptop-panel-on-when-lid-is-closed - disable-monitor-names - strict-new-window-focus-policy - honor-xdg-activation-with-invalid-serial - skip-cursor-only-updates-during-vrr - deactivate-unfocused-windows - keep-max-bpc-unchanged -} - -binds { - Mod+Shift+Ctrl+T { toggle-debug-tint; } - Mod+Shift+Ctrl+O { debug-toggle-opaque-regions; } - Mod+Shift+Ctrl+D { debug-toggle-damage; } -} -``` - -### `preview-render` - -Make niri render the monitors the same way as for a screencast or a screen capture. - -Useful for previewing the `block-out-from` window rule. - -```kdl -debug { - preview-render "screencast" - // preview-render "screen-capture" -} -``` - -### `enable-overlay-planes` - -Enable direct scanout into overlay planes. -May cause frame drops during some animations on some hardware (which is why it is not the default). - -Direct scanout into the primary plane is always enabled. - -```kdl -debug { - enable-overlay-planes -} -``` - -### `disable-cursor-plane` - -Disable the use of the cursor plane. -The cursor will be rendered together with the rest of the frame. - -Useful to work around driver bugs on specific hardware. - -```kdl -debug { - disable-cursor-plane -} -``` - -### `disable-direct-scanout` - -Disable direct scanout to both the primary plane and the overlay planes. - -```kdl -debug { - disable-direct-scanout -} -``` - -### `restrict-primary-scanout-to-matching-format` - -Restricts direct scanout to the primary plane to when the window buffer exactly matches the composition swapchain format. - -This flag may prevent unexpected bandwidth changes when going between composition and scanout. -The plan is to make it default in the future, when we implement a way to tell the clients the composition swapchain format. -As is, it may prevent some clients (mpv on my machine) from scanning out to the primary plane. - -```kdl -debug { - restrict-primary-scanout-to-matching-format -} -``` - -### `render-drm-device` - -Override the DRM device that niri will use for all rendering. - -You can set this to make niri use a different primary GPU than the default one. - -```kdl -debug { - render-drm-device "/dev/dri/renderD129" -} -``` - -### `force-pipewire-invalid-modifier` - -Since: 25.01 - -Forces PipeWire screencasting to use the invalid modifier, even when DRM offers more modifiers. - -Useful for testing the invalid modifier code path that is hit by drivers that don't support modifiers. - -```kdl -debug { - force-pipewire-invalid-modifier -} -``` - -### `dbus-interfaces-in-non-session-instances` - -Make niri create its D-Bus interfaces even if it's not running as a `--session`. - -Useful for testing screencasting changes without having to relogin. - -The main niri instance will *not* currently take back the interfaces when you close the test instance, so you will need to relogin in the end to make screencasting work again. - -```kdl -debug { - dbus-interfaces-in-non-session-instances -} -``` - -### `wait-for-frame-completion-before-queueing` - -Wait until every frame is done rendering before handing it over to DRM. - -Useful for diagnosing certain synchronization and performance problems. - -```kdl -debug { - wait-for-frame-completion-before-queueing -} -``` - -### `emulate-zero-presentation-time` - -Emulate zero (unknown) presentation time returned from DRM. - -This is a thing on NVIDIA proprietary drivers, so this flag can be used to test that niri doesn't break too hard on those systems. - -```kdl -debug { - emulate-zero-presentation-time -} -``` - -### `disable-resize-throttling` - -Since: 0.1.9 - -Disable throttling resize events sent to windows. - -By default, when resizing quickly (e.g. interactively), a window will only receive the next size once it has made a commit for the previously requested size. -This is required for resize transactions to work properly, and it also helps certain clients which don't batch incoming resizes from the compositor. - -Disabling resize throttling will send resizes to windows as fast as possible, which is potentially very fast (for example, on a 1000 Hz mouse). - -```kdl -debug { - disable-resize-throttling -} -``` - -### `disable-transactions` - -Since: 0.1.9 - -Disable transactions (resize and close). - -By default, windows which must resize together, do resize together. -For example, all windows in a column must resize at the same time to maintain the combined column height equal to the screen height, and to maintain the same window width. - -Transactions make niri wait until all windows finish resizing before showing them all on screen in one, synchronized frame. -For them to work properly, resize throttling shouldn't be disabled (with the previous debug flag). - -```kdl -debug { - disable-transactions -} -``` - -### `keep-laptop-panel-on-when-lid-is-closed` - -Since: 0.1.10 - -By default, niri will disable the internal laptop monitor when the laptop lid is closed. -This flag turns off this behavior and will leave the internal laptop monitor on. - -```kdl -debug { - keep-laptop-panel-on-when-lid-is-closed -} -``` - -### `disable-monitor-names` - -Since: 0.1.10 - -Disables the make/model/serial monitor names, as if niri fails to read them from the EDID. - -Use this flag to work around a crash present in 0.1.9 and 0.1.10 when connecting two monitors with matching make/model/serial. - -```kdl -debug { - disable-monitor-names -} -``` - -### `strict-new-window-focus-policy` - -Since: 25.01 - -Disables heuristic automatic focusing for new windows. -Only windows that activate themselves with a valid xdg-activation token will be focused. - -```kdl -debug { - strict-new-window-focus-policy -} -``` - -### `honor-xdg-activation-with-invalid-serial` - -Since: 25.05 - -Widely-used clients such as Discord and Telegram make fresh xdg-activation tokens upon clicking on their tray icon or on their notification. -Most of the time, these fresh tokens will have invalid serials, because the app needs to be focused to get a valid serial, and if the user clicks on a tray icon or a notification, it is usually because the app *isn't* focused, and the user wants to focus it. - -By default, niri ignores xdg-activation tokens with invalid serials, to prevent windows from randomly stealing focus. -This debug flag makes niri honor such tokens, making the aforementioned widely-used apps get focus when clicking on their tray icon or notification. - -Amusingly, clicking on a notification sends the app a perfectly valid activation token from the notification daemon, but these apps seem to simply ignore it. -Maybe in the future these apps/toolkits (Electron, Qt) are fixed, making this debug flag unnecessary. - -```kdl -debug { - honor-xdg-activation-with-invalid-serial -} -``` - -### `skip-cursor-only-updates-during-vrr` - -Since: next release - -Skips redrawing the screen from cursor input while variable refresh rate is active. - -Useful for games where the cursor isn't drawn internally to prevent erratic VRR shifts in response to cursor movement. - -Note that the current implementation has some issues, for example when there's nothing redrawing the screen (like a game), the rendering will appear to completely freeze (since cursor movements won't cause redraws). - -```kdl -debug { - skip-cursor-only-updates-during-vrr -} -``` - -### `deactivate-unfocused-windows` - -Since: next release - -Some clients (notably, Chromium- and Electron-based, like Teams or Slack) erroneously use the Activated xdg window state instead of keyboard focus for things like deciding whether to send notifications for new messages, or for picking where to show an IME popup. -Niri keeps the Activated state on unfocused workspaces and invisible tabbed windows (to reduce unwanted animations), surfacing bugs in these applications. - -Set this debug flag to work around these problems. -It will cause niri to drop the Activated state for all unfocused windows. - -```kdl -debug { - deactivate-unfocused-windows -} -``` - -### `keep-max-bpc-unchanged` - -Since: next release - -When connecting monitors, niri sets their max bpc to 8 in order to reduce display bandwidth and to potentially allow more monitors to be connected at once. -Restricting bpc to 8 is not a problem since we don't support HDR or color management yet and can't really make use of higher bpc. - -Apparently, setting max bpc to 8 breaks some displays driven by AMDGPU. -If this happens to you, set this debug flag, which will prevent niri from changing max bpc. -AMDGPU bug report: https://gitlab.freedesktop.org/drm/amd/-/issues/4487. - -```kdl -debug { - keep-max-bpc-unchanged -} -``` - -### Key Bindings - -These are not debug options, but rather key bindings. - -#### `toggle-debug-tint` - -Tints all surfaces green, unless they are being directly scanned out. - -Useful to check if direct scanout is working. - -```kdl -binds { - Mod+Shift+Ctrl+T { toggle-debug-tint; } -} -``` - -#### `debug-toggle-opaque-regions` - -Since: 0.1.6 - -Tints regions marked as opaque with blue and the rest of the render elements with red. - -Useful to check how Wayland surfaces and internal render elements mark their parts as opaque, which is a rendering performance optimization. - -```kdl -binds { - Mod+Shift+Ctrl+O { debug-toggle-opaque-regions; } -} -``` - -#### `debug-toggle-damage` - -Since: 0.1.6 - -Tints damaged regions with red. - -```kdl -binds { - Mod+Shift+Ctrl+D { debug-toggle-damage; } -} -``` diff --git a/wiki/Configuration:-Gestures.md b/wiki/Configuration:-Gestures.md deleted file mode 100644 index bdb7a407..00000000 --- a/wiki/Configuration:-Gestures.md +++ /dev/null @@ -1,96 +0,0 @@ -### Overview - -Since: 25.02 - -The `gestures` config section contains gesture settings. -For an overview of all niri gestures, see the [Gestures](./Gestures.md) wiki page. - -Here's a quick glance at the available settings along with their default values. - -```kdl -gestures { - dnd-edge-view-scroll { - trigger-width 30 - delay-ms 100 - max-speed 1500 - } - - dnd-edge-workspace-switch { - trigger-height 50 - delay-ms 100 - max-speed 1500 - } - - hot-corners { - // off - } -} -``` - -### `dnd-edge-view-scroll` - -Scroll the tiling view when moving the mouse cursor against a monitor edge during drag-and-drop (DnD). -Also works on a touchscreen. - -This will work for regular drag-and-drop (e.g. dragging a file from a file manager), and for window interactive move when targeting the tiling layout. - -The options are: - -- `trigger-width`: size of the area near the monitor edge that will trigger the scrolling, in logical pixels. -- `delay-ms`: delay in milliseconds before the scrolling starts. -Avoids unwanted scrolling when dragging things across monitors. -- `max-speed`: maximum scrolling speed in logical pixels per second. -The scrolling speed increases linearly as you move your mouse cursor from `trigger-width` to the very edge of the monitor. - -```kdl -gestures { - // Increase the trigger area and maximum speed. - dnd-edge-view-scroll { - trigger-width 100 - max-speed 3000 - } -} -``` - -### `dnd-edge-workspace-switch` - -Since: 25.05 - -Scroll the workspaces up/down when moving the mouse cursor against a monitor edge during drag-and-drop (DnD) while in the overview. -Also works on a touchscreen. - -The options are: - -- `trigger-height`: size of the area near the monitor edge that will trigger the scrolling, in logical pixels. -- `delay-ms`: delay in milliseconds before the scrolling starts. -Avoids unwanted scrolling when dragging things across monitors. -- `max-speed`: maximum scrolling speed; 1500 corresponds to one screen height per second. -The scrolling speed increases linearly as you move your mouse cursor from `trigger-width` to the very edge of the monitor. - -```kdl -gestures { - // Increase the trigger area and maximum speed. - dnd-edge-workspace-switch { - trigger-height 100 - max-speed 3000 - } -} -``` - -### `hot-corners` - -Since: 25.05 - -Put your mouse at the very top-left corner of a monitor to toggle the overview. -Also works during drag-and-dropping something. - -`off` disables the hot corners. - -```kdl -// Disable the hot corners. -gestures { - hot-corners { - off - } -} -``` diff --git a/wiki/Configuration:-Input.md b/wiki/Configuration:-Input.md deleted file mode 100644 index c9ca0ba2..00000000 --- a/wiki/Configuration:-Input.md +++ /dev/null @@ -1,379 +0,0 @@ -### Overview - -In this section you can configure input devices like keyboard and mouse, and some input-related options. - -There's a section for each device type: `keyboard`, `touchpad`, `mouse`, `trackpoint`, `tablet`, `touch`. -Settings in those sections will apply to every device of that type. -Currently, there's no way to configure specific devices individually (but that is planned). - -All settings at a glance: - -```kdl -input { - keyboard { - xkb { - // layout "us" - // variant "colemak_dh_ortho" - // options "compose:ralt,ctrl:nocaps" - // model "" - // rules "" - // file "~/.config/keymap.xkb" - } - - // repeat-delay 600 - // repeat-rate 25 - // track-layout "global" - numlock - } - - touchpad { - // off - tap - // dwt - // dwtp - // drag false - // drag-lock - natural-scroll - // accel-speed 0.2 - // accel-profile "flat" - // scroll-factor 1.0 - // scroll-method "two-finger" - // scroll-button 273 - // scroll-button-lock - // tap-button-map "left-middle-right" - // click-method "clickfinger" - // left-handed - // disabled-on-external-mouse - // middle-emulation - } - - mouse { - // off - // natural-scroll - // accel-speed 0.2 - // accel-profile "flat" - // scroll-factor 1.0 - // scroll-method "no-scroll" - // scroll-button 273 - // scroll-button-lock - // left-handed - // middle-emulation - } - - trackpoint { - // off - // natural-scroll - // accel-speed 0.2 - // accel-profile "flat" - // scroll-method "on-button-down" - // scroll-button 273 - // scroll-button-lock - // left-handed - // middle-emulation - } - - trackball { - // off - // natural-scroll - // accel-speed 0.2 - // accel-profile "flat" - // scroll-method "on-button-down" - // scroll-button 273 - // scroll-button-lock - // left-handed - // middle-emulation - } - - tablet { - // off - map-to-output "eDP-1" - // left-handed - // calibration-matrix 1.0 0.0 0.0 0.0 1.0 0.0 - } - - touch { - // off - map-to-output "eDP-1" - } - - // disable-power-key-handling - // warp-mouse-to-focus - // focus-follows-mouse max-scroll-amount="0%" - // workspace-auto-back-and-forth - - // mod-key "Super" - // mod-key-nested "Alt" -} -``` - -### Keyboard - -#### Layout - -In the `xkb` section, you can set layout, variant, options, model and rules. -These are passed directly to libxkbcommon, which is also used by most other Wayland compositors. -See the `xkeyboard-config(7)` manual for more information. - -```kdl -input { - keyboard { - xkb { - layout "us" - variant "colemak_dh_ortho" - options "compose:ralt,ctrl:nocaps" - } - } -} -``` - -> [!TIP] -> -> Since: 25.02 -> -> Alternatively, you can directly set a path to a .xkb file containing an xkb keymap. -> This overrides all other xkb settings. -> -> ```kdl -> input { -> keyboard { -> xkb { -> file "~/.config/keymap.xkb" -> } -> } -> } -> ``` - -> [!NOTE] -> -> Since: next release -> -> If the `xkb` section is empty (like it is by default), niri will fetch xkb settings from systemd-localed at `org.freedesktop.locale1` over D-Bus. -> This way, for example, system installers can dynamically set the niri keyboard layout. -> You can see this layout in `localectl` and change it with `localectl set-x11-keymap`, for example: -> -> ```sh -> $ localectl set-x11-keymap "us" "" "colemak_dh_ortho" "compose:ralt,ctrl:nocaps" -> $ localectl -> System Locale: LANG=en_US.UTF-8 -> LC_NUMERIC=ru_RU.UTF-8 -> LC_TIME=ru_RU.UTF-8 -> LC_MONETARY=ru_RU.UTF-8 -> LC_PAPER=ru_RU.UTF-8 -> LC_MEASUREMENT=ru_RU.UTF-8 -> VC Keymap: us-colemak_dh_ortho -> X11 Layout: us -> X11 Variant: colemak_dh_ortho -> X11 Options: compose:ralt,ctrl:nocaps -> ``` -> -> By default, `localectl` will set the TTY keymap to the closest match of the XKB keymap. -> You can prevent that with a `--no-convert` flag, for example: `localectl set-x11-keymap --no-convert "us,ru"`. -> -> These settings are picked up by some other programs too, like GDM. - -When using multiple layouts, niri can remember the current layout globally (the default) or per-window. -You can control this with the `track-layout` option. - -- `global`: layout change is global for all windows. -- `window`: layout is tracked for each window individually. - -```kdl -input { - keyboard { - track-layout "global" - } -} -``` - -#### Repeat - -Delay is in milliseconds before the keyboard repeat starts. -Rate is in characters per second. - -```kdl -input { - keyboard { - repeat-delay 600 - repeat-rate 25 - } -} -``` - -#### Num Lock - -Since: 25.05 - -Set the `numlock` flag to turn on Num Lock automatically at startup. - -You might want to disable (comment out) `numlock` if you're using a laptop with a keyboard that overlays Num Lock keys on top of regular keys. - -```kdl -input { - keyboard { - numlock - } -} -``` - -### Pointing Devices - -Most settings for the pointing devices are passed directly to libinput. -Other Wayland compositors also use libinput, so it's likely you will find the same settings there. -For flags like `tap`, omit them or comment them out to disable the setting. - -A few settings are common between input devices: - -- `off`: if set, no events will be sent from this device. - -A few settings are common between `touchpad`, `mouse`, `trackpoint`, and `trackball`: - -- `natural-scroll`: if set, inverts the scrolling direction. -- `accel-speed`: pointer acceleration speed, valid values are from `-1.0` to `1.0` where the default is `0.0`. -- `accel-profile`: can be `adaptive` (the default) or `flat` (disables pointer acceleration). -- `scroll-method`: when to generate scroll events instead of pointer motion events, can be `no-scroll`, `two-finger`, `edge`, or `on-button-down`. - The default and supported methods vary depending on the device type. -- `scroll-button`: Since: 0.1.10 the button code used for the `on-button-down` scroll method. You can find it in `libinput debug-events`. -- `scroll-button-lock`: Since: next release when enabled, the button does not need to be held down. Pressing once engages scrolling, pressing a second time disengages it, and double click acts as single click of the the underlying button. -- `left-handed`: if set, changes the device to left-handed mode. -- `middle-emulation`: emulate a middle mouse click by pressing left and right mouse buttons at once. - -Settings specific to `touchpad`s: - -- `tap`: tap-to-click. -- `dwt`: disable-when-typing. -- `dwtp`: disable-when-trackpointing. -- `drag`: Since: 25.05 can be `true` or `false`, controls if tap-and-drag is enabled. -- `drag-lock`: Since: 25.02 if set, lifting the finger off for a short time while dragging will not drop the dragged item. See the [libinput documentation](https://wayland.freedesktop.org/libinput/doc/latest/tapping.html#tap-and-drag). -- `tap-button-map`: can be `left-right-middle` or `left-middle-right`, controls which button corresponds to a two-finger tap and a three-finger tap. -- `click-method`: can be `button-areas` or `clickfinger`, changes the [click method](https://wayland.freedesktop.org/libinput/doc/latest/clickpad-softbuttons.html). -- `disabled-on-external-mouse`: do not send events while external pointer device is plugged in. - -Settings specific to `touchpad` and `mouse`: - -- `scroll-factor`: Since: 0.1.10 scales the scrolling speed by this value. - -Settings specific to `tablet`s: - -- `calibration-matrix`: Since: 25.02 set to six floating point numbers to change the calibration matrix. See the [`LIBINPUT_CALIBRATION_MATRIX` documentation](https://wayland.freedesktop.org/libinput/doc/latest/device-configuration-via-udev.html) for examples. - -Tablets and touchscreens are absolute pointing devices that can be mapped to a specific output like so: - -```kdl -input { - tablet { - map-to-output "eDP-1" - } - - touch { - map-to-output "eDP-1" - } -} -``` - -Valid output names are the same as the ones used for output configuration. - -Since: 0.1.7 When a tablet is not mapped to any output, it will map to the union of all connected outputs, without aspect ratio correction. - -### General Settings - -These settings are not specific to a particular input device. - -#### `disable-power-key-handling` - -By default, niri will take over the power button to make it sleep instead of power off. -Set this if you would like to configure the power button elsewhere (i.e. `logind.conf`). - -```kdl -input { - disable-power-key-handling -} -``` - -#### `warp-mouse-to-focus` - -Makes the mouse warp to newly focused windows. - -Does not make the cursor visible if it had been hidden. - -```kdl -input { - warp-mouse-to-focus -} -``` - -By default, the cursor warps *separately* horizontally and vertically. -I.e. if moving the mouse only horizontally is enough to put it inside the newly focused window, then the mouse will move only horizontally, and not vertically. - -Since: 25.05 You can customize this with the `mode` property. - -- `mode="center-xy"`: warps by both X and Y coordinates together. -So if the mouse was anywhere outside the newly focused window, it will warp to the center of the window. -- `mode="center-xy-always"`: warps by both X and Y coordinates together, even if the mouse was already somewhere inside the newly focused window. - -```kdl -input { - warp-mouse-to-focus mode="center-xy" -} -``` - -#### `focus-follows-mouse` - -Focuses windows and outputs automatically when moving the mouse over them. - -```kdl -input { - focus-follows-mouse -} -``` - -Since: 0.1.8 You can optionally set `max-scroll-amount`. -Then, focus-follows-mouse won't focus a window if it will result in the view scrolling more than the set amount. -The value is a percentage of the working area width. - -```kdl -input { - // Allow focus-follows-mouse when it results in scrolling at most 10% of the screen. - focus-follows-mouse max-scroll-amount="10%" -} -``` - -```kdl -input { - // Allow focus-follows-mouse only when it will not scroll the view. - focus-follows-mouse max-scroll-amount="0%" -} -``` - -#### `workspace-auto-back-and-forth` - -Normally, switching to the same workspace by index twice will do nothing (since you're already on that workspace). -If this flag is enabled, switching to the same workspace by index twice will switch back to the previous workspace. - -Niri will correctly switch to the workspace you came from, even if workspaces were reordered in the meantime. - -```kdl -input { - workspace-auto-back-and-forth -} -``` - -#### `mod-key`, `mod-key-nested` - -Since: 25.05 - -Customize the `Mod` key for [key bindings](./Configuration:-Key-Bindings.md). -Only valid modifiers are allowed, e.g. `Super`, `Alt`, `Mod3`, `Mod5`, `Ctrl`, `Shift`. - -By default, `Mod` is equal to `Super` when running niri on a TTY, and to `Alt` when running niri as a nested winit window. - -> [!NOTE] -> There are a lot of default bindings with Mod, none of them "make it through" to the underlying window. -> You probably don't want to set `mod-key` to Ctrl or Shift, since Ctrl is commonly used for app hotkeys, and Shift is used for, well, regular typing. - -```kdl -// Switch the mod keys around: use Alt normally, and Super inside a nested window. -input { - mod-key "Alt" - mod-key-nested "Super" -} -``` diff --git a/wiki/Configuration:-Introduction.md b/wiki/Configuration:-Introduction.md deleted file mode 100644 index 3966a650..00000000 --- a/wiki/Configuration:-Introduction.md +++ /dev/null @@ -1,150 +0,0 @@ -### Per-Section Documentation - -You can find documentation for various sections of the config on these wiki pages: - -* [`input {}`](./Configuration:-Input.md) -* [`output "eDP-1" {}`](./Configuration:-Outputs.md) -* [`binds {}`](./Configuration:-Key-Bindings.md) -* [`switch-events {}`](./Configuration:-Switch-Events.md) -* [`layout {}`](./Configuration:-Layout.md) -* [top-level options](./Configuration:-Miscellaneous.md) -* [`window-rule {}`](./Configuration:-Window-Rules.md) -* [`layer-rule {}`](./Configuration:-Layer-Rules.md) -* [`animations {}`](./Configuration:-Animations.md) -* [`gestures {}`](./Configuration:-Gestures.md) -* [`debug {}`](./Configuration:-Debug-Options.md) - -### Loading - -Niri will load configuration from `$XDG_CONFIG_HOME/niri/config.kdl` or `~/.config/niri/config.kdl`, falling back to `/etc/niri/config.kdl`. -If both of these files are missing, niri will create `$XDG_CONFIG_HOME/niri/config.kdl` with the contents of [the default configuration file](https://github.com/YaLTeR/niri/blob/main/resources/default-config.kdl), which are embedded into the niri binary at build time. -Please use the default configuration file as the starting point for your custom configuration. - -The configuration is live-reloaded. -Simply edit and save the config file, and your changes will be applied. -This includes key bindings, output settings like mode, window rules, and everything else. - -You can run `niri validate` to parse the config and see any errors. - -To use a different config file path, pass it in the `--config` or `-c` argument to `niri`. - -You can also set `$NIRI_CONFIG` to the path of the config file. -`--config` always takes precedence. -If `--config` or `$NIRI_CONFIG` doesn't point to a real file, the config will not be loaded. -If `$NIRI_CONFIG` is set to an empty string, it is ignored and the default config location is used instead. - -### Syntax - -The config is written in [KDL]. - -#### Comments - -Lines starting with `//` are comments; they are ignored. - -Also, you can put `/-` in front of a section to comment out the entire section: - -```kdl -/-output "eDP-1" { - // Everything inside here is ignored. - // The display won't be turned off - // as the whole section is commented out. - off -} -``` - -#### Flags - -Toggle options in niri are commonly represented as flags. -Writing out the flag enables it, and omitting it or commenting it out disables it. -For example: - -```kdl -// "Focus follows mouse" is enabled. -input { - focus-follows-mouse - - // Other settings... -} -``` - -```kdl -// "Focus follows mouse" is disabled. -input { - // focus-follows-mouse - - // Other settings... -} -``` - -#### Sections - -Most sections cannot be repeated. For example: - -```kdl -// This is valid: every section appears once. -input { - keyboard { - // ... - } - - touchpad { - // ... - } -} -``` - -```kdl,must-fail -// This is NOT valid: input section appears twice. -input { - keyboard { - // ... - } -} - -input { - touchpad { - // ... - } -} -``` - -Exceptions are, for example, sections that configure different devices by name: - - -```kdl -output "eDP-1" { - // ... -} - -// This is valid: this section configures a different output. -output "HDMI-A-1" { - // ... -} - -// This is NOT valid: "eDP-1" already appeared above. -// It will either throw a config parsing error, or otherwise not work. -output "eDP-1" { - // ... -} -``` - -### Defaults - -Omitting most of the sections of the config file will leave you with the default values for that section. -A notable exception is [`binds {}`](./Configuration:-Key-Bindings.md): they do not get filled with defaults, so make sure you do not erase this section. - -### Breaking Change Policy - -As a rule, niri updates should not break existing config files. -(For example, the default config from niri v0.1.0 still parses fine on v25.02 as I'm writing this.) - -Exceptions can be made for parsing bugs. -For example, niri used to accept multiple binds to the same key, but this was not intended and did not do anything (the first bind was always used). -A patch release changed niri from silently accepting this to causing a parsing failure. -This is not a blanket rule, I will consider the potential impact of every breaking change like this before deciding to carry on with it. - -Keep in mind that the breaking change policy applies only to niri releases. -Commits between releases can and do occasionally break the config as new features are ironed out. -However, I do try to limit these, since several people are running git builds. - -[KDL]: https://kdl.dev/ diff --git a/wiki/Configuration:-Key-Bindings.md b/wiki/Configuration:-Key-Bindings.md deleted file mode 100644 index 3295b0d7..00000000 --- a/wiki/Configuration:-Key-Bindings.md +++ /dev/null @@ -1,375 +0,0 @@ -### 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: - -```kdl -binds { - Mod+Left { focus-column-left; } - Super+Alt+L { spawn "swaylock"; } -} -``` - -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; -- `ISO_Level5_Shift`: can be used with an xkb lv5 option like `lv5:caps_switch`; -- `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. - -Since: 25.05 You can customize the `Mod` key [in the `input` section of the config](./Configuration:-Input.md#mod-key-mod-key-nested). - -> [!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. -> -> Keep in mind that binding shifted keys requires spelling out Shift and the unshifted version of the key, according to your XKB layout. -> For example, on the US QWERTY layout, < is on Shift + ,, so to bind it, you spell out something like `Mod+Shift+Comma`. -> -> As another example, if you've configured the French [BÉPO](https://en.wikipedia.org/wiki/B%C3%89PO) XKB layout, your < is on AltGr + «. -> AltGr is `ISO_Level3_Shift`, or equivalently `Mod5`, so to bind it, you spell out something like `Mod+Mod5+guillemotleft`. -> -> When resolving latin keys, niri will search for the *first* configured XKB layout that has the latin key. -> So for example with US QWERTY and RU layouts configured, US QWERTY will be used for latin binds. - -Since: 0.1.8 Binds will repeat by default (i.e. holding down a bind will make it trigger repeatedly). -You can disable that for specific binds with `repeat=false`: - -```kdl -binds { - Mod+T repeat=false { spawn "alacritty"; } -} -``` - -Binds can also have a cooldown, which will rate-limit the bind and prevent it from repeatedly triggering too quickly. - -```kdl -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. - -```kdl -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. - -```kdl -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. - -### Mouse Click Bindings - -Since: 25.01 - -You can bind mouse clicks using the following syntax. - -```kdl -binds { - Mod+MouseLeft { close-window; } - Mod+MouseRight { close-window; } - Mod+MouseMiddle { close-window; } - Mod+MouseForward { close-window; } - Mod+MouseBack { close-window; } -} -``` - -Mouse clicks operate on the window that was focused at the time of the click, not the window you're clicking. - -Note that binding `Mod+MouseLeft` or `Mod+MouseRight` will override the corresponding gesture (moving or resizing the window). - -### Custom Hotkey Overlay Titles - -Since: 25.02 - -The hotkey overlay (the Important Hotkeys dialog) shows a hardcoded list of binds. -You can customize this list using the `hotkey-overlay-title` property. - -To add a bind to the hotkey overlay, set the property to the title that you want to show: -```kdl -binds { - Mod+Shift+S hotkey-overlay-title="Toggle Dark/Light Style" { spawn "some-script.sh"; } -} -``` - -Binds with custom titles are listed after the hardcoded binds and before non-customized Spawn binds. - -To remove a hardcoded bind from the hotkey overlay, set the property to null: -```kdl -binds { - Mod+Q hotkey-overlay-title=null { close-window; } -} -``` - -> [!TIP] -> When multiple key combinations are bound to the same action: -> - If any of the binds has a custom hotkey overlay title, niri will show that bind. -> - Otherwise, if any of the binds has a null title, niri will hide the bind. -> - Otherwise, niri will show the first key combination. - -Custom titles support [Pango markup](https://docs.gtk.org/Pango/pango_markup.html): - -```kdl -binds { - Mod+Shift+S hotkey-overlay-title="Toggle Dark/Light Style" { spawn "some-script.sh"; } -} -``` - -![Custom markup example.](https://github.com/user-attachments/assets/2a2ba914-bfa7-4dfa-bb5e-49839034765d) - -### 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: - -```kdl -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+"; } -} -``` - -> [!TIP] -> -> Since: 0.1.5 -> -> Spawn bindings have a special `allow-when-locked=true` property that makes them work even while the session is locked: -> -> ```kdl -> binds { -> // This mute bind will work even when the session is locked. -> XF86AudioMute allow-when-locked=true { spawn "wpctl" "set-mute" "@DEFAULT_AUDIO_SINK@" "toggle"; } -> } -> ``` - -Currently, niri *does not* use a shell to run commands, which means that you need to manually separate arguments. - -```kdl -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+D { spawn "alacritty -e /usr/bin/fish"; } - - // Wrong: will pass `-e /usr/bin/fish` as one argument, which alacritty won't understand. - Mod+Q { 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. - -```kdl -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+D { 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+Q { spawn "sh" "-c" "notify-send clipboard \"$(wl-past