Qtile root object

The root node represents the main Qtile manager instance. Many of the commands on this node are therefore related to the running of the application itself.

The root can access every other node in the command graph. Certain objects can be accessed without a selector resulting in the current object being selected (e.g. current group, screen, layout, window).

strict digraph root {
bgcolor="transparent"
node [pos="0,0!", color="DarkGray", fillcolor="Gray", href="root.html", style="filled", label="root", fontname="bold"];
root;

node [pos="-1.94,-0.44!", color="Purple", fillcolor="Violet", href="bars.html", style="filled", label="bar", fontname="regular"];
bar;

node [pos="-1.56,1.24!", color="SlateBlue", fillcolor="SlateBlue1", href="backend.html", style="filled", label="core", fontname="regular"];
core;

node [pos="1.56,1.24!", color="OrangeRed", fillcolor="Orange", href="groups.html", style="filled", label="group", fontname="regular"];
group;

node [pos="1.94,-0.44!", color="Goldenrod", fillcolor="Gold", href="layouts.html", style="filled", label="layout", fontname="regular"];
layout;

node [pos="0.86,-1.8!", color="DarkGreen", fillcolor="LimeGreen", href="screens.html", style="filled", label="screen", fontname="regular"];
screen;

node [pos="-0.86,-1.8!", color="Blue", fillcolor="LightBlue", href="widgets.html", style="filled", label="widget", fontname="regular"];
widget;

node [pos="0,2!", color="Red", fillcolor="Tomato", href="windows.html", style="filled", label="window", fontname="regular"];
window;

root -> bar;
root -> group;
root -> layout;
root -> screen;
root -> widget;
root -> window;
root -> core;
bar -> screen [color="Gray", dir="both"];
bar -> widget [color="Gray", dir="both"];
group -> layout [color="Gray", dir="both"];
group -> window [color="Gray", dir="both"];
group -> screen [color="Gray", dir="both"];
layout -> window [color="Gray", dir="both"];
layout -> screen [color="Gray", dir="both"];
screen -> window [color="Gray", dir="both"];
screen -> widget [color="Gray", dir="both"];
}

class libqtile.core.manager.Qtile[source]

API commands

To access commands on this object via the command graph, use one of the following options:

lazy.<command>()

qtile cmd-obj -o cmd -f <command>

The following commands are available for this object:

add_rule(match_args, rule_args[, min_priorty])

Add a dgroup rule, returns rule_id needed to remove it

addgroup(group[, label, layout, layouts, index])

Add a group with the given name

change_window_order(new_location)

Change the order of the current window within the current group.

commands()

Returns a list of possible commands for this object

critical()

Set log level to CRITICAL

debug()

Set log level to DEBUG

delgroup(group)

Delete a group with the given name

display_kb()

Display table of key bindings

doc(name)

Returns the documentation for a specified command name

error()

Set log level to ERROR

eval(code)

Evaluates code in the same context as this function

findwindow([prompt, widget])

Launch prompt widget to find a window of the given name

fire_user_hook(hook_name, *args)

Fire a custom hook.

function(function, *args, **kwargs)

Call a function with current object as argument

get_groups()

Return a dictionary containing information for all groups

get_screens()

Return a list of dictionaries providing information on all screens

get_state()

Get pickled state for restarting qtile

get_test_data()

Returns any content arbitrarily set in the self.test_data attribute.

hide_show_bar([position])

Toggle visibility of a given bar

info()

Set log level to INFO

internal_windows()

Return info for each internal window (bars, for example)

items(name)

Build a list of contained items for the given item class.

labelgroup([prompt, widget])

Launch prompt widget to label the current group

list_widgets()

List of all addressible widget names

loglevel()

loglevelname()

next_layout([name])

Switch to the next layout.

next_screen()

Move to next screen

next_urgent()

Focus next window with urgent hint

pause()

Drops into pdb

prev_layout([name])

Switch to the previous layout.

prev_screen()

Move to the previous screen

qtile_info()

Returns a dictionary of info on the Qtile instance

qtilecmd([prompt, widget, messenger])

Execute a Qtile command using the client syntax

reconfigure_screens(*_, **__)

This can be used to set up screens again during run time.

reload_config()

Reload the configuration file.

remove_rule(rule_id)

Remove a dgroup rule by rule_id

restart()

Restart Qtile.

run_extension(extension)

Run extensions

shutdown()

Quit Qtile

simulate_keypress(modifiers, key)

Simulates a keypress on the focused window.

spawn(cmd[, shell, env])

Spawn a new process.

spawncmd([prompt, widget, command, ...])

Spawn a command using a prompt widget, with tab-completion.

status()

Return "OK" if Qtile is running

switch_groups(namea, nameb)

Switch position of two groups by name

switch_window(location)

Change to the window at the specified index in the current group.

switchgroup([prompt, widget])

Launch prompt widget to switch to a given group to the current screen

sync()

Sync the backend's event queue.

to_layout_index(index[, name])

Switch to the layout with the given index in self.layouts.

to_screen(n)

Warp focus to screen n, where n is a 0-based screen number

togroup([prompt, widget])

Launch prompt widget to move current window to a given group

tracemalloc_dump()

Dump tracemalloc snapshot

tracemalloc_toggle()

Toggle tracemalloc status

ungrab_all_chords()

Leave all chord modes and grab the root bindings

ungrab_chord()

Leave a chord mode

validate_config()

warning()

Set log level to WARNING

windows()

Return info for each client window

Command documentation

add_rule(match_args: dict[str, Any], rule_args: dict[str, Any], min_priorty: bool = False) int | None[source]

Add a dgroup rule, returns rule_id needed to remove it

Parameters:
match_args

config.Match arguments

rule_args

config.Rule arguments

min_priorty

If the rule is added with minimum priority (last) (default: False)

addgroup(group: str, label: str | None = None, layout: str | None = None, layouts: list[Layout] | None = None, index: int | None = None) bool[source]

Add a group with the given name

change_window_order(new_location: int) None[source]

Change the order of the current window within the current group.

commands() list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

critical() None[source]

Set log level to CRITICAL

debug() None[source]

Set log level to DEBUG

delgroup(group: str) None[source]

Delete a group with the given name

display_kb() str[source]

Display table of key bindings

doc(name) str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

error() None[source]

Set log level to ERROR

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.

findwindow(prompt: str = 'window', widget: str = 'prompt') None[source]

Launch prompt widget to find a window of the given name

Parameters:
prompt

Text with which to prompt user (default: "window")

widget

Name of the prompt widget (default: "prompt")

fire_user_hook(hook_name: str, *args: Any) None[source]

Fire a custom hook.

function(function, *args, **kwargs) None

Call a function with current object as argument

get_groups() dict[str, dict[str, Any]][source]

Return a dictionary containing information for all groups

Examples

get_groups()

get_screens() list[dict[str, Any]][source]

Return a list of dictionaries providing information on all screens

get_state() str[source]

Get pickled state for restarting qtile

get_test_data() Any[source]

Returns any content arbitrarily set in the self.test_data attribute. Useful in tests.

hide_show_bar(position: Literal['top', 'bottom', 'left', 'right', 'all'] = 'all') None[source]

Toggle visibility of a given bar

Parameters:
position

one of: "top", "bottom", "left", "right", or "all" (default: "all")

info() None[source]

Set log level to INFO

internal_windows() list[dict[str, Any]][source]

Return info for each internal window (bars, for example)

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

labelgroup(prompt: str = 'label', widget: str = 'prompt') None[source]

Launch prompt widget to label the current group

Parameters:
prompt

Text with which to prompt user (default: "label")

widget

Name of the prompt widget (default: "prompt")

list_widgets() list[str][source]

List of all addressible widget names

loglevel() int[source]
loglevelname() str[source]
next_layout(name: str | None = None) None[source]

Switch to the next layout.

Parameters:
name

Group name. If not specified, the current group is assumed

next_screen() None[source]

Move to next screen

next_urgent() None[source]

Focus next window with urgent hint

pause() None[source]

Drops into pdb

prev_layout(name: str | None = None) None[source]

Switch to the previous layout.

Parameters:
name

Group name. If not specified, the current group is assumed

prev_screen() None[source]

Move to the previous screen

qtile_info() dict[source]

Returns a dictionary of info on the Qtile instance

qtilecmd(prompt: str = 'command', widget: str = 'prompt', messenger: str = 'xmessage') None[source]

Execute a Qtile command using the client syntax

Tab completion aids navigation of the command tree

Parameters:
prompt

Text to display at the prompt (default: "command: ")

widget

Name of the prompt widget (default: "prompt")

messenger

Command to display output, set this to None to disable (default: "xmessage")

reconfigure_screens(*_: list[Any], **__: dict[Any, Any]) None[source]

This can be used to set up screens again during run time. Intended usage is to be called when the screen_change hook is fired, responding to changes in physical monitor setup by configuring qtile.screens accordingly. The args are ignored; it is here in case this function is hooked directly to screen_change.

reload_config() None[source]

Reload the configuration file.

Can also be triggered by sending Qtile a SIGUSR1 signal.

remove_rule(rule_id: int) None[source]

Remove a dgroup rule by rule_id

restart() None[source]

Restart Qtile.

Can also be triggered by sending Qtile a SIGUSR2 signal.

run_extension(extension: _Extension) None[source]

Run extensions

shutdown() None[source]

Quit Qtile

simulate_keypress(modifiers: list[str], key: str) None[source]

Simulates a keypress on the focused window.

This triggers internal bindings only; for full simulation see external tools such as xdotool or ydotool.

Parameters:
modifiers

A list of modifier specification strings. Modifiers can be one of "shift", "lock", "control" and "mod1" - "mod5".

key

Key specification.

Examples

simulate_keypress(["control", "mod2"], "k")

spawn(cmd: str | list[str], shell: bool = False, env: dict[str, str] = {}) int[source]

Spawn a new process.

Parameters:
cmd:

The command to execute either as a single string or list of strings.

shell:

Whether to execute the command in a new shell by prepending it with "/bin/sh -c". This enables the use of shell syntax within the command (e.g. pipes).

env:

Dictionary of environmental variables to pass with command.

Examples

spawn("firefox")

spawn(["xterm", "-T", "Temporary terminal"])

spawn("screenshot | xclip", shell=True)

spawncmd(prompt: str = 'spawn', widget: str = 'prompt', command: str = '%s', complete: str = 'cmd', shell: bool = True, aliases: dict[str, str] | None = None) None[source]

Spawn a command using a prompt widget, with tab-completion.

Parameters:
prompt

Text with which to prompt user (default: "spawn: ").

widget

Name of the prompt widget (default: "prompt").

command

command template (default: "%s").

complete

Tab completion function (default: "cmd")

shell

Execute the command with /bin/sh (default: True)

aliases

Dictionary mapping aliases to commands. If the entered command is a key in this dict, the command it maps to will be executed instead.

status() Literal['OK'][source]

Return "OK" if Qtile is running

switch_groups(namea: str, nameb: str) None[source]

Switch position of two groups by name

switch_window(location: int) None[source]

Change to the window at the specified index in the current group.

switchgroup(prompt: str = 'group', widget: str = 'prompt') None[source]

Launch prompt widget to switch to a given group to the current screen

Parameters:
prompt

Text with which to prompt user (default: "group")

widget

Name of the prompt widget (default: "prompt")

sync() None[source]

Sync the backend's event queue. Should only be used for development.

to_layout_index(index: str, name: str | None = None) None[source]

Switch to the layout with the given index in self.layouts.

Parameters:
index

Index of the layout in the list of layouts.

name

Group name. If not specified, the current group is assumed.

to_screen(n: int) None[source]

Warp focus to screen n, where n is a 0-based screen number

Examples

to_screen(0)

togroup(prompt: str = 'group', widget: str = 'prompt') None[source]

Launch prompt widget to move current window to a given group

Parameters:
prompt

Text with which to prompt user (default: "group")

widget

Name of the prompt widget (default: "prompt")

tracemalloc_dump() tuple[bool, str][source]

Dump tracemalloc snapshot

tracemalloc_toggle() None[source]

Toggle tracemalloc status

Running tracemalloc is required for qtile top

ungrab_all_chords() None[source]

Leave all chord modes and grab the root bindings

ungrab_chord() None[source]

Leave a chord mode

validate_config() None[source]
warning() None[source]

Set log level to WARNING

windows() list[dict[str, Any]][source]

Return info for each client window