Screens¶
The screens configuration variable is where the physical screens, their
associated bars, and the widgets contained within the bars are defined
(see built-in widgets for a listing of available widgets).
Example¶
Tying together screens, bars and widgets, we get something like this:
from libqtile.config import Screen
from libqtile import bar, widget
window_name = widget.WindowName()
screens = [
Screen(
bottom=bar.Bar([
widget.GroupBox(),
window_name,
], 30
),
),
Screen(
bottom=bar.Bar([
widget.GroupBox(),
window_name,
], 30
),
)
]
Note that a widget can be passed to multiple bars (and likewise multiple times to the same bar). Its contents is mirrored across all copies so this is useful where you want identical content (e.g. the name of the focussed window, like in this example).
Bars support both solid background colors and gradients by supplying a list of
colors that make up a linear gradient. For example, :code:bar.Bar(...,
background="#000000") will give you a black back ground (the default), while
bar.Bar(..., background=["#000000", "#FFFFFF"]) will give you a
background that fades from black to white.
Bars (and widgets) also support transparency by adding an alpha value to the
desired color. For example, bar.Bar(..., background="#00000000") will
result in a fully transparent bar. Widget contents will not be impacted i.e.
this is different to the opacity parameter which sets the transparency of the
entire window.
Note
In X11 backends, transparency will be disabled in a bar if the background
color is fully opaque.
Users can add borders to the bar by using the border_width and
border_color parameters. Providing a single value sets the value for all
four sides while sides can be customised individually by setting four values
in a list (top, right, bottom, left) e.g. border_width=[2, 0, 2, 0] would
draw a border 2 pixels thick on the top and bottom of the bar.
Multiple Screens¶
You will see from the example above that screens is a list of individual
Screen objects. The order of the screens in this list should match the order
of screens as seen by your display server.
X11¶
You can view the current order of your screens by running xrandr --listmonitors.
Examples of how to set the order of your screens can be found on the Arch wiki.
Wayland¶
The Wayland backend supports the wlr-output-management protocol for configuration of outputs by tools such as Kanshi.
Fake Screens¶
instead of using the variable screens the variable fake_screens can be used to set split a physical monitor into multiple screens.
They can be used like this:
from libqtile.config import Screen
from libqtile import bar, widget
# screens look like this
# 600 300
# |-------------|-----|
# | 480| |580
# | A | B |
# |----------|--| |
# | 400|--|-----|
# | C | |400
# |----------| D |
# 500 |--------|
# 400
#
# Notice there is a hole in the middle
# also D goes down below the others
fake_screens = [
Screen(
bottom=bar.Bar(
[
widget.Prompt(),
widget.Sep(),
widget.WindowName(),
widget.Sep(),
widget.Systray(),
widget.Sep(),
widget.Clock(format='%H:%M:%S %d.%m.%Y')
],
24,
background="#555555"
),
x=0,
y=0,
width=600,
height=480
),
Screen(
top=bar.Bar(
[
widget.GroupBox(),
widget.WindowName(),
widget.Clock()
],
30,
),
x=600,
y=0,
width=300,
height=580
),
Screen(
top=bar.Bar(
[
widget.GroupBox(),
widget.WindowName(),
widget.Clock()
],
30,
),
x=0,
y=480,
width=500,
height=400
),
Screen(
top=bar.Bar(
[
widget.GroupBox(),
widget.WindowName(),
widget.Clock()
],
30,
),
x=500,
y=580,
width=400,
height=400
),
]
Third-party bars¶
There might be some reasons to use third-party bars. For instance you can come from another window manager and you have already configured dzen2, xmobar, or something else. They definitely can be used with Qtile too. In fact, any additional configurations aren't needed. Just run the bar and qtile will adapt.
Reference¶
Screen(
top: BarType | None = None,
bottom: BarType | None = None,
left: BarType | None = None,
right: BarType | None = None,
wallpaper: str | None = None,
wallpaper_mode: str | None = None,
x11_drag_polling_rate: int | None = None,
x: int | None = None,
y: int | None = None,
width: int | None = None,
height: int | None = None,
)
Bases: CommandObject
A physical screen, and its associated paraphernalia.
Define a screen with a given set of [Bar][Bar]s of a specific geometry. Also,
x, y, width, and height aren't specified usually unless you are
using 'fake screens'.
The wallpaper parameter, if given, should be a path to an image file. How this
image is painted to the screen is specified by the wallpaper_mode parameter. By
default, the image will be placed at the screens origin and retain its own
dimensions. If the mode is "fill", the image will be centred on the screen and
resized to fill it. If the mode is "stretch", the image is stretched to fit all
of it into the screen.
The x11_drag_polling_rate parameter specifies the rate for drag events in the X11 backend.
By default this is set to None, indicating no limit.
Because in the X11 backend we already handle motion notify events later,
the performance should already be okay. However, to limit these events further
you can use this variable and e.g. set it to your monitor refresh rate.
60 would mean that we handle a drag event 60 times per second.
Methods:
-
command–Return the command with the given name.
-
commands–Returns a list of possible commands for this object.
-
doc–Returns the documentation for a specified command name.
-
eval–Evaluates code in the same context as this function.
-
function–Call a function with current object as argument.
-
info–Returns a dictionary of info for this screen.
-
items–Build a list of contained items for the given item class.
-
next_group–Switch to the next group.
-
prev_group–Switch to the previous group.
-
select–Return a selected object.
-
set_group–Put group on this screen.
-
set_wallpaper–Set the wallpaper to the given file.
-
toggle_group–Switch to the selected group or to the previously active one.
Returns a list of possible commands for this object.
Used by qsh for command completion and online help
doc(name) -> str
Returns the documentation for a specified command name.
Used by qsh to provide online help.
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.
function(function, *args, **kwargs) -> None
Call a function with current object as argument.
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
Switch to the next group.
Switch to the previous group.
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.
Put group on this screen.
Set the wallpaper to the given file.
Bases: Gap, Configurable, CommandObject
A bar, which can contain widgets.
Parameters:
-
widgets(list[_Widget]) –A list of widget objects.
-
size(int) –The "thickness" of the bar, i.e. the height of a horizontal bar, or the width of a vertical bar.
Methods:
-
add_defaults–Add defaults to this object, overwriting any which already exist.
-
command–Return the command with the given name.
-
commands–Returns a list of possible commands for this object.
-
doc–Returns the documentation for a specified command name.
-
eval–Evaluates code in the same context as this function.
-
fake_button_press–Fake a mouse-button-press on the bar.
-
function–Call a function with current object as argument.
-
info–Info for this object.
-
items–Build a list of contained items for the given item class.
-
kill_window–Kill the window when the bar's screen is no longer being used.
-
select–Return a selected object.
-
widget_grab_keyboard–A widget can call this method to grab the keyboard focus and receive keyboard messages.
-
widget_ungrab_keyboard–Removes keyboard focus from the widget.
add_defaults(defaults)
Add defaults to this object, overwriting any which already exist.
Returns a list of possible commands for this object.
Used by qsh for command completion and online help
doc(name) -> str
Returns the documentation for a specified command name.
Used by qsh to provide online help.
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.
Fake a mouse-button-press on the bar.
Coordinates are relative to the top-left corner of the bar.
function(function, *args, **kwargs) -> None
Call a function with current object as argument.
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
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.
widget_grab_keyboard(widget: _Widget) -> None
A widget can call this method to grab the keyboard focus and receive keyboard messages.
When done, widget_ungrab_keyboard() must be called.