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_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_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_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_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_layout
(self, group=None)[source]¶ Switch to the next layout.
Parameters: - group :
Group name. If not specified, the current group is assumed
-
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_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_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_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_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”)
-
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
(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.
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 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=None, bottom=None, left=None, right=None, wallpaper=None, wallpaper_mode=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
, 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.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.
- wallpaper: Dict, 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_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.
Window¶
-
class
libqtile.window.
Window
(window, qtile)[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_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_focus
(self, warp=None)¶ Focuses the window.
-
cmd_function
(self, function, *args, **kwargs) → None¶ Call a function with current object as argument
-
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_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)
-