Window Manager API Wrapper (wm.py)

Wrapper around libwnck for interacting with the window manager

class WindowManager(screen=None, x_display=None)[source]

A simple API-wrapper class for manipulating window positioning.

Parameters
Raises

XInitError – None was specified for x_display and the attempt to open a new X connection failed.

_property_prep(win, name)[source]

Common code for get_property and set_property

Parameters

  • win (Union[Gdk.Window, Wnck.Window, int]) – A GTK or Wnck Window object or a raw X11 window ID.

  • name (Union[str, int]) – An atom name or a handle returned by Xlib.display.Display.create_resource_object().

get_monitor(win)[source]

Given a window, retrieve the ID and geometry of the monitor it’s on.

Parameters

win (Wnck.Window) – The window to find the containing monitor for.

Return type

Tuple[int, Rectangle]

Returns

(monitor_id, geometry)

get_property(win, name, prop_type, empty=None)[source]

Get the value of the X11 property name on window win

Parameters

  • win (Union[Gdk.Window, Wnck.Window, int]) – A GTK or Wnck Window object or a raw X11 window ID.

  • name (Union[str, int]) – An atom name or a handle returned by Xlib.display.Display.create_resource_object().

  • prop_type (int) – A constant from Xlib.Xatom

  • empty (Any) – The value to return if the property is unset.

As this is a semi-internal API not meriting too much work to make pretty, the design follows the underlying XGetWindowProperty API.

Some variable names have been changed to avoid colliding with Python built-ins while others are abstracted away to present a simpler API.

prop_type instructs the client library how to correctly un-marshall the data it receives.

get_relevant_windows(workspace)[source]

Wrapper for Wnck.Screen.get_windows() that filters out windows of type Wnck.WindowType.DESKTOP or Wnck.WindowType.DOCK.

Parameters

workspace (Wnck.Workspace) – The virtual desktop to retrieve windows from.

Return type

Iterable[Wnck.Window]

get_workspace(window=None, direction=None, wrap_around=True)[source]

Get a workspace (virtual desktop) relative to the one containing the given or active window.

Parameters

  • window (Optional[Wnck.Window]) – The point of reference. None for the active workspace.

  • direction (Optional[int]) –

    The direction in which to look, relative to the point of reference. Accepts the following types:

    • Wnck.MotionDirection: Absolute direction (will not cycle around when it reaches the edge)

    • int: Relative position in the list of workspaces (eg. 1 or -2).

    • None: The workspace containing window

  • wrap_around (bool) – Whether relative indexes should wrap around.

Return type

Optional[Wnck.Workspace]

Returns

The workspace object or None if no match was found.

static is_relevant(window)[source]

Return False if the window should be ignored.

(i.e. If it’s the desktop or a panel)

Parameters

window (Wnck.Window) –

Return type

bool

reposition(win, geom=None, monitor=Rectangle(x=0, y=0, width=0, height=0), keep_maximize=False, geometry_mask=<flags WNCK_WINDOW_CHANGE_X | WNCK_WINDOW_CHANGE_Y | WNCK_WINDOW_CHANGE_WIDTH | WNCK_WINDOW_CHANGE_HEIGHT of type Wnck.WindowMoveResizeMask>)[source]

Move and resize a window, decorations inclusive, according to the provided target window and monitor geometry rectangles.

If no monitor rectangle is specified, the target position will be relative to the desktop as a whole.

Parameters

  • win (Wnck.Window) – The window to reposition.

  • geom (Optional[Rectangle]) – The new geometry for the window. Can be left unspecified if the intent is to move the window to another monitor without repositioning it.

  • monitor (Rectangle) – The frame relative to which geom should be interpreted. The whole desktop if unspecified.

  • keep_maximize (bool) – Whether to re-maximize the window if it had to be un-maximized to ensure it would move.

  • geometry_mask (Wnck.WindowMoveResizeMask) – 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.)

Return type

None

set_property(win, name, value, prop_type=31, format_size=8)[source]

Set the value of X11 property name on window win to the contents of value.

Parameters

  • win (Union[Gdk.Window, Wnck.Window, int]) – A GTK or Wnck Window object or a raw X11 window ID.

  • name (Union[str, int]) – An atom name or a handle returned by Xlib.display.Display.create_resource_object().

  • value – The value to be stored

  • prop_type (int) – A constant from Xlib.Xatom

  • format_size (int) – The size of the value in bits.

As this is a semi-internal API not meriting too much work to make pretty, the design follows the underlying XChangeProperty API, which expects a C-style “list of items as a packed sequence of bits with out-of-band metadata” data type.

Some variable names have been changed to avoid colliding with Python built-ins while others are abstracted away to present a simpler API.

prop_type is metadata for the X client library to correctly un-marshall the data later and the server doesn’t use it for anything.

format_size specifies the size of an item in the sequence (even if it’s a sequence of length 1) and is also necessary for correct operation if the X server decides that it needs to byte-swap the values.

This is why format_size is necessary for things where you’d think that prop_type would be enough to describe the data type.

update_geometry_cache()[source]

Update the internal cache of monitor & panel shapes by querying them from the desktop and processing them into a quicktile.util.UsableRegion.

Raises

Exception – Unable to retrieve monitor geometries

persist_maximization(win, keep_maximize=True)[source]

Context manager to persist maximization state after a call to WindowManager.reposition.

Parameters

  • win (Wnck.Window) – The window to operate on.

  • keep_maximize (bool) – If False, this decoration becomes a no-op to ease writing clean code which needs to support both behaviours.