Interfaces
Introduction
This page provides an overview of the various interfaces available to interact with Qtile's command graph.
lazy
callswhen running
qtile shell
when running
qtile cmd-obj
when using
CommandClient
orInteractiveCommandClient
in python
The way that these commands are called varies depending on which option you select. However, all interfaces follow the same, basic approach: navigate to the desired object and then execute a command on that object. The following examples illustrate this principle by showing how the same command can be accessed by the various interfaces:
Lazy call:
lazy.widget["volume"].increase_volume()
qtile shell:
> cd widget/volume
widget[volume] > increase_volume()
qtile cmd-obj:
qtile cmd-obj -o widget volume -f increase_volume
CommandClient:
>>> from libqtile.command.client import CommandClient
>>> c = CommandClient()
>>> c.navigate("widget", "volume").call("increase_volume")
InteractiveCommandClient:
>>> from libqtile.command.client import InteractiveCommandClient
>>> c = InteractiveCommandClient()
>>> c.widget["volume"].increase_volume()
The Interfaces
From the examples above, you can see that there are five main interfaces which can be used to interact with Qtile's command graph. Which one you choose will depend on how you intend to use it as each interface is suited to different scenarios.
The
lazy
interface is used in config scripts to bind commands to keys and mouse callbacks.The
qtile shell
is a tool for exploring the graph by presenting it as a file structure. It is not designed to be used for scripting.For users creating shell scripts, the
qtile cmd-obj
interface would be the recommended choice.For users wanting to control Qtile from a python script, there are two available interfaces
libqtile.command.client.CommandClient
andlibqtile.command.client.InteractiveCommandClient
. Users are advised to use theInteractiveCommandClient
as this simplifies the syntax for navigating the graph and calling commands.
The Lazy interface
The lazy.lazy
object is a special helper object to specify a command
for later execution. Lazy objects are typically users' first exposure to Qtile's
command graph but they may not realise it. However, understanding this will
help users when they try using some of the other interfaces listed on this page.
The basic syntax for a lazy command is:
lazy.node[selector].command(arguments)
No node is required when accessing commands on the root node. In addition, multiple nodes can be sequenced if required to navigate to a specific object. For example, bind a key that would focus the next window on the active group on screen 2, you would create a lazy object as follows:
lazy.screen[1].group.next_window()
Note
As noted above, lazy
calls do not call the
relevant command but only create a reference to it. While this makes it
ideal for binding commands to key presses and mouse_callbacks
for
widgets, it also means that lazy
calls cannot be included
in user-defined functions.
qtile shell
The qtile shell maps the command graph to a virtual filesystem that can be navigated in a similar
way. While it is unlikely to be used for scripting, the qtile shell
interface provides an
excellent means for users to navigate and familiarise themselves with the command graph.
For more information, please refer to qtile shell
qtile cmd-obj
qtile cmd-obj
is a command line interface for executing commands on the command graph. It can
be used as a standalone command (e.g. executed directly from the terminal) or incorporated into shell
scripts.
For more information, please refer to qtile cmd-obj
CommandClient
The CommandClient
interface is a low-level python interface for accessing and navigating the
command graph. The low-level nature means that navigation steps must be called explicitly,
rather than being inferred from the body of the calling command.
For example:
from libqtile.command.client import CommandClient
c = CommandClient()
# Call info command on clock widget
info = c.navigate("widget", "clock").call("info")
# Call info command on the screen displaying the clock widget
info = c.navigate("widget", "clock").navigate("screen", None).call("info")
Note from the last example that each navigation step must be called separately. The arguments
passed to navigate()
are node
and selector
. selector
is None
when you wish to access
the default object on that node (e.g. the current screen).
More technical explanation about the python command clients can be found at Executing graph commands: Command Interface.
InteractiveCommandClient
The InteractiveCommandClient
is likely to be the more popular interface for users wishing
to access the command graph via external python scripts. One of the key differences between the
InteractiveCommandClient
and the above CommandClient
is that the InteractiveCommandClient
removes the need to call navigate
and call
explicitly. Instead, the syntax mimics that of
the lazy
interface.
For example, to call the same commands in the above example:
from libqtile.command.client import InteractiveCommandClient
c = InteractiveCommandClient()
# Call info command on clock widget
info = c.widget["clock"].info()
# Call info command on the screen displaying the clock widget
info = c.widget["clock"].screen.info()