Stack

Stack(**config)

Bases: Layout

A layout composed of stacks of windows.

The stack layout divides the screen_rect horizontally into a set of stacks. Commands allow you to switch between stacks, to next and previous windows within a stack, and to split a stack to show all windows in the stack, or unsplit it to show only the current window.

Unlike the columns layout the number of stacks is fixed.

Methods:

• add –

  Add another stack to the layout.

• add_client –

  Called whenever a window is added to the group.

• add_defaults –

  Add defaults to this object, overwriting any which already exist.

• blur –

  Called whenever focus is gone from this layout.

• client_to_next –

  Send the current client to the next stack.

• client_to_previous –

  Send the current client to the previous stack.

• client_to_stack –

  Send the current client to stack n, where n is an integer offset. If

• clone –

  Duplicate a layout.

• command –

  Return the command with the given name.

• commands –

  Returns a list of possible commands for this object.

• configure –

  Configure the layout.

• delete –

  Delete the current stack from the layout.

• doc –

  Returns the documentation for a specified command name.

• down –

  Switch to the next window in this stack.

• eval –

  Evaluates code in the same context as this function.

• focus –

  Called whenever the focus changes.

• focus_first –

  Called when the first client in Layout shall be focused.

• focus_last –

  Called when the last client in Layout shall be focused.

• focus_next –

  Called when the next client in Layout shall be focused.

• focus_previous –

  Called when the previous client in Layout shall be focused.

• function –

  Call a function with current object as argument.

• hide –

  Called when layout is being hidden.

• info –

  Returns a dictionary of layout information.

• items –

  Build a list of contained items for the given item class.

• next –

  Focus next stack.

• previous –

  Focus previous stack.

• remove –

  Called whenever a window is removed from the group.

• rotate –

  Rotate order of the stacks.

• select –

  Return a selected object.

• show –

  Called when layout is being shown.

• shuffle_down –

  Shuffle the order of this stack down.

• shuffle_up –

  Shuffle the order of this stack up.

• swap –

  Swap the two given clients c1 and c2.

• toggle_split –

  Toggle vertical split on the current stack.

• up –

  Switch to the previous window in this stack.

Attributes:

• group (_Group) –

  Returns the group this layout is attached to.

group property

group: _Group

Returns the group this layout is attached to.

Layouts start out unattached, and are attached when the group is configured and each layout is cloned for every group.

add

add()

Add another stack to the layout.

add_client

add_client(client: Window) -> None

Called whenever a window is added to the group.

Called whether the layout is current or not. The layout should just add the window to its internal datastructures, without mapping or configuring.

add_defaults

add_defaults(defaults)

Add defaults to this object, overwriting any which already exist.

blur

blur() -> None

Called whenever focus is gone from this layout.

client_to_next

client_to_next()

Send the current client to the next stack.

client_to_previous

client_to_previous()

Send the current client to the previous stack.

client_to_stack

client_to_stack(n)

Send the current client to stack n, where n is an integer offset. If is too large or less than 0, it is wrapped modulo the number of stacks.

clone

clone(group: _Group) -> Self

Duplicate a layout.

Make a copy of this layout. This is done to provide each group with a unique instance of every layout.

Parameters:

• group (_Group) –

  Group to attach new layout instance to.

command

command(name: str) -> Callable | None

Return the command with the given name.

Parameters:

• name (str) –

  The name of the command to fetch.

commands

commands() -> list[str]

Returns a list of possible commands for this object.

Used by qsh for command completion and online help

configure

configure(client: Window, screen_rect: ScreenRect) -> None

Configure the layout.

This method should:

• Configure the dimensions and borders of a window using the .place() method.
• Call either .hide() or .unhide() on the window.

delete

delete()

Delete the current stack from the layout.

doc

doc(name) -> str

Returns the documentation for a specified command name.

Used by qsh to provide online help.

down

down()

Switch to the next window in this stack.

eval

eval(code: str) -> tuple[bool, str | None]

Evaluates code in the same context as this function.

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

focus

focus(client: Window) -> None

Called whenever the focus changes.

focus_first

focus_first() -> Window | None

Called when the first client in Layout shall be focused.

This method should:

• Return the first client in Layout, if any.
• Not focus the client itself, this is done by caller.

focus_last

focus_last() -> Window | None

Called when the last client in Layout shall be focused.

This method should:

• Return the last client in Layout, if any.
• Not focus the client itself, this is done by caller.

focus_next

focus_next(client: Window) -> Window | None

Called when the next client in Layout shall be focused.

This method should:

• Return the next client in Layout, if any.
• Return None if the next client would be the first client.
• Not focus the client itself, this is done by caller.

Do not implement a full cycle here, because the Groups cycling relies on returning None here if the end of Layout is hit, such that Floating clients are included in cycle.

Parameters:

• win (Window) –

  The currently focused client.

focus_previous

focus_previous(client: Window) -> Window | None

Called when the previous client in Layout shall be focused.

This method should:

• Return the previous client in Layout, if any.
• Return None if the previous client would be the last client.
• Not focus the client itself, this is done by caller.

Do not implement a full cycle here, because the Groups cycling relies on returning None here if the end of Layout is hit, such that Floating clients are included in cycle.

Parameters:

• win (Window) –

  The currently focused client.

function

function(function, *args, **kwargs) -> None

Call a function with current object as argument.

hide

hide() -> None

Called when layout is being hidden.

info

info() -> dict[str, Any]

Returns a dictionary of layout information.

items

items(name: str) -> tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows qsh to navigate the command graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a "naked" specification without an
item seletion (e.g. "layout" defaults to current layout), and False
if it does not (e.g. no default "widget").

items: a list of contained items

next

next() -> None

Focus next stack.

previous

previous() -> None

Focus previous stack.

remove

remove(client: Window) -> Window | None

Called whenever a window is removed from the group.

Called whether the layout is current or not. The layout should just de-register the window from its data structures, without unmapping the window.

Returns the "next" window that should gain focus or None.

rotate

rotate()

Rotate order of the stacks.

select

select(selectors: list[SelectorType]) -> CommandObject

Return a selected object.

Recursively finds an object specified by a list of (name, selector) items.

Raises SelectError if the object does not exist.

show

show(screen_rect: ScreenRect) -> None

Called when layout is being shown.

shuffle_down

shuffle_down()

Shuffle the order of this stack down.

shuffle_up

shuffle_up()

Shuffle the order of this stack up.

swap

swap(c1: Window, c2: Window) -> None

Swap the two given clients c1 and c2.

toggle_split

toggle_split()

Toggle vertical split on the current stack.

up

up()

Switch to the previous window in this stack.