ssokolow / quicktile

# -*- coding: utf-8 -*-

# pylint: disable=line-too-long,too-many-lines

"""QuickTile, a WinSplit clone for X11 desktops

Thanks to Thomas Vander Stichele for some of the documentation cleanups.

@todo:

 - Reconsider use of C{--daemonize}. That tends to imply self-backgrounding.

 - Look into supporting XPyB (the Python equivalent to C{libxcb}) for global

   keybinding.

 - Clean up the code. It's functional, but an ugly rush-job.

 - Implement the secondary major features of WinSplit Revolution (eg.

   process-shape associations, locking/welding window edges, etc.)

 - Consider rewriting L{cycle_dimensions} to allow command-line use to jump to

   a specific index without actually flickering the window through all the

   intermediate shapes.

 - Can I hook into the GNOME and KDE keybinding APIs without using PyKDE or

   gnome-python? (eg. using D-Bus, perhaps?)

@todo: Merge remaining appropriate portions of:

 - U{https://thomas.apestaart.org/thomas/trac/changeset/1123/patches/quicktile/quicktile.py}

 - U{https://thomas.apestaart.org/thomas/trac/changeset/1122/patches/quicktile/quicktile.py}

 - U{https://thomas.apestaart.org/thomas/trac/browser/patches/quicktile/README}

@todo 1.0.0: Retire L{KEYLOOKUP}. (API-breaking change)

@newfield appname: Application Name

"""  # NOQA

__author__ = "Stephan Sokolow (deitarion/SSokolow)"

__appname__ = "QuickTile"

__version__ = "0.2.2"

__license__ = "GNU GPL 2.0 or later"

import errno, logging, os, sys, time

from ConfigParser import RawConfigParser

from heapq import heappop, heappush

from itertools import chain, combinations

from functools import wraps

from UserDict import DictMixin

# TODO: Decide on a way to test this since Nose can't.

#: Used to filter spurious libwnck error messages from stderr since PyGTK

#: doesn't expose g_log_set_handler() to allow proper filtering.

if __name__ == '__main__':  # pragma: nocover

    import subprocess

    glib_log_filter = subprocess.Popen(

            ['grep', '-v', 'Unhandled action type _OB_WM'],

            stdin=subprocess.PIPE)

    # Redirect stderr through grep

    os.dup2(glib_log_filter.stdin.fileno(), sys.stderr.fileno())

try:

    import pygtk

    pygtk.require('2.0')

except ImportError:

    pass  # Apparently Travis-CI's build environment doesn't add this

import gtk, gobject, wnck

logging.basicConfig(level=logging.INFO, format='%(levelname)s: %(message)s')

wnck.set_client_type(wnck.CLIENT_TYPE_PAGER)  # pylint: disable=no-member

try:

    from Xlib import X

    from Xlib.display import Display

    from Xlib.error import BadAccess, DisplayConnectionError

    XLIB_PRESENT = True  #: Indicates presence of python-xlib (runtime check)

except ImportError:

    XLIB_PRESENT = False  #: Indicates presence of python-xlib (runtime check)

DBUS_PRESENT = False  #: Indicates availability of D-Bus (runtime check)

try:

    import dbus.service

    from dbus import SessionBus

    from dbus.exceptions import DBusException

    from dbus.mainloop.glib import DBusGMainLoop

except ImportError:

    pass

else:

    try:

        DBusGMainLoop(set_as_default=True)

        sessBus = SessionBus()  #: D-Bus Session Bus for L{QuickTileApp.run}

    except DBusException:

        pass

    else:

        DBUS_PRESENT = True  #: Indicates availability of D-Bus (runtime check)

#: Location for config files (determined at runtime).

XDG_CONFIG_DIR = os.environ.get('XDG_CONFIG_HOME',

                                os.path.expanduser('~/.config'))

#{ Settings

class GravityLayout(object):  # pylint: disable=too-few-public-methods

    """Helper for translating top-left relative dimensions to other corners.

    Used to generate L{cycle_dimensions} presets.

    Expects to operate on decimal percentage values. (0 <= x <= 1)

    """

    #: Possible window alignments relative to the monitor/desktop.

    #: @todo 1.0.0: Normalize these to X11 or CSS terminology for 1.0

    #:     (API-breaking change)

    GRAVITIES = {

        'top-left': (0.0, 0.0),

        'top': (0.5, 0.0),

        'top-right': (1.0, 0.0),

        'left': (0.0, 0.5),

        'middle': (0.5, 0.5),

        'right': (1.0, 0.5),

        'bottom-left': (0.0, 1.0),

        'bottom': (0.5, 1.0),

        'bottom-right': (1.0, 1.0),

    }

    def __init__(self, margin_x=0, margin_y=0):

        """

        @param margin_x: Horizontal margin to apply when calculating window

            positions, as decimal percentage of screen width.

        @param margin_y: Vertical margin to apply when calculating window

            positions, as decimal percentage of screen height.

        """

        self.margin_x = margin_x

        self.margin_y = margin_y

    # pylint: disable=too-many-arguments

    def __call__(self, w, h, gravity='top-left', x=None, y=None):

        """Return an C{(x, y, w, h)} tuple relative to C{gravity}.

        This function takes and returns percentages, represented as decimals

        in the range 0 <= x <= 1, which can be multiplied by width and height

        values in actual units to produce actual window geometry.

        It can be used in two ways:

          1. If called B{without} C{x} and C{y} values, it will compute a

          geometry tuple which will align a window C{w} wide and C{h} tall

          according to C{geometry}.

          2. If called B{with} C{x} and C{y} values, it will translate a

          geometry tuple which is relative to the top-left corner so that it is

          instead relative to another corner.

        @param w: Desired width

        @param h: Desired height

        @param gravity: Desired window alignment from L{GRAVITIES}

        @param x: Desired horizontal position if not the same as C{gravity}

        @param y: Desired vertical position if not the same as C{gravity}

        @returns: C{(x, y, w, h)}

        @note: All parameters except C{gravity} are decimal values in the range

        C{0 <= x <= 1}.

        """

        x = x or self.GRAVITIES[gravity][0]

        y = y or self.GRAVITIES[gravity][1]

        offset_x = w * self.GRAVITIES[gravity][0]

        offset_y = h * self.GRAVITIES[gravity][1]

        return (x - offset_x + self.margin_x,

                y - offset_y + self.margin_y,

                w - (self.margin_x * 2),

                h - (self.margin_y * 2))

#: Number of columns to base generated L{POSITIONS} presets on

#: @todo: Store COLUMN_COUNT in quicktile.cfg for easy editing

COLUMN_COUNT = 3

def _make_positions():

    """Generate the classic WinSplit Revolution tiling presets

    @todo: Figure out how best to put this in the config file.

    """

    # TODO: Plumb GravityLayout.__init__'s arguments into the config file

    gvlay = GravityLayout()

    col_width = 1.0 / COLUMN_COUNT

    cycle_steps = tuple(col_width * x for x in range(1, COLUMN_COUNT))

    edge_steps = (1.0,) + cycle_steps

    corner_steps = (0.5,) + cycle_steps

    positions = {

        'middle': [gvlay(width, 1, 'middle') for width in edge_steps],

    }

    for grav in ('top', 'bottom'):

        positions[grav] = [gvlay(width, 0.5, grav) for width in edge_steps]

    for grav in ('left', 'right'):

        positions[grav] = [gvlay(width, 1, grav) for width in corner_steps]

    for grav in ('top-left', 'top-right', 'bottom-left', 'bottom-right'):

        positions[grav] = [gvlay(width, 0.5, grav) for width in corner_steps]

    return positions

#: command-to-position mappings for L{cycle_dimensions}

POSITIONS = _make_positions()

#: Default content for the config file

DEFAULTS = {

    'general': {

        # Use Ctrl+Alt as the default base for key combinations

        'ModMask': '<Ctrl><Alt>',

        'UseWorkarea': True,

    },

    'keys': {

        "KP_Enter": "monitor-switch",

        "KP_0": "maximize",

        "KP_1": "bottom-left",

        "KP_2": "bottom",

        "KP_3": "bottom-right",

        "KP_4": "left",

        "KP_5": "middle",

        "KP_6": "right",

        "KP_7": "top-left",

        "KP_8": "top",

        "KP_9": "top-right",

        "V": "vertical-maximize",

        "H": "horizontal-maximize",

        "C": "move-to-center",

    }

}

KEYLOOKUP = {

    ',': 'comma',

    '.': 'period',

    '+': 'plus',

    '-': 'minus',

}  #: Used for resolving certain keysyms

#}

#{ Helpers

def powerset(iterable):

    """C{powerset([1,2,3])} --> C{() (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)}

    @rtype: iterable

    """

    i = list(iterable)

    return chain.from_iterable(combinations(i, j) for j in range(len(i) + 1))

def fmt_table(rows, headers, group_by=None):

    """Format a collection as a textual table.

    @param headers: Header labels for the columns

    @param group_by: Index of the column to group results by.

    @type rows: C{dict} or iterable of iterables

    @type headers: C{list(str)}

    @type group_by: C{int}

    @attention: This uses C{zip()} to combine things. The number of columns

        displayed will be defined by the narrowest of all rows.

    @rtype: C{str}

    """

    output = []

    if isinstance(rows, dict):

        rows = list(sorted(rows.items()))

    groups = {}

    if group_by is not None:

        headers = list(headers)

        headers.pop(group_by)

        rows = [list(row) for row in rows]

        for row in rows:

            group = row.pop(group_by)

            groups.setdefault(group, []).append(row)

    else:

        groups[''] = rows

    # Identify how much space needs to be allocated for each column

    col_maxlens = []

    for pos, header in enumerate(headers):

        maxlen = max(len(x[pos]) for x in rows if len(x) > pos)

        col_maxlens.append(max(maxlen, len(header)))

    def fmt_row(row, pad=' ', indent=0, min_width=0):

        result = []

        for width, label in zip(col_maxlens, row):

            result.append('%s%s ' % (' ' * indent, label.ljust(width, pad)))

        _w = sum(len(x) for x in result)

        if _w < min_width:

            result[-1] = result[-1][:-1]

            result.append(pad * (min_width - _w + 1))

        result.append('\n')

        return result

    # Print the headers and divider

    group_width = max(len(x) for x in groups)

    output.extend(fmt_row(headers))

    output.extend(fmt_row([''] * len(headers), '-', min_width=group_width + 1))

    for group in sorted(groups):

        if group:

            output.append("\n%s\n" % group)

        for row in groups[group]:

            output.extend(fmt_row(row, indent=1))

    return ''.join(output)

class EnumSafeDict(DictMixin):

    """A dict-like object which avoids comparing objects of different types

    to avoid triggering spurious Glib "comparing different enum types"

    warnings.

    """

    def __init__(self, *args):

        self._contents = {}

        for inDict in args:

            for key, val in inDict.items():

                self[key] = val

    def __contains__(self, key):

        ktype = type(key)

        return ktype in self._contents and key in self._contents[ktype]

    def __delitem__(self, key):

        if key in self:

            ktype = type(key)

            section = self._contents[ktype]

            del section[key]

            if not section:

                del self._contents[ktype]

        else:

            raise KeyError(key)

    def __getitem__(self, key):

        if key in self:

            return self._contents[type(key)][key]

        else:

            raise KeyError(key)

    def __iter__(self):

        for section in self._contents.values():

            for key in section.keys():

                yield key

    def __repr__(self):

        return "%s(%s)" % (self.__class__.__name__,

            ', '.join(repr(x) for x in self._contents.values()))

    def __setitem__(self, key, value):

        ktype = type(key)

        self._contents.setdefault(ktype, {})[key] = value

    def iteritems(self):

        return [(key, self[key]) for key in self]

    def keys(self):

        """D.keys() -> list of D's keys"""

        return list(self)

class XInitError(Exception):

    """Raised when something outside our control causes the X11 connection to

       fail.

    """

    def __str__(self):

        return ("%s\n\t(The cause of this error lies outside of QuickTile)" %

                Exception.__str__(self))

#}

class CommandRegistry(object):

    """Handles lookup and boilerplate for window management commands.

    Separated from WindowManager so its lifecycle is not tied to a specific

    GDK Screen object.

    """

    def __init__(self):

        self.commands = {}

        self.help = {}

    def __iter__(self):

        for x in self.commands:

            yield x

    def __str__(self):

        return fmt_table(self.help, ('Known Commands', 'desc'), group_by=1)

    def add(self, name, *p_args, **p_kwargs):

        """Decorator to wrap a function in boilerplate and add it to the

            command registry under the given name.

            @param name: The name to know the command by.

            @param p_args: Positional arguments to prepend to all calls made

                via C{name}.

            @param p_kwargs: Keyword arguments to prepend to all calls made

                via C{name}.

            @type name: C{str}

            """

        def decorate(func):

            """Closure used to allow decorator to take arguments"""

            @wraps(func)

            # pylint: disable=missing-docstring

            def wrapper(winman, window=None, *args, **kwargs):

                # Get Wnck and GDK window objects

                window = window or winman.screen.get_active_window()

                if isinstance(window, gtk.gdk.Window):

                    win = wnck.window_get(window.xid)  # pylint: disable=E1101

                else:

                    win = window

                # pylint: disable=no-member

                if not win:

                    logging.debug("Received no window object to manipulate.")

                    return None

                elif win.get_window_type() == wnck.WINDOW_DESKTOP:

                    logging.debug("Received desktop window object. Ignoring.")

                    return None

                else:

                    # FIXME: Make calls to win.get_* lazy in case --debug

                    #        wasn't passed.

                    logging.debug("Operating on window 0x%x with title \"%s\" "

                                  "and geometry %r",

                                  win.get_xid(), win.get_name(),

                                  win.get_geometry())

                monitor_id, monitor_geom = winman.get_monitor(window)

                use_area, use_rect = winman.get_workarea(

                    monitor_geom, winman.ignore_workarea)

                # TODO: Replace this MPlayer safety hack with a properly

                #       comprehensive exception catcher.

                if not use_rect:

                    logging.debug("Received a worthless value for largest "

                                  "rectangular subset of desktop (%r). Doing "

                                  "nothing.", use_rect)

                    return None

                state = {

                    "cmd_name": name,

                    "monitor_id": monitor_id,

                    "monitor_geom": monitor_geom,

                    "usable_region": use_area,

                    "usable_rect": use_rect,

                }

                args, kwargs = p_args + args, dict(p_kwargs, **kwargs)

                func(winman, win, state, *args, **kwargs)

            if name in self.commands:

                logging.warn("Redefining existing command: %s", name)

            self.commands[name] = wrapper

            help_str = func.__doc__.strip().split('\n')[0].split('. ')[0]

            self.help[name] = help_str.strip('.')

            # Return the unwrapped function so decorators can be stacked

            # to define multiple commands using the same code with different

            # arguments

            return func

        return decorate

    def add_many(self, command_map):

        """Convenience decorator to allow many commands to be defined from

           the same function with different arguments.

           @param command_map: A dict mapping command names to argument lists.

           @type command_map: C{dict}

        """

        def decorate(func):

            """Closure used to allow decorator to take arguments"""

            for cmd, arglist in command_map.items():

                self.add(cmd, *arglist)(func)

            return func

        return decorate

    def call(self, command, winman, *args, **kwargs):

        """Resolve a textual positioning command and execute it."""

        cmd = self.commands.get(command, None)

        if cmd:

            logging.debug("Executing command '%s' with arguments %r, %r",

                          command, args, kwargs)

            cmd(winman, *args, **kwargs)

        else:

            logging.error("Unrecognized command: %s", command)

class WindowManager(object):

    """A simple API-wrapper class for manipulating window positioning."""

    #: Lookup table for internal window gravity support.

    #: (libwnck's support is either unreliable or broken)

    gravities = EnumSafeDict({

        'NORTH_WEST': (0.0, 0.0),

        'NORTH': (0.5, 0.0),

        'NORTH_EAST': (1.0, 0.0),

        'WEST': (0.0, 0.5),

        'CENTER': (0.5, 0.5),

        'EAST': (1.0, 0.5),

        'SOUTH_WEST': (0.0, 1.0),

        'SOUTH': (0.5, 1.0),

        'SOUTH_EAST': (1.0, 1.0),

    })

    key, val = None, None  # Safety cushion for the "del" line.

    for key, val in gravities.items():

        del gravities[key]

        # Support GDK gravity constants

        gravities[getattr(gtk.gdk, 'GRAVITY_%s' % key)] = val

        # Support libwnck gravity constants

        _name = 'WINDOW_GRAVITY_%s' % key.replace('_', '')

        gravities[getattr(wnck, _name)] = val

    # Prevent these temporary variables from showing up in the apidocs

    del _name, key, val

    def __init__(self, screen=None, ignore_workarea=False):

        """

        Initializes C{WindowManager}.

        @param screen: The X11 screen to operate on. If C{None}, the default

            screen as retrieved by C{gtk.gdk.screen_get_default} will be used.

        @type screen: C{gtk.gdk.Screen}

        @todo: Confirm that the root window only changes on X11 server

               restart. (Something which will crash QuickTile anyway since

               PyGTK makes X server disconnects uncatchable.)

               It could possibly change while toggling "allow desktop icons"

               in KDE 3.x. (Not sure what would be equivalent elsewhere)

        """

        self.gdk_screen = screen or gtk.gdk.screen_get_default()

        if self.gdk_screen is None:

            raise XInitError("GTK+ could not open a connection to the X server"

                             " (bad DISPLAY value?)")

        # pylint: disable=no-member

        self.screen = wnck.screen_get(self.gdk_screen.get_number())

        self.ignore_workarea = ignore_workarea

    @classmethod

    def calc_win_gravity(cls, geom, gravity):

        """Calculate the X and Y coordinates necessary to simulate non-topleft

        gravity on a window.

        @param geom: The window geometry to which to apply the corrections.

        @param gravity: A desired gravity chosen from L{gravities}.

        @type geom: C{gtk.gdk.Rectangle}

        @type gravity: C{wnck.WINDOW_GRAVITY_*} or C{gtk.gdk.GRAVITY_*}

        @returns: The coordinates to be used to achieve the desired position.

        @rtype: C{(x, y)}

        """

        grav_x, grav_y = cls.gravities[gravity]

        return (

            int(geom.x - (geom.width * grav_x)),

            int(geom.y - (geom.height * grav_y))

        )

    @staticmethod

    def get_geometry_rel(window, monitor_geom):

        """Get window position relative to the monitor rather than the desktop.

        @param monitor_geom: The rectangle returned by

            C{gdk.Screen.get_monitor_geometry}

        @type window: C{wnck.Window}

        @type monitor_geom: C{gtk.gdk.Rectangle}

        @rtype: C{gtk.gdk.Rectangle}

        """

        win_geom = gtk.gdk.Rectangle(*window.get_geometry())

        win_geom.x -= monitor_geom.x

        win_geom.y -= monitor_geom.y

        return win_geom

    @staticmethod

    def get_monitor(win):

        """Given a Window (Wnck or GDK), retrieve the monitor ID and geometry.

        @type win: C{wnck.Window} or C{gtk.gdk.Window}

        @returns: A tuple containing the monitor ID and geometry.

        @rtype: C{(int, gtk.gdk.Rectangle)}

        """

        # TODO: Look for a way to get the monitor ID without having

        #       to instantiate a gtk.gdk.Window

        if not isinstance(win, gtk.gdk.Window):

            win = gtk.gdk.window_foreign_new(win.get_xid())

        # TODO: How do I retrieve the root window from a given one?

        monitor_id = winman.gdk_screen.get_monitor_at_window(win)

        monitor_geom = winman.gdk_screen.get_monitor_geometry(monitor_id)

        logging.debug(" Window is on monitor %s, which has geometry %s",

                      monitor_id, monitor_geom)

        return monitor_id, monitor_geom

    def get_workarea(self, monitor, ignore_struts=False):

        """Retrieve the usable area of the specified monitor using

        the most expressive method the window manager supports.

        @param monitor: The number or dimensions of the desired monitor.

        @param ignore_struts: If C{True}, just return the size of the whole

            monitor, allowing windows to overlap panels.

        @type monitor: C{int} or C{gtk.gdk.Rectangle}

        @type ignore_struts: C{bool}

        @returns: The usable region and its largest rectangular subset.

        @rtype: C{gtk.gdk.Region}, C{gtk.gdk.Rectangle}

        """

        if isinstance(monitor, int):

            usable_rect = self.gdk_screen.get_monitor_geometry(monitor)

            logging.debug("Retrieved geometry %s for monitor #%s",

                          usable_rect, monitor)

        elif not isinstance(monitor, gtk.gdk.Rectangle):

            logging.debug("Converting geometry %s to gtk.gdk.Rectangle",

                          monitor)

            usable_rect = gtk.gdk.Rectangle(monitor)

        else:

            usable_rect = monitor

        usable_region = gtk.gdk.region_rectangle(usable_rect)

        if not usable_region.get_rectangles():

            logging.error("get_workarea received an empty monitor region!")

        if ignore_struts:

            logging.debug("Panels ignored. Reported monitor geometry is:\n%s",

                          usable_rect)

            return usable_region, usable_rect

        root_win = self.gdk_screen.get_root_window()

        struts = []

        if self.gdk_screen.supports_net_wm_hint("_NET_WM_STRUT_PARTIAL"):

            # Gather all struts

            struts.append(root_win.property_get("_NET_WM_STRUT_PARTIAL"))

            if self.gdk_screen.supports_net_wm_hint("_NET_CLIENT_LIST"):

                # Source: http://stackoverflow.com/a/11332614/435253

                for wid in root_win.property_get('_NET_CLIENT_LIST')[2]:

                    w = gtk.gdk.window_foreign_new(wid)

                    struts.append(w.property_get("_NET_WM_STRUT_PARTIAL"))

            struts = [x[2] for x in struts if x]

            logging.debug("Gathered _NET_WM_STRUT_PARTIAL values:\n\t%s",

                          struts)

            # Subtract the struts from the usable region

            _Sub = lambda *g: usable_region.subtract(

                gtk.gdk.region_rectangle(g))

            _w, _h = self.gdk_screen.get_width(), self.gdk_screen.get_height()

            for g in struts:  # pylint: disable=invalid-name

                # http://standards.freedesktop.org/wm-spec/1.5/ar01s05.html

                # XXX: Must not cache unless watching for notify events.

                _Sub(0, g[4], g[0], g[5] - g[4] + 1)             # left

                _Sub(_w - g[1], g[6], g[1], g[7] - g[6] + 1)     # right

                _Sub(g[8], 0, g[9] - g[8] + 1, g[2])             # top

                _Sub(g[10], _h - g[3], g[11] - g[10] + 1, g[3])  # bottom

            # Generate a more restrictive version used as a fallback

            usable_rect = usable_region.copy()

            _Sub = lambda *g: usable_rect.subtract(gtk.gdk.region_rectangle(g))

            for geom in struts:

                # http://standards.freedesktop.org/wm-spec/1.5/ar01s05.html

                # XXX: Must not cache unless watching for notify events.

                _Sub(0, geom[4], geom[0], _h)             # left

                _Sub(_w - geom[1], geom[6], geom[1], _h)  # right

                _Sub(0, 0, _w, geom[2])                   # top

                _Sub(0, _h - geom[3], _w, geom[3])        # bottom

                # TODO: The required "+ 1" in certain spots confirms that we're

                #       going to need unit tests which actually check that the

                #       WM's code for constraining windows to the usable area

                #       doesn't cause off-by-one bugs.

                # TODO: Share this on http://stackoverflow.com/q/2598580/435253

            usable_rect = usable_rect.get_clipbox()

        elif self.gdk_screen.supports_net_wm_hint("_NET_WORKAREA"):

            desktop_geo = tuple(root_win.property_get('_NET_WORKAREA')[2][0:4])

            logging.debug("Falling back to _NET_WORKAREA: %s", desktop_geo)

            usable_region.intersect(gtk.gdk.region_rectangle(desktop_geo))

            usable_rect = usable_region.get_clipbox()

        # FIXME: Only call get_rectangles if --debug

        logging.debug("Usable region of monitor calculated as:\n"

                      "\tRegion: %r\n\tRectangle: %r",

                      usable_region.get_rectangles(), usable_rect)

        return usable_region, usable_rect

    def get_workspace(self, window=None, direction=None):

        """Get a workspace relative to either a window or the active one.

        @param window: The point of reference. C{None} for the active workspace

        @param direction: The direction in which to look, relative to the point

            of reference. Accepts the following types:

             - C{wnck.MotionDirection}: Non-cycling direction

             - C{int}: Relative index in the list of workspaces

             - C{None}: Just get the workspace object for the point of

               reference

        @type window: C{wnck.Window} or C{None}

        @rtype: C{wnck.Workspace} or C{None}

        @returns: The workspace object or C{None} if no match could be found.

        """

        if window:

            cur = window.get_workspace()

        else:

            cur = self.screen.get_active_workspace()

        if not cur:

            return None  # It's either pinned or on no workspaces

        # pylint: disable=no-member

        if isinstance(direction, wnck.MotionDirection):

            nxt = cur.get_neighbor(direction)

        elif isinstance(direction, int):

            nxt = winman.screen.get_workspace((cur.get_number() + direction) %

                    winman.screen.get_workspace_count())

        elif direction is None:

            nxt = cur

        else:

            nxt = None

            logging.warn("Unrecognized direction: %r", direction)

        return nxt

    @classmethod

    def reposition(cls,

            win,

            geom=None,

            monitor=gtk.gdk.Rectangle(0, 0, 0, 0),

            keep_maximize=False,

            gravity=wnck.WINDOW_GRAVITY_NORTHWEST,

            geometry_mask=wnck.WINDOW_CHANGE_X | wnck.WINDOW_CHANGE_Y |

                wnck.WINDOW_CHANGE_WIDTH | wnck.WINDOW_CHANGE_HEIGHT

                   ):  # pylint: disable=no-member,too-many-arguments

        """

        Position and size a window, decorations inclusive, according to the

        provided target window and monitor geometry rectangles.

        If no monitor rectangle is specified, position relative to the desktop

        as a whole.

        @param win: The C{wnck.Window} to operate on.

        @param geom: The new geometry for the window. Can be left unspecified

            if the intent is to move the window to another monitor without

            repositioning it.

        @param monitor: The frame relative to which C{geom} should be

            interpreted. The whole desktop if unspecified.

        @param keep_maximize: Whether to re-maximize a maximized window after

            un-maximizing it to move it.

        @param gravity: A constant specifying which point on the window is

            referred to by the X and Y coordinates in C{geom}.

        @param geometry_mask: A set of flags determining which aspects of the

            requested geometry should actually be applied to the window.

            (Allows the same geometry definition to easily be shared between

            operations like move and resize.)

        @type win: C{gtk.gdk.Window}

        @type geom: C{gtk.gdk.Rectangle}

        @type monitor: C{gtk.gdk.Rectangle}

        @type keep_maximize: C{bool}

        @type gravity: U{WnckWindowGravity<https://developer.gnome.org/libwnck/stable/WnckWindow.html#WnckWindowGravity>} or U{GDK Gravity Constant<http://www.pygtk.org/docs/pygtk/gdk-constants.html#gdk-gravity-constants>}

        @type geometry_mask: U{WnckWindowMoveResizeMask<https://developer.gnome.org/libwnck/2.30/WnckWindow.html#WnckWindowMoveResizeMask>}

        @todo 1.0.0: Look for a way to accomplish this with a cleaner method

            signature. This is getting a little hairy. (API-breaking change)

        """  # NOQA

        # We need to ensure that ignored values are still present for

        # gravity calculations.

        old_geom = winman.get_geometry_rel(win, winman.get_monitor(win)[1])

        if geom:

            for attr in ('x', 'y', 'width', 'height'):

                if not geometry_mask & getattr(wnck,

                        'WINDOW_CHANGE_%s' % attr.upper()):

                    setattr(geom, attr, getattr(old_geom, attr))

        else:

            geom = old_geom

        # Unmaximize and record the types we may need to restore

        max_types, maxed = ['', '_horizontally', '_vertically'], []

        for maxtype in max_types:

            if getattr(win, 'is_maximized' + maxtype)():

                maxed.append(maxtype)

                getattr(win, 'unmaximize' + maxtype)()

        # Apply gravity and resolve to absolute desktop coordinates.

        new_x, new_y = cls.calc_win_gravity(geom, gravity)

        new_x += monitor.x

        new_y += monitor.y

        logging.debug(" Repositioning to (%d, %d, %d, %d)\n",

                new_x, new_y, geom.width, geom.height)

        # XXX: I'm not sure whether wnck, Openbox, or both are at fault,

        #      but window gravities seem to have no effect beyond double-

        #      compensating for window border thickness unless using

        #      WINDOW_GRAVITY_STATIC.

        #

        #      My best guess is that the gravity modifiers are being applied

        #      to the window frame rather than the window itself, hence why

        #      static gravity would position correctly and north-west gravity

        #      would double-compensate for the titlebar and border dimensions.

        #

        #      ...however, that still doesn't explain why the non-topleft

        #      gravities have no effect. I'm guessing something's just broken.

        win.set_geometry(wnck.WINDOW_GRAVITY_STATIC, geometry_mask,

                new_x, new_y, geom.width, geom.height)

        # Restore maximization if asked

        if maxed and keep_maximize:

            for maxtype in maxed:

                getattr(win, 'maximize' + maxtype)()

class KeyBinder(object):

    """A convenience class for wrapping C{XGrabKey}."""

    #: @todo: Figure out how to set the modifier mask in X11 and use

    #:        C{gtk.accelerator_get_default_mod_mask()} to feed said code.

    ignored_modifiers = ['Mod2Mask', 'LockMask']

    #: Used to pass state from L{handle_xerror}

    keybind_failed = False

    def __init__(self, xdisplay=None):

        """Connect to X11 and the Glib event loop.

        @param xdisplay: A C{python-xlib} display handle.

        @type xdisplay: C{Xlib.display.Display}

        """

        try:

            self.xdisp = xdisplay or Display()

        except (UnicodeDecodeError, DisplayConnectionError), err:

            raise XInitError("python-xlib failed with %s when asked to open"

                             " a connection to the X server. Cannot bind keys."

                             "\n\tIt's unclear why this happens, but it is"

                             " usually fixed by deleting your ~/.Xauthority"

                             " file and rebooting."

                             % err.__class__.__name__)

        self.xroot = self.xdisp.screen().root

        self._keys = {}

        # Resolve these at runtime to avoid NameErrors

        self.ignored_modifiers = [getattr(X, name) for name in

                self.ignored_modifiers]

        # We want to receive KeyPress events

        self.xroot.change_attributes(event_mask=X.KeyPressMask)

        # Set up a handler to catch XGrabKey() failures

        self.xdisp.set_error_handler(self.handle_xerror)

        # Merge python-xlib into the Glib event loop

        # Source: http://www.pygtk.org/pygtk2tutorial/sec-MonitoringIO.html

        gobject.io_add_watch(self.xroot.display,

                             gobject.IO_IN, self.handle_xevent)

    def bind(self, accel, callback):

        """Bind a global key combination to a callback.

        @param accel: An accelerator as either a string to be parsed by

            C{gtk.accelerator_parse()} or a tuple as returned by it.)

        @param callback: The function to call when the key is pressed.

        @type accel: C{str} or C{(int, gtk.gdk.ModifierType)} or C{(int, int)}

        @type callback: C{function}

        @returns: A boolean indicating whether the provided keybinding was

            parsed successfully. (But not whether it was registered

            successfully due to the asynchronous nature of the C{XGrabKey}

            request.)

        @rtype: C{bool}

        """

        if isinstance(accel, basestring):

            # pylint: disable=no-member

            keysym, modmask = gtk.accelerator_parse(accel)

        else:

            keysym, modmask = accel

        if not gtk.accelerator_valid(keysym, modmask):  # pylint: disable=E1101

            logging.error("Invalid keybinding: %s", accel)

            return False

        if modmask > 2**16 - 1:

            logging.error("Modifier out of range for XGrabKey "

                          "(int(modmask) > 65535). "

                          "Did you use <Super> instead of <Mod4>?")

            return False

        # Convert to what XGrabKey expects

        keycode = self.xdisp.keysym_to_keycode(keysym)

        if isinstance(modmask, gtk.gdk.ModifierType):

            modmask = modmask.real

        # Ignore modifiers like Mod2 (NumLock) and Lock (CapsLock)

        for mmask in self._vary_modmask(modmask, self.ignored_modifiers):

            self._keys.setdefault(keycode, []).append((mmask, callback))

            self.xroot.grab_key(keycode, mmask,

                    1, X.GrabModeAsync, X.GrabModeAsync)

        # If we don't do this, then nothing works.

        # I assume it flushes the XGrabKey calls to the server.

        self.xdisp.sync()

        if self.keybind_failed:

            self.keybind_failed = False

            logging.warning("Failed to bind key. It may already be in use: %s",

                accel)

    def handle_xerror(self, err, _):

        """Used to identify when attempts to bind keys fail.

        @note: If you can make python-xlib's C{CatchError} actually work or if

               you can retrieve more information to show, feel free.

        """

        if isinstance(err, BadAccess):

            self.keybind_failed = True

        else:

            self.xdisp.display.default_error_handler(err)

    def handle_xevent(self, src, cond, handle=None):  # pylint: disable=W0613

        """Dispatch C{XKeyPress} events to their callbacks.

        @rtype: C{True}

        @todo: Make sure uncaught exceptions are prevented from making

            quicktile unresponsive in the general case.

        """

        handle = handle or self.xroot.display

        for _ in range(0, handle.pending_events()):

            xevent = handle.next_event()

            if xevent.type == X.KeyPress:

                if xevent.detail in self._keys:

                    for mmask, callback in self._keys[xevent.detail]:

                        if mmask == xevent.state:

                            # FIXME: Only call accelerator_name if --debug

                            # FIXME: Proper "index" arg for keycode_to_keysym

                            keysym = self.xdisp.keycode_to_keysym(

                                xevent.detail, 0)

                            # pylint: disable=no-member

                            kb_str = gtk.accelerator_name(keysym, xevent.state)

                            logging.debug("Received keybind: %s", kb_str)

                            callback()

                            break

                        elif mmask == 0:

                            logging.debug("X11 returned null modifier!")

                            callback()

                            break

                    else:

                        logging.error("Received an event for a recognized key "

                                  "with unrecognized modifiers: %s, %s",

                                  xevent.detail, xevent.state)

                else:

                    logging.error("Received an event for an unrecognized "

                        "keybind: %s, %s", xevent.detail, xevent.state)

        # Necessary for proper function

        return True

    @staticmethod

    def _vary_modmask(modmask, ignored):

        """Generate all possible variations on C{modmask} that need to be

        taken into consideration if we can't properly ignore the modifiers in

        C{ignored}. (Typically NumLock and CapsLock)

        @param modmask: A bitfield to be combinatorically grown.

        @param ignored: Modifiers to be combined with C{modmask}.

        @type modmask: C{int} or C{gtk.gdk.ModifierType}

        @type ignored: C{list(int)}

        @rtype: generator of C{type(modmask)}

        """

        for ignored in powerset(ignored):

            imask = reduce(lambda x, y: x | y, ignored, 0)

            yield modmask | imask

#: The instance of L{CommandRegistry} to be used in 99.9% of use cases.

commands = CommandRegistry()

#{ Tiling Commands

@commands.add_many(POSITIONS)

def cycle_dimensions(winman, win, state, *dimensions):

    """Cycle the active window through a list of positions and shapes.

    Takes one step each time this function is called.

    If the window's dimensions are not within 100px (by euclidean distance)

    of an entry in the list, set them to the first list entry.

    @param dimensions: A list of tuples representing window geometries as

        floating-point values between 0 and 1, inclusive.

    @type dimensions: C{[(x, y, w, h), ...]}

    @type win: C{gtk.gdk.Window}

    @returns: The new window dimensions.

    @rtype: C{gtk.gdk.Rectangle}

    """

    win_geom = winman.get_geometry_rel(win, state['monitor_geom'])

    usable_region = state['usable_region']

    # Get the bounding box for the usable region (overlaps panels which

    # don't fill 100% of their edge of the screen)

    clip_box = usable_region.get_clipbox()

    logging.debug("Selected preset sequence:\n\t%r", dimensions)

    # Resolve proportional (eg. 0.5) and preserved (None) coordinates

    dims = []

    for tup in dimensions:

        current_dim = []

        for pos, val in enumerate(tup):

            if val is None:

                current_dim.append(tuple(win_geom)[pos])

            else:

                # FIXME: This is a bit of an ugly way to get (w, h, w, h)

                # from clip_box.

                current_dim.append(int(val * tuple(clip_box)[2 + pos % 2]))

        dims.append(current_dim)