Screen objects

Screens are the display area that holds bars and an active group. Screen commands include changing the current group and changing the wallpaper.

Screens can access objects displayed on that screen e.g. bar, widgets, groups, layouts and windows.

.. qtile_graph:: :root: screen

config

Classes:

• Click –

  Bind commands to a clicking action.

• Drag –

  Bind commands to a dragging action.

• DropDown –

  Configure a specified command and its associated window for the [ScratchPad][ScratchPad].

• EzClick –

  Bind commands to a clicking action using the Emacs-like format.

• EzConfig –

  Helper class for defining key and button bindings in an Emacs-like format.

• EzDrag –

  Bind commands to a dragging action using the Emacs-like format.

• EzKey –

  Defines a keybinding using the Emacs-like format.

• EzKeyChord –

  Define a key chord using the Emacs-like format.

• Group –

  Represents a "dynamic" group.

• InvertMatch –

  Wrapper to invert the result of the comparison.

• Key –

  Defines a keybinding.

• KeyChord –

  Define a key chord aka Vim-like mode.

• Match –

  Window properties to compare (match) with a window.

• MatchAll –

  Wrapper to check if all comparisons return True.

• MatchAny –

  Wrapper to check if at least one of the comparisons returns True.

• MatchOnlyOne –

  Wrapper to check if only one of the two comparisons returns True.

• Mouse –

  Bind commands to a mouse action.

• Rule –

  How to act on a match.

• ScratchPad –

  Represents a "ScratchPad" group.

• Screen –

  A physical screen, and its associated paraphernalia.

Click

Click(
    modifiers: list[str], button: str, *commands: LazyCall
)

Bases: Mouse

Bind commands to a clicking action.

Parameters:

• modifiers (list[str]) –

  A list of modifier specifications. Modifier specifications are one of: "shift", "lock", "control", "mod1", "mod2", "mod3", "mod4", "mod5".

• button (str) –

  The button used, e.g. "Button1".

• commands (LazyCall, default: () ) –

  A list [LazyCall][LazyCall] objects to evaluate in sequence upon using the button.

Drag

Drag(
    modifiers: list[str],
    button: str,
    *commands: LazyCall,
    start: LazyCall | None = None,
    warp_pointer: bool = False
)

Bases: Mouse

Bind commands to a dragging action.

On each motion event the bound commands are executed with two additional parameters specifying the x and y offset from the previous position.

Parameters:

• modifiers (list[str]) –

  A list of modifier specifications. Modifier specifications are one of: "shift", "lock", "control", "mod1", "mod2", "mod3", "mod4", "mod5".

• button (str) –

  The button used to start dragging e.g. "Button1".

• commands (LazyCall, default: () ) –

  A list [LazyCall][LazyCall] objects to evaluate in sequence upon drag.

• start (LazyCall | None, default: None ) –

  A [LazyCall][LazyCall] object to be evaluated when dragging begins. (Optional)

• warp_pointer (bool, default: False ) –

  A bool indicating if the pointer should be warped to the bottom right of the window at the start of dragging. (Default: False)

DropDown

DropDown(name: str, cmd: str, **config: Any)

Bases: Configurable

Configure a specified command and its associated window for the [ScratchPad][ScratchPad].

That window can be shown and hidden using a configurable keystroke or any other scripted trigger.

Define a command to spawn a process for the first time the class:DropDown is shown.

Parameters:

• name (str) –

  The name of the dropdown.

• cmd (str) –

  Command to spawn a window to be captured by the dropdown.

Methods:

• add_defaults –

  Add defaults to this object, overwriting any which already exist.

add_defaults

add_defaults(defaults)

Add defaults to this object, overwriting any which already exist.

EzClick

EzClick(btndef: str, *commands: LazyCall)

Bases: EzConfig, Click

Bind commands to a clicking action using the Emacs-like format.

Parameters:

• btndef (str) –

  The Emacs-like button specification, e.g. "M-1".

• commands (LazyCall, default: () ) –

  A list [LazyCall][LazyCall] objects to evaluate in sequence upon click.

EzConfig

Helper class for defining key and button bindings in an Emacs-like format.

Inspired by Xmonad's XMonad.Util.EZConfig.

Splits an emacs keydef into modifiers and keys. For example:

"m-s-a"     -> ['mod4', 'shift'], 'a'
"a-<minus>" -> ['mod1'], 'minus'
"C-<Tab>"   -> ['control'], 'Tab'

EzDrag

EzDrag(
    btndef: str,
    *commands: LazyCall,
    start: LazyCall | None = None
)

Bases: EzConfig, Drag

Bind commands to a dragging action using the Emacs-like format.

Parameters:

• btndef (str) –

  The Emacs-like button specification, e.g. "M-1".

• commands (LazyCall, default: () ) –

  A list [LazyCall][LazyCall] objects to evaluate in sequence upon drag.

• start (LazyCall | None, default: None ) –

  A [LazyCall][LazyCall] object to be evaluated when dragging begins (optional).

EzKey

EzKey(keydef: str, *commands: LazyCall, desc: str = '')

Bases: EzConfig, Key

Defines a keybinding using the Emacs-like format.

Parameters:

• keydef (str) –

  The Emacs-like key specification, e.g. "M-S-a".

• commands (LazyCall, default: () ) –

  A list [LazyCall][LazyCall] objects to evaluate in sequence upon keypress.

• desc (str, default: '' ) –

  Description to be added to the key binding (optional).

EzKeyChord

EzKeyChord(
    keydef: str,
    submappings: list[Key | KeyChord],
    mode: bool | str = False,
    name: str = "",
    desc: str = "",
)

Bases: EzConfig, KeyChord

Define a key chord using the Emacs-like format.

Parameters:

• keydef (str) –

  The Emacs-like key specification, e.g. "M-S-a".

• submappings (list[Key | KeyChord]) –

  A list of [Key][Key] or [KeyChord][KeyChord] declarations to bind in this chord.

• mode (bool | str, default: False ) –

  Setting to True will result in the chord persisting until Escape is pressed. Setting to False (default) will exit the chord once the sequence has ended.

• name (str, default: '' ) –

  A string to name the chord. The name will be displayed in the Chord widget.

• desc (str, default: '' ) –

  A string to describe the chord. This attribute is not directly used by Qtile but users may want to access this when creating scripts to show configured keybindings.

Group

Group(
    name: str,
    matches: list[Match] | None = None,
    exclusive: bool = False,
    spawn: str | list[str] | None = None,
    layout: str | None = None,
    layouts: list[Layout] | None = None,
    persist: bool = True,
    init: bool = True,
    layout_opts: dict[str, Any] | None = None,
    screen_affinity: int | None = None,
    position: int = maxsize,
    label: str | None = None,
)

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 (str) –

  The name of this group.

• matches (list[Match] | None, default: None ) –

  List of [Match][Match] objects whose matched windows will be assigned to this group.

• exclusive (bool, default: False ) –

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

• spawn (str | list[str] | None, default: None ) –

  This will be executed (via qtile.spawn()) when the group is created. You can pass either a program name or a list of programs to exec().

• layout (str | None, default: None ) –

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

• layouts (list[Layout] | None, default: None ) –

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

• persist (bool, default: True ) –

  Should this group stay alive when it has no member windows?

• init (bool, default: True ) –

  Should this group be alive when Qtile starts?

• layout_opts (dict[str, Any] | None, default: None ) –

  Options to pass to a layout.

• screen_affinity (int | None, default: None ) –

  Make a dynamic group prefer to start on a specific screen.

• position (int, default: maxsize ) –

  The position of this group.

• label (str | None, default: None ) –

  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.

InvertMatch

InvertMatch(match: _Match)

Bases: _Match

Wrapper to invert the result of the comparison.

Key

Key(
    modifiers: list[str],
    key: str,
    *commands: LazyCall,
    desc: str = "",
    swallow: bool = True
)

Defines a keybinding.

Parameters:

• modifiers (list[str]) –

  A list of modifier specifications. Modifier specifications are one of: "shift", "lock", "control", "mod1", "mod2", "mod3", "mod4", "mod5".

• key (str) –

  A key specification, e.g. "a", "Tab", "Return", "space".

• commands (LazyCall, default: () ) –

  One or more [LazyCall][LazyCall] objects to evaluate in sequence upon keypress. Multiple commands should be separated by commas.

• desc (str, default: '' ) –

  Description to be added to the key binding (optional).

• swallow (bool, default: True ) –

  Configures when we swallow the key binding (optional). Setting it to False will forward the key binding to the focused window after the commands have been executed.

KeyChord

KeyChord(
    modifiers: list[str],
    key: str,
    submappings: list[Key | KeyChord],
    mode: bool | str = False,
    name: str = "",
    desc: str = "",
    swallow: bool = True,
)

Define a key chord aka Vim-like mode.

Parameters:

• modifiers (list[str]) –

  A list of modifier specifications. Modifier specifications are one of: "shift", "lock", "control", "mod1", "mod2", "mod3", "mod4", "mod5".

• key (str) –

  A key specification, e.g. "a", "Tab", "Return", "space".

• submappings (list[Key | KeyChord]) –

  A list of [Key][Key] or [KeyChord][KeyChord] declarations to bind in this chord.

• mode (bool | str, default: False ) –

  Boolean. Setting to True will result in the chord persisting until Escape is pressed. Setting to False (default) will exit the chord once the sequence has ended.

• name (str, default: '' ) –

  A string to name the chord. The name will be displayed in the Chord widget.

• desc (str, default: '' ) –

  A string to describe the chord. This attribute is not directly used by Qtile but users may want to access this when creating scripts to show configured keybindings.

• swallow (bool, default: True ) –

  Configures when we swallow the key binding of the chord. (Optional) Setting it to False will forward the key binding to the focused window after the commands have been executed.

Match

Match(
    title: str | Pattern | None = None,
    wm_class: str | Pattern | None = None,
    role: str | Pattern | None = None,
    wm_type: str | Pattern | None = None,
    wm_instance_class: str | Pattern | None = None,
    net_wm_pid: int | None = None,
    func: Callable[[Window], bool] | None = None,
    wid: int | None = None,
)

Bases: _Match

Window properties to compare (match) with a window.

The properties will be compared to a [libqtile.base.Window][libqtile.base.Window] to determine if its properties match. It can match by title, wm_class, role, wm_type, wm_instance_class, net_wm_pid, or wid. Additionally, a function may be passed, which takes in the [libqtile.base.Window][libqtile.base.Window] to be compared against and returns a boolean.

For some properties, [Match][Match] supports both regular expression objects (i.e. the result of re.compile()) or strings (match as an exact string). If a window matches all specified values, it is considered a match.

Parameters:

• title (str | Pattern | None, default: None ) –

  Match against the WM_NAME atom (X11) or title (Wayland).

• wm_class (str | Pattern | None, default: None ) –

  Match against any value in the whole WM_CLASS atom (X11) or app ID (Wayland).

• role (str | Pattern | None, default: None ) –

  Match against the WM_ROLE atom (X11 only).

• wm_type (str | Pattern | None, default: None ) –

  Match against the WM_TYPE atom (X11 only).

• wm_instance_class (str | Pattern | None, default: None ) –

  Match against the first string in WM_CLASS atom (X11) or app ID (Wayland).

• net_wm_pid (int | None, default: None ) –

  Match against the _NET_WM_PID atom (X11) or PID (Wayland).

• func (Callable[[Window], bool] | None, default: None ) –

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

• wid (int | None, default: None ) –

  Match against the window ID. This is a unique ID given to each window.

Methods:

• map –

  Apply callback to each client that matches this Match.

map

map(
    callback: Callable[[Window], Any], clients: list[Window]
) -> None

Apply callback to each client that matches this Match.

MatchAll

MatchAll(*matches: _Match)

Bases: _Match

Wrapper to check if all comparisons return True.

MatchAny

MatchAny(*matches: _Match)

Bases: MatchAll

Wrapper to check if at least one of the comparisons returns True.

MatchOnlyOne

MatchOnlyOne(match1: _Match, match2: _Match)

Bases: _Match

Wrapper to check if only one of the two comparisons returns True.

Mouse

Mouse(
    modifiers: list[str], button: str, *commands: LazyCall
)

Bind commands to a mouse action.

Parameters:

• modifiers (list[str]) –

  A list of modifier specifications. Modifier specifications are one of: "shift", "lock", "control", "mod1", "mod2", "mod3", "mod4", "mod5".

• button (str) –

  The button used, e.g. "Button1".

• commands (LazyCall, default: () ) –

  A list [LazyCall][LazyCall] objects to evaluate in sequence upon using the button.

Rule

Rule(
    match: _Match | list[_Match],
    group: _Group | None = None,
    float: bool = False,
    intrusive: bool = False,
    break_on_match: bool = True,
)

How to act on a match.

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

Parameters:

• match (_Match | list[_Match]) –

  [Match][Match] object or a list of such associated with this rule.

• float (bool, default: False ) –

  Should we auto float this window?

• intrusive (bool, default: False ) –

  Should we override the group's exclusive setting?

• break_on_match (bool, default: True ) –

  Should we stop applying rules if this rule is matched?

ScratchPad

ScratchPad(
    name: str,
    dropdowns: list[DropDown] | None = None,
    position: int = maxsize,
    label: str = "",
    single: bool = False,
)

Bases: Group

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][DropDown] configuration.

Parameters:

• name (str) –

  The name of this group.

• dropdowns (list[DropDown] | None, default: None ) –

  [DropDown][DropDown] s available on the scratchpad.

• position (int, default: maxsize ) –

  The position of this group.

• label (str, default: '' ) –

  The display name of the [ScratchPad][ScratchPad] group. Defaults to the empty string such that the group is hidden in libqtile.widget.GroupBox widget.

• single (bool, default: False ) –

  If True, only one of the dropdowns will be visible at a time.

Screen

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.

command

command(name: str) -> Callable | None

Return the command with the given name.

Parameters:

• name (str) –

  The name of the command to fetch.

commands

commands() -> list[str]

Returns a list of possible commands for this object.

Used by qsh for command completion and online help

doc

doc(name) -> str

Returns the documentation for a specified command name.

Used by qsh to provide online help.

eval

eval(code: str) -> tuple[bool, str | None]

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(function, *args, **kwargs) -> None

Call a function with current object as argument.

info

info() -> dict[str, int]

Returns a dictionary of info for this screen.

items

items(name: str) -> tuple[bool, list[str | int] | None]

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

next_group

next_group(
    skip_empty: bool = False, skip_managed: bool = False
) -> None

Switch to the next group.

prev_group

prev_group(
    skip_empty: bool = False,
    skip_managed: bool = False,
    warp: bool = True,
) -> None

Switch to the previous group.

select

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.

set_group

set_group(
    new_group: _Group | None,
    save_prev: bool = True,
    warp: bool = True,
) -> None

Put group on this screen.

set_wallpaper

set_wallpaper(path: str, mode: str | None = None) -> None

Set the wallpaper to the given file.

toggle_group

toggle_group(
    group_name: str | None = None, warp: bool = True
) -> None

Switch to the selected group or to the previously active one.