Welcome to pyewmh’s documentation!

Contents:

The ewmh python module

This module intends to provide an implementation of Extended Window Manager Hints, based on the Xlib modules for python.

See the freedesktop.org specification for more information.

EWMH class

class ewmh.ewmh.EWMH(_display=None, root=None)

This class provides the ability to get and set properties defined by the EWMH spec.

Each property can be accessed in two ways. For example, to get the active window:

win = ewmh.getActiveWindow()
# or: win = ewmh.getProperty('_NET_ACTIVE_WINDOW')

Similarly, to set the active window:

ewmh.setActiveWindow(myWindow)
# or: ewmh.setProperty('_NET_ACTIVE_WINDOW', myWindow)

When a property is written, don’t forget to really send the notification by flushing requests:

ewmh.display.flush()
Parameters:
  • _display – the display to use. If not given, Xlib.display.Display() is used.
  • root – the root window to use. If not given, self.display.screen().root is used.
NET_WM_ACTIONS = ('_NET_WM_ACTION_MOVE', '_NET_WM_ACTION_RESIZE', '_NET_WM_ACTION_MINIMIZE', '_NET_WM_ACTION_SHADE', '_NET_WM_ACTION_STICK', '_NET_WM_ACTION_MAXIMIZE_HORZ', '_NET_WM_ACTION_MAXIMIZE_VERT', '_NET_WM_ACTION_FULLSCREEN', '_NET_WM_ACTION_CHANGE_DESKTOP', '_NET_WM_ACTION_CLOSE', '_NET_WM_ACTION_ABOVE', '_NET_WM_ACTION_BELOW')

List of strings representing all known window actions.

NET_WM_STATES = ('_NET_WM_STATE_MODAL', '_NET_WM_STATE_STICKY', '_NET_WM_STATE_MAXIMIZED_VERT', '_NET_WM_STATE_MAXIMIZED_HORZ', '_NET_WM_STATE_SHADED', '_NET_WM_STATE_SKIP_TASKBAR', '_NET_WM_STATE_SKIP_PAGER', '_NET_WM_STATE_HIDDEN', '_NET_WM_STATE_FULLSCREEN', '_NET_WM_STATE_ABOVE', '_NET_WM_STATE_BELOW', '_NET_WM_STATE_DEMANDS_ATTENTION')

List of strings representing all known window states.

NET_WM_WINDOW_TYPES = ('_NET_WM_WINDOW_TYPE_DESKTOP', '_NET_WM_WINDOW_TYPE_DOCK', '_NET_WM_WINDOW_TYPE_TOOLBAR', '_NET_WM_WINDOW_TYPE_MENU', '_NET_WM_WINDOW_TYPE_UTILITY', '_NET_WM_WINDOW_TYPE_SPLASH', '_NET_WM_WINDOW_TYPE_DIALOG', '_NET_WM_WINDOW_TYPE_DROPDOWN_MENU', '_NET_WM_WINDOW_TYPE_POPUP_MENU', '_NET_WM_WINDOW_TYPE_NOTIFICATION', '_NET_WM_WINDOW_TYPE_COMBO', '_NET_WM_WINDOW_TYPE_DND', '_NET_WM_WINDOW_TYPE_NORMAL')

List of strings representing all known window types.

getActiveWindow()

Get the current active (toplevel) window or None (property _NET_ACTIVE_WINDOW)

Returns:Window object or None
getClientList()

Get the list of windows maintained by the window manager for the property _NET_CLIENT_LIST.

Returns:list of Window objects
getClientListStacking()

Get the list of windows maintained by the window manager for the property _NET_CLIENT_LIST_STACKING.

Returns:list of Window objects
getCurrentDesktop()

Get the current desktop number (property _NET_CURRENT_DESKTOP)

Returns:int
getDesktopGeometry()

Get the desktop geometry (property _NET_DESKTOP_GEOMETRY) as an array of two integers [width, height].

Returns:[int, int]
getDesktopViewPort()

Get the current viewports of each desktop as a list of [x, y] representing the top left corner (property _NET_DESKTOP_VIEWPORT).

Returns:list of [int, int]
getNumberOfDesktops()

Get the number of desktops (property _NET_NUMBER_OF_DESKTOPS).

Returns:int
getProperty(prop, *args, **kwargs)

Get the value of a property. See the corresponding method for the required arguments. For example, for the property _NET_WM_STATE, look for getWmState()

getReadableProperties()

Get all the readable properties’ names

getShowingDesktop()

Get the value of “showing the desktop” mode of the window manager (property _NET_SHOWING_DESKTOP). 1 means the mode is activated, and 0 means deactivated.

Returns:int
getWmAllowedActions(win, str=False)

Get the list of allowed actions for the given window (property _NET_WM_ALLOWED_ACTIONS).

Parameters:
  • win – the window object
  • str – True to get a list of string allowed actions instead of int
Returns:

list of (int|str)

getWmDesktop(win)

Get the current desktop number of the given window (property _NET_WM_DESKTOP).

Parameters:win – the window object
Returns:int
getWmName(win)

Get the property _NET_WM_NAME for the given window as a string.

Parameters:win – the window object
Returns:str
getWmPid(win)

Get the pid of the application associated to the given window (property _NET_WM_PID)

Parameters:win – the window object
getWmState(win, str=False)

Get the list of states of the given window (property _NET_WM_STATE).

Parameters:
  • win – the window object
  • str – True to get a list of string states instead of int
Returns:

list of (int|str)

getWmVisibleName(win)

Get the property _NET_WM_VISIBLE_NAME for the given window as a string.

Parameters:win – the window object
Returns:str
getWmWindowType(win, str=False)

Get the list of window types of the given window (property _NET_WM_WINDOW_TYPE).

Parameters:
  • win – the window object
  • str – True to get a list of string types instead of int
Returns:

list of (int|str)

getWorkArea()

Get the work area for each desktop (property _NET_WORKAREA) as a list of [x, y, width, height]

Returns:a list of [int, int, int, int]
getWritableProperties()

Get all the writable properties names

setActiveWindow(win)

Set the given window active (property _NET_ACTIVE_WINDOW)

Parameters:win – the window object
setCloseWindow(win)

Close the given window (property _NET_CLOSE_WINDOW)

Parameters:win – the window object
setCurrentDesktop(i)

Set the current desktop (property _NET_CURRENT_DESKTOP).

Parameters:i – the desired desktop number
setDesktopGeometry(w, h)

Set the desktop geometry (property _NET_DESKTOP_GEOMETRY)

Parameters:
  • w – desktop width
  • h – desktop height
setDesktopViewport(w, h)

Set the viewport size of the current desktop (property _NET_DESKTOP_VIEWPORT)

Parameters:
  • w – desktop width
  • h – desktop height
setMoveResizeWindow(win, gravity=0, x=None, y=None, w=None, h=None)

Set the property _NET_MOVERESIZE_WINDOW to move or resize the given window. Flags are automatically calculated if x, y, w or h are defined.

Parameters:
  • win – the window object
  • gravity – gravity (one of the Xlib.X.*Gravity constant or 0)
  • x – int or None
  • y – int or None
  • w – int or None
  • h – int or None
setNumberOfDesktops(nb)

Set the number of desktops (property _NET_NUMBER_OF_DESKTOPS).

Parameters:nb – the number of desired desktops
setProperty(prop, *args, **kwargs)

Set the value of a property by sending an event on the root window. See the corresponding method for the required arguments. For example, for the property _NET_WM_STATE, look for setWmState()

setShowingDesktop(show)

Set/unset the mode Showing desktop (property _NET_SHOWING_DESKTOP)

Parameters:show – 1 to set the desktop mode, else 0
setWmDesktop(win, i)

Move the window to the desired desktop by changing the property _NET_WM_DESKTOP.

Parameters:
  • win – the window object
  • i – desired desktop number
setWmName(win, name)

Set the property _NET_WM_NAME

Parameters:
  • win – the window object
  • name – desired name
setWmState(win, action, state, state2=0)

Set/unset one or two state(s) for the given window (property _NET_WM_STATE).

Parameters:
  • win – the window object
  • action – 0 to remove, 1 to add or 2 to toggle state(s)
  • state (int or str (see NET_WM_STATES)) – a state
  • state2 (int or str (see NET_WM_STATES)) – a state or 0
setWmVisibleName(win, name)

Set the property _NET_WM_VISIBLE_NAME

Parameters:
  • win – the window object
  • name – desired visible name

Examples

These examples are tested on gnome.

Exemple to set the active window in fullscreen mode:

from ewmh import EWMH
ewmh = EWMH()

# get the active window
win = ewmh.getActiveWindow()

# list all possible names states:
# print EWMH.NET_WM_STATES

# set the state on win
ewmh.setWmState(win, 1, '_NET_WM_STATE_FULLSCREEN')

# flush request
ewmh.display.flush()

Exemple to move every iceweasel windows on desktop 2:

from ewmh import EWMH
ewmh = EWMH()

# get every displayed windows
wins = ewmh.getClientList()

# get every iceweasel windows, by looking their class name:
icewins = filter(lambda w: w.get_wm_class()[1] == 'Iceweasel', wins)

# move them to desktop 2 (desktop numbering starts from 0):
for w in icewins:
  ewmh.setWmDesktop(w, 1)

# flush requests
ewmh.display.flush()

Example trying to close every windows on desktop 2:

from ewmh import EWMH
ewmh = EWMH()

# get every displayed windows on desktop 2:
wins = filter(lambda w: ewmh.getWmDesktop(w) == 1, ewmh.getClientList())

# trying to close them:
for w in wins:
  ewmh.setCloseWindow(w)

# flush requests
ewmh.display.flush()

Indices and tables