Plasma ¶

Plasma(**config)

Bases: Layout

A flexible tree-based layout.

Each tree node represents a container whose children are aligned either horizontally or vertically. Each window is attached to a leaf of the tree and takes either a calculated relative amount or a custom absolute amount of space in its parent container. Windows can be resized, rearranged and integrated into other containers.

Windows in a container will all open in the same direction. Calling lazy.layout.mode_vertical/horizontal() will insert a new container allowing windows to be added in the new direction.

Windows can be focused selectively by using lazy.layout.up/down/left/right() to focus the nearest window in that direction relative to the currently focused window.

"Integrating" windows is best explained with an illustation. Starting with three windows, a, b, c. b is currently focused. Calling lazy.layout.integrate_left() will have the following effect:

----------------------         ----------------------
| a    | b    | c    |         | a        | c       |
|      |      |      |         |          |         |
|      |      |      |  -->    |          |         |
|      |      |      |         |----------|         |
|      |      |      |         | b        |         |
|      |      |      |         |          |         |
|      |      |      |         |          |         |
----------------------         ----------------------

Finally, windows can me moved around the layout with lazy.layout.move_up/down/left/right().

Example keybindings:

from libqtile.config import EzKey
from libqtile.lazy import lazy

...

keymap = {
    'M-h': lazy.layout.left(),
    'M-j': lazy.layout.down(),
    'M-k': lazy.layout.up(),
    'M-l': lazy.layout.right(),
    'M-S-h': lazy.layout.move_left(),
    'M-S-j': lazy.layout.move_down(),
    'M-S-k': lazy.layout.move_up(),
    'M-S-l': lazy.layout.move_right(),
    'M-A-h': lazy.layout.integrate_left(),
    'M-A-j': lazy.layout.integrate_down(),
    'M-A-k': lazy.layout.integrate_up(),
    'M-A-l': lazy.layout.integrate_right(),
    'M-d': lazy.layout.mode_horizontal(),
    'M-v': lazy.layout.mode_vertical(),
    'M-S-d': lazy.layout.mode_horizontal_split(),
    'M-S-v': lazy.layout.mode_vertical_split(),
    'M-a': lazy.layout.grow_width(30),
    'M-x': lazy.layout.grow_width(-30),
    'M-S-a': lazy.layout.grow_height(30),
    'M-S-x': lazy.layout.grow_height(-30),
    'M-C-5': lazy.layout.size(500),
    'M-C-8': lazy.layout.size(800),
    'M-n': lazy.layout.reset_size(),
}

keys = [EzKey(k, v) for k, v in keymap.items()]

Acknowledgements: This layout was developed by numirias and published at https://github.com/numirias/qtile-plasma. A few minor amendments have been made to that layout as part of incorporating this into the main qtile codebase but the majority of the work is theirs.

Methods:

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.
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.
doc –

Returns the documentation for a specified command name.
down –

Focus window below.
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.
grow –

Grow size of current window.
grow_height –

Grow height of current window.
grow_width –

Grow width of current window.
hide –

Called when layout is being hidden.
info –

Returns a dictionary of layout information.
integrate_down –

Integrate current window down.
integrate_left –

Integrate current window left.
integrate_right –

Integrate current window right.
integrate_up –

Integrate current window up.
items –

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

Focus window to the left.
mode_horizontal –

Next window will be added horizontally.
mode_horizontal_split –

Next window will be added horizontally, splitting space of current
mode_vertical –

Next window will be added vertically.
mode_vertical_split –

Next window will be added vertically, splitting space of current
move_down –

Move current window down.
move_left –

Move current window left.
move_right –

Move current window right.
move_up –

Move current window up.
next –

Focus next window.
previous –

Focus previous window.
recent –

Focus most recently focused window.
remove –

Called whenever a window is removed from the group.
reset_size –

Reset size of current window to automatic (relative) sizing.
right –

Focus window to the right.
select –

Return a selected object.
set_height –

Set height of current window.
set_size –

Change size of current window.
set_width –

Set width of current window.
show –

Called when layout is being shown.
swap –

Swap the two given clients c1 and c2.
up –

Focus window above.

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_client ¶

add_client(client)

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.

clone ¶

clone(group)

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

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.

doc ¶

doc(name) -> str

Returns the documentation for a specified command name.

Used by qsh to provide online help.

down ¶

down()

Focus window below.

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)

Called whenever the focus changes.

focus_first ¶

focus_first()

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

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(win)

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(win)

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.

grow ¶

grow(x)

Grow size of current window.

(It's recommended to use grow_width()/grow_height() instead.)

grow_height ¶

grow_height(x)

Grow height of current window.

grow_width ¶

grow_width(x)

Grow width of current window.

hide ¶

hide() -> None

Called when layout is being hidden.

info ¶

info()

Returns a dictionary of layout information.

integrate_down ¶

integrate_down()

Integrate current window down.

integrate_left ¶

integrate_left()

Integrate current window left.

integrate_right ¶

integrate_right()

Integrate current window right.

integrate_up ¶

integrate_up()

Integrate current window up.

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

left ¶

left()

Focus window to the left.

mode_horizontal ¶

mode_horizontal()

Next window will be added horizontally.

mode_horizontal_split ¶

mode_horizontal_split()

Next window will be added horizontally, splitting space of current window.

mode_vertical ¶

mode_vertical()

Next window will be added vertically.

mode_vertical_split ¶

mode_vertical_split()

Next window will be added vertically, splitting space of current window.

move_down ¶

move_down()

Move current window down.

move_left ¶

move_left()

Move current window left.

move_right ¶

move_right()

Move current window right.

move_up ¶

move_up()

Move current window up.

next ¶

next()

Focus next window.

previous ¶

previous()

Focus previous window.

recent ¶

recent()

Focus most recently focused window.

(Toggles between the two latest active windows.)

remove ¶

remove(client)

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.

reset_size ¶

reset_size()

Reset size of current window to automatic (relative) sizing.

right ¶

right()

Focus window to the right.

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.

set_height ¶

set_height(x)

Set height of current window.

set_size ¶

set_size(x)

Change size of current window.

(It's recommended to use width()/height() instead.)

set_width ¶

set_width(x)

Set width of current window.

show ¶

show(screen_rect: ScreenRect) -> None

Called when layout is being shown.

swap ¶

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

Swap the two given clients c1 and c2.

up ¶

up()

Focus window above.

Plasma ¶

group property ¶

add_client ¶

add_defaults ¶

blur ¶

clone ¶

command ¶

commands ¶

configure ¶

doc ¶

down ¶

eval ¶

focus ¶

focus_first ¶

focus_last ¶

focus_next ¶

focus_previous ¶

function ¶

grow ¶

grow_height ¶

grow_width ¶

hide ¶

info ¶

integrate_down ¶

integrate_left ¶

integrate_right ¶

integrate_up ¶

items ¶

left ¶

mode_horizontal ¶

mode_horizontal_split ¶

mode_vertical ¶

mode_vertical_split ¶

move_down ¶

move_left ¶

move_right ¶

move_up ¶

next ¶

previous ¶

recent ¶

remove ¶

reset_size ¶

right ¶

select ¶

set_height ¶

set_size ¶

set_width ¶

show ¶

swap ¶

up ¶

group `property` ¶