diff --git a/README.md b/README.md index 57adcf9..2d37636 100644 --- a/README.md +++ b/README.md @@ -214,7 +214,7 @@ Click on the image to open a full-size web view. |`window.border_color` | #6d531f | Color of the border around windows | |`window.active.border_color` | #d79921 | Color of the border around an active window | |`window.normalize_on_remove` | True | Whether or not to normalize the remaining windows after a window is removed.
If `True`, the remaining sibling windows will all become of equal size.
If `False`, the next (right/down) window will take up the free space. | -|`window.default_add_mode` | tab | (Experimental) Determines how windows get added if they are not explicitly
spawned as a split or a tab.
Can be one of "tab" or "match_previous".
If "match_previous", then then new window will get added in the same way the
previous window was. eg. if the previous window was added as a y-split, so will
the new window.

NOTE:
Setting this to "tab" may seem convenient, since externally spawned GUI apps get
added as background tabs instead of messing up the current split layout.
But due to how the window creation flow happens, when many splits are requested
in quick succession, this may cause some windows requested as a split to open up
as a tab instead. | +|`window.default_add_mode` | tab | (Experimental)

Determines how windows get added if they are not explicitly spawned as a split
or a tab.
Can be one of "tab" or "match_previous".
If "match_previous", then then new window will get added in the same way the
previous window was. eg. if the previous window was added as a y-split, so will
the new window.

NOTE:
Setting this to "tab" may seem convenient, since externally spawned GUI apps get
added as background tabs instead of messing up the current split layout.
But due to how the window creation flow happens, when many splits are requested
in quick succession, this may cause some windows requested as a split to open up
as a tab instead. | |`tab_bar.height` | 20 | Height of tab bars | |`tab_bar.hide_when` | single_tab | When to hide the tab bar. Allowed values are 'never', 'always', 'single_tab'.

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. | |`tab_bar.margin` | 0 | Size of the margin space around tab bars.

Can be an int or a list of ints in [top, right, bottom, left] ordering. | @@ -230,7 +230,7 @@ Click on the image to open a full-size web view. |`tab_bar.tab.font_size` | 15 | Font size to use for tab titles | |`tab_bar.tab.active.bg_color` | #7c6f64 | Background color of active tabs | |`tab_bar.tab.active.fg_color` | #ebdbb2 | Foreground text color of the active tab | -|`auto_cwd_for_terminals` | True | (Experimental) 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. | +|`auto_cwd_for_terminals` | True | (Experimental)

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. | |`restore.threshold_seconds` | 4 | You likely don't need to tweak this.
Controls the time within which a persisted state file is considered to be from a
recent qtile config-reload/restart event. If the persisted file is this many
seconds old, we restore our window tree from it. | @@ -239,25 +239,25 @@ Click on the image to open a full-size web view. | 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 top/bottom windows.
        A `y` split will end up with two left/right 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 y-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.

Args:
    `wrap`:
        If `True`, will wrap around the edge and select windows from the other end of the screen.
        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 top/bottom windows.
        A `y` split will end up with two left/right 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 y-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.

Args:
    `wrap`:
        If `True`, will wrap around the edge and select windows 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`. | +|`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. | -|`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_mo="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 SplitContainer, make all windows in the container of equal size.

Args:
    `recurse`:
        If `True`, then nested nodes are also normalized similarly. | +|`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 SplitContainer, 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.

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. | diff --git a/scripts/generate_readme.py b/scripts/generate_readme.py index ec7fdcd..707d481 100755 --- a/scripts/generate_readme.py +++ b/scripts/generate_readme.py @@ -72,7 +72,7 @@ def is_exposed_command(node): { "name": node.name, "docstring": rewrap( - docstring, width=100, dedent=True, html_whitespace=True + docstring, width=85, dedent=True, html_whitespace=True ), } )