Backend core objects¶

The backend core is the link between the Qtile objects (windows, layouts, groups etc.) and the specific backend (X11 or Wayland). This core should be largely invisible to users and, as a result, these objects do not expose many commands.

Nevertheless, both backends do contain important commands, notably set_keymap on X11 and change_vt used to change to a different TTY on Wayland.

The backend core has no access to other nodes on the command graph.

.. qtile_graph:: :root: core

X11 backend¶

core ¶

Classes:

Core –

Core ¶

Core(display_name: str | None = None)

Bases: Core

Parameters:

display_name (str | None, default: None ) –

The display name to setup the X11 connection to. Uses the DISPLAY environment variable if not given.

Methods:

check_stacking –

Triggers restacking if a fullscreen window loses focus.
command –

Return the command with the given name.
commands –

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

Create an internal window controlled by Qtile.
doc –

Returns the documentation for a specified command name.
eval –

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

Destructor/Clean up resources.
flush –

If needed, flush the backend's event queue.
focus_by_click –

Bring a window to the front.
function –

Call a function with current object as argument.
get_mouse_position –

Get mouse coordinates.
get_screen_info –

Get the screen information.
get_valid_timestamp –

Get a valid timestamp, i.e. not CurrentTime, for X server.
grab_button –

Grab the given mouse button for events.
grab_key –

Map the key to receive events on it.
grab_pointer –

Get the focus for pointer events.
graceful_shutdown –

Try to close windows gracefully before exiting.
handle_event –

Handle an X11 event by forwarding it to the right target.
info –

Get basic information about the running backend.
items –

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

Get the keysym for a key from its name.
lookup_key –

Find the keysym and the modifier mask for the given key.
masked –

A context manager to suppress window events while operating on many windows.
on_config_load –

Assign windows to groups.
remove_listener –

Remove the listener from the given event loop.
select –

Return a selected object.
setup_listener –

Setup a listener for the given qtile instance.
simulate_keypress –

Simulates a keypress on the focused window.
ungrab_buttons –

Un-grab all mouse events.
ungrab_key –

Ungrab the key corresponding to the given keysym and modifier mask.
ungrab_keys –

Ungrab all of the key events.
ungrab_pointer –

Ungrab the focus for pointer events.
update_client_lists –

Updates the _NET_CLIENT_LIST and _NET_CLIENT_LIST_STACKING properties.
update_desktops –

Set the current desktops of the window manager.
warp_pointer –

Warp the pointer to the given coordinates relative.

Attributes:

display_name (str) –

The name of the connected display.
name –

The name of the backend.

display_name `property` ¶

display_name: str

The name of the connected display.

name `property` ¶

name

The name of the backend.

check_stacking ¶

check_stacking(win: Window) -> None

Triggers restacking if a fullscreen window loses focus.

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

create_internal ¶

create_internal(
    x: int,
    y: int,
    width: int,
    height: int,
    desired_depth: int | None = 32,
) -> Internal

Create an internal window controlled by Qtile.

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.

finalize ¶

finalize() -> None

Destructor/Clean up resources.

flush ¶

flush()

If needed, flush the backend's event queue.

focus_by_click ¶

focus_by_click(e, window=None)

Bring a window to the front.

Parameters:

e (xcb event) –

Click event used to determine window to focus.

function ¶

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

Call a function with current object as argument.

get_mouse_position ¶

get_mouse_position() -> tuple[int, int]

Get mouse coordinates.

get_screen_info ¶

get_screen_info() -> list[tuple[int, int, int, int]]

Get the screen information.

get_valid_timestamp ¶

get_valid_timestamp()

Get a valid timestamp, i.e. not CurrentTime, for X server.

It may be used in cases where CurrentTime is unacceptable for X server.

grab_button ¶

grab_button(mouse: Mouse) -> int

Grab the given mouse button for events.

grab_key ¶

grab_key(key: Key | KeyChord) -> tuple[int, int]

Map the key to receive events on it.

grab_pointer ¶

grab_pointer() -> None

Get the focus for pointer events.

graceful_shutdown ¶

graceful_shutdown()

Try to close windows gracefully before exiting.

handle_event ¶

handle_event(event)

Handle an X11 event by forwarding it to the right target.

info ¶

info() -> dict[str, Any]

Get basic information about the running backend.

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

keysym_from_name ¶

keysym_from_name(name: str) -> int

Get the keysym for a key from its name.

lookup_key ¶

lookup_key(key: Key | KeyChord) -> tuple[int, int]

Find the keysym and the modifier mask for the given key.

masked ¶

masked()

A context manager to suppress window events while operating on many windows.

on_config_load ¶

on_config_load(initial) -> None

Assign windows to groups.

remove_listener ¶

remove_listener() -> None

Remove the listener from the given event loop.

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.

setup_listener ¶

setup_listener() -> None

Setup a listener for the given qtile instance.

simulate_keypress ¶

simulate_keypress(modifiers, key)

Simulates a keypress on the focused window.

ungrab_buttons ¶

ungrab_buttons() -> None

Un-grab all mouse events.

ungrab_key ¶

ungrab_key(key: Key | KeyChord) -> tuple[int, int]

Ungrab the key corresponding to the given keysym and modifier mask.

ungrab_keys ¶

ungrab_keys() -> None

Ungrab all of the key events.

ungrab_pointer ¶

ungrab_pointer() -> None

Ungrab the focus for pointer events.

update_client_lists ¶

update_client_lists() -> None

Updates the _NET_CLIENT_LIST and _NET_CLIENT_LIST_STACKING properties.

This is needed for third party tasklists and drag and drop of tabs in chrome

update_desktops ¶

update_desktops(groups, index: int) -> None

Set the current desktops of the window manager.

The list of desktops is given by the list of groups, with the current desktop given by the index

warp_pointer ¶

warp_pointer(x, y)

Warp the pointer to the given coordinates relative.

Wayland backend¶

core ¶

Classes:

Core –
ImplicitGrab –

Keep track of an implicit pointer grab.

Core ¶

Core()

Bases: Core, HasListeners

Methods:

change_vt –

Change virtual terminal to that specified.
check_idle_inhibitor –

Checks if any window that is currently mapped has idle inhibitor and if so inhibits idle.
command –

Return the command with the given name.
commands –

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

Create an internal window controlled by Qtile.
doc –

Returns the documentation for a specified command name.
eval –

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

Destructor/Clean up resources.
flush –

If needed, flush the backend's event queue.
function –

Call a function with current object as argument.
get_inputs –

Get information on all input devices.
get_mouse_position –

Get mouse coordinates.
get_screen_info –

Get the output information.
grab_button –

Configure the backend to grab the mouse event.
grab_key –

Configure the backend to grab the key event.
grab_pointer –

Configure the backend to grab mouse events.
graceful_shutdown –

Try to close windows gracefully before exiting.
hide_cursor –

Hide the cursor.
info –

Get basic information about the running backend.
items –

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

Get the keysym for a key from its name.
masked –

A context manager to suppress window events while operating on many windows.
new_wid –

Get a new unique window ID.
on_config_load –

Respond to config loading.
query_tree –

Get IDs of all mapped windows in ascending Z order.
remove_listener –

Remove the listener from the given event loop.
select –

Return a selected object.
set_keymap –

Set the keymap for the current keyboard.
setup_listener –

Setup a listener for the given qtile instance.
simulate_keypress –

Simulates a keypress on the focused window.
ungrab_buttons –

Release the grabbed button events.
ungrab_key –

Release the given key event.
ungrab_keys –

Release the grabbed key events.
ungrab_pointer –

Release grabbed pointer events.
unhide_cursor –

Unhide the cursor.
update_desktops –

Set the current desktops of the window manager.
warp_pointer –

Warp the pointer to the coordinates in relative to the output layout.

Attributes:

name (str) –

The name of the backend.

name `property` ¶

name: str

The name of the backend.

change_vt ¶

change_vt(vt: int) -> bool

Change virtual terminal to that specified.

check_idle_inhibitor ¶

check_idle_inhibitor() -> None

Checks if any window that is currently mapped has idle inhibitor and if so inhibits idle.

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

create_internal ¶

create_internal(
    x: int, y: int, width: int, height: int
) -> Internal

Create an internal window controlled by Qtile.

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.

finalize ¶

finalize() -> None

Destructor/Clean up resources.

flush ¶

flush() -> None

If needed, flush the backend's event queue.

function ¶

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

Call a function with current object as argument.

get_inputs ¶

get_inputs() -> dict[str, list[dict[str, str]]]

Get information on all input devices.

get_mouse_position ¶

get_mouse_position() -> tuple[int, int]

Get mouse coordinates.

get_screen_info ¶

get_screen_info() -> list[tuple[int, int, int, int]]

Get the output information.

grab_button ¶

grab_button(mouse: Mouse) -> int

Configure the backend to grab the mouse event.

grab_key ¶

grab_key(key: Key | KeyChord) -> tuple[int, int]

Configure the backend to grab the key event.

grab_pointer ¶

grab_pointer() -> None

Configure the backend to grab mouse events.

graceful_shutdown ¶

graceful_shutdown() -> None

Try to close windows gracefully before exiting.

hide_cursor ¶

hide_cursor() -> None

Hide the cursor.

info ¶

info() -> dict[str, Any]

Get basic information about the running backend.

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

keysym_from_name ¶

keysym_from_name(name: str) -> int

Get the keysym for a key from its name.

masked ¶

masked() -> Generator

A context manager to suppress window events while operating on many windows.

new_wid ¶

new_wid() -> int

Get a new unique window ID.

on_config_load ¶

on_config_load(initial: bool) -> None

Respond to config loading.

initial will be True if Qtile just started.

query_tree ¶

query_tree() -> list[int]

Get IDs of all mapped windows in ascending Z order.

remove_listener ¶

remove_listener() -> None

Remove the listener from the given event loop.

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_keymap ¶

set_keymap(
    layout: str | None = None,
    options: str | None = None,
    variant: str | None = None,
) -> None

Set the keymap for the current keyboard.

The options correspond to xkbcommon configuration environmental variables and if not specified are taken from the environment. Acceptable values are strings identical to those accepted by the env variables.

setup_listener ¶

setup_listener() -> None

Setup a listener for the given qtile instance.

simulate_keypress ¶

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

Simulates a keypress on the focused window.

ungrab_buttons ¶

ungrab_buttons() -> None

Release the grabbed button events.

ungrab_key ¶

ungrab_key(key: Key | KeyChord) -> tuple[int, int]

Release the given key event.

ungrab_keys ¶

ungrab_keys() -> None

Release the grabbed key events.

ungrab_pointer ¶

ungrab_pointer() -> None

Release grabbed pointer events.

unhide_cursor ¶

unhide_cursor() -> None

Unhide the cursor.

update_desktops ¶

update_desktops(groups: list[_Group], index: int) -> None

Set the current desktops of the window manager.

warp_pointer ¶

warp_pointer(x: float, y: float) -> None

Warp the pointer to the coordinates in relative to the output layout.

ImplicitGrab ¶

ImplicitGrab(
    core: Core,
    surface: Surface,
    start_x: int,
    start_y: int,
    start_sx: int,
    start_sy: int,
)

Bases: HasListeners

Keep track of an implicit pointer grab.

A Wayland client expects to receive pointer events from the moment a pointer button is pressed on its surface until the moment the button is released. The Wayland protocol leaves this behavior to the compositor.

Backend core objects¶

X11 backend¶

core ¶

Core ¶

display_name property ¶

name property ¶

check_stacking ¶

command ¶

commands ¶

create_internal ¶

doc ¶

eval ¶

finalize ¶

flush ¶

focus_by_click ¶

function ¶

get_mouse_position ¶

get_screen_info ¶

get_valid_timestamp ¶

grab_button ¶

grab_key ¶

grab_pointer ¶

graceful_shutdown ¶

handle_event ¶

info ¶

items ¶

keysym_from_name ¶

lookup_key ¶

masked ¶

on_config_load ¶

remove_listener ¶

select ¶

setup_listener ¶

simulate_keypress ¶

ungrab_buttons ¶

ungrab_key ¶

ungrab_keys ¶

ungrab_pointer ¶

update_client_lists ¶

update_desktops ¶

warp_pointer ¶

Wayland backend¶

core ¶

Core ¶

name property ¶

change_vt ¶

check_idle_inhibitor ¶

command ¶

commands ¶

create_internal ¶

doc ¶

eval ¶

finalize ¶

flush ¶

function ¶

get_inputs ¶

get_mouse_position ¶

get_screen_info ¶

grab_button ¶

grab_key ¶

grab_pointer ¶

graceful_shutdown ¶

hide_cursor ¶

info ¶

items ¶

keysym_from_name ¶

masked ¶

new_wid ¶

on_config_load ¶

query_tree ¶

remove_listener ¶

select ¶

set_keymap ¶

setup_listener ¶

simulate_keypress ¶

ungrab_buttons ¶

ungrab_key ¶

ungrab_keys ¶

ungrab_pointer ¶

unhide_cursor ¶

display_name `property` ¶

name `property` ¶

name `property` ¶