Qtile 0.4 - screens

The screens configuration variable is where the physical screens, their associated bars, and the widgets contained within the bars are defined.

screens

libqtile.manager.Screen

A physical screen, and its associated paraphernalia.

class Screen:
    def __init__(self, top=None, bottom=None, left=None, right=None):
        ...
  • top, bottom, left, right: Instances of bar objects, or None.

Note that bar.Bar objects can only be placed at the top or the bottom of the screen (bar.Gap objects can be placed anywhere).

command description
commands()

Returns a list of possible commands for this object. Used by qsh for command completion and online help.
doc(name)

Returns the documentation for a specified command name. Used by qsh to provide online help.
info()

Returns a dictionary of info for this object.
items(name)

Returns a list of contained items for the specified name. Used by qsh to allow navigation of the object graph.
resize(x=None, y=None, w=None, h=None)

Resize the screen.

bars

libqtile.bar.Bar

A bar, which can contain widgets. Note that bars can only be placed at the top or bottom of the screen.

class Bar:
    def __init__(self, widgets, size, **config):
        ...
  • widgets: A list of widget objects.
  • size: The height of the bar.
config default description
background '#000000' Background colour.
opacity 1 Bar window opacity.
command description
commands()

Returns a list of possible commands for this object. Used by qsh for command completion and online help.
doc(name)

Returns the documentation for a specified command name. Used by qsh to provide online help.
fake_click(screen, position, x, y)

Fake a mouse-click on the bar. Co-ordinates are relative to the top-left corner of the bar.

:screen The integer screen offset :position One of "top", "bottom", "left", or "right"
info()

Info for this object.
items(name)

Returns a list of contained items for the specified name. Used by qsh to allow navigation of the object graph.

libqtile.bar.Gap

A gap, placed along one of the edges of the screen. If a gap has been defined, Qtile will avoid covering it with windows. The most probable reason for configuring a gap is to make space for a third-party bar or other static window.

class Gap:
    def __init__(self, size):
        ...
  • size: The width of the gap.
command description
commands()

Returns a list of possible commands for this object. Used by qsh for command completion and online help.
doc(name)

Returns the documentation for a specified command name. Used by qsh to provide online help.
info()

Info for this object.
items(name)

Returns a list of contained items for the specified name. Used by qsh to allow navigation of the object graph.

widgets

libqtile.widget.Clock

A simple but flexible text-based clock.

class Clock:
    def __init__(self, fmt='%H:%M', width=CALCULATED, **config):
        ...

  • fmt: A Python datetime format string.

  • width: A fixed width, or bar.CALCULATED to calculate the width automatically (which is recommended).

config default description
font 'Monospace' Clock font
fontsize None Clock pixel size. Calculated if None.
padding None Clock padding. Calculated if None.
background '000000' Background colour
foreground 'ffffff' Foreground colour
command description
commands()

Returns a list of possible commands for this object. Used by qsh for command completion and online help.
doc(name)

Returns the documentation for a specified command name. Used by qsh to provide online help.
info()

Info for this object.
items(name)

Returns a list of contained items for the specified name. Used by qsh to allow navigation of the object graph.

libqtile.widget.GroupBox

A widget that graphically displays the group list, indicating which groups have focus, and which groups contain clients.

class GroupBox:
    def __init__(self, **config):
        ...

config default description
padding_y 2 Y padding outside the box
padding_x 2 X padding outside the box
borderwidth 3 Current group border width.
font 'Monospace' Font face
active 'FFFFFF' Active group font colour
inactive '404040' Inactive group font colour
background '000000' Widget background
this_screen_border '215578' Border colour for group on this screen.
other_screen_border '404040' Border colour for group on other screen.
min_margin_x 5 Minimum X margin (inside the box).
command description
commands()

Returns a list of possible commands for this object. Used by qsh for command completion and online help.
doc(name)

Returns the documentation for a specified command name. Used by qsh to provide online help.
info()

Info for this object.
items(name)

Returns a list of contained items for the specified name. Used by qsh to allow navigation of the object graph.

libqtile.widget.Spacer

Just an empty space on the bar. Often used with width equal to bar.STRETCH to push bar widgets to the right edge of the screen.

class Spacer:
    def __init__(self, width=STRETCH):
        ...
  • width: bar.STRETCH, or a pixel width.
command description
commands()

Returns a list of possible commands for this object. Used by qsh for command completion and online help.
doc(name)

Returns the documentation for a specified command name. Used by qsh to provide online help.
info()

Info for this object.
items(name)

Returns a list of contained items for the specified name. Used by qsh to allow navigation of the object graph.

libqtile.widget.TextBox

A flexible textbox that can be updated from bound keys, scripts and qsh.

class TextBox:
    def __init__(self, name, text=' ', width=CALCULATED, **config):
        ...
  • name: Name for this widget. Used to address the widget from scripts, commands and qsh.
  • text: Initial widget text.
  • width: An integer width, bar.STRETCH, or bar.CALCULATED .
config default description
font 'Monospace' Text font
fontsize None Font pixel size. Calculated if None.
padding None Padding left and right. Calculated if None.
background None Background colour.
foreground '#ffffff' Foreground colour.
command description
commands()

Returns a list of possible commands for this object. Used by qsh for command completion and online help.
doc(name)

Returns the documentation for a specified command name. Used by qsh to provide online help.
get()

Retrieve the text in a TextBox widget.
info()

Info for this object.
items(name)

Returns a list of contained items for the specified name. Used by qsh to allow navigation of the object graph.
update(text)

Update the text in a TextBox widget.

libqtile.widget.WindowName

Displays the name of the window that currently has focus.

class WindowName:
    def __init__(self, **config):
        ...

config default description
font 'Monospace' Font face.
fontsize None Font pixel size. Calculated if None.
padding None Padding left and right.
background '000000' Background colour.
foreground 'ffffff' Foreground colour.
command description
commands()

Returns a list of possible commands for this object. Used by qsh for command completion and online help.
doc(name)

Returns the documentation for a specified command name. Used by qsh to provide online help.
info()

Info for this object.
items(name)

Returns a list of contained items for the specified name. Used by qsh to allow navigation of the object graph.

Example

Tying together screens, bars and widgets, we get something like this:

from libqtile.manager import Screen
from libqtile import bar, widget
screens = [
    Screen(
        bottom = bar.Bar(
                    [
                        widget.GroupBox(),
                        widget.WindowName()
                    ],
                    30,
                ),
    ),
    Screen(
        bottom = bar.Bar(
                    [
                        widget.GroupBox(),
                        widget.WindowName()
                    ],
                    30,
                ),
    )
]

Copyright (c) 2010 Aldo Cortesi