KX11Extras Class Reference

#include <kx11extras.h>

Inheritance diagram for KX11Extras:

Public Types
enum	IconSource { NETWM = 1, WMHints = 2, ClassHint = 4, XApp = 8 }

Signals
void	activeWindowChanged (WId id)
void	compositingChanged (bool enabled)
void	currentDesktopChanged (int desktop)
void	desktopNamesChanged ()
void	numberOfDesktopsChanged (int num)
void	stackingOrderChanged ()
void	strutChanged ()
void	windowAdded (WId id)
void	windowChanged (WId id, NET::Properties properties, NET::Properties2 properties2)
void	windowRemoved (WId id)
void	workAreaChanged ()

Static Public Member Functions
static void	activateWindow (WId win, long time=0)
static WId	activeWindow ()
static bool	compositingActive ()
static int	currentDesktop ()
static QString	desktopName (int desktop)
static void	forceActiveWindow (WId win, long time=0)
static bool	hasWId (WId id)
static QPixmap	icon (WId win, int width, int height, bool scale, int flags)
static QPixmap	icon (WId win, int width, int height, bool scale, int flags, NETWinInfo *info)
static QPixmap	icon (WId win, int width=-1, int height=-1, bool scale=false)
static bool	mapViewport ()
static void	minimizeWindow (WId win)
static int	numberOfDesktops ()
static QString	readNameProperty (WId window, unsigned long atom)
static KX11Extras *	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	setOnActivities (WId win, const QStringList &activities)
static void	setOnAllDesktops (WId win, bool b)
static void	setOnDesktop (WId win, int desktop)
static void	setStrut (WId win, int left, int right, int top, int bottom)
static QList< WId >	stackingOrder ()
static void	unminimizeWindow (WId win)
static QList< WId >	windows ()
static QRect	workArea (const QList< WId > &excludes, int desktop=-1)
static QRect	workArea (int desktop=-1)
Static Public Member Functions inherited from QObject
QMetaObject::Connection	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
QMetaObject::Connection	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
bool	disconnect (const QMetaObject::Connection &connection)
bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
bool	disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
QString	tr (const char *sourceText, const char *disambiguation, int n)
QString	trUtf8 (const char *sourceText, const char *disambiguation, int n)

Protected Member Functions
void	connectNotify (const QMetaMethod &signal) override
Protected Member Functions inherited from QObject
virtual void	childEvent (QChildEvent *event)
virtual void	customEvent (QEvent *event)
virtual void	disconnectNotify (const QMetaMethod &signal)
bool	isSignalConnected (const QMetaMethod &signal) const const
int	receivers (const char *signal) const const
QObject *	sender () const const
int	senderSignalIndex () const const
virtual void	timerEvent (QTimerEvent *event)

Additional Inherited Members
Properties inherited from QObject
	objectName
Public Member Functions inherited from QObject
	QObject (QObject *parent)
bool	blockSignals (bool block)
const QObjectList &	children () const const
QMetaObject::Connection	connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
void	deleteLater ()
void	destroyed (QObject *obj)
bool	disconnect (const char *signal, const QObject *receiver, const char *method) const const
bool	disconnect (const QObject *receiver, const char *method) const const
void	dumpObjectInfo ()
void	dumpObjectInfo () const const
void	dumpObjectTree ()
void	dumpObjectTree () const const
QList< QByteArray >	dynamicPropertyNames () const const
virtual bool	event (QEvent *e)
virtual bool	eventFilter (QObject *watched, QEvent *event)
T	findChild (const QString &name, Qt::FindChildOptions options) const const
QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const
bool	inherits (const char *className) const const
void	installEventFilter (QObject *filterObj)
bool	isWidgetType () const const
bool	isWindowType () const const
void	killTimer (int id)
virtual const QMetaObject *	metaObject () const const
void	moveToThread (QThread *targetThread)
QString	objectName () const const
void	objectNameChanged (const QString &objectName)
QObject *	parent () const const
QVariant	property (const char *name) const const
	Q_CLASSINFO (Name, Value)
	Q_DISABLE_COPY (Class)
	Q_DISABLE_COPY_MOVE (Class)
	Q_DISABLE_MOVE (Class)
	Q_EMIT Q_EMIT
	Q_ENUM (...)
	Q_ENUM_NS (...)
	Q_ENUMS (...)
	Q_FLAG (...)
	Q_FLAG_NS (...)
	Q_FLAGS (...)
	Q_GADGET Q_GADGET
	Q_INTERFACES (...)
	Q_INVOKABLE Q_INVOKABLE
	Q_NAMESPACE Q_NAMESPACE
	Q_NAMESPACE_EXPORT (EXPORT_MACRO)
	Q_OBJECT Q_OBJECT
	Q_PROPERTY (...)
	Q_REVISION Q_REVISION
	Q_SET_OBJECT_NAME (Object)
	Q_SIGNAL Q_SIGNAL
	Q_SIGNALS Q_SIGNALS
	Q_SLOT Q_SLOT
	Q_SLOTS Q_SLOTS
T	qFindChild (const QObject *obj, const QString &name)
QList< T >	qFindChildren (const QObject *obj, const QRegExp &regExp)
QList< T >	qFindChildren (const QObject *obj, const QString &name)
T	qobject_cast (const QObject *object)
T	qobject_cast (QObject *object)
	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
void	removeEventFilter (QObject *obj)
void	setObjectName (const QString &name)
void	setParent (QObject *parent)
bool	setProperty (const char *name, const QVariant &value)
bool	signalsBlocked () const const
int	startTimer (int interval, Qt::TimerType timerType)
int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
QThread *	thread () const const
Public Attributes inherited from QObject
typedef	QObjectList

Detailed Description

A collection of functions to obtain information from and manipulate X11 windows.

These are generally not applicable to other window systems

Since

5.101

Definition at line 27 of file kx11extras.h.

Member Enumeration Documentation

IconSource

enum KX11Extras::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 196 of file kx11extras.h.

Member Function Documentation

activateWindow()

void KX11Extras::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@.nosp@m.kde..nosp@m.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 59 of file kx11extras.cpp.

activeWindow()

WId KX11Extras::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 54 of file kx11extras.cpp.

activeWindowChanged

void KX11Extras::activeWindowChanged ( WId  id )

signal

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

Parameters

id	the id of the window that is active

compositingActive()

bool KX11Extras::compositingActive ( )

static

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

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

Definition at line 69 of file kx11extras.cpp.

compositingChanged

void KX11Extras::compositingChanged ( bool  enabled )

signal

Compositing was enabled or disabled.

Note that this signal may be emitted before any compositing plugins have been initialized in the window manager.

If you need to check if a specific compositing plugin such as the blur effect is enabled, you should track that separately rather than test for it in a slot connected to this signal.

currentDesktop()

int KX11Extras::currentDesktop ( )

static

Returns the current virtual desktop.

Returns

the current virtual desktop

Definition at line 74 of file kx11extras.cpp.

currentDesktopChanged

void KX11Extras::currentDesktopChanged ( int  desktop )

signal

Switched to another virtual desktop.

Parameters

desktop

the number of the new desktop

desktopName()

QString KX11Extras::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 231 of file kx11extras.cpp.

desktopNamesChanged

void KX11Extras::desktopNamesChanged ( )

signal

Desktops have been renamed.

forceActiveWindow()

void KX11Extras::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 64 of file kx11extras.cpp.

hasWId()

bool KX11Extras::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 44 of file kx11extras.cpp.

icon() [1/3]

QPixmap KX11Extras::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 109 of file kx11extras.cpp.

icon() [2/3]

QPixmap KX11Extras::icon ( WId  win, int  width, int  height, bool  scale, int  flags, NETWinInfo *  info  )

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 passing in the NETWinInfo to use for reading the information.

This variant is only useful on the X11 platform, other platforms do not use NETWinInfo and delegate to the variant without NETWinInfo. Though if compiled with X11 support the X11 variant is used on other platforms if info is not nullptr. This can be used by applications using e.g. platform wayland but also connecting to an XServer.

The NETWinInfo must be constructed with property NET::WMIcon in order to use the IconSource flag NETWM. NET::WM2IconPixmap for IconSource flag WMHints and NET::WM2WindowClass for IconSource flag ClassHint.

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
into	the NETWinInfo to use for reading properties.

Definition at line 197 of file kx11extras.cpp.

icon() [3/3]

QPixmap KX11Extras::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 104 of file kx11extras.cpp.

mapViewport()

bool KX11Extras::mapViewport ( )

static

Returns true if viewports are mapped to virtual desktops.

Definition at line 246 of file kx11extras.cpp.

minimizeWindow()

void KX11Extras::minimizeWindow ( WId  win )

static

Minimizes the window with id win.

On X11 this follows the protocol described in ICCCM section 4.1.4.

Parameters

win	The window to minimize

See also

unminimizeWindow()

Definition at line 211 of file kx11extras.cpp.

numberOfDesktops()

int KX11Extras::numberOfDesktops ( )

static

Returns the number of virtual desktops.

Returns

the number of virtual desktops

Definition at line 79 of file kx11extras.cpp.

numberOfDesktopsChanged

void KX11Extras::numberOfDesktopsChanged ( int  num )

signal

The number of desktops changed.

Parameters

num	the new number of desktops

readNameProperty()

QString KX11Extras::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 241 of file kx11extras.cpp.

setCurrentDesktop()

void KX11Extras::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 84 of file kx11extras.cpp.

setDesktopName()

void KX11Extras::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 236 of file kx11extras.cpp.

setExtendedStrut()

void KX11Extras::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 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 251 of file kx11extras.cpp.

setOnActivities()

void KX11Extras::setOnActivities ( WId  win, const QStringList &  activities  )

static

Moves window win to activities activities.

Parameters

win	the id of the window
activities	the list of activity UUIDs

See also

KWindowInfo::activities

Definition at line 99 of file kx11extras.cpp.

setOnAllDesktops()

void KX11Extras::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 89 of file kx11extras.cpp.

setOnDesktop()

void KX11Extras::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 94 of file kx11extras.cpp.

setStrut()

void KX11Extras::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 281 of file kx11extras.cpp.

stackingOrder()

QList< WId > KX11Extras::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 49 of file kx11extras.cpp.

stackingOrderChanged

void KX11Extras::stackingOrderChanged ( )

signal

Emitted when the stacking order of the window changed.

The new order can be obtained with stackingOrder().

strutChanged

void KX11Extras::strutChanged ( )

signal

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

Usually just using the workAreaChanged() signal is sufficient.

unminimizeWindow()

void KX11Extras::unminimizeWindow ( WId  win )

static

Unminimizes the window with id win.

On X11 this follows the protocol described in ICCCM section 4.1.4.

Parameters

win	The window to unminimize

See also

minimizeWindow()

Definition at line 216 of file kx11extras.cpp.

windowAdded

void KX11Extras::windowAdded ( WId  id )

signal

A window has been added.

Parameters

id	the id of the window

windowChanged

void KX11Extras::windowChanged ( WId  id, NET::Properties  properties, NET::Properties2  properties2  )

signal

The window changed.

Carries the NET::Properties and NET::Properties2 that were changed.

Parameters

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

windowRemoved

void KX11Extras::windowRemoved ( WId  id )

signal

A window has been removed.

Parameters

id	the id of the window that has been removed

windows()

QList< WId > KX11Extras::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> windows = KWindowSystem::windows();
for (auto it = windows.cbegin(), end = windows.cend(); it != end; ++it) {
   ... do something here,  (*it) is the current WId.
}

Returns

the list of all toplevel windows

Definition at line 39 of file kx11extras.cpp.

workArea() [1/2]

QRect KX11Extras::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 226 of file kx11extras.cpp.

workArea() [2/2]

QRect KX11Extras::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 221 of file kx11extras.cpp.

workAreaChanged

void KX11Extras::workAreaChanged ( )

signal

The workarea has changed.

---

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

• kx11extras.h
• kx11extras.cpp