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).

.. qtile_graph:: :root: root

Qtile ¶

Qtile(
    kore: Core,
    config: Config,
    no_spawn: bool = False,
    state: str | None = None,
    socket_path: str | None = None,
)

Bases: CommandObject

This object is the root of the command graph.

Methods:

add_rule –

Add a dgroup rule, returns rule_id needed to remove it.
addgroup –

Add a group with the given name.
async_loop –

Run the event loop.
call_later –

Another event loop proxy, see call_soon.
call_soon –

A wrapper for the event loop's call_soon which also flushes the core's
call_soon_threadsafe –

Another event loop proxy, see call_soon.
change_window_order –

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

Return the command with the given name.
commands –

Returns a list of possible commands for this object.
critical –

Set log level to CRITICAL.
debug –

Set log level to DEBUG.
delgroup –

Delete a group with the given name.
display_kb –

Display table of key bindings.
doc –

Returns the documentation for a specified command name.
error –

Set log level to ERROR.
eval –

Evaluates code in the same context as this function.
find_closest_screen –

If find_screen returns None, then this basically extends a
find_screen –

Find a screen based on the x and y offset.
findwindow –

Launch prompt widget to find a window of the given name.
fire_user_hook –

Fire a custom hook.
focus_screen –

Have Qtile move to screen and put focus there.
free_reserved_space –

Free up space that has previously been reserved at the edge(s) of a screen.
function –

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.
grab_button –

Grab the given mouse button event.
grab_key –

Grab the given key event.
grab_keys –

Re-grab all of the keys configured in the key map.
hide_show_bar –

Toggle visibility of a given bar.
info –

Set log level to INFO.
internal_windows –

Return info for each internal window (bars, for example).
items –

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

Launch prompt widget to label the current group.
list_widgets –

List of all addressible widget names.
move_to_group –

Create a group if it doesn't exist and move the current window there.
next_layout –

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 –

Switch to the previous layout.
prev_screen –

Move to the previous screen.
qtile_info –

Returns a dictionary of info on the Qtile instance.
qtilecmd –

Execute a Qtile command using the client syntax.
reconfigure_screens –

This can be used to set up screens again during run time. Intended usage is to
register_widget –

Register a bar widget.
reload_config –

Reload the configuration file.
remove_rule –

Remove a dgroup rule by rule_id.
reserve_space –

Reserve some space at the edge(s) of a screen.
restart –

Restart Qtile.
run_extension –

Run extensions.
run_in_executor –

A wrapper for running a function in the event loop's default
select –

Return a selected object.
shutdown –

Quit Qtile.
simulate_keypress –

Simulates a keypress on the focused window.
spawn –

Spawn a new process.
spawncmd –

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

Return "OK" if Qtile is running.
switch_groups –

Switch position of two groups by name.
switch_window –

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

Launch prompt widget to switch to a given group to the current screen.
sync –

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

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

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

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.
ungrab_key –

Ungrab a given key event.
ungrab_keys –

Ungrab all key events.
warning –

Set log level to WARNING.
windows –

Return info for each client window.

add_rule ¶

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

Add a dgroup rule, returns rule_id needed to remove it.

Parameters:

match_args (dict[str, Any]) –

config.Match arguments.
rule_args (dict[str, Any]) –

config.Rule arguments.
min_priorty (bool, default: False ) –

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

addgroup ¶

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

Add a group with the given name.

async_loop `async` ¶

async_loop() -> None

Run the event loop.

Finalizes the Qtile instance on exit.

call_later ¶

call_later(
    delay: int, func: Callable, *args: Any
) -> TimerHandle

Another event loop proxy, see call_soon.

call_soon ¶

call_soon(func: Callable, *args: Any) -> Handle

A wrapper for the event loop's call_soon which also flushes the core's event queue after func is called.

call_soon_threadsafe ¶

call_soon_threadsafe(func: Callable, *args: Any) -> Handle

Another event loop proxy, see call_soon.

change_window_order ¶

change_window_order(new_location: int) -> None

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

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

critical ¶

critical() -> None

Set log level to CRITICAL.

debug ¶

debug() -> None

Set log level to DEBUG.

delgroup ¶

delgroup(group: str) -> None

Delete a group with the given name.

display_kb ¶

display_kb() -> str

Display table of key bindings.

doc ¶

doc(name) -> str

Returns the documentation for a specified command name.

Used by qsh to provide online help.

error ¶

error() -> None

Set log level to ERROR.

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.

find_closest_screen ¶

find_closest_screen(x: int, y: int) -> Screen

If find_screen returns None, then this basically extends a screen vertically and horizontally and see if x,y lies in the band.

Only works if it can find a SINGLE closest screen, else we revert to _find_closest_closest.

Useful when dragging a window out of a screen onto another but having leftmost corner above viewport.

find_screen ¶

find_screen(x: int, y: int) -> Screen | None

Find a screen based on the x and y offset.

findwindow ¶

findwindow(
    prompt: str = "window", widget: str = "prompt"
) -> None

Launch prompt widget to find a window of the given name.

Parameters:

prompt (str, default: 'window' ) –

Text with which to prompt user (default: "window").
widget (str, default: 'prompt' ) –

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

fire_user_hook ¶

fire_user_hook(hook_name: str, *args: Any) -> None

Fire a custom hook.

focus_screen ¶

focus_screen(n: int, warp: bool = True) -> None

Have Qtile move to screen and put focus there.

free_reserved_space ¶

free_reserved_space(
    reserved_space: tuple[int, int, int, int],
    screen: Screen,
) -> None

Free up space that has previously been reserved at the edge(s) of a screen.

function ¶

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

Call a function with current object as argument.

get_groups ¶

get_groups() -> dict[str, dict[str, Any]]

Return a dictionary containing information for all groups.

Examples:

>>> get_groups()

get_screens ¶

get_screens() -> list[dict[str, Any]]

Return a list of dictionaries providing information on all screens.

get_state ¶

get_state() -> str

Get pickled state for restarting qtile.

get_test_data ¶

get_test_data() -> Any

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

grab_button ¶

grab_button(button: Mouse) -> None

Grab the given mouse button event.

grab_key ¶

grab_key(key: Key | KeyChord) -> None

Grab the given key event.

grab_keys ¶

grab_keys() -> None

Re-grab all of the keys configured in the key map.

Useful when a keyboard mapping event is received.

hide_show_bar ¶

hide_show_bar(
    position: Literal[
        "top", "bottom", "left", "right", "all"
    ] = "all"
) -> None

Toggle visibility of a given bar.

Parameters:

position (Literal['top', 'bottom', 'left', 'right', 'all'], default: 'all' ) –

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

info ¶

info() -> None

Set log level to INFO.

internal_windows ¶

internal_windows() -> list[dict[str, Any]]

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

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

labelgroup ¶

labelgroup(
    prompt: str = "label", widget: str = "prompt"
) -> None

Launch prompt widget to label the current group.

Parameters:

prompt (str, default: 'label' ) –

Text with which to prompt user (default: "label").
widget (str, default: 'prompt' ) –

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

list_widgets ¶

list_widgets() -> list[str]

List of all addressible widget names.

move_to_group ¶

move_to_group(group: str) -> None

Create a group if it doesn't exist and move the current window there.

next_layout ¶

next_layout(name: str | None = None) -> None

Switch to the next layout.

Parameters:

name (str | None, default: None ) –

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

next_screen ¶

next_screen() -> None

Move to next screen.

next_urgent ¶

next_urgent() -> None

Focus next window with urgent hint.

pause ¶

pause() -> None

Drops into pdb.

prev_layout ¶

prev_layout(name: str | None = None) -> None

Switch to the previous layout.

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

prev_screen ¶

prev_screen() -> None

Move to the previous screen.

qtile_info ¶

qtile_info() -> dict

Returns a dictionary of info on the Qtile instance.

qtilecmd ¶

qtilecmd(
    prompt: str = "command",
    widget: str = "prompt",
    messenger: str = "xmessage",
) -> None

Execute a Qtile command using the client syntax.

Tab completion aids navigation of the command tree.

Parameters:

prompt (str, default: 'command' ) –

Text to display at the prompt (default: "command: ").
widget (str, default: 'prompt' ) –

Name of the prompt widget (default: "prompt").
messenger (str, default: 'xmessage' ) –

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

reconfigure_screens ¶

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

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.

register_widget ¶

register_widget(w: _Widget) -> None

Register a bar widget.

If a widget with the same name already exists, the new widget will be automatically renamed by appending numeric suffixes. For example, if the widget is named "foo", we will attempt "foo_1", "foo_2", and so on, until a free name is found.

This naming convention is only used for qtile.widgets_map as every widget MUST be registered here to ensure that objects are finalised correctly.

Widgets can still be accessed by their name when using lazy.screen.widget[name] or lazy.bar["top"].widget[name] unless there are duplicate widgets in the bar/screen.

A warning will be provided where renaming has occurred.

reload_config ¶

reload_config() -> None

Reload the configuration file.

Can also be triggered by sending Qtile a SIGUSR1 signal.

remove_rule ¶

remove_rule(rule_id: int) -> None

Remove a dgroup rule by rule_id.

reserve_space ¶

reserve_space(
    reserved_space: tuple[int, int, int, int],
    screen: Screen,
) -> None

Reserve some space at the edge(s) of a screen.

The requested space is added to space reserved previously: repeated calls to this method are not idempotent.

restart ¶

restart() -> None

Restart Qtile.

Can also be triggered by sending Qtile a SIGUSR2 signal.

run_extension ¶

run_extension(extension: _Extension) -> None

Run extensions.

run_in_executor ¶

run_in_executor(func: Callable, *args: Any) -> Future

A wrapper for running a function in the event loop's default executor.

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.

shutdown ¶

shutdown() -> None

Quit Qtile.

simulate_keypress ¶

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

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

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

Key specification.

Examples:

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

spawn ¶

spawn(
    cmd: list[str] | str,
    shell: bool = False,
    env: dict[str, str] = dict(),
) -> int

Spawn a new process.

Parameters:

cmd (list[str] | str) –

The command to execute either as a single string or list of strings.
shell (bool, default: False ) –

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 (dict[str, str], default: dict() ) –

Dictionary of environmental variables to pass with command.

Examples:

>>> spawn("firefox")

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

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

spawncmd ¶

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

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

Parameters:

prompt (str, default: 'spawn' ) –

Text with which to prompt user (default: "spawn: ").
widget (str, default: 'prompt' ) –

Name of the prompt widget (default: "prompt").
command (str, default: '%s' ) –

command template (default: "%s").
complete (str, default: 'cmd' ) –

Tab completion function (default: "cmd").
shell (bool, default: True ) –

Execute the command with /bin/sh (default: True).
aliases (dict[str, str] | None, default: None ) –

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 ¶

status() -> Literal['OK']

Return "OK" if Qtile is running.

switch_groups ¶

switch_groups(namea: str, nameb: str) -> None

Switch position of two groups by name.

switch_window ¶

switch_window(location: int) -> None

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

switchgroup ¶

switchgroup(
    prompt: str = "group", widget: str = "prompt"
) -> None

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

Parameters:

prompt (str, default: 'group' ) –

Text with which to prompt user (default: "group").
widget (str, default: 'prompt' ) –

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

sync ¶

sync() -> None

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

to_layout_index ¶

to_layout_index(
    index: int, name: str | None = None
) -> None

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

Parameters:

index (int) –

Index of the layout in the list of layouts.
name (str | None, default: None ) –

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

to_screen ¶

to_screen(n: int) -> None

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

Examples:

>>> to_screen(0)

togroup ¶

togroup(
    prompt: str = "group", widget: str = "prompt"
) -> None

Launch prompt widget to move current window to a given group.

Parameters:

prompt (str, default: 'group' ) –

Text with which to prompt user (default: "group").
widget (str, default: 'prompt' ) –

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

tracemalloc_dump ¶

tracemalloc_dump() -> tuple[bool, str]

Dump tracemalloc snapshot.

tracemalloc_toggle ¶

tracemalloc_toggle() -> None

Toggle tracemalloc status.

Running tracemalloc is required for qtile top

ungrab_all_chords ¶

ungrab_all_chords() -> None

Leave all chord modes and grab the root bindings.

ungrab_chord ¶

ungrab_chord() -> None

Leave a chord mode.

ungrab_key ¶

ungrab_key(key: Key | KeyChord) -> None

Ungrab a given key event.

ungrab_keys ¶

ungrab_keys() -> None

Ungrab all key events.

warning ¶

warning() -> None

Set log level to WARNING.

windows ¶

windows() -> list[dict[str, Any]]

Return info for each client window.

Qtile root object¶

Qtile ¶

add_rule ¶

addgroup ¶

async_loop async ¶

call_later ¶

call_soon ¶

call_soon_threadsafe ¶

change_window_order ¶

command ¶

commands ¶

critical ¶

debug ¶

delgroup ¶

display_kb ¶

doc ¶

error ¶

eval ¶

find_closest_screen ¶

find_screen ¶

findwindow ¶

fire_user_hook ¶

focus_screen ¶

free_reserved_space ¶

function ¶

get_groups ¶

get_screens ¶

get_state ¶

get_test_data ¶

grab_button ¶

grab_key ¶

grab_keys ¶

hide_show_bar ¶

info ¶

internal_windows ¶

items ¶

labelgroup ¶

list_widgets ¶

move_to_group ¶

next_layout ¶

next_screen ¶

next_urgent ¶

pause ¶

prev_layout ¶

prev_screen ¶

qtile_info ¶

qtilecmd ¶

reconfigure_screens ¶

register_widget ¶

reload_config ¶

remove_rule ¶

reserve_space ¶

restart ¶

run_extension ¶

run_in_executor ¶

select ¶

shutdown ¶

simulate_keypress ¶

spawn ¶

spawncmd ¶

status ¶

switch_groups ¶

switch_window ¶

switchgroup ¶

sync ¶

to_layout_index ¶

to_screen ¶

togroup ¶

tracemalloc_dump ¶

tracemalloc_toggle ¶

ungrab_all_chords ¶

ungrab_chord ¶

ungrab_key ¶

ungrab_keys ¶

warning ¶

windows ¶

async_loop `async` ¶