KDE 4.6 PyKDE API Reference

- KDE's Python API

# KWindowSystem Class Reference

`from PyKDE4.kdeui import *`

Inherits: QObject,NET

## Detailed Description

Convenience access to certain properties and features of the window manager.

The class KWindowSystem provides information about the state of the window manager and allows asking the window manager to change them using a more high-level interface than the NETWinInfo/NETRootInfo lowlevel classes.

Because of limitiations of the way Qt is implemented on Mac OSX, the WId's returned by methods in this class are not compatible with those expected by other Qt methods. So while it should be fine to pass WId's retrieved by for example calling the winId method on a QWidget to methods in this class the reverse is not true. You should never pass a WId obtained from this class to a Qt method accepting a WId parameter.

Class for interaction with the window manager.

Author:
  Matthias Ettrich (ettrich@kde.org)

## Enumerations

IconSource | { NETWM, WMHints, ClassHint, XApp }

## Signals

| activeWindowChanged (int id)
| currentDesktopChanged (int desktop)
| desktopNamesChanged ()
| numberOfDesktopsChanged (int num)
| showingDesktopChanged (bool showing)
| stackingOrderChanged ()
| strutChanged ()
| windowAdded (int id)
| windowChanged (int id, long properties)
| windowChanged (int id)
| windowRemoved (int id)
| workAreaChanged ()

## Methods

| __init__ (self)
| connectNotify (self, SIP_SIGNAL a0)

## Static Methods

| activateWindow (int win, long time=0)
int | activeWindow ()
| allowExternalProcessWindowActivation (int pid=-1)
bool | allowedActionsSupported ()
| clearState (int win, long state)
bool | compositingActive ()
QPoint | constrainViewportRelativePosition (QPoint pos)
int | currentDesktop ()
| demandAttention (int win, bool set=1)
QString | desktopName (int desktop)
QPoint | desktopToViewport (int desktop, bool absolute)
| doNotManage (QString title)
| forceActiveWindow (int win, long time=0)
int | groupLeader (int window)
bool | hasWId (int id)
bool | icccmCompliantMappingState ()
QPixmap | icon (int win, int width=-1, int height=-1, bool scale=0)
QPixmap | icon (int win, int width, int height, bool scale, int flags)
| lowerWindow (int win)
bool | mapViewport ()
| minimizeWindow (int win, bool animation=1)
int | numberOfDesktops ()
| raiseWindow (int win)
QString | readNameProperty (int window, long atom)
KWindowSystem | self ()
| setCurrentDesktop (int desktop)
| setDesktopName (int desktop, QString name)
| setExtendedStrut (int win, int left_width, int left_start, int left_end, int right_width, int right_start, int right_end, int top_width, int top_start, int top_end, int bottom_width, int bottom_start, int bottom_end)
| setIcons (int win, QPixmap icon, QPixmap miniIcon)
| setMainWindow (QWidget subwindow, int mainwindow)
| setOnAllDesktops (int win, bool b)
| setOnDesktop (int win, int desktop)
| setState (int win, long state)
| setStrut (int win, int left, int right, int top, int bottom)
| setType (int win, NET.WindowType windowType)
| setUserTime (int win, long time)
bool | showingDesktop ()
[int] | stackingOrder ()
int | transientFor (int window)
| unminimizeWindow (int win, bool animation=1)
int | viewportToDesktop (QPoint pos)
int | viewportWindowToDesktop (QRect r)
KWindowInfo | windowInfo (int win, long properties, long properties2=0)
[int] | windows ()
QRect | workArea (int desktop=-1)
QRect | workArea ([int] excludes, int desktop=-1)

## Signal Documentation

activeWindowChanged | ( | int | id
| ) |  |  |

Hint that <Window> is active (= has focus) now.

Parameters:

  | id | the id of the window that is active

Signal syntax:
  `QObject.connect(source, SIGNAL("activeWindowChanged(WId)"), target_slot)`

currentDesktopChanged | ( | int | desktop
| ) |  |  |

Switched to another virtual desktop.

Parameters:

  | desktop | the number of the new desktop

Signal syntax:
  `QObject.connect(source, SIGNAL("currentDesktopChanged(int)"), target_slot)`

desktopNamesChanged | ( |  | ) |

Desktops have been renamed.

Signal syntax:
  `QObject.connect(source, SIGNAL("desktopNamesChanged()"), target_slot)`

numberOfDesktopsChanged | ( | int | num
| ) |  |  |

The number of desktops changed.

Parameters:

  | num | the new number of desktops

Signal syntax:
  `QObject.connect(source, SIGNAL("numberOfDesktopsChanged(int)"), target_slot)`

showingDesktopChanged | ( | bool | showing
| ) |  |  |

The state of showing the desktop has changed.

Signal syntax:
  `QObject.connect(source, SIGNAL("showingDesktopChanged(bool)"), target_slot)`

stackingOrderChanged | ( |  | ) |

Emitted when the stacking order of the window changed. The new order can be obtained with stackingOrder().

Signal syntax:
  `QObject.connect(source, SIGNAL("stackingOrderChanged()"), target_slot)`

strutChanged | ( |  | ) |

Something changed with the struts, may or may not have changed the work area. Usually just using the workAreaChanged() signal is sufficient.

Signal syntax:
  `QObject.connect(source, SIGNAL("strutChanged()"), target_slot)`

windowAdded | ( | int | id
| ) |  |  |

A window has been added.

Parameters:

  | id | the id of the window

Signal syntax:
  `QObject.connect(source, SIGNAL("windowAdded(WId)"), target_slot)`

windowChanged | ( | int | id,
|  | long | properties
| ) |  |  |

The window changed somehow.

Parameters:

  | id | the id of the window

Signal syntax:
  `QObject.connect(source, SIGNAL("windowChanged(WId, unsigned int)"), target_slot)`

windowChanged | ( | int | id
| ) |  |  |

The window changed somehow.

Parameters:

  | id | the id of the window

Signal syntax:
  `QObject.connect(source, SIGNAL("windowChanged(WId)"), target_slot)`

windowRemoved | ( | int | id
| ) |  |  |

A window has been removed.

Parameters:

  | id | the id of the window that has been removed

Signal syntax:
  `QObject.connect(source, SIGNAL("windowRemoved(WId)"), target_slot)`

workAreaChanged | ( |  | ) |

The workarea has changed.

Signal syntax:
  `QObject.connect(source, SIGNAL("workAreaChanged()"), target_slot)`

## Method Documentation

__init__ | ( |  | self ) |

connectNotify | ( | self, |
|  | SIP_SIGNAL | a0
| ) |  |  |

## Static Method Documentation

activateWindow | ( | int | win,
|  | long | time=0
| ) |  |  |

Requests that window win is activated.

There are two ways how to activate a window, by calling activateWindow() and forceActiveWindow(). Generally, applications shouldn't make attempts to explicitly activate their windows, and instead let the user to activate them. In the special cases where this may be needed, applications should use activateWindow(). Window manager may consider whether this request wouldn't result in focus stealing, which would be obtrusive, and may refuse the request.

The usage of forceActiveWindow() is meant only for pagers and similar tools, which represent direct user actions related to window manipulation. Except for rare cases, this request will be always honored, and normal applications are forbidden to use it.

In case of problems, consult the KWin README in the kdebase package (kdebase/kwin/README), or ask on the kwin@kde.org mailing list.

Parameters:

  | win | the id of the window to make active
  | time | X server timestamp of the user activity that caused this request

int activeWindow | ( |  | ) |

Returns the currently active window, or 0 if no window is active.

Returns:
  the window id of the active window, or 0 if no window is active

allowExternalProcessWindowActivation | ( | int | pid=-1
| ) |  |  |

Allows a window from another process to raise and activate itself. Depending on the window manager, the grant may only be temporary, or for a single activation, and it may require the current process to be the "foreground" one" (ie. the process with the input focus).

You should call this function before executing actions that may trigger the showing of a window or dialog in another process, e.g. a dbus signal or function call, or any other inter-process notification mechanism.

This is mostly used on Windows, where windows are not allowed to be raised and activated if their process is not the foreground one, but it may also apply to other window managers.

Parameters:

  | pid | if specified, the grant only applies to windows belonging to the specific process. By default, a value of -1 means all processes.

bool allowedActionsSupported | ( |  | ) |

Returns true if the WM announces which actions it allows for windows.

clearState | ( | int | win,
|  | long | state
| ) |  |  |

Clears the state of window win from state.

Possible values are or'ed combinations of NET.Modal, NET.Sticky, NET.MaxVert, NET.MaxHoriz, NET.Shaded, NET.SkipTaskbar, NET.SkipPager, NET.Hidden, NET.FullScreen, NET.KeepAbove, NET.KeepBelow, NET.StaysOnTop

Parameters:

  | win | the id of the window
  | state | the flags that will be cleared

bool compositingActive | ( |  | ) |

Returns true if a compositing manager is running (i.e. ARGB windows are supported, effects will be provided, etc.).

QPoint constrainViewportRelativePosition | ( | QPoint | pos
| ) |  |  |

Internal:

Since:
  4.0.1 Checks the relative difference used to move a window will still be inside valid desktop area.

int currentDesktop | ( |  | ) |

Returns the current virtual desktop.

Returns:
  the current virtual desktop

demandAttention | ( | int | win,
|  | bool | set=1
| ) |  |  |

When application finishes some operation and wants to notify the user about it, it can call demandAttention(). Instead of activating the window, which could be obtrusive, the window will be marked specially as demanding user's attention. See also explanation in description of activateWindow().

Note that it's usually better to use KNotifyClient.

QString desktopName | ( | int | desktop
| ) |  |  |

Returns the name of the specified desktop.

Parameters:

  | desktop | the number of the desktop

Returns:
  the name of the desktop

QPoint desktopToViewport | ( | int | desktop,
|  | bool | absolute
| ) |  |  |

Internal:
  Returns topleft corner of the viewport area for the given mapped virtual desktop.

doNotManage | ( | QString | title
| ) |  |  |

Informs kwin via dbus to not manage a window with the specified title.

Useful for swallowing legacy applications, for example java applets.

Parameters:

  | title | the title of the window

forceActiveWindow | ( | int | win,
|  | long | time=0
| ) |  |  |

Sets window win to be the active window. Note that this should be called only in special cases, applications shouldn't force themselves or other windows to be the active window. Generally, this call should used only by pagers and similar tools. See the explanation in description of activateWindow().

Parameters:

  | win | the id of the window to make active
  | time | X server timestamp of the user activity that caused this request

int groupLeader | ( | int | window
| ) |  |  |

Returns the leader window for the group the given window is in, if any.

Parameters:

  | window | the id of the window

bool hasWId | ( | int | id
| ) |  |  |

Test to see if id still managed at present.

Parameters:

  | id | the window id to test

Returns:
  true if the window id is still managed

bool icccmCompliantMappingState | ( |  | ) |

Internal:
  Returns true if the WM uses IconicState also for windows on inactive virtual desktops.

QPixmap icon | ( | int | win,
|  | int | width=-1,
|  | int | height=-1,
|  | bool | scale=0
| ) |  |  |

Overloaded variant that allows specifying from which sources the icon should be read. You should usually prefer the simpler variant which tries all possibilities to get an icon.

Parameters:

  | win | the id of the window
  | width | the desired width, or -1
  | height | the desired height, or -1
  | scale | if true the icon will be scaled to the desired size. Otherwise the icon will not be modified.
  | flags | OR-ed flags from the IconSource enum

QPixmap icon | ( | int | win,
|  | int | width,
|  | int | height,
|  | bool | scale,
|  | int | flags
| ) |  |  |

Overloaded variant that allows specifying from which sources the icon should be read. You should usually prefer the simpler variant which tries all possibilities to get an icon.

Parameters:

  | win | the id of the window
  | width | the desired width, or -1
  | height | the desired height, or -1
  | scale | if true the icon will be scaled to the desired size. Otherwise the icon will not be modified.
  | flags | OR-ed flags from the IconSource enum

lowerWindow | ( | int | win
| ) |  |  |

Lowers the given window. This call is only for pagers and similar tools that represent direct user actions. Applications should not use it, they should keep using QWidget.lower() or XLowerWindow() if necessary.

bool mapViewport | ( |  | ) |

Internal:
  Returns true if viewports are mapped to virtual desktops.

minimizeWindow | ( | int | win,
|  | bool | animation=1
| ) |  |  |

Iconifies a window. Compatible to XIconifyWindow but has an additional parameter animation.

Parameters:

  | win | the id of the window
  | animation | true to show an animation

See also:
  deIconifyWindow()

int numberOfDesktops | ( |  | ) |

Returns the number of virtual desktops.

Returns:
  the number of virtual desktops

raiseWindow | ( | int | win
| ) |  |  |

Raises the given window. This call is only for pagers and similar tools that represent direct user actions. Applications should not use it, they should keep using QWidget.raise() or XRaiseWindow() if necessary.

QString readNameProperty | ( | int | window,
|  | long | atom
| ) |  |  |

Function that reads and returns the contents of the given text property (WM_NAME, WM_ICON_NAME,...).

KWindowSystem self | ( |  | ) |

Access to the singleton instance. Useful mainly for connecting to signals.

setCurrentDesktop | ( | int | desktop
| ) |  |  |

Convenience function to set the current desktop to desktop. See NETRootInfo.

Parameters:

  | desktop | the number of the new desktop

setDesktopName | ( | int | desktop,
|  | QString | name
| ) |  |  |

Sets the name of the specified desktop.

Parameters:

  | desktop | the number of the desktop
  | name | the new name for the desktop

setExtendedStrut | ( | int | win,
|  | int | left_width,
|  | int | left_start,
|  | int | left_end,
|  | int | right_width,
|  | int | right_start,
|  | int | right_end,
|  | int | top_width,
|  | int | top_start,
|  | int | top_end,
|  | int | bottom_width,
|  | int | bottom_start,
|  | int | bottom_end
| ) |  |  |

Sets the strut of window win to to left width ranging from left_start to left_end on the left edge, and simiarly for the other edges. For not reserving a strut, pass 0 as the width. E.g. to reserve 10x10 square in the topleft corner, use e.g. setExtendedStrut( w, 10, 0, 10, 0, 0, 0, 0, 0, 0, 0, 0, 0 ).

Parameters:

  | win | the id of the window
  | left_width | width of the strut at the left edge
  | left_start | starting y coordinate of the strut at the left edge
  | left_end | ending y coordinate of the strut at the left edge
  | right_width | width of the strut at the right edge
  | right_start | starting y coordinate of the strut at the right edge
  | right_end | ending y coordinate of the strut at the right edge
  | top_width | width of the strut at the top edge
  | top_start | starting x coordinate of the strut at the top edge
  | top_end | ending x coordinate of the strut at the top edge
  | bottom_width | width of the strut at the bottom edge
  | bottom_start | starting x coordinate of the strut at the bottom edge
  | bottom_end | ending x coordinate of the strut at the bottom edge

setIcons | ( | int | win,
|  | QPixmap | icon,
|  | QPixmap | miniIcon
| ) |  |  |

Sets an icon and a miniIcon on window win

Parameters:

  | win | the id of the window
  | icon | the new icon
  | miniIcon | the new mini icon

setMainWindow | ( | QWidget | subwindow,
|  | int | mainwindow
| ) |  |  |

Sets the parent window of subwindow to be mainwindow. This overrides the parent set the usual way as the QWidget parent, but only for the window manager - e.g. stacking order and window grouping will be affected, but features like automatic deletion of children when the parent is deleted are unaffected and normally use the QWidget parent.

This function should be used before a dialog is shown for a window that belongs to another application.

setOnAllDesktops | ( | int | win,
|  | bool | b
| ) |  |  |

Sets window win to be present on all virtual desktops if @p is true. Otherwise the window lives only on one single desktop.

Parameters:

  | win | the id of the window
  | b | true to show the window on all desktops, false otherwise

setOnDesktop | ( | int | win,
|  | int | desktop
| ) |  |  |

Moves window win to desktop desktop.

Parameters:

  | win | the id of the window
  | desktop | the number of the new desktop

setState | ( | int | win,
|  | long | state
| ) |  |  |

Sets the state of window win to state.

Possible values are or'ed combinations of NET.Modal, NET.Sticky, NET.MaxVert, NET.MaxHoriz, NET.Shaded, NET.SkipTaskbar, NET.SkipPager, NET.Hidden, NET.FullScreen, NET.KeepAbove, NET.KeepBelow, NET.StaysOnTop

Parameters:

  | win | the id of the window
  | state | the new flags that will be set

setStrut | ( | int | win,
|  | int | left,
|  | int | right,
|  | int | top,
|  | int | bottom
| ) |  |  |

Convenience function for setExtendedStrut() that automatically makes struts as wide/high as the screen width/height. Sets the strut of window win to left, right, top, bottom.

Parameters:

  | win | the id of the window
  | left | the left strut
  | right | the right strut
  | top | the top strut
  | bottom | the bottom strut

setType | ( | int | win,
|  | NET.WindowType | windowType
| ) |  |  |

Sets the type of window win to windowType.

Parameters:

  | win | the id of the window
  | windowType | the type of the window (see NET.WindowType)

setUserTime | ( | int | win,
|  | long | time
| ) |  |  |

Sets user timestamp time on window win. The timestamp is expressed as XServer time. If a window is shown with user timestamp older than the time of the last user action, it won't be activated after being shown. The most common case is the special value 0 which means not to activate the window after being shown.

bool showingDesktop | ( |  | ) |

Returns the state of showing the desktop.

[int] stackingOrder | ( |  | ) |

Returns the list of all toplevel windows currently managed by the window manager in the current stacking order (from lower to higher). May be useful for pagers.

Returns:
  the list of all toplevel windows in stacking order

int transientFor | ( | int | window
| ) |  |  |

Returns the WM_TRANSIENT_FOR property for the given window, i.e. the mainwindow for this window.

Parameters:

  | window | the id of the window

unminimizeWindow | ( | int | win,
|  | bool | animation=1
| ) |  |  |

DeIconifies a window. Compatible to XMapWindow but has an additional parameter animation.

Parameters:

  | win | the id of the window
  | animation | true to show an animation

See also:
  iconifyWindow()

int viewportToDesktop | ( | QPoint | pos
| ) |  |  |

Internal:
  Returns mapped virtual desktop for the given position in the viewport.

int viewportWindowToDesktop | ( | QRect | r
| ) |  |  |

Internal:
  Returns mapped virtual desktop for the given window geometry.

KWindowInfo windowInfo | ( | int | win,
|  | long | properties,
|  | long | properties2=0
| ) |  |  |

Returns information about window win. It is recommended to check whether the returned info is valid by calling the valid() method.

Parameters:

  | win | the id of the window
  | properties | all properties that should be retrieved (see NET.Property enum for details). Unlisted properties cause related information to be invalid in the returned data, but make this function faster when not all data is needed.
  | properties2 | additional properties (see NET.Property2 enum)

Returns:
  the window information

[int] windows | ( |  | ) |

Returns the list of all toplevel windows currently managed by the window manager in the order of creation. Please do not rely on indexes of this list: Whenever you enter Qt's event loop in your application, it may happen that entries are removed or added. Your module should perhaps work on a copy of this list and verify a window with hasWId() before any operations.

Iteration over this list can be done easily with

      QList<WId>.ConstIterator it;
      for ( it = KWindowSystem.windows().begin();
            it != KWindowSystem.windows().end(); ++it ) {
         ... do something here,  (*it) is the current WId.
           }

Returns:
  the list of all toplevel windows

QRect workArea | ( | int | desktop=-1
| ) |  |  |

Returns the workarea for the specified desktop, or the current work area if no desktop has been specified. Excludes struts of clients in the exclude List.

Parameters:

  | excludes | the list of clients whose struts will be excluded
  | desktop | the number of the desktop to check, -1 for the current desktop

Returns:
  the size and position of the desktop

QRect workArea | ( | [int] | excludes,
|  | int | desktop=-1
| ) |  |  |

Returns the workarea for the specified desktop, or the current work area if no desktop has been specified. Excludes struts of clients in the exclude List.

Parameters:

  | excludes | the list of clients whose struts will be excluded
  | desktop | the number of the desktop to check, -1 for the current desktop

Returns:
  the size and position of the desktop

## Enumeration Documentation

IconSource

Masks specifying from which sources to read an icon. They are tried from the best until an icon is found.

- NETWM from property from the window manager specification
- WMHints from WMHints property
- ClassHint load icon after getting name from the classhint
- XApp load the standard X icon (last fallback)

Enumerator:

  NETWM = 1 |
  WMHints = 2 |
  ClassHint = 4 |
  XApp = 8 |