Usage

QuickTile is built around a simple model of applying tiling commands to either the active window or, for some commands, the desktop as a whole.

These commands can be invoked in one of three ways:

Global Hotkeys

If QuickTile is started with the --daemonize option, it will try to bind global hotkeys as defined by the mappings in quicktile.cfg.

A typical use of QuickTile’s hotkeys is:

  1. Focus the window you want to tile (eg. with Alt + Tab)

  2. Hold the modifiers defined in ModMask (Ctrl Alt by default).

  3. Repeatedly press one of the keybindings to cycle through window sizes available at the requested location.

See the Command Reference section for a listing of default keybindings and what they do, or run quicktile --show-actions to list all available commands and quicktile --show-bindings to list commands that have hotkeys bound to them.

Command-Line Invocation

If QuickTile is started without --daemonize but with one or more positional arguments, it will perform the given sequence of actions on the active window (or, depending on the command, on the desktop as a whole) and then exit.

$ quicktile top-left top-left

This is intended for incorporating QuickTile into shell scripts or triggering it from places its internal keybinding system can’t watch, such as LIRC-based remote controls via irexec(1).

If running this in a context where it is undesirable for your script to block and display an error dialog upon encountering an unexpected bug in QuickTile, please pass --no-excepthook when invoking QuickTile.

For more details on QuickTile’s command-line interface, run quicktile --help or see the Command-Line Arguments section of this manual.

Note

Historically, QuickTile has received most of its testing under --daemonize and command-line invocation has known bugs in how it interacts with the X server.

Most notably, when multiple commands are specified on a single command-line, it triggers a race condition where QuickTile doesn’t properly wait for a command’s effects to take hold before the next command begins querying window shapes.

The simplest demonstration of this on a mulit-monitor system is quicktile monitor-next top-left which will cause the top-left to reverse the effect of the monitor-next.

A fix for this is intended, but the non-trivial re-architecting involved means that I don’t want to do it until after the automated test suite is sufficiently complete.

D-Bus API

Command-line invocation is useful but it does have a tendency to induce a perceptible delay between pressing a key/button and having the window respond.

If dbus-python is installed, the --daemonize command-line option will also attempt to claim the com.ssokolow.QuickTile service name.

It will expose a single object path (/com/ssokolow/QuickTile) with a single interface (com.ssokolow.QuickTile) containing a single method (doCommand) which can be used to call tiling commands as if invoked by the global keybinding code.

A good way to test this out is using Qt’s qdbus command, which serves as both a command-line D-Bus explorer and a client for calling D-Bus methods.

$ qdbus com.ssokolow.QuickTile
/
/com
/com/ssokolow
/com/ssokolow/QuickTile
$ qdbus com.ssokolow.QuickTile /com/ssokolow/QuickTile
method QString org.freedesktop.DBus.Introspectable.Introspect()
method bool com.ssokolow.QuickTile.doCommand(QString command)
$ qdbus com.ssokolow.QuickTile /com/ssokolow/QuickTile \
    doCommand top-left
true
[terminal window is repositioned to the screen's top-left quarter]

The more ubiquitous dbus-send command can also be used to accomplish the same thing, but it’s much less convenient to work with and cannot double as a D-Bus browser:

$ dbus-send --type=method_call       \
    --dest=com.ssokolow.QuickTile    \
    /com/ssokolow/QuickTile          \
    com.ssokolow.QuickTile.doCommand \
    string:top-left

The bool returned by doCommand indicates whether the given name was found in the list of registered tiling commands.

Both of these commands can also be used as drop-in replacements for the command-line interface as long as quicktile --daemonize has been started beforehand.

While it takes more work to set up, the D-Bus interface has two advantages over the command-line interface:

  • qdbus and dbus-send start more quickly than QuickTile, so this is likely to have lower latency even if being invoked from a shell script rather than doing a direct D-Bus call from a resident process to QuickTile.

  • Because the D-Bus and X11 client libraries share the same --daemonize event loop, the D-Bus interface is free from known race conditions currently affecting the command-line interface.