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, 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_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_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_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_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_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_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_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_restart() None [source]¶
Restart Qtile.
Can also be triggered by sending Qtile a SIGUSR2 signal.
- cmd_screens() List[Dict[str, Any]] [source]¶
Return a list of dictionaries providing information on all screens
- 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, 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_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_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")
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, 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 toexec()
- 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
, andheight
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 thewallpaper_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_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.
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.
- 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() Dict ¶
Return a dictionary of info.
- 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_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_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_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.
- cmd_togroup(group_name: Optional[str] = None, groupName: Optional[str] = None, switch_group: bool = False) None [source]¶
Move window to a specified group
Also switch to that group if switch_group is True.
groupName is deprecated and will be dropped soon. Please use group_name instead.