This page provides an overview of the various interfaces available to interact with Qtile's command graph.
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()
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.
lazyinterface is used in config scripts to bind commands to keys and mouse callbacks.
qtile shellis a tool for exploring the graph my presenting it as a file structure. It is not designed to be used for scripting.
For users creating shell scripts, the
qtile cmd-objinterface would be the recommended choice.
For users wanting to control Qtile from a python script, there are two available interfaces
libqtile.command.client.InteractiveCommandClient. Users are advised to use the
InteractiveCommandClientas this simplifies the syntax for navigating the graph and calling commands.
The Lazy interface¶
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:
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:
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
widgets, it also means that
lazy calls cannot be included
in user-defined functions.
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 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
For more information, please refer to qtile cmd-obj
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 explicityly,
rather than being inferred from the body of the calling command.
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
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 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
removes the need to call
call explicitly. Instead, the syntax mimics that of
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()