diff --git a/README.md b/README.md
index 593cfe6..ebbdcf5 100644
--- a/README.md
+++ b/README.md
@@ -339,30 +339,30 @@ Click on the image to open a web view with the full guide.
| Command Name | Description |
| --- | --- |
-|`spawn_split` | Launch the provided `program` into a new window that splits the currently
focused window along the specified `axis`.
Args:
`program`:
The program to launch.
`axis`:
The axis along which to split the currently focused window. Can be
'x' or 'y'.
An `x` split will end up with two left/right windows.
A `y` split will end up with two top/bottom windows.
`ratio`:
The ratio of sizes by which to split the current window.
If a window has a width of 100, then splitting on the x-axis with a
ratio = 0.3 will result in a left window of width 30 and a right
window of width 70.
Defaults to 0.5.
`normalize`:
If `True`, overrides `ratio` and leads to the new window and all
sibling windows becoming of equal size along the corresponding
split axis.
Defaults to `True`.
`position`:
Whether the new split content appears after or before the currently
focused window.
Can be `"next"` or `"previous"`. Defaults to `"next"`.
Examples:
- `layout.spawn_split(my_terminal, "x")`
- `layout.spawn_split(my_terminal, "y", ratio=0.2, normalize=False)`
- `layout.spawn_split(my_terminal, "x", position="previous")` |
-|`spawn_tab` | Launch the provided `program` into a new window as a new tab.
Args:
`program`:
The program to launch.
`new_level`:
If `True`, create a new sub-tab level with 2 tabs. The first sub-
tab being the currently focused window, the second sub-tab being
the newly launched program.
`level`:
If provided, launch the new window as a tab at the provided `level`
of tabs in the currently focused window's tab hierarchy.
Level 1 is the topmost level.
Examples:
- `layout.spawn_tab(my_terminal)`
- `layout.spawn_tab(my_terminal, new_level=True)`
- `layout.spawn_tab("qutebrowser", level=1)` |
-|`move_focus` | Move focus to the window in the specified direction relative to the
currently focused window. If there are multiple candidates, the most
recently focused of them will be chosen.
When `container_select_mode` is active, will similarly pick neighboring
nodes, which may consist of multiple windows under it.
Args:
`direction`:
The direction in which a neighbor is found to move focus to. Can be
"up"/"down"/"left"/"right".
`wrap`:
If `True`, will wrap around the edge and select items from the
other end of the screen. Defaults to `True`. |
-|`left` | Same as `move_focus("left")`. For compatibility with API of other built-in
layouts. |
-|`right` | Same as `move_focus("right")`. For compatibility with API of other built-in
layouts. |
-|`up` | Same as `move_focus("up")`. For compatibility with API of other built-in
layouts. |
-|`down` | Same as `move_focus("down")`. For compatibility with API of other built-in
layouts. |
-|`next_tab` | Switch focus to the next tab. The window that was previously active there
will be focused.
Args:
`wrap`:
If `True`, will cycle back to the fist tab if invoked on the last
tab.
Defaults to `True`. |
+|`spawn_split` | Launch the provided `program` into a new window that splits the
currently focused window along the specified `axis`.
Args:
`program`:
The program to launch.
`axis`:
The axis along which to split the currently focused window. Can
be 'x' or 'y'.
An `x` split will end up with two left/right windows.
A `y` split will end up with two top/bottom windows.
`ratio`:
The ratio of sizes by which to split the current window.
If a window has a width of 100, then splitting on the x-axis
with a ratio = 0.3 will result in a left window of width 30 and
a right window of width 70.
Defaults to 0.5.
`normalize`:
If `True`, overrides `ratio` and leads to the new window and
all sibling windows becoming of equal size along the
corresponding split axis.
Defaults to `True`.
`position`:
Whether the new split content appears after or before the
currently focused window.
Can be `"next"` or `"previous"`. Defaults to `"next"`.
Examples:
- `layout.spawn_split(my_terminal, "x")`
- `layout.spawn_split(my_terminal, "y", ratio=0.2,
normalize=False)`
- `layout.spawn_split(my_terminal, "x", position="previous")` |
+|`spawn_tab` | Launch the provided `program` into a new window as a new tab.
Args:
`program`:
The program to launch.
`new_level`:
If `True`, create a new sub-tab level with 2 tabs. The first
sub-tab being the currently focused window, the second sub-tab
being the newly launched program.
`level`:
If provided, launch the new window as a tab at the provided
`level` of tabs in the currently focused window's tab
hierarchy.
Level 1 is the topmost level.
Examples:
- `layout.spawn_tab(my_terminal)`
- `layout.spawn_tab(my_terminal, new_level=True)`
- `layout.spawn_tab("qutebrowser", level=1)` |
+|`move_focus` | Move focus to the window in the specified direction relative to the
currently focused window. If there are multiple candidates, the most
recently focused of them will be chosen.
When `container_select_mode` is active, will similarly pick neighboring
nodes, which may consist of multiple windows under it.
Args:
`direction`:
The direction in which a neighbor is found to move focus to.
Can be "up"/"down"/"left"/"right".
`wrap`:
If `True`, will wrap around the edge and select items from the
other end of the screen. Defaults to `True`. |
+|`left` | Same as `move_focus("left")`. For compatibility with API of other
built-in layouts. |
+|`right` | Same as `move_focus("right")`. For compatibility with API of other
built-in layouts. |
+|`up` | Same as `move_focus("up")`. For compatibility with API of other built-
in layouts. |
+|`down` | Same as `move_focus("down")`. For compatibility with API of other
built-in layouts. |
+|`next_tab` | Switch focus to the next tab. The window that was previously active
there will be focused.
Args:
`wrap`:
If `True`, will cycle back to the fist tab if invoked on the
last tab.
Defaults to `True`. |
|`prev_tab` | Same as `next_tab()` but switches focus to the previous tab. |
-|`focus_nth_tab` | Switches focus to the nth tab at the specified tab `level`.
Args:
`n`:
The 1-based index of the tab that should be focused.
`level`:
When there are subtab levels at play, specifies which
`TabContainer's`
tabs among the hierarchy of active `TabContainers` is being acted
upon.
Tab levels are 1-based.
`level=1` indicates outermost/top-level tabs.
`level=-1` (default) indicates the innermost/nearest tabs.
Examples:
- `layout.focus_nth_tab(2) # Pick the 2nd top-level tab`
- `layout.focus_nth_tab(3, level=-1)` # Pick 3rd from nearest tabs |
-|`focus_nth_window` | Switches focus to the nth window.
Counting is always done based on the geospatial position of windows - ie.
starting from the leftmost+innermost window (ie. we traverse leaves of the
tree, left to right).
Args:
`n`:
The 1-based index of the window in the list of all candidate
windows.
`ignore_inactive_tabs_at_levels`:
For the specified list of tab levels, only consider windows under
the active tab at that level, ignoring windows under
inactive/background tabs.
eg. `[1]` means we should start counting `n` from the first window
in the currently active level 1 (top-level) tab, ignoring windows
under inactive tabs. But if there are any subtabs under this active
tabs, we DO consider the inactive windows under background/inactive
subtabs.
eg. `[1,2]` means we start counting `n` from the first window of
the active top-level tab, and if there are any level 2 subtabs
under the active tab, we pick windows only from the active level 2
tab as well, ignoring inactive subtabs.
eg. `[]` or `None` (default) means consider every single window -
even if it's inactive under a background tab.
eg. `[2]` means we start counting from the very first window at the
top level, even if it is inactive under a background tab. But
whenever there are level 2 subtabs to consider, we only count its
windows that are under the active level 2 subtab.
Examples:
- `layout.focus_nth_window(1)`
- `layout.focus_nth_window(3, ignore_inactive_tabs_at_levels=[1])`
- layout.focus_nth_window(2, ignore_inactive_tabs_at_levels=[1, 2]) |
-|`resize` | Resizes by moving an appropriate border leftwards. Usually this is the
right/bottom border, but for the 'last' node under a SplitContainer, it
will be the left/top border.
Basically the way tmux does resizing.
If there are multiple nested windows under the area being resized, those
windows are resized proportionally.
Args:
`amount`:
The amount by which to resize.
Examples:
- `layout.resize("left", 100)`
- `layout.resize("right", 100)` |
-|`swap` | Swaps the currently focused window with the nearest window in the specified
direction. If there are multiple candidates to pick from, then the most
recently focused one is chosen.
Args:
`wrap`:
If `True`, will wrap around the edge and select windows from the
other end of the screen to swap.
Defaults to `False`. |
-|`swap_tabs` | Swaps the currently active tab with the previous tab.
Args:
`wrap`:
If `True`, will wrap around the edge of the tab bar and swap with
the last tab.
Defaults to `True`. |
-|`rename_tab` | Rename the currently active tab.
Args:
`widget`:
The qtile widget that should be used for obtaining user input for
the renaming. The 'prompt' widget is used by default. |
-|`merge_tabs` | Merge the currently active tab with another tab, such that both tabs'
contents now appear in 2 splits.
Args:
`direction`:
Which neighbor tab to merge with. Can be either "next" or
"previous".
`axis`:
The axis along which the merged content should appear as splits.
Examples:
- `layout.merge_tabs("previous")`
- `layout.merge_tabs("next", "y")` |
-|`merge_to_subtab` | Merge the currently focused window (or an ancestor node) with a neighboring
node in the specified `direction`, so that they both come under a (possibly
new)
subtab.
Args:
`direction`:
The direction in which to find a neighbor to merge with.
`src_selection`:
Determines how the source window/node should be resolved. ie. do we
pick just the current window, or all windows under an appropriate
ancestor container.
Valid values are defined in `NodeHierarchySelectionMode`. See
below.
`dest_selection`:
Determines how the neighboring node should be resolved, similar to
how `src_selection` is resolved.
Valid values are defined in `NodeHierarchySelectionMode`. See
below.
`normalize`:
If `True`, any removals during the merge process will ensure all
sibling nodes are resized to be of equal dimensions.
Valid values for `NodeHierarchySelectionMode` are:
`"mru_deepest"`:
Pick a single innermost window. If there are multiple such
neighboring windows, pick the most recently used (MRU) one.
`"mru_subtab_else_deepest"` (default):
If the target is under a subtab, pick the subtab. If there is no
subtab in play, behaves like `mru_deepest`.
`"mru_largest"`
Given a window, pick the largest ancestor node that the window's
border is a fragment of. This resolves to a SplitContainer or a
TabContainer.
`"mru_subtab_else_largest"`
If the target is under a subtab, pick the subtab. If there is no
subtab in play, behaves like `mru_largest`.
Examples:
- layout.merge_to_subtab( "right",
dest_selection="mru_subtab_else_deepest", )
- layout.merge_to_subtab( "up", src_selection="mru_deepest",
dest_selection="mru_deepest", ) |
-|`push_in` | Move the currently focused window (or a related node in its hierarchy) into
a neighboring window's container.
Args:
`direction`:
The direction in which to find a neighbor whose container we push
into.
`src_selection`:
(See docs in `merge_to_subtab()`)
`dest_selection`:
(See docs in `merge_to_subtab()`)
`normalize`:
If `True`, any removals during the process will ensure all sibling
nodes are resized to be of equal dimensions.
`wrap`:
If `True`, will wrap around the edge of the screen and push into
the container on the other end.
Examples:
- `layout.push_in("right", dest_selection="mru_deepest")`
- `layout.push_in("down", dest_selection="mru_largest", wrap=False)` |
-|`pull_out` | Move the currently focused window out from its SplitContainer into an
ancestor SplitContainer at a higher level. It effectively moves a window
'outwards'.
Args:
`position`:
Whether the pulled out node appears before or after its original
container node.
Can be `"next"` or `"previous"`. Defaults to `"previous"`.
`src_selection`:
Can either be `"mru_deepest"` (default) or
`"mru_subtab_else_deepest"`.
(See docs in `merge_to_subtab()`)
`normalize`:
If `True`, all sibling nodes involved in the rearrangement are
resized to be of equal dimensions.
Examples:
- `layout.pull_out()`
- `layout.pull_out(src_selection="mru_subtab_else_deepest")`
- `layout.pull_out(position="next")` |
-|`pull_out_to_tab` | Extract the currently focused window into a new tab at the nearest
TabContainer.
Args:
`normalize`:
If `True`, any removals during the process will ensure all sibling
nodes are resized to be of equal dimensions. |
+|`focus_nth_tab` | Switches focus to the nth tab at the specified tab `level`.
Args:
`n`:
The 1-based index of the tab that should be focused.
`level`:
When there are subtab levels at play, specifies which
`TabContainer's`
tabs among the hierarchy of active `TabContainers` is being
acted upon.
Tab levels are 1-based.
`level=1` indicates outermost/top-level tabs.
`level=-1` (default) indicates the innermost/nearest tabs.
Examples:
- `layout.focus_nth_tab(2) # 2nd top-level tab`
- `layout.focus_nth_tab(3, level=-1) # 3rd from nearest tabs` |
+|`focus_nth_window` | Switches focus to the nth window.
Counting is always done based on the geospatial position of windows -
ie.
starting from the leftmost+innermost window (ie. we traverse leaves of
the tree, left to right).
Args:
`n`:
The 1-based index of the window in the list of all candidate
windows.
`ignore_inactive_tabs_at_levels`:
For the specified list of tab levels, only consider windows
under the active tab at that level, ignoring windows under
inactive/background tabs.
eg. `[1]` means we should start counting `n` from the first
window in the currently active level 1 (top-level) tab,
ignoring windows under inactive tabs. But if there are any
subtabs under this active tabs, we DO consider the inactive
windows under background/inactive subtabs.
eg. `[1,2]` means we start counting `n` from the first window
of the active top-level tab, and if there are any level 2
subtabs under the active tab, we pick windows only from the
active level 2 tab as well, ignoring inactive subtabs.
eg. `[]` or `None` (default) means consider every single window
- even if it's inactive under a background tab.
eg. `[2]` means we start counting from the very first window at
the top level, even if it is inactive under a background tab.
But whenever there are level 2 subtabs to consider, we only
count its windows that are under the active level 2 subtab.
Examples:
- `layout.focus_nth_window(1)`
- layout.focus_nth_window(3,
ignore_inactive_tabs_at_levels=[1])
- layout.focus_nth_window(2, ignore_inactive_tabs_at_levels=[1,
2]) |
+|`resize` | Resizes by moving an appropriate border leftwards. Usually this is the
right/bottom border, but for the 'last' node under a SplitContainer, it
will be the left/top border.
Basically the way tmux does resizing.
If there are multiple nested windows under the area being resized,
those windows are resized proportionally.
Args:
`amount`:
The amount by which to resize.
Examples:
- `layout.resize("left", 100)`
- `layout.resize("right", 100)` |
+|`swap` | Swaps the currently focused window with the nearest window in the
specified direction. If there are multiple candidates to pick from,
then the most recently focused one is chosen.
Args:
`wrap`:
If `True`, will wrap around the edge and select windows from
the other end of the screen to swap.
Defaults to `False`. |
+|`swap_tabs` | Swaps the currently active tab with the previous tab.
Args:
`wrap`:
If `True`, will wrap around the edge of the tab bar and swap
with the last tab.
Defaults to `True`. |
+|`rename_tab` | Rename the currently active tab.
Args:
`widget`:
The qtile widget that should be used for obtaining user input
for the renaming. The 'prompt' widget is used by default. |
+|`merge_tabs` | Merge the currently active tab with another tab, such that both tabs'
contents now appear in 2 splits.
Args:
`direction`:
Which neighbor tab to merge with. Can be either "next" or
"previous".
`axis`:
The axis along which the merged content should appear as
splits.
Examples:
- `layout.merge_tabs("previous")`
- `layout.merge_tabs("next", "y")` |
+|`merge_to_subtab` | Merge the currently focused window (or an ancestor node) with a
neighboring node in the specified `direction`, so that they both come
under a (possibly new) subtab.
Args:
`direction`:
The direction in which to find a neighbor to merge with.
`src_selection`:
Determines how the source window/node should be resolved. ie.
do we pick just the current window, or all windows under an
appropriate ancestor container.
Valid values are defined in `NodeHierarchySelectionMode`. See
below.
`dest_selection`:
Determines how the neighboring node should be resolved, similar
to how `src_selection` is resolved.
Valid values are defined in `NodeHierarchySelectionMode`. See
below.
`normalize`:
If `True`, any removals during the merge process will ensure
all sibling nodes are resized to be of equal dimensions.
Valid values for `NodeHierarchySelectionMode` are:
`"mru_deepest"`:
Pick a single innermost window. If there are multiple such
neighboring windows, pick the most recently used (MRU) one.
`"mru_subtab_else_deepest"` (default):
If the target is under a subtab, pick the subtab. If there is
no subtab in play, behaves like `mru_deepest`.
`"mru_largest"`
Given a window, pick the largest ancestor node that the
window's border is a fragment of. This resolves to a
SplitContainer or a TabContainer.
`"mru_subtab_else_largest"`
If the target is under a subtab, pick the subtab. If there is
no subtab in play, behaves like `mru_largest`.
Examples:
- layout.merge_to_subtab( "right",
dest_selection="mru_subtab_else_deepest", )
- layout.merge_to_subtab( "up", src_selection="mru_deepest",
dest_selection="mru_deepest", ) |
+|`push_in` | Move the currently focused window (or a related node in its hierarchy)
into a neighboring window's container.
Args:
`direction`:
The direction in which to find a neighbor whose container we
push into.
`src_selection`:
(See docs in `merge_to_subtab()`)
`dest_selection`:
(See docs in `merge_to_subtab()`)
`normalize`:
If `True`, any removals during the process will ensure all
sibling nodes are resized to be of equal dimensions.
`wrap`:
If `True`, will wrap around the edge of the screen and push
into the container on the other end.
Examples:
- `layout.push_in("right", dest_selection="mru_deepest")`
- `layout.push_in("down", dest_selection="mru_largest",
wrap=False)` |
+|`pull_out` | Move the currently focused window out from its SplitContainer into an
ancestor SplitContainer at a higher level. It effectively moves a
window 'outwards'.
Args:
`position`:
Whether the pulled out node appears before or after its
original container node.
Can be `"next"` or `"previous"`. Defaults to `"previous"`.
`src_selection`:
Can either be `"mru_deepest"` (default) or
`"mru_subtab_else_deepest"`.
(See docs in `merge_to_subtab()`)
`normalize`:
If `True`, all sibling nodes involved in the rearrangement are
resized to be of equal dimensions.
Examples:
- `layout.pull_out()`
- `layout.pull_out(src_selection="mru_subtab_else_deepest")`
- `layout.pull_out(position="next")` |
+|`pull_out_to_tab` | Extract the currently focused window into a new tab at the nearest
TabContainer.
Args:
`normalize`:
If `True`, any removals during the process will ensure all
sibling nodes are resized to be of equal dimensions. |
|`normalize` | Starting from the focused window's container, make all windows in the
container of equal size.
Args:
`recurse`:
If `True`, then nested nodes are also normalized similarly. |
|`normalize_tab` | Starting from the focused window's tab, make all windows in the tab of
equal size under their respective containers.
Args:
`recurse`:
If `True`, then nested nodes are also normalized similarly.
Defaults to `True`. |
|`normalize_all` | Make all windows under all tabs be of equal size under their respective
containers. |
-|`toggle_container_select_mode` | Enable container-select mode where we can select not just a window, but
even their container nodes.
This will activate a special border around the active selection. You can
move its focus around using the same bindings as for switching window
focus. You can also select upper/parent or lower/child nodes with the
`select_container_outer()` and `select_container_inner()` commands.
Handy for cases where you want to split over a collection of windows or
make a new subtab level over a collection of windows.
Aside from focus-switching motions, the only operations supported are
`spawn_split()` and `spawn_tab()`. Triggering other commands will simply
exit container-select mode. |
+|`toggle_container_select_mode` | Enable container-select mode where we can select not just a window, but
even their container nodes.
This will activate a special border around the active selection. You
can move its focus around using the same bindings as for switching
window focus. You can also select upper/parent or lower/child nodes
with the `select_container_outer()` and `select_container_inner()`
commands.
Handy for cases where you want to split over a collection of windows or
make a new subtab level over a collection of windows.
Aside from focus-switching motions, the only operations supported are
`spawn_split()` and `spawn_tab()`. Triggering other commands will
simply exit container-select mode. |
|`select_container_inner` | When in container-select mode, it will narrow the active selection by
selecting the first descendent node. |
|`select_container_outer` | When in container-select mode, it will expand the active selection by
selecting the next ancestor node. |
|`tree_repr` | Returns a YAML-like text representation of the internal tree hierarchy. |
diff --git a/scripts/generate_readme.py b/scripts/generate_readme.py
index 5f44578..ab92101 100755
--- a/scripts/generate_readme.py
+++ b/scripts/generate_readme.py
@@ -80,7 +80,7 @@ def is_exposed_command(node):
{
"name": node.name,
"docstring": rewrap(
- docstring, width=75, dedent=True, html_whitespace=True
+ docstring, width=71, dedent=True, html_whitespace=True
),
}
)
diff --git a/src/qtile_bonsai/layout.py b/src/qtile_bonsai/layout.py
index a593479..efb17c0 100644
--- a/src/qtile_bonsai/layout.py
+++ b/src/qtile_bonsai/layout.py
@@ -723,8 +723,8 @@ def focus_nth_tab(self, n: int, *, level: int = -1):
`level=-1` (default) indicates the innermost/nearest tabs.
Examples:
- - `layout.focus_nth_tab(2) # Pick the 2nd top-level tab`
- - `layout.focus_nth_tab(3, level=-1)` # Pick 3rd from nearest tabs
+ - `layout.focus_nth_tab(2) # 2nd top-level tab`
+ - `layout.focus_nth_tab(3, level=-1) # 3rd from nearest tabs`
"""
if self._tree.is_empty:
return
@@ -782,7 +782,7 @@ def focus_nth_window(
Examples:
- `layout.focus_nth_window(1)`
- - `layout.focus_nth_window(3, ignore_inactive_tabs_at_levels=[1])`
+ - layout.focus_nth_window(3, ignore_inactive_tabs_at_levels=[1])
- layout.focus_nth_window(2, ignore_inactive_tabs_at_levels=[1, 2])
"""
if n < 1:
@@ -948,8 +948,8 @@ def merge_to_subtab(
):
"""
Merge the currently focused window (or an ancestor node) with a neighboring
- node in the specified `direction`, so that they both come under a (possibly new)
- subtab.
+ node in the specified `direction`, so that they both come under a (possibly
+ new) subtab.
Args:
`direction`:
@@ -1183,8 +1183,8 @@ def normalize_all(self):
@expose_command
def toggle_container_select_mode(self):
"""
- Enable container-select mode where we can select not just a window, but even their
- container nodes.
+ Enable container-select mode where we can select not just a window, but even
+ their container nodes.
This will activate a special border around the active selection. You can move
its focus around using the same bindings as for switching window focus. You can