/qtile-plasma

🔮 A flexible, tree-based layout for Qtile

Primary LanguagePythonMIT LicenseMIT

Plasma

Build Status codecov PyPI Version Python Versions

Plasma is a flexible, tree-based layout for Qtile.

If you're looking for a well-tested and maintained alternative to Qtile's default layouts, give it a try.

About

Plasma works on a tree structure. Each node represents a container with child containers aligned either horizontally or vertically (similar to i3). Each window is attached to a leaf, taking either a proportional or a specific custom amount of space in its parent container. Windows can be resized, rearranged and integrated into other containers, enabling lots of different setups.

Demo

Here is a quick demo showing some of the main features (adding modes, moving, integrating and resizing):

Demo

Installation

Install the package. You can get it from PyPI:

pip install --upgrade qtile-plasma

Then, add the layout to your config (~/.config/qtile/config.py):

from plasma import Plasma
...
layouts = [
    Plasma(
        border_normal='#333333',
        border_focus='#00e891',
        border_normal_fixed='#006863',
        border_focus_fixed='#00e8dc',
        border_width=1,
        border_width_single=0,
        margin=0
    ),
    ...
]

Add some key bindings, too. I am using these:

from libqtile.command import lazy
from libqtile.config import EzKey
...
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()]

Done!

Commands

The layout exposes the following commands:

next() Focus next window.
previous() Focus previous window.
recent() Focus most recently focused window.
(Toggles between the two latest active windows.)
left() Focus window to the left.
right() Focus window to the right.
up() Focus window above.
down() Focus window below.
move_left() Move current window left.
move_right() Move current window right.
move_up() Move current window up.
move_down() Move current window down.
integrate_left() Integrate current window left.
integrate_right() Integrate current window right.
integrate_up() Integrate current window up.
integrate_down() Integrate current window down.
mode_horizontal() Next window will be added horizontally.
mode_vertical() Next window will be added vertically.
mode_horizontal_split() Next window will be added horizontally, splitting space of current window.
mode_vertical_split() Next window will be added vertically, splitting space of current window.
size(x) Change size of current window.
(It's recommended to use width()/height() instead.)
width(x) Set width of current window.
height(x) Set height of current window.
reset_size() Reset size of current window to automatic (relative) sizing.
grow(x) Grow size of current window.
(It's recommended to use grow_width()/grow_height() instead.)
grow_width(x) Grow width of current window.
grow_height(x) Grow height of current window.

Contributing

If you have found a bug or want to suggest a feature, please file an issue.

To work on Plasma locally, you need to clone submodules too, since the layout integration tests use some of Qtile's test fixtures:

git clone --recursive https://github.com/numirias/qtile-plasma/

Also make sure you meet the hacking requirements of Qtile. In particular, have xserver-xephyr installed. Then run:

make init

If that fails, run the init instructions from the Makefile one by one.

All new changes need to be fully test-covered and pass the linting:

make lint
make test

If you made changes to the layout API, also re-build this README's commands section:

make readme