Scripting Commands

Here is documented some of the commands available on objects in the command tree when running qshell 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, no_spawn: bool = False, state: Optional[str] = None, socket_path: Optional[str] = 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)[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: Optional[str] = None, layout: Optional[str] = None, layouts: Optional[List[Layout]] = None) bool[source]

Add a group with the given name

cmd_change_vt(vt: int) bool[source]

Change virtual terminal, returning success.

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(*args) 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, Optional[str]]

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, Optional[List[Union[str, int]]]]

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_remove_rule(rule_id: int) None[source]

Remove a dgroup rule by rule_id

cmd_restart() None[source]

Restart qtile

cmd_run_extension(extension: libqtile.extension.base._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, key) 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: Union[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) 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”)

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.

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, Optional[str]]

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, Optional[List[Union[str, int]]]]

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: Optional[List[libqtile.config.Match]] = None, exclusive=False, spawn: Optional[Union[str, List[str]]] = None, layout: Optional[str] = None, layouts: Optional[List] = None, persist=True, init=True, layout_opts=None, screen_affinity=None, position=9223372036854775807, label: Optional[str] = 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: string

the name of this group

matches: default ``None``

list of Match objects whose windows will be assigned to this group

exclusive: boolean

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

spawn: string or list of strings

this will be exec() d when the group is created, you can pass either a program name or a list of programs to exec()

layout: string

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

layouts: list

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

persist: boolean

should this group stay alive with no member windows?

init: boolean

is this group alive when qtile starts?

position int

group position

label: string

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: Optional[Union[libqtile.bar.Bar, libqtile.bar.Gap]] = None, bottom: Optional[Union[libqtile.bar.Bar, libqtile.bar.Gap]] = None, left: Optional[Union[libqtile.bar.Bar, libqtile.bar.Gap]] = None, right: Optional[Union[libqtile.bar.Bar, libqtile.bar.Gap]] = None, wallpaper: Optional[str] = None, wallpaper_mode: Optional[str] = None, x: Optional[int] = None, y: Optional[int] = None, width: Optional[int] = None, height: Optional[int] = None)[source]

A physical screen, and its associated paraphernalia.

Define a screen with a given set of Bars of a specific geometry. Note that bar.Bar objects can only be placed at the top or the bottom of the screen (bar.Gap objects can be placed anywhere). 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, Optional[str]]

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()[source]

Returns a dictionary of info for this screen.

cmd_items(name) Tuple[bool, Optional[List[Union[str, int]]]]

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=False, skip_managed=False)[source]

Switch to the next group

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

Switch to the previous group

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

Resize the screen

cmd_toggle_group(group_name=None, warp=True)[source]

Switch to the selected group or to the previously active one

Window

class libqtile.backend.x11.window.Window(window, qtile)[source]
cmd_bring_to_front()[source]

Bring the window to the front

cmd_commands() List[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_disable_floating()[source]

Tile the window.

cmd_disable_fullscreen()[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()[source]

Decrease the window’s opacity

cmd_enable_floating()[source]

Float the window.

cmd_enable_fullscreen()[source]

Fullscreen the window

cmd_eval(code: str) Tuple[bool, Optional[str]]

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_focus(warp: bool = True) None

Focuses the window.

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

Call a function with current object as argument

cmd_get_position()[source]

Get the (x, y) of the window

cmd_get_size()[source]

Get the (width, height) of the window

cmd_hints()

Returns the X11 hints (WM_HINTS and WM_SIZE_HINTS) for this window.

cmd_info() Dict

Return a dictionary of info.

cmd_inspect()

Tells you more than you ever wanted to know about a window

cmd_items(name) Tuple[bool, Optional[List[Union[str, int]]]]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_kill()[source]

Kill this window

Try to do this politely if the client support this, otherwise be brutal.

cmd_match(*args, **kwargs)[source]
cmd_move_floating(dx, dy)[source]

Move window by dx and dy

cmd_opacity(opacity)[source]

Set the window’s opacity

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

Place the window with the given position and geometry.

cmd_resize_floating(dw, dh)[source]

Add dw and dh to size of window

cmd_set_position(x, y)[source]
cmd_set_position_floating(x, y)[source]

Move window to x and y

cmd_set_size_floating(w, h)[source]

Set window dimensions to w and h

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

If any of the arguments are left unspecified, the values given by the window itself are used instead. So, for a window that’s aware of its appropriate size and location (like dzen), you don’t have to specify anything.

cmd_toggle_floating()[source]

Toggle the floating state of the window.

cmd_toggle_fullscreen()[source]

Toggle the fullscreen state of the window.

cmd_toggle_maximize()[source]

Toggle the fullscreen state of the window.

cmd_toggle_minimize()[source]
cmd_togroup(groupName=None, *, switch_group=False)[source]

Move window to a specified group.

If groupName is not specified, we assume the current group. If switch_group is True, also switch to that group.

Examples

Move window to current group:

togroup()

Move window to group “a”:

togroup("a")

Move window to group “a”, and switch to group “a”:

togroup("a", switch_group=True)
cmd_toscreen(index=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()[source]

Increase the window’s opacity