Window Manager API Wrapper (wm.py)

Wrapper around libwnck for interacting with the window manager

class WindowManager(screen=None, x_display=None)

A simple API-wrapper class for manipulating window positioning.

Parameters:

• screen (Gdk.Screen) – The screen to operate on. If None, the default screen as retrieved by Gdk.Screen.get_default will be used.

• x_display (Optional[Display]) – The Xlib.display.Display to operate on. If None, a new X connection will be created.

Raises:

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

get_monitor(win)

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)

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)

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)

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

Parameters:

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

• direction (Union[Wnck.MotionDirection, 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)

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=(0, 0, 0, 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>)

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)

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()

Update the internal cache of monitor & panel shapes by querying them from the desktop, either using _GTK_WORKAREAS_D0 or by running and processing them into a quicktile.util.UsableRegion.

Raises:

Exception – Unable to retrieve monitor geometries

update_workarea_manually()

Query strut information manually to update the geometry cache.

Raises:

Exception – Unable to retrieve monitor geometries

persist_maximization(win, keep_maximize=True)

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.