Window stacking

A number of window commands (move_up/down(), bring_to_front() etc.) relate to the stacking order of windows.

The aim of this page is to provide more details as to how stacking is implemented in Qtile.

Important

Currently, stacking is only implemented in the X11 background. Support will be added to the Wayland backend in future and this page will be updated accordingly.

Layer priority groups

We have tried to adhere to the EWMH specification. Windows are therefore stacked, from the bottom, according to the following priority rules:

  • windows of type _NET_WM_TYPE_DESKTOP

  • windows having state _NET_WM_STATE_BELOW

  • windows not belonging in any other layer

  • windows of type _NET_WM_TYPE_DOCK (unless they have state _NET_WM_TYPE_BELOW) and windows having state _NET_WM_STATE_ABOVE

  • focused windows having state _NET_WM_STATE_FULLSCREEN

Qtile had then added an additional layer so that Scratchpad windows are placed above everything else.

Tiled windows will open in the default, "windows not belonging in any other layer", layer. If floats_kept_above is set to True in the config then new floating windows will have the _NET_WM_STATE_ABOVE property set which will ensure they remain above tiled windows.

Moving windows

Imagine you have four tiled windows stacked (from the top) as follows:

"One"
"Two"
"Three"
"Four"

If you call move_up() on window "Four", the result will be:

"One"
"Two"
"Four"
"Three"

If you now call move_to_top() on window "Three", the result will be:

"Three"
"One"
"Two"
"Four"

Note

bring_to_front() has a special behaviour in Qtile. This will bring any window to the very top of the stack, disregarding the priority rules set out above. When that window loses focus, it will be restacked in the appropriate location.

This can cause undesirable results if the config contains bring_front_click=True and the user has an app like a dock which is activated by mousing over the window. In this situation, tiled windows will be displayed above the dock making it difficult to activate. To fix this, set bring_front_click to False to disable the behaviour completely, or "floating_only" to only have this behaviour apply to floating windows.