wiki: Document window rules

6 files changed, 280 insertions, 0 deletions

diff --git a/wiki/Configuration:-Window-Rules.md b/wiki/Configuration:-Window-Rules.md
new file mode 100644
index 00000000..0390c132
--- /dev/null
+++ b/wiki/Configuration:-Window-Rules.md
@@ -0,0 +1,267 @@
+### Overview
+
+Window rules let you adjust behavior for individual windows.
+They have `match` and `exclude` directives that control which windows the rule should apply to, and a number of properties that you can set.
+
+Window rules are processed in order of appearance in the config file.
+This means that you can put more generic rules first, then override them for specific windows later.
+For example:
+
+```
+// Set open-maximized to true for all windows.
+window-rule {
+    open-maximized true
+}
+
+// Then, for Alacritty, set open-maximized back to false.
+window-rule {
+    match app-id="Alacritty"
+    open-maximized false
+}
+```
+
+Here are all matchers and properties that a window rule could have:
+
+```
+window-rule {
+    match title="Firefox"
+    match app-id="Alacritty"
+    match is-active=true
+    match is-focused=false
+
+    // Properties that apply once upon window opening.
+    default-column-width { proportion 0.75; }
+    open-on-output "eDP-1"
+    open-maximized true
+    open-fullscreen true
+
+    // Properties that apply continuously.
+    draw-border-with-background false
+    opacity 0.5
+    block-out-from "screencast"
+    // block-out-from "screen-capture"
+
+    min-width 100
+    max-width 200
+    min-height 300
+    max-height 300
+}
+```
+
+### Window Matching
+
+Each window rule can have several `match` and `exclude` directives.
+In order for the rule to apply, a window needs to match *any* of the `match` directives, and *none* of the `exclude` directives.
+
+```
+window-rule {
+    // Match all Telegram windows...
+    match app-id=r#"^org\.telegram\.desktop$"#
+
+    // ...except the media viewer window.
+    exclude title="^Media viewer$"
+
+    // Properties to apply.
+    open-on-output "HDMI-A-1"
+}
+```
+
+Match and exclude directives have the same syntax.
+Here is what you can match on.
+
+#### `title` and `app-id
+
+These are regular expressions that should match anywhere in the window title and app ID respectively.
+
+```
+window-rule {
+    match title="Mozilla Firefox"
+    match app-id="Alacritty"
+}
+```
+
+Raw KDL strings can be helpful for writing out regular expressions:
+
+```
+window-rule {
+    exclude app-id=r#"^org\.keepassxc\.KeePassXC$"#
+}
+```
+
+#### `is-active`
+
+Can be `true` or `false`.
+Matches active windows (same windows that have the active border / focus ring color).
+
+Every workspace on the focused monitor will have one active window.
+This means that you will usually have multiple active windows (one per workspace), and when you switch between workspaces, you can see two active windows at once.
+
+```
+window-rule {
+    match is-active=true
+}
+```
+
+#### `is-focused`
+
+Can be `true` or `false`.
+Matches the window that has the keyboard focus.
+
+Contrary to `is-active`, there can only be a single focused window.
+Also, when opening a layer-shell application launcher or pop-up menu, the keyboard focus goes to layer-shell.
+While layer-shell has the keyboard focus, windows will not match this rule.
+
+### Window Opening Properties
+
+These properties apply once, when a window first opens.
+
+To be precise, they apply at the point when niri sends the initial configure request to the window.
+
+#### `default-column-width`
+
+Set the default width for the new window.
+
+```
+window-rule {
+    default-column-width { proportion 0.75; }
+}
+```
+
+#### `open-on-output`
+
+Make the window open on a specific output.
+
+If such an output does not exist, the window will open on the currently focused output as usual.
+
+If the window opens on an output that is not currently focused, the window will not be automatically focused.
+
+```
+window-rule {
+    open-on-output "eDP-1"
+}
+```
+
+#### `open-maximized`
+
+Make the window open as a maximized column.
+
+```
+window-rule {
+    open-maximized true
+}
+```
+
+#### `open-fullscreen`
+
+Make the window open fullscreen.
+
+```
+window-rule {
+    open-fullscreen true
+}
+```
+
+You can also set this to `false` to *prevent* a window from opening fullscreen.
+
+```
+window-rule {
+    open-fullscreen false
+}
+```
+
+### Dynamic Properties
+
+These properties apply continuously to open windows.
+
+#### `block-out-from`
+
+You can block out windows from xdg-desktop-portal screencasts.
+They will be replaced with solid black rectangles.
+
+This can be useful for password managers or messenger windows, etc.
+
+![Screenshot showing a window visible normally, but blocked out on OBS.](./img/block-out-from-screencast.png)
+
+To preview and set up this rule, check the `preview-render` option in the debug section of the config.
+
+> [!CAUTION]
+> The window is **not** blocked out from third-party screenshot tools.
+> If you open some screenshot tool with preview while screencasting, blocked out windows **will be visible** on the screencast.
+
+The built-in screenshot UI is not affected though, you can use it safely, and windows will remain blocked out even when screencasting it.
+
+```
+window-rule {
+    block-out-from "screencast"
+}
+```
+
+Alternatively, you can block out the window out of *all* screen captures, including third-party screenshot tools.
+This way you avoid accidentally showing the window on a screencast when opening a third-party screenshot preview.
+
+This setting will still let you use the interactive built-in screenshot UI, but it will block out the window from the fully automatic screenshot actions, such as `screenshot-screen` and `screenshot-window`.
+The reasoning is that with an interactive selection, you can make sure that you avoid screenshotting sensitive content.
+
+```
+window-rule {
+    block-out-from "screen-capture"
+}
+```
+
+#### `opacity`
+
+Sets the opacity of the window.
+`0.0` is fully transparent, `1.0` is fully opaque.
+This is applied on top of the window's own opacity, so semitransparent windows will become even more transparent.
+
+Opacity is applied to every surface of the window individually, so subsurfaces and pop-up menus will show window content behind them.
+
+![Screenshot showing Adwaita Demo with a semitransparent pop-up menu.](./img/opacity-popup.png)
+
+Also, focus ring and border with background will show through semitransparent windows (see `prefer-no-csd` and the `draw-border-with-background` window rule below).
+
+```
+window-rule {
+    opacity 0.9
+}
+```
+
+#### `draw-border-with-background`
+
+Override whether the border and the focus ring draw with a background.
+
+Set this to `true` to draw them as solid colored rectangles even for windows which agreed to omit their client-side decorations.
+Set this to `false` to draw them as borders around the window even for windows which use client-side decorations.
+
+This property can be useful for rectangular windows that do not support the xdg-decoration protocol.
+
+| With Background | Without Background |
+| --------------- | ------------------ |
+| ![](./img/simple-egl-border-with-background.png) | ![](./img/simple-egl-border-without-background.png) |
+
+```
+window-rule {
+    draw-border-with-background false
+}
+```
+
+#### Size Overrides
+
+You can amend the window's minimum and maximum size in logical pixels.
+
+Keep in mind that the window itself always has a final say in its size.
+These values instruct niri to never ask the window to be smaller than the minimum you set, or to be bigger than the maximum you set.
+
+> [!NOTE]
+> `max-height` will only apply to automatically-sized windows if it is equal to `min-height`.
+> Either set it equal to `min-height`, or change the window height manually after opening it with `set-window-height`.
+>
+> This is a limitation of niri's window height distribution algorithm.
+
+```
+window-rule {
+    min-width 100
+    max-width 200
+    min-height 300
+    max-height 300
+}
diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md
index e70cf305..ae582f47 100644
--- a/wiki/_Sidebar.md
+++ b/wiki/_Sidebar.md
@@ -8,6 +8,7 @@
 ## Configuration
 * [Overview](https://github.com/YaLTeR/niri/wiki/Configuration:-Overview)
 * [Input](https://github.com/YaLTeR/niri/wiki/Configuration:-Input)
+* [Window Rules](https://github.com/YaLTeR/niri/wiki/Configuration:-Window-Rules)
 
 ## Development
 * [Design Principles](https://github.com/YaLTeR/niri/wiki/Design-Principles)
diff --git a/wiki/img/block-out-from-screencast.png b/wiki/img/block-out-from-screencast.png
new file mode 100644
index 00000000..ec12a621
--- /dev/null
+++ b/wiki/img/block-out-from-screencast.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c1e4e6809fff666c324a6e19bc888fe8cbafb5d159cea36703e7020510c53a52
+size 669362
diff --git a/wiki/img/opacity-popup.png b/wiki/img/opacity-popup.png
new file mode 100644
index 00000000..e5d920ca
--- /dev/null
+++ b/wiki/img/opacity-popup.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d1e456ff87be58fcda542473dcbb5c5d63bef4f95b7e71bc1790de5e012f640d
+size 15837
diff --git a/wiki/img/simple-egl-border-with-background.png b/wiki/img/simple-egl-border-with-background.png
new file mode 100644
index 00000000..6bbbfe37
--- /dev/null
+++ b/wiki/img/simple-egl-border-with-background.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:db034a4d42c382df3ff8aab1178f1978e1d7a20ff2318145c28a7f87e710eeaa
+size 4999
diff --git a/wiki/img/simple-egl-border-without-background.png b/wiki/img/simple-egl-border-without-background.png
new file mode 100644
index 00000000..08d5087f
--- /dev/null
+++ b/wiki/img/simple-egl-border-without-background.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2623c4f1b11d82b0588893c87908b14337f42bd2ee328d17d1db74acf9c7bd17
+size 15729