KWindowSystem Class Reference

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

#include <kwindowsystem.h>

Inheritance diagram for KWindowSystem:

List of all members.

Public Types
enum	IconSource { NETWM = 1, WMHints = 2, ClassHint = 4, XApp = 8 }
Signals
void	activeWindowChanged (WId id)
void	currentDesktopChanged (int desktop)
void	desktopNamesChanged ()
void	numberOfDesktopsChanged (int num)
void	showingDesktopChanged (bool showing)
void	stackingOrderChanged ()
void	strutChanged ()
void	windowAdded (WId id)
void	windowChanged (WId id, unsigned int properties)
void	windowChanged (WId id)
void	windowChanged (WId id, const unsigned long *properties)
void	windowRemoved (WId id)
void	workAreaChanged ()
Static Public Member Functions
static void	activateWindow (WId win, long time=0)
static WId	activeWindow ()
static bool	allowedActionsSupported ()
static void	allowExternalProcessWindowActivation (int pid=-1)
static void	clearState (WId win, unsigned long state)
static bool	compositingActive ()
static QPoint	constrainViewportRelativePosition (const QPoint &pos)
static int	currentDesktop ()
static void	demandAttention (WId win, bool set=true)
static QString	desktopName (int desktop)
static QPoint	desktopToViewport (int desktop, bool absolute)
static void	doNotManage (const QString &title)
static void	forceActiveWindow (WId win, long time=0)
static WId	groupLeader (WId window)
static bool	hasWId (WId id)
static bool	icccmCompliantMappingState ()
static QPixmap	icon (WId win, int width=-1, int height=-1, bool scale=false)
static QPixmap	icon (WId win, int width, int height, bool scale, int flags)
static void	lowerWindow (WId win)
static bool	mapViewport ()
static void	minimizeWindow (WId win, bool animation=true)
static int	numberOfDesktops ()
static void	raiseWindow (WId win)
static QString	readNameProperty (WId window, unsigned long atom)
static KWindowSystem *	self ()
static void	setCurrentDesktop (int desktop)
static void	setDesktopName (int desktop, const QString &name)
static void	setExtendedStrut (WId 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)
static void	setIcons (WId win, const QPixmap &icon, const QPixmap &miniIcon)
static void	setMainWindow (QWidget *subwindow, WId mainwindow)
static void	setOnAllDesktops (WId win, bool b)
static void	setOnDesktop (WId win, int desktop)
static void	setState (WId win, unsigned long state)
static void	setStrut (WId win, int left, int right, int top, int bottom)
static void	setType (WId win, NET::WindowType windowType)
static void	setUserTime (WId win, long time)
static bool	showingDesktop ()
static QList< WId >	stackingOrder ()
static WId	transientFor (WId window)
static void	unminimizeWindow (WId win, bool animation=true)
static int	viewportToDesktop (const QPoint &pos)
static int	viewportWindowToDesktop (const QRect &r)
static KWindowInfo	windowInfo (WId win, unsigned long properties, unsigned long properties2=0)
static const QList< WId > &	windows ()
static QRect	workArea (int desktop=-1)
static QRect	workArea (const QList< WId > &excludes, int desktop=-1)
Protected Member Functions
virtual void	connectNotify (const char *signal)

---

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)

Definition at line 55 of file kwindowsystem.h.

---

Member Enumeration Documentation

enum KWindowSystem::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	read from property from the window manager specification
WMHints	read from WMHints property
ClassHint	load icon after getting name from the classhint
XApp	load the standard X icon (last fallback)

Definition at line 268 of file kwindowsystem.h.

---

Member Function Documentation

void KWindowSystem::activateWindow	(	WId	win,
		long	time = 0
	)		[static]

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

Definition at line 356 of file kwindowsystem_mac.cpp.

WId KWindowSystem::activeWindow

(

)

[static]

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

Definition at line 349 of file kwindowsystem_mac.cpp.

void KWindowSystem::activeWindowChanged

(

WId

id

)

[signal]

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

Parameters:

id	the id of the window that is active

bool KWindowSystem::allowedActionsSupported

(

)

[static]

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

Definition at line 598 of file kwindowsystem_mac.cpp.

void KWindowSystem::allowExternalProcessWindowActivation

(

int

pid = -1

)

[static]

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.

Definition at line 623 of file kwindowsystem_mac.cpp.

void KWindowSystem::clearState	(	WId	win,
		unsigned long	state
	)		[static]

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

Definition at line 513 of file kwindowsystem_mac.cpp.

bool KWindowSystem::compositingActive

(

)

[static]

Returns true if a compositing manager is running (i.e.

ARGB windows are supported, effects will be provided, etc.).

Definition at line 380 of file kwindowsystem_mac.cpp.

void KWindowSystem::connectNotify

(

const char *

signal

)

[protected, virtual]

Definition at line 617 of file kwindowsystem_mac.cpp.

QPoint KWindowSystem::constrainViewportRelativePosition

(

const QPoint &

pos

)

[static]

Since:

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

Definition at line 1054 of file kwindowsystem_x11.cpp.

int KWindowSystem::currentDesktop

(

)

[static]

Returns the current virtual desktop.

Returns:

the current virtual desktop

Definition at line 385 of file kwindowsystem_mac.cpp.

void KWindowSystem::currentDesktopChanged

(

int

desktop

)

[signal]

Switched to another virtual desktop.

Parameters:

desktop

the number of the new desktop

void KWindowSystem::demandAttention	(	WId	win,
		bool	set = true
	)		[static]

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.

Definition at line 374 of file kwindowsystem_mac.cpp.

QString KWindowSystem::desktopName

(

int

desktop

)

[static]

Returns the name of the specified desktop.

Parameters:

desktop

the number of the desktop

Returns:

the name of the desktop

Definition at line 562 of file kwindowsystem_mac.cpp.

void KWindowSystem::desktopNamesChanged

(

)

[signal]

Desktops have been renamed.

QPoint KWindowSystem::desktopToViewport	(	int	desktop,
		bool	absolute
	)		[static]

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

Definition at line 1027 of file kwindowsystem_x11.cpp.

void KWindowSystem::doNotManage

(

const QString &

title

)

[static]

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

Definition at line 610 of file kwindowsystem_mac.cpp.

void KWindowSystem::forceActiveWindow	(	WId	win,
		long	time = 0
	)		[static]

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

Definition at line 367 of file kwindowsystem_mac.cpp.

WId KWindowSystem::groupLeader

(

WId

window

)

[static]

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

Parameters:

window

the id of the window

Definition at line 571 of file kwindowsystem_x11.cpp.

bool KWindowSystem::hasWId

(

WId

id

)

[static]

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

Definition at line 325 of file kwindowsystem_mac.cpp.

bool KWindowSystem::icccmCompliantMappingState

(

)

[static]

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

Definition at line 543 of file kwindowsystem_mac.cpp.

QPixmap KWindowSystem::icon	(	WId	win,
		int	width = -1,
		int	height = -1,
		bool	scale = false
	)		[static]

Returns an icon for window win.

If width and height are specified, the best icon for the requested size is returned.

If scale is true, the icon is smooth-scaled to have exactly the requested size.

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.

Returns:

the icon of the window

Definition at line 419 of file kwindowsystem_mac.cpp.

QPixmap KWindowSystem::icon	(	WId	win,
		int	width,
		int	height,
		bool	scale,
		int	flags
	)		[static]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. 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

Definition at line 462 of file kwindowsystem_mac.cpp.

void KWindowSystem::lowerWindow

(

WId

win

)

[static]

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.

Definition at line 537 of file kwindowsystem_mac.cpp.

bool KWindowSystem::mapViewport

(

)

[static]

Returns true if viewports are mapped to virtual desktops.

Definition at line 980 of file kwindowsystem_x11.cpp.

void KWindowSystem::minimizeWindow	(	WId	win,
		bool	animation = true
	)		[static]

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

Definition at line 519 of file kwindowsystem_mac.cpp.

int KWindowSystem::numberOfDesktops

(

)

[static]

Returns the number of virtual desktops.

Returns:

the number of virtual desktops

Definition at line 390 of file kwindowsystem_mac.cpp.

void KWindowSystem::numberOfDesktopsChanged

(

int

num

)

[signal]

The number of desktops changed.

Parameters:

num	the new number of desktops

void KWindowSystem::raiseWindow

(

WId

win

)

[static]

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.

Definition at line 531 of file kwindowsystem_mac.cpp.

QString KWindowSystem::readNameProperty	(	WId	window,
		unsigned long	atom
	)		[static]

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

Definition at line 603 of file kwindowsystem_mac.cpp.

KWindowSystem * KWindowSystem::self

(

)

[static]

Access to the singleton instance.

Useful mainly for connecting to signals.

Definition at line 309 of file kwindowsystem_mac.cpp.

void KWindowSystem::setCurrentDesktop

(

int

desktop

)

[static]

Convenience function to set the current desktop to desktop.

See NETRootInfo.

Parameters:

desktop

the number of the new desktop

Definition at line 395 of file kwindowsystem_mac.cpp.

void KWindowSystem::setDesktopName	(	int	desktop,
		const QString &	name
	)		[static]

Sets the name of the specified desktop.

Parameters:

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

Definition at line 567 of file kwindowsystem_mac.cpp.

void KWindowSystem::setExtendedStrut	(	WId	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
	)		[static]

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

Definition at line 584 of file kwindowsystem_mac.cpp.

void KWindowSystem::setIcons	(	WId	win,
		const QPixmap &	icon,
		const QPixmap &	miniIcon
	)		[static]

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

Definition at line 468 of file kwindowsystem_mac.cpp.

void KWindowSystem::setMainWindow	(	QWidget *	subwindow,
		WId	mainwindow
	)		[static]

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.

Definition at line 413 of file kwindowsystem_mac.cpp.

void KWindowSystem::setOnAllDesktops	(	WId	win,
		bool	b
	)		[static]

Sets window win to be present on all virtual desktops if 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

Definition at line 401 of file kwindowsystem_mac.cpp.

void KWindowSystem::setOnDesktop	(	WId	win,
		int	desktop
	)		[static]

Moves window win to desktop desktop.

Parameters:

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

Definition at line 407 of file kwindowsystem_mac.cpp.

void KWindowSystem::setState	(	WId	win,
		unsigned long	state
	)		[static]

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

Definition at line 507 of file kwindowsystem_mac.cpp.

void KWindowSystem::setStrut	(	WId	win,
		int	left,
		int	right,
		int	top,
		int	bottom
	)		[static]

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

Definition at line 592 of file kwindowsystem_mac.cpp.

void KWindowSystem::setType	(	WId	win,
		NET::WindowType	windowType
	)		[static]

Sets the type of window win to windowType.

Parameters:

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

Definition at line 474 of file kwindowsystem_mac.cpp.

void KWindowSystem::setUserTime	(	WId	win,
		long	time
	)		[static]

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.

Definition at line 578 of file kwindowsystem_mac.cpp.

bool KWindowSystem::showingDesktop

(

)

[static]

Returns the state of showing the desktop.

Definition at line 573 of file kwindowsystem_mac.cpp.

void KWindowSystem::showingDesktopChanged

(

bool

showing

)

[signal]

The state of showing the desktop has changed.

QList< WId > KWindowSystem::stackingOrder

(

)

[static]

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

Definition at line 341 of file kwindowsystem_mac.cpp.

void KWindowSystem::stackingOrderChanged

(

)

[signal]

Emitted when the stacking order of the window changed.

The new order can be obtained with stackingOrder().

void KWindowSystem::strutChanged

(

)

[signal]

Something changed with the struts, may or may not have changed the work area.

Usually just using the workAreaChanged() signal is sufficient.

WId KWindowSystem::transientFor

(

WId

window

)

[static]

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

the mainwindow for this window.

Parameters:

window

the id of the window

Definition at line 552 of file kwindowsystem_x11.cpp.

void KWindowSystem::unminimizeWindow	(	WId	win,
		bool	animation = true
	)		[static]

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

Definition at line 525 of file kwindowsystem_mac.cpp.

int KWindowSystem::viewportToDesktop

(

const QPoint &

pos

)

[static]

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

Definition at line 997 of file kwindowsystem_x11.cpp.

int KWindowSystem::viewportWindowToDesktop

(

const QRect &

r

)

[static]

Returns mapped virtual desktop for the given window geometry.

Definition at line 1010 of file kwindowsystem_x11.cpp.

void KWindowSystem::windowAdded

(

WId

id

)

[signal]

A window has been added.

Parameters:

id	the id of the window

void KWindowSystem::windowChanged	(	WId	id,
		unsigned int	properties
	)		[signal]

Deprecated:

The window changed.

The unsigned int parameter contains the NET properties that were modified (see netwm_def.h).

Parameters:

id	the id of the window
properties	the properties that were modified

void KWindowSystem::windowChanged	(	WId	id,
		const unsigned long *	properties
	)		[signal]

The window changed.

The properties parameter contains the NET properties that were modified (see netwm_def.h). First element are NET::Property values, second element are NET::Property2 values (i.e. the format is the same like for the NETWinInfo class constructor).

Parameters:

id	the id of the window
properties	the properties that were modified

void KWindowSystem::windowChanged

(

WId

id

)

[signal]

The window changed somehow.

Parameters:

id	the id of the window

KWindowInfo KWindowSystem::windowInfo	(	WId	win,
		unsigned long	properties,
		unsigned long	properties2 = 0
	)		[static]

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

Definition at line 331 of file kwindowsystem_mac.cpp.

void KWindowSystem::windowRemoved

(

WId

id

)

[signal]

A window has been removed.

Parameters:

id	the id of the window that has been removed

const QList< WId > & KWindowSystem::windows

(

)

[static]

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

Definition at line 319 of file kwindowsystem_mac.cpp.

QRect KWindowSystem::workArea

(

int

desktop = - 1

)

[static]

Returns the workarea for the specified desktop, or the current work area if no desktop has been specified.

Parameters:

desktop

the number of the desktop to check, -1 for the current desktop

Returns:

the size and position of the desktop

Definition at line 548 of file kwindowsystem_mac.cpp.

QRect KWindowSystem::workArea	(	const QList< WId > &	excludes,
		int	desktop = -1
	)		[static]

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

Definition at line 555 of file kwindowsystem_mac.cpp.

void KWindowSystem::workAreaChanged

(

)

[signal]

The workarea has changed.

---

The documentation for this class was generated from the following files:

• kwindowsystem.h
• kwindowsystem_mac.cpp
• kwindowsystem_qws.cpp
• kwindowsystem_win.cpp
• kwindowsystem_x11.cpp