Groups

A group is a container for a bunch of windows, analogous to workspaces in other window managers. Each client window managed by the window manager belongs to exactly one group. The groups config file variable should be initialized to a list of DGroup objects.

DGroup objects provide several options for group configuration. Groups can be configured to show and hide themselves when they’re not empty, spawn applications for them when they start, automatically acquire certain groups, and various other options.

Example

from libqtile.config import Group, Match
groups = [
    Group("a"),
    Group("b"),
    Group("c", matches=[Match(wm_class=["Firefox"])]),
]

# allow mod3+1 through mod3+0 to bind to groups; if you bind your groups
# by hand in your config, you don't need to do this.
from libqtile.dgroups import simple_key_binder
dgroups_key_binder = simple_key_binder("mod3")

Reference

Group

class libqtile.config.Group(name: str, matches: Optional[List[libqtile.config.Match]] = None, exclusive=False, spawn: Optional[Union[str, List[str]]] = None, layout: Optional[str] = None, layouts: Optional[List] = None, persist=True, init=True, layout_opts=None, screen_affinity=None, position=9223372036854775807, label: Optional[str] = None)[source]

Represents a “dynamic” group

These groups can spawn apps, only allow certain Matched windows to be on them, hide when they’re not in use, etc. Groups are identified by their name.

Parameters
name: string

the name of this group

matches: default ``None``

list of Match objects whose windows will be assigned to this group

exclusive: boolean

when other apps are started in this group, should we allow them here or not?

spawn: string or list of strings

this will be exec() d when the group is created, you can pass either a program name or a list of programs to exec()

layout: string

the name of default layout for this group (e.g. ‘max’ or ‘stack’). This is the name specified for a particular layout in config.py or if not defined it defaults in general the class name in all lower case.

layouts: list

the group layouts list overriding global layouts. Use this to define a separate list of layouts for this particular group.

persist: boolean

should this group stay alive with no member windows?

init: boolean

is this group alive when qtile starts?

position int

group position

label: string

the display name of the group. Use this to define a display name other than name of the group. If set to None, the display name is set to the name.

libqtile.dgroups.simple_key_binder(mod, keynames=None)[source]

Bind keys to mod+group position or to the keys specified as second argument

Group Matching

Match

class libqtile.config.Match(title=None, wm_class=None, role=None, wm_type=None, wm_instance_class=None, net_wm_pid=None, func: Optional[Callable[[libqtile.backend.x11.window.Window], bool]] = None)[source]

Match for dynamic groups

It can match by title, wm_class, role, wm_type, wm_instance_class or net_wm_pid.

Match supports both regular expression objects (i.e. the result of re.compile()) or strings (match as an “include”-match). If a window matches all specified values, it is considered a match.

Parameters
title:

matches against the title (WM_NAME)

wm_class:

matches against the second string in WM_CLASS atom

role:

matches against the WM_ROLE atom

wm_type:

matches against the WM_TYPE atom

wm_instance_class:

matches against the first string in WM_CLASS atom

net_wm_pid:

matches against the _NET_WM_PID atom (only int allowed for this rule)

func:

delegate the match to the given function, which receives the tested client as argument and must return True if it matches, False otherwise

Rule

class libqtile.config.Rule(match, group=None, float=False, intrusive=False, break_on_match=True)[source]

How to act on a match

A Rule contains a list of Match objects, and a specification about what to do when any of them is matched.

Parameters
match :

Match object or a list of such associated with this Rule

float :

auto float this window?

intrusive :

override the group’s exclusive setting?

break_on_match :

Should we stop applying rules if this rule is matched?

ScratchPad and DropDown

ScratchPad is a special - by default invisible - group which acts as a container for DropDown configurations. A DropDown can be configured to spawn a defined process and bind thats process’ window to it. The associated window can then be shown and hidden by the lazy command dropdown_toggle() (see Lazy objects) from the ScratchPad group. Thus - for example - your favorite terminal emulator turns into a quake-like terminal by the control of qtile.

If the DropDown window turns visible it is placed as a floating window on top of the current group. If the DropDown is hidden, it is simply switched back to the ScratchPad group.

Example

from libqtile.config import Group, ScratchPad, DropDown, Key
from libqtile.command import lazy
groups = [
    ScratchPad("scratchpad", [
        # define a drop down terminal.
        # it is placed in the upper third of screen by default.
        DropDown("term", "urxvt", opacity=0.8),

        # define another terminal exclusively for qshell at different position
        DropDown("qshell", "urxvt -hold -e qshell",
                 x=0.05, y=0.4, width=0.9, height=0.6, opacity=0.9,
                 on_focus_lost_hide=True) ]),
    Group("a"),
]

keys = [
  # toggle visibiliy of above defined DropDown named "term"
  Key([], 'F11', lazy.group['scratchpad'].dropdown_toggle('term')),
  Key([], 'F12', lazy.group['scratchpad'].dropdown_toggle('qshell')),
]

There is only one DropDown visible in current group at a time. If a further DropDown is set visible the currently shown DropDown turns invisble immediately.

Note that if the window is set to not floating, it is detached from DropDown and ScratchPad, and a new pocess is spawned next time the DropDown is set visible.

Reference

ScratchPad

class libqtile.config.ScratchPad(name, dropdowns=None, position=9223372036854775807, label='')[source]

Represents a “ScratchPad” group

ScratchPad adds a (by default) invisible group to qtile. That group is used as a place for currently not visible windows spawned by a DropDown configuration.

Parameters
namestring

the name of this group

dropdownsdefault None

list of DropDown objects

positionint

group position

labelstring

The display name of the ScratchPad group. Defaults to the empty string such that the group is hidden in GroupList widget.