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, matches=None, exclusive=False, spawn=None, layout=None, layouts=None, persist=True, init=True, layout_opts=None, screen_affinity=None, position=9223372036854775807, label=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 toexec()
- 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)[source]¶ Match for dynamic groups
It can match by title, class or role.
Match
supports both regular expression objects (i.e. the result ofre.compile()
) or strings (match as a “include” match). If a window matches any of the things in any of the lists, it is considered a match.Parameters: - title:
things to match against the title (WM_NAME)
- wm_class:
things to match against the second string in WM_CLASS atom
- role:
things to match against the WM_ROLE atom
- wm_type:
things to match against the WM_TYPE atom
- wm_instance_class:
things to match against the first string in WM_CLASS atom
- net_wm_pid:
things to match against the _NET_WM_PID atom (only int allowed in this rule)
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 Match object, and a specification about what to do when that object is matched.
Parameters: - match :
Match
object associated with thisRule
- 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: - name : string
the name of this group
- dropdowns : default
None
list of DropDown objects
- position : int
group position
- label : string
The display name of the ScratchPad group. Defaults to the empty string such that the group is hidden in
GroupList
widget.
DropDown¶
-
class
libqtile.config.
DropDown
(name, cmd, **config)[source]¶ Configure a specified command and its associated window for the ScratchPad. That window can be shown and hidden using a configurable keystroke or any other scripted trigger.
key default description height
0.35
‘Height of window as fraction of current screen.’ on_focus_lost_hide
True
‘Shall the window be hidden if focus is lost? If so, the DropDown is hidden if window focus or the group is changed.’ opacity
0.9
‘Opacity of window as fraction. Zero is opaque.’ warp_pointer
True
‘Shall pointer warp to center of window on activation? This has only effect if any of the on_focus_lost_xxx configurations is True’ width
0.8
‘Width of window as fraction of current screen width’ x
0.1
‘X position of window as fraction of current screen width. 0 is the left most position.’ y
0.0
‘Y position of window as fraction of current screen height. 0 is the top most position. To show the window at bottom, you have to configure a value < 1 and an appropriate height.’