GitHub - aravinda0/qtile-bonsai: A flexible layout for the qtile tiling window manager that allows arbitrarily nestable tabs/splits and rearrangements

Determines how windows should be added
to the layout if they weren't explicitly
spawned from a tab/split command.

The following values are allowed:
    1. "tab" (default):
        Open as a top level tab.
        This is the default and may be
        convenient since externally
        spawned GUI apps would added as
        background tabs instead of
        messing up any active split
        layout.

    2. "split_x":
        Open as a top-level split, on
        the right end.

    3. "split_y":
        Open as a top-level split, on
        the bottom end.

    4. "match_previous":
        Remember how the previous window
        was opened (tab/split), and open
        the new window in the same way.

    5. (custom-function):
        A callback of the form
        (BonsaiTree) -> BonsaiPane.
        For advanced handling of
        implicitly-added windows. You
        are given the internal
        BonsaiTree object to
        manipulate however, and should
        return the Pane that should
        receive focus after the window
        is added.

        This callback could
        theoretically be used to drive
        more 'automatic' layouts. eg.
        one could re-implement all of
        the built-in qtile layouts with
        this. But you might as well
        subclass BonsaiLayout for
        elaborate customizations.

When 'single_tab' is configured, the bar
is not shown whenever there is a lone
tab remaining, but shows up again when
another tab is added.

For nested tab levels, configuring
'always' or 'single_tab' actually means
that when only a single tab remains, its
contents get 'merged' upwards,
eliminating the sub-tab level.

This is dynamic and essentially makes it
so the L1 tab bar shows up 'when
required'.
Handy in multi-screen setups if some
screens aren't configured to have a
qtile-bar, but the main screen does and
has a BonsaiBar widget as well.

Note that this takes precedence over
tab_bar.hide_when for L1 bars.

Can be an int or auto. If auto, the
tabs take up as much of the available
screen space as possible.

Note that this width follows the 'margin
box'/'principal box' model, so it
includes any configured margin amount.

For example, here's a callback that
returns the active window's title:
def my_title_provider(index,
active_pane, tab):
    return active_pane.window.name

If True, when spawning new windows by
specifying a program that happens to
be a well-known terminal emulator, will
try to open the new terminal window in
same working directory as the last
focused window.

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")

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)

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.

Args:
    level:
        When subtabs are involved, specifies at which (1-based) tab-
        level the tab-activation should take place.
        Defaults to -1, meaning the nearest tab.
    wrap:
        If True, will cycle back to the fist tab if invoked on the
        last tab.
        Defaults to True.

Examples:
    - layout.next_tab()<br>&nbsp;&nbsp;&nbsp;&nbsp;- layout.next_tab(level=1) # Explicitly activate the next top-most
    tab.

Args:
    n:
        The 1-based index of the tab that should be focused.
    level:
        When there are subtab levels at play, which level of tabs among
        the hierarchy should be 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(4) # 4th tab - layout.focus_nth_tab(2,
    level=1) # 2nd topmost-level tab<br>&nbsp;&nbsp;&nbsp;&nbsp;- layout.focus_nth_tab(3, level=-1) # 3rd of the 'nearest' tabs`

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])

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)

Args:
    wrap:
        If True, will wrap around the edge and select windows from
        the other end of the screen to swap.
        Defaults to False.

Args:
    level:
        When there are subtab levels at play, which level of tabs among
        the hierarchy should be acted upon. Tab levels are 1-based.
        level=1 indicates outermost/top-level tabs.
        level=-1 (default) indicates the innermost/nearest tabs.
    wrap:
        If True, will wrap around the edge of the tab bar and swap
        with the last tab.
        Defaults to True.

Args:
    widget:
        The qtile widget that should be used for obtaining user input
        for the renaming. The 'prompt' widget is used by default.

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")

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", )

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)

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")

Args:
    normalize:
        If True, any removals during the process will ensure all
        sibling nodes are resized to be of equal dimensions.

Args:
    recurse:
        If True, then nested nodes are also normalized similarly.

Args:
    recurse:
        If True, then nested nodes are also normalized similarly.
        Defaults to True.

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.

As usual, it can be a fixed integer, or
one of the 'special' bar constants:
bar.CALCULATED or bar.STRETCH.

Can be one of the following:
    - bonsai_with_focus:
        The Bonsai layout of the window
        that is currently focused. This
        is relevant in a multi-screen
        setup - the widget will keep
        updating based on which screen's
        Bonsai layout has focus.
    - bonsai_on_same_screen:
        The widget will stick to
        displaying the state of the
        Bonsai layout that is on the
        same screen as the widget's bar.

Can be an int or auto. If auto, the
tabs take up as much of the available
space on the bar as possible.

Note that if the length option is set
to bar.CALCULATED, then you cannot
provide auto here, as we would need
fixed tab width values to perform the
bar.CALCULATED computation.

Note that this width follows the 'margin
box'/'principal box' model, so it
includes any configured margin amount.