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 attempt to bind global hotkeys as defined by the mappings in quicktile.cfg.

A typical use of QuickTile’s hotkeys is as follows:

  1. Focus the window you want to tile

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

  3. Repeatedly press one of the defined keybindings to cycle through window sizes available at the desired location on the screen.

This works best when combined with functionality your existing window manager provides (eg. Alt + Tab) to minimize the need to switch your hand between your keyboard and your mouse.

See the Command Reference section for a listing of default keybindings and what they do, or run quicktile --show-bindings and quicktile --show-actions.

Command-Line Invocation

If QuickTile is started without --daemonize but with one or more positional arguments, it will perform the specified 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 useful for invoking QuickTile from incorporating it into shell scripts or binding tiling commands to things XGrabKey can’t see, 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 on encountering an exception within 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, most of the attention paid to QuickTile has been to its function under the influence of --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 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.

Regardless of how you invoke the D-Bus interface, it 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 it uses --daemonize to spin up a persistent event loop shared by the D-Bus and X server client libraries, the D-Bus interface is demonstrably free from all race conditions currently known to affect the command-line interface.