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, config, eventloop, no_spawn=False, state=None)[source]

This object is the root of the command graph

cmd_add_rule(self, match_args, rule_args, min_priorty=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 prioriry (last) (default: False)

cmd_addgroup(self, group, label=None, layout=None, layouts=None)[source]

Add a group with the given name

cmd_commands(self) → List[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_critical(self)[source]

Set log level to CRITICAL

cmd_debug(self)[source]

Set log level to DEBUG

cmd_delgroup(self, group)[source]

Delete a group with the given name

cmd_display_kb(self, *args)[source]

Display table of key bindings

cmd_doc(self, name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_error(self)[source]

Set log level to ERROR

cmd_eval(self, code: str) → Tuple[bool, Union[str, NoneType]]

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(self, prompt='window', widget='prompt')[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_focus_by_click(self, e)[source]

Bring a window to the front

Parameters:
e : xcb event

Click event used to determine window to focus

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

Call a function with current object as argument

cmd_get_info(self)[source]

Prints info for all groups

cmd_get_state(self)[source]

Get pickled state for restarting qtile

cmd_get_test_data(self)[source]

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

cmd_groups(self)[source]

Return a dictionary containing information for all groups

Examples

groups()

cmd_hide_show_bar(self, position='all')[source]

Toggle visibility of a given bar

Parameters:
position :

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

cmd_info(self)[source]

Set log level to INFO

cmd_internal_windows(self)[source]

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

cmd_items(self, name) → Tuple[bool, List[str]]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_list_widgets(self)[source]

List of all addressible widget names

cmd_loglevel(self)[source]
cmd_loglevelname(self)[source]
cmd_next_layout(self, group=None)[source]

Switch to the next layout.

Parameters:
group :

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

cmd_next_screen(self)[source]

Move to next screen

cmd_next_urgent(self)[source]

Focus next window with urgent hint

cmd_pause(self)[source]

Drops into pdb

cmd_prev_layout(self, group=None)[source]

Switch to the previous layout.

Parameters:
group :

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

cmd_prev_screen(self)[source]

Move to the previous screen

cmd_qtile_info(self)[source]

Returns a dictionary of info on the Qtile instance

cmd_qtilecmd(self, prompt='command', widget='prompt', messenger='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_remove_rule(self, rule_id)[source]

Remove a dgroup rule by rule_id

cmd_restart(self)[source]

Restart qtile

cmd_run_extension(self, extension)[source]

Run extensions

cmd_run_external(self, full_path)[source]

Run external Python script

cmd_screens(self)[source]

Return a list of dictionaries providing information on all screens

cmd_shutdown(self)[source]

Quit Qtile

cmd_simulate_keypress(self, modifiers, key)[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(self, cmd)[source]

Run cmd in a shell.

cmd may be a string, which is parsed by shlex.split, or a list (similar to subprocess.Popen).

Examples

spawn(“firefox”)

spawn([“xterm”, “-T”, “Temporary terminal”])

cmd_spawncmd(self, prompt='spawn', widget='prompt', command='%s', complete='cmd')[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(self)[source]

Return “OK” if Qtile is running

cmd_switch_groups(self, groupa, groupb)[source]

Switch position of groupa to groupb

cmd_switchgroup(self, prompt='group', widget='prompt')[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(self)[source]

Sync the X display. Should only be used for development

cmd_to_layout_index(self, index, group=None)[source]

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

Parameters:
index :

Index of the layout in the list of layouts.

group :

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

cmd_to_screen(self, n)[source]

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

Examples

to_screen(0)

cmd_togroup(self, prompt='group', widget='prompt')[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(self)[source]

Dump tracemalloc snapshot

cmd_tracemalloc_toggle(self)[source]

Toggle tracemalloc status

Running tracemalloc is required for qtile-top

cmd_warning(self)[source]

Set log level to WARNING

cmd_windows(self)[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.
opacity 1 Bar window opacity.
cmd_commands(self) → List[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(self, name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(self, code: str) → Tuple[bool, Union[str, NoneType]]

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(self, 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(self, function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info(self)

Info for this object.

cmd_items(self, name) → Tuple[bool, List[str]]

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, matches=None, exclusive=False, spawn=None, layout=None, layouts=None, persist=True, init=True, layout_opts=None, screen_affinity=None, position=9223372036854775807, label=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=None, bottom=None, left=None, right=None, x=None, y=None, width=None, height=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’.

Parameters:
top: Gap/Bar object, or None.
bottom: Gap/Bar object, or None.
left: Gap/Bar object, or None.
right: Gap/Bar object, or None.
x : int or None
y : int or None
width : int or None
height : int or None
cmd_commands(self) → List[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_doc(self, name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_eval(self, code: str) → Tuple[bool, Union[str, NoneType]]

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(self, function, *args, **kwargs) → None

Call a function with current object as argument

cmd_info(self)[source]

Returns a dictionary of info for this screen.

cmd_items(self, name) → Tuple[bool, List[str]]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_next_group(self, skip_empty=False, skip_managed=False)[source]

Switch to the next group

cmd_prev_group(self, skip_empty=False, skip_managed=False)[source]

Switch to the previous group

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

Resize the screen

cmd_toggle_group(self, group_name=None)[source]

Switch to the selected group or to the previously active one

cmd_togglegroup(self, groupName=None)[source]

Switch to the selected group or to the previously active one

Deprecated: use toggle_group()

Window

class libqtile.window.Window(window, qtile)[source]
cmd_bring_to_front(self)[source]
cmd_commands(self) → List[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

cmd_disable_floating(self)[source]
cmd_disable_fullscreen(self)[source]
cmd_disable_maximize(self)[source]
cmd_disable_minimize(self)[source]
cmd_doc(self, name) → str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

cmd_down_opacity(self)[source]
cmd_enable_floating(self)[source]
cmd_enable_fullscreen(self)[source]
cmd_enable_maximize(self)[source]
cmd_enable_minimize(self)[source]
cmd_eval(self, code: str) → Tuple[bool, Union[str, NoneType]]

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(self, warp=None)

Focuses the window.

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

Call a function with current object as argument

cmd_get_position(self)[source]
cmd_get_size(self)[source]
cmd_info(self)

Returns a dictionary of info for this object

cmd_inspect(self)

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

cmd_items(self, name) → Tuple[bool, List[str]]

Returns a list of contained items for the specified name

Used by __qsh__ to allow navigation of the object graph.

cmd_kill(self)[source]

Kill this window

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

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

Move window by dx and dy

cmd_opacity(self, opacity)[source]
cmd_resize_floating(self, dw, dh)[source]

Add dw and dh to size of window

cmd_set_position(self, dx, dy)[source]
cmd_set_position_floating(self, x, y)[source]

Move window to x and y

cmd_set_size_floating(self, w, h)[source]

Set window dimensions to w and h

cmd_static(self, screen, x, y, width, height)[source]
cmd_toggle_floating(self)[source]
cmd_toggle_fullscreen(self)[source]
cmd_toggle_maximize(self)[source]
cmd_toggle_minimize(self)[source]
cmd_togroup(self, 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(self, 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(self)[source]