Scripting Commands

Here is documented some of the commands available on objects in the command tree when running qtile shell or scripting commands to qtile. Note that this is an incomplete list, some objects, such as layouts and widgets, may implement their own set of commands beyond those given here.

Qtile

class libqtile.core.manager.Qtile(kore: base.Core, config: Config, no_spawn: bool = False, state: str | None = None, socket_path: str | None = None)[source]

This object is the root of the command graph

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

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

Add a group with the given name

cmd_commands() list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_critical() None[source]

Set log level to CRITICAL

cmd_debug() None[source]

Set log level to DEBUG

cmd_delgroup(group: str) None[source]

Delete a group with the given name

cmd_display_kb() str[source]

Display table of key bindings

cmd_doc(name) str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_error() None[source]

Set log level to ERROR

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

cmd_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")

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

Call a function with current object as argument

cmd_get_state() str[source]

Get pickled state for restarting qtile

cmd_get_test_data() Any[source]

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

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

Return a dictionary containing information for all groups

Examples

groups()

cmd_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")

cmd_info() None[source]

Set log level to INFO

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

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

cmd_items(name) tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_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")

cmd_list_widgets() list[str][source]

List of all addressible widget names

cmd_loglevel() int[source]
cmd_loglevelname() str[source]
cmd_next_layout(name: Optional[str] = None) None[source]

Switch to the next layout.

Parameters
name

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

cmd_next_screen() None[source]

Move to next screen

cmd_next_urgent() None[source]

Focus next window with urgent hint

cmd_pause() None[source]

Drops into pdb

cmd_prev_layout(name: Optional[str] = None) None[source]

Switch to the previous layout.

Parameters
name

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

cmd_prev_screen() None[source]

Move to the previous screen

cmd_qtile_info() dict[source]

Returns a dictionary of info on the Qtile instance

cmd_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")

cmd_reconfigure_screens(ev: Any = None) 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 ev kwarg is ignored; it is here in case this function is hooked directly to screen_change.

cmd_reload_config() None[source]

Reload the configuration file.

Can also be triggered by sending Qtile a SIGUSR1 signal.

cmd_remove_rule(rule_id: int) None[source]

Remove a dgroup rule by rule_id

cmd_restart() None[source]

Restart Qtile.

Can also be triggered by sending Qtile a SIGUSR2 signal.

cmd_run_extension(extension: _Extension) None[source]

Run extensions

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

Return a list of dictionaries providing information on all screens

cmd_shutdown() None[source]

Quit Qtile

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

Simulates a keypress on the focused window.

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

cmd_spawn(cmd: str | list[str], shell: bool = False) int[source]

Run cmd, in a shell or not (default).

cmd may be a string or a list (similar to subprocess.Popen).

Examples

spawn("firefox")

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

cmd_spawncmd(prompt: str = 'spawn', widget: str = 'prompt', command: str = '%s', complete: str = 'cmd', shell: bool = True, aliases: Optional[dict[str, str]] = 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.

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

Return "OK" if Qtile is running

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

Switch position of two groups by name

cmd_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")

cmd_sync() None[source]

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

cmd_to_layout_index(index: str, name: Optional[str] = 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.

cmd_to_screen(n: int) None[source]

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

Examples

to_screen(0)

cmd_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")

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

Dump tracemalloc snapshot

cmd_tracemalloc_toggle() None[source]

Toggle tracemalloc status

Running tracemalloc is required for qtile top

cmd_ungrab_all_chords() None[source]

Leave all chord modes and grab the root bindings

cmd_ungrab_chord() None[source]

Leave a chord mode

cmd_validate_config() None[source]
cmd_warning() None[source]

Set log level to WARNING

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

Return info for each client window

Bar

class libqtile.bar.Bar(widgets, size, **config)[source]

A bar, which can contain widgets

Parameters
widgets

A list of widget objects.

size

The "thickness" of the bar, i.e. the height of a horizontal bar, or the width of a vertical bar.

key

default

description

background

'#000000'

Background colour.

border_color

'#000000'

Border colour as str or list of str [N E S W]

border_width

0

Width of border as int of list of ints [N E S W]

margin

0

Space around bar as int or list of ints [N E S W].

opacity

1

Bar window opacity.

cmd_commands() list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

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

cmd_fake_button_press(screen, position, x, y, button=1)[source]

Fake a mouse-button-press 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"

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

Call a function with current object as argument

cmd_info()

Info for this object.

cmd_items(name) tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

Group

class libqtile.config.Group(name: str, matches: list[Match] | None = None, exclusive: bool = False, spawn: str | list[str] | None = None, layout: str | None = None, layouts: list[str] | None = None, persist: bool = True, init: bool = True, layout_opts: dict[str, Any] | None = None, screen_affinity: int | None = None, position: int = 9223372036854775807, label: str | None = None)[source]

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:

The name of this group.

matches:

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

exclusive:

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

spawn:

This will be exec() d when the group is created. Tou can pass either a program name or a list of programs to exec()

layout:

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:

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

persist:

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

init:

Should this group be alive when Qtile starts?

layout_opts:

Options to pass to a layout.

screen_affinity:

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

position:

The position of this group.

label:

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.

Screen

class libqtile.config.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, x: int | None = None, y: int | None = None, width: int | None = None, height: int | None = None)[source]

A physical screen, and its associated paraphernalia.

Define a screen with a given set of 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.

cmd_commands() list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(name) str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

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

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

Call a function with current object as argument

cmd_info() dict[str, int][source]

Returns a dictionary of info for this screen.

cmd_items(name) tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_next_group(skip_empty: bool = False, skip_managed: bool = False) None[source]

Switch to the next group

cmd_prev_group(skip_empty: bool = False, skip_managed: bool = False, warp: bool = True) None[source]

Switch to the previous group

cmd_resize(x: Optional[int] = None, y: Optional[int] = None, w: Optional[int] = None, h: Optional[int] = None) None[source]

Resize the screen

cmd_set_wallpaper(path: str, mode: Optional[str] = None) None[source]

Set the wallpaper to the given file.

cmd_toggle_group(group_name: Optional[str] = None, warp: bool = True) None[source]

Switch to the selected group or to the previously active one

Window

class libqtile.backend.base.Window[source]

A regular Window belonging to a client.

Abstract methods are required to be defined as part of a specific backend's implementation. Non-abstract methods have default implementations here to be shared across backends.

abstract cmd_bring_to_front() None[source]

Bring the window to the front

cmd_center() None[source]

Centers a floating window on the screen.

cmd_commands() list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

abstract cmd_disable_floating() None[source]

Tile the window.

abstract cmd_disable_fullscreen() None[source]

Un-fullscreen the window

cmd_doc(name) str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_down_opacity() None[source]

Decrease the window's opacity by 10%.

abstract cmd_enable_floating() None[source]

Float the window.

abstract cmd_enable_fullscreen() None[source]

Fullscreen the window

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

abstract cmd_focus(warp: bool = True) None[source]

Focuses the window.

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

Call a function with current object as argument

abstract cmd_get_position() tuple[int, int][source]

Get the (x, y) of the window

abstract cmd_get_size() tuple[int, int][source]

Get the (width, height) of the window

cmd_info() dict

Return a dictionary of info.

cmd_is_visible() bool

Is this window visible (i.e. not hidden)?

cmd_items(name) tuple[bool, list[str | int] | None]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

abstract cmd_kill() None[source]

Kill the window. Try to be polite.

cmd_match(*args, **kwargs) bool[source]
abstract cmd_move_floating(dx: int, dy: int) None[source]

Move window by dx and dy

cmd_opacity(opacity: float) None[source]

Set the window's opacity.

The value must be between 0 and 1 inclusive.

abstract cmd_place(x, y, width, height, borderwidth, bordercolor, above=False, margin=None) None[source]

Place the window with the given position and geometry.

abstract cmd_resize_floating(dw: int, dh: int) None[source]

Add dw and dh to size of window

abstract cmd_set_position(x: int, y: int) None[source]

Move floating window to x and y; swap tiling window with the window under the pointer.

abstract cmd_set_position_floating(x: int, y: int) None[source]

Move window to x and y

abstract cmd_set_size_floating(w: int, h: int) None[source]

Set window dimensions to w and h

abstract cmd_static(screen: Optional[int] = None, x: Optional[int] = None, y: Optional[int] = None, width: Optional[int] = None, height: Optional[int] = None) None[source]

Makes this window a static window, attached to a Screen.

Values left unspecified are taken from the existing window state.

abstract cmd_toggle_floating() None[source]

Toggle the floating state of the window.

abstract cmd_toggle_fullscreen() None[source]

Toggle the fullscreen state of the window.

abstract cmd_toggle_maximize() None[source]

Toggle the maximize state of the window.

abstract cmd_toggle_minimize() None[source]

Toggle the minimize state of the window.

cmd_togroup(group_name: Optional[str] = None, groupName: Optional[str] = None, switch_group: bool = False, toggle: bool = False) None[source]

Move window to a specified group

Also switch to that group if switch_group is True.

If toggle is True and and the specified group is already on the screen, use the last used group as target instead.

groupName is deprecated and will be dropped soon. Please use group_name instead.

cmd_toscreen(index: Optional[int] = None) None[source]

Move window to a specified screen.

If index is not specified, we assume the current screen

Examples

Move window to current screen:

toscreen()

Move window to screen 0:

toscreen(0)
cmd_up_opacity() None[source]

Increase the window's opacity by 10%.