From a5cd7808a99c87dcce873159ce9a836e5a2e89e3 Mon Sep 17 00:00:00 2001 From: Bugg4 Date: Sat, 9 Aug 2025 01:50:06 +0200 Subject: [PATCH 1/6] Configuring/Dwindle Layout: Improvements, punctuation, clearer wording - Turn `Quirks` into a `Preface` - Improve formatting for table content - mouse --> cursor --- content/Configuring/Dwindle-Layout.md | 84 ++++++++++++++++----------- 1 file changed, 51 insertions(+), 33 deletions(-) diff --git a/content/Configuring/Dwindle-Layout.md b/content/Configuring/Dwindle-Layout.md index c1ae0eace..e1bcb8fb5 100644 --- a/content/Configuring/Dwindle-Layout.md +++ b/content/Configuring/Dwindle-Layout.md @@ -3,55 +3,73 @@ weight: 11 title: Dwindle Layout --- -Dwindle is a BSPWM-like layout, where every window on a workspace is a member of +Dwindle is a [BSPWM](https://github.com/baskerville/bspwm)-like layout, where every window on a workspace is a member of a binary tree. -## Quirks +## Preface + +{{< callout type=info >}} + +In this section we'll be referring to both **orientation** and **direction**, with a very specific meaning: +- **Orientation**: can be horizontal or vertical. + - It refers to the position of two windows relative to eachother. + - The orientation of Dwindle splits is **not fixed**, instead, it's determined **dynamically** by the width-height ratio of the parent node. + - If **width** > **height**, the split "line" will be vertical, resulting in left and right children. + - If **height** > **width**, the split "line" will be horizonal, resulting in top and bottom children. +- **Direction**: can be `left`, `right`, `top` or `bottom`. + - Refers to the _side_ a window can appear on, **relative** to its **parent**. + - Can be influenced by cursor placement and other factors. + +{{< /callout >}} + +{{< callout type=info >}} + +You can make the orientation **fixed** by enabling `preserve_split`. + +{{< /callout >}} + -Dwindle splits are NOT PERMANENT. The split is determined dynamically with the -W/H ratio of the parent node. If W > H, it's side-by-side. If H > W, it's -top-and-bottom. You can make them permanent by enabling `preserve_split`. ## Config category name: `dwindle` -| name | description | type | default | -| --- | --- | --- | --- | -| pseudotile | enable pseudotiling. Pseudotiled windows retain their floating size when tiled. | bool | false | -| force_split | 0 -> split follows mouse, 1 -> always split to the left (new = left or top) 2 -> always split to the right (new = right or bottom) | int | 0 | -| preserve_split | if enabled, the split (side/top) will not change regardless of what happens to the container. | bool | false | -| smart_split | if enabled, allows a more precise control over the window split direction based on the cursor's position. The window is conceptually divided into four triangles, and cursor's triangle determines the split direction. This feature also turns on preserve_split. | bool | false | -| smart_resizing | if enabled, resizing direction will be determined by the mouse's position on the window (nearest to which corner). Else, it is based on the window's tiling position. | bool | true | -| permanent_direction_override | if enabled, makes the preselect direction persist until either this mode is turned off, another direction is specified, or a non-direction is specified (anything other than l,r,u/t,d/b) | bool | false | -| special_scale_factor | specifies the scale factor of windows on the special workspace [0 - 1] | float | 1 | -| split_width_multiplier | specifies the auto-split width multiplier. Multiplying window size is useful on widescreen monitors where window W > H even after several splits. | float | 1.0 | -| use_active_for_splits | whether to prefer the active window or the mouse position for splits | bool | true | -| default_split_ratio | the default split ratio on window open. 1 means even 50/50 split. [0.1 - 1.9] | float | 1.0 | -| split_bias | specifies which window will receive the larger half of a split. positional - 0, current window - 1, opening window - 2 [0/1/2] | int | 0 | -| precise_mouse_move | bindm movewindow will drop the window more precisely depending on where your mouse is. | bool | false | -| single_window_aspect_ratio | whenever only a single window is shown on a screen, add padding so that it conforms to the specified aspect ratio. A value like `4 3` on a 16:9 screen will make it a 4:3 window in the middle with padding to the sides. | Vec2D | 0 0 | -| single_window_aspect_ratio_tolerance | sets a tolerance for `single_window_aspect_ratio`, so that if the padding that would have been added is smaller than the specified fraction of the height or width of the screen, it will not attempt to adjust the window size [0 - 1] | int | 0.1 | +| Name | Description | Type | Default | +| ---- | ----------- | ---- | ------- | +| `pseudotile` | Enable pseudotiling.
Pseudotiled windows retain their floating size when tiled. | bool | `false` | +| `force_split` | `0` -> Split direction follows cursor.
`1` -> Always split to the left or top.
`2` -> always split to the right or bottom. | int | `0` | +| `preserve_split` | If enabled, the split orientation will not change, regardless of the parent dimensions. | bool | `false` | +| `smart_split` | If enabled, allows for more precise control over the split direction based on the cursor's position.

The window is conceptually divided into four triangles, and the one currently under the cursor determines the split direction.

This also enables `preserve_split`. | bool | `false` | +| `smart_resizing` | If enabled, resizing direction will be determined by the cursor's nearest window corner.
Else, it is based on the window's tiling position. | bool | `true` | +| `permanent_direction_override` | If enabled, makes the preselected direction persist until either: | bool \| direction \| string | `false` | +| `special_scale_factor` | Specifies the scale factor of windows on the special workspace. | float [`0.0 .. 1.0`] | `1.0` | +| `split_width_multiplier` | Specifies the auto-split width multiplier.
Multiplying window size is useful on widescreen monitors where window W > H even after several splits. | float | `1.0` | +| `use_active_for_splits` | Whether to prefer the active window or the cursor position for splits. | bool | `true` | +| `default_split_ratio` | The default split ratio on window open.
`1.0` means an even 50/50 split. | float [`0.1 .. 1.9`] | `1.0` | +| `split_bias` | Specifies which window will receive the larger half of a split.
`0` -> positional
`1` -> current window
`2` -> new window | int [`0\|1\|2`] | `0` | +| `precise_mouse_move` | `bindm movewindow` will drop the window more precisely depending your cursor's position. | bool | `false` | +| `single_window_aspect_ratio` | Whenever only a single window is shown on a screen, add padding so that it conforms to the specified aspect ratio.
A value like `4 3` on a 16:9 screen will make it a 4:3 window in the middle with padding to the sides. | Vec2D | `0 0` | +| `single_window_aspect_ratio_tolerance` | Sets a tolerance for `single_window_aspect_ratio` so that if the padding to be added is smaller than the specified fraction of the height or width of the screen, it will not attempt to adjust the window size. [0 - 1] | int | `0.1` | ## Bind Dispatchers -| dispatcher | description | params | -| --- | --- | --- | -| pseudo | toggles the given window's pseudo mode | left empty / `active` for current, or `window` for a specific window | +| Dispatcher | Description | Params | +| ---------- | ----------- | ------ | +| `pseudo` | Toggles the given window's pseudo mode. | Leave empty / `active` for current, or `window` for a specific window. | -## Layout messages +## Layout Messages Dispatcher `layoutmsg` params: -| param | description | args | -| --- | --- | --- | -| togglesplit | toggles the split (top/side) of the current window. `preserve_split` must be enabled for toggling to work. | none | -| swapsplit | swaps the two halves of the split of the current window. | none | -| preselect | A one-time override for the split direction. (valid for the next window to be opened, only works on tiled windows) | direction | -| movetoroot | moves the selected window (active window if unspecified) to the root of its workspace tree. The default behavior maximizes the window in its current subtree. If `unstable` is provided as the second argument, the window will be swapped with the other subtree instead. It is not possible to only provide the second argument, but `movetoroot active unstable` will achieve the same result. | [window, [ string ]] | +| Param | Description | Args | +| ----- | ----------- | ---- | +| `togglesplit` | Toggles between the two possible split orientations of the current window.
`preserve_split` must be enabled for toggling to work. | none | +| `swapsplit` | Swaps the two halves of the split of the current window. | none | +| `preselect` | A one-time override for the split direction.
(valid for the next window to be opened, only works on tiled windows) | direction | +| `movetoroot` | Moves the selected window (active window if unspecified) to the root of its workspace tree.
The default behavior maximizes the window in its current subtree.
If `unstable` is provided as the second argument, the window will be swapped with the other subtree instead.
It is not possible to only provide the second argument, but `movetoroot active unstable` will achieve the same result. | [window, [ string ]] | -e.g.: +E.g.: ```ini bind = SUPER, A, layoutmsg, preselect l -``` +``` \ No newline at end of file From a17bd59779dd1ccf4139c791404919e523a3e139 Mon Sep 17 00:00:00 2001 From: Bugg4 Date: Fri, 15 Aug 2025 17:46:28 +0200 Subject: [PATCH 2/6] Fix `single_window_aspect_ratio_tolerance` type --- content/Configuring/Dwindle-Layout.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/Configuring/Dwindle-Layout.md b/content/Configuring/Dwindle-Layout.md index e1bcb8fb5..544c54df0 100644 --- a/content/Configuring/Dwindle-Layout.md +++ b/content/Configuring/Dwindle-Layout.md @@ -49,7 +49,7 @@ category name: `dwindle` | `split_bias` | Specifies which window will receive the larger half of a split.
`0` -> positional
`1` -> current window
`2` -> new window | int [`0\|1\|2`] | `0` | | `precise_mouse_move` | `bindm movewindow` will drop the window more precisely depending your cursor's position. | bool | `false` | | `single_window_aspect_ratio` | Whenever only a single window is shown on a screen, add padding so that it conforms to the specified aspect ratio.
A value like `4 3` on a 16:9 screen will make it a 4:3 window in the middle with padding to the sides. | Vec2D | `0 0` | -| `single_window_aspect_ratio_tolerance` | Sets a tolerance for `single_window_aspect_ratio` so that if the padding to be added is smaller than the specified fraction of the height or width of the screen, it will not attempt to adjust the window size. [0 - 1] | int | `0.1` | +| `single_window_aspect_ratio_tolerance` | Sets a tolerance for `single_window_aspect_ratio` so that if the padding to be added is smaller than the specified fraction of the height or width of the screen, it will not attempt to adjust the window size. | float [`0.0 .. 1.0`] | `0.1` | ## Bind Dispatchers From 6287e7c7b4fcfe05b80e95628d561268fafb3227 Mon Sep 17 00:00:00 2001 From: Bugg4 Date: Fri, 15 Aug 2025 21:54:56 +0200 Subject: [PATCH 3/6] Fix type of `permanent_direction_override` --- content/Configuring/Dwindle-Layout.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/Configuring/Dwindle-Layout.md b/content/Configuring/Dwindle-Layout.md index 544c54df0..68481fa8b 100644 --- a/content/Configuring/Dwindle-Layout.md +++ b/content/Configuring/Dwindle-Layout.md @@ -41,7 +41,7 @@ category name: `dwindle` | `preserve_split` | If enabled, the split orientation will not change, regardless of the parent dimensions. | bool | `false` | | `smart_split` | If enabled, allows for more precise control over the split direction based on the cursor's position.

The window is conceptually divided into four triangles, and the one currently under the cursor determines the split direction.

This also enables `preserve_split`. | bool | `false` | | `smart_resizing` | If enabled, resizing direction will be determined by the cursor's nearest window corner.
Else, it is based on the window's tiling position. | bool | `true` | -| `permanent_direction_override` | If enabled, makes the preselected direction persist until either:
  • this mode disabled
  • another direction is specified
  • a non-direction is specified
| bool \| direction \| string | `false` | +| `permanent_direction_override` | If enabled, makes the preselected direction persist until either:
  • this mode disabled
  • another direction is specified
  • a non-direction is specified
| bool | `false` | | `special_scale_factor` | Specifies the scale factor of windows on the special workspace. | float [`0.0 .. 1.0`] | `1.0` | | `split_width_multiplier` | Specifies the auto-split width multiplier.
Multiplying window size is useful on widescreen monitors where window W > H even after several splits. | float | `1.0` | | `use_active_for_splits` | Whether to prefer the active window or the cursor position for splits. | bool | `true` | From 65def7e3e63fc652ae3216cd3db129eba49dd2b2 Mon Sep 17 00:00:00 2001 From: Bugg4 Date: Fri, 15 Aug 2025 21:55:50 +0200 Subject: [PATCH 4/6] Clarify option `0` for `split_bias` --- content/Configuring/Dwindle-Layout.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/Configuring/Dwindle-Layout.md b/content/Configuring/Dwindle-Layout.md index 68481fa8b..1a1b94a0b 100644 --- a/content/Configuring/Dwindle-Layout.md +++ b/content/Configuring/Dwindle-Layout.md @@ -46,7 +46,7 @@ category name: `dwindle` | `split_width_multiplier` | Specifies the auto-split width multiplier.
Multiplying window size is useful on widescreen monitors where window W > H even after several splits. | float | `1.0` | | `use_active_for_splits` | Whether to prefer the active window or the cursor position for splits. | bool | `true` | | `default_split_ratio` | The default split ratio on window open.
`1.0` means an even 50/50 split. | float [`0.1 .. 1.9`] | `1.0` | -| `split_bias` | Specifies which window will receive the larger half of a split.
`0` -> positional
`1` -> current window
`2` -> new window | int [`0\|1\|2`] | `0` | +| `split_bias` | Specifies which window will receive the larger half of a split.
`0` -> positional: the new window is larger only if it opens to the `top` or `left` of the parent.
`1` -> always the current window.
`2` -> always the new window. | int [`0\|1\|2`] | `0` | | `precise_mouse_move` | `bindm movewindow` will drop the window more precisely depending your cursor's position. | bool | `false` | | `single_window_aspect_ratio` | Whenever only a single window is shown on a screen, add padding so that it conforms to the specified aspect ratio.
A value like `4 3` on a 16:9 screen will make it a 4:3 window in the middle with padding to the sides. | Vec2D | `0 0` | | `single_window_aspect_ratio_tolerance` | Sets a tolerance for `single_window_aspect_ratio` so that if the padding to be added is smaller than the specified fraction of the height or width of the screen, it will not attempt to adjust the window size. | float [`0.0 .. 1.0`] | `0.1` | From 3563f19e5236d1f9b77c52508ce970116514ada5 Mon Sep 17 00:00:00 2001 From: Bugg4 Date: Fri, 15 Aug 2025 21:58:58 +0200 Subject: [PATCH 5/6] positional -> directional To be consistent with the new Preface section. --- content/Configuring/Dwindle-Layout.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/Configuring/Dwindle-Layout.md b/content/Configuring/Dwindle-Layout.md index 1a1b94a0b..aaeea0873 100644 --- a/content/Configuring/Dwindle-Layout.md +++ b/content/Configuring/Dwindle-Layout.md @@ -46,7 +46,7 @@ category name: `dwindle` | `split_width_multiplier` | Specifies the auto-split width multiplier.
Multiplying window size is useful on widescreen monitors where window W > H even after several splits. | float | `1.0` | | `use_active_for_splits` | Whether to prefer the active window or the cursor position for splits. | bool | `true` | | `default_split_ratio` | The default split ratio on window open.
`1.0` means an even 50/50 split. | float [`0.1 .. 1.9`] | `1.0` | -| `split_bias` | Specifies which window will receive the larger half of a split.
`0` -> positional: the new window is larger only if it opens to the `top` or `left` of the parent.
`1` -> always the current window.
`2` -> always the new window. | int [`0\|1\|2`] | `0` | +| `split_bias` | Specifies which window will receive the larger half of a split.
`0` -> directional: the new window is larger only if it opens to the `top` or `left` of the parent.
`1` -> always the current window.
`2` -> always the new window. | int [`0\|1\|2`] | `0` | | `precise_mouse_move` | `bindm movewindow` will drop the window more precisely depending your cursor's position. | bool | `false` | | `single_window_aspect_ratio` | Whenever only a single window is shown on a screen, add padding so that it conforms to the specified aspect ratio.
A value like `4 3` on a 16:9 screen will make it a 4:3 window in the middle with padding to the sides. | Vec2D | `0 0` | | `single_window_aspect_ratio_tolerance` | Sets a tolerance for `single_window_aspect_ratio` so that if the padding to be added is smaller than the specified fraction of the height or width of the screen, it will not attempt to adjust the window size. | float [`0.0 .. 1.0`] | `0.1` | From 4cfce4a175315b5bb43e0f2f5c42dfe3350d8dbe Mon Sep 17 00:00:00 2001 From: Bugg4 Date: Sun, 17 Aug 2025 22:19:38 +0200 Subject: [PATCH 6/6] Update `split_bias` Incorporate changes from #1202 to avoid merge conflicts --- content/Configuring/Dwindle-Layout.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/Configuring/Dwindle-Layout.md b/content/Configuring/Dwindle-Layout.md index aaeea0873..ceac923e7 100644 --- a/content/Configuring/Dwindle-Layout.md +++ b/content/Configuring/Dwindle-Layout.md @@ -46,7 +46,7 @@ category name: `dwindle` | `split_width_multiplier` | Specifies the auto-split width multiplier.
Multiplying window size is useful on widescreen monitors where window W > H even after several splits. | float | `1.0` | | `use_active_for_splits` | Whether to prefer the active window or the cursor position for splits. | bool | `true` | | `default_split_ratio` | The default split ratio on window open.
`1.0` means an even 50/50 split. | float [`0.1 .. 1.9`] | `1.0` | -| `split_bias` | Specifies which window will receive the larger half of a split.
`0` -> directional: the new window is larger only if it opens to the `top` or `left` of the parent.
`1` -> always the current window.
`2` -> always the new window. | int [`0\|1\|2`] | `0` | +| `split_bias` | Specifies which window will receive the split ratio.
`0` -> directional (the top or left window)
`1` -> the current window | int [`0\|1`] | `0` | | `precise_mouse_move` | `bindm movewindow` will drop the window more precisely depending your cursor's position. | bool | `false` | | `single_window_aspect_ratio` | Whenever only a single window is shown on a screen, add padding so that it conforms to the specified aspect ratio.
A value like `4 3` on a 16:9 screen will make it a 4:3 window in the middle with padding to the sides. | Vec2D | `0 0` | | `single_window_aspect_ratio_tolerance` | Sets a tolerance for `single_window_aspect_ratio` so that if the padding to be added is smaller than the specified fraction of the height or width of the screen, it will not attempt to adjust the window size. | float [`0.0 .. 1.0`] | `0.1` |