KWindowInfo

KWindowInfo Class Reference

#include <kwindowinfo.h>

Public Member Functions

 KWindowInfo (WId window, NET::Properties properties, NET::Properties2 properties2=NET::Properties2())
 
 KWindowInfo (const KWindowInfo &)
 
bool actionSupported (NET::Action action) const
 
QStringList activities () const
 
QByteArray applicationMenuObjectPath () const
 
QByteArray applicationMenuServiceName () const
 
QByteArray clientMachine () const
 
int desktop () const
 
QByteArray desktopFileName () const
 
NETExtendedStrut extendedStrut () const
 
QRect frameGeometry () const
 
QRect geometry () const
 
WId groupLeader () const
 
bool hasState (NET::States s) const
 
QString iconName () const
 
bool isMinimized () const
 
bool isOnCurrentDesktop () const
 
bool isOnDesktop (int desktop) const
 
NET::MappingState mappingState () const
 
QString name () const
 
bool onAllDesktops () const
 
KWindowInfooperator= (const KWindowInfo &)
 
int pid () const
 
NET::States state () const
 
WId transientFor () const
 
bool valid (bool withdrawn_is_valid=false) const
 
QString visibleIconName () const
 
QString visibleIconNameWithState () const
 
QString visibleName () const
 
QString visibleNameWithState () const
 
WId win () const
 
QByteArray windowClassClass () const
 
QByteArray windowClassName () const
 
QByteArray windowRole () const
 
NET::WindowType windowType (NET::WindowTypes supported_types) const
 

Detailed Description

This class provides information about a given window in the platform specific windowing system.

It provides the information for the current state when a KWindowInfo instance gets created. The instance does not get updated when the window changes. To get update about window changes connect to the windowChanged signal of KWindowSystem and create a new KWindowInfo instance to reflect the current state.

KWindowInfo does not encapsulate all information about the window. One needs to request which information is required by passing the appropriate NET::Property and NET::Property2 flags to the constructor. Please refer to the documentation of the methods to see which flags are required. This is done to limit the interaction with the underlying windowing system as fetching the information can cause several context switches and roundtrips to a server instance (e.g. when using the X11 platform).

Please note that KWindowInfo is an abstraction of the underlying windowing system inspired by the X11 platform. Thus not all concepts apply to all platforms and some methods might return a default value for some platforms.

Example usage of this class illustrated by monitoring a QWidget for change of the demands attention window state:

QWidget *widget = new QWidget(nullptr);
widget->show(); // ensures native window gets created
connect(KWindowSystem::self(), static_cast<void (KWindowSystem::*)(WId, unsigned int)>(&KWindowSystem::windowChanged),
[window](WId winId, unsigned int properties) {
if (widget->winId() != winId) {
return; // not our window
}
if (properties & NET::WMState) {
// let's check whether our window is demanding attention
KWindowInfo info(widget->winId(), NET::WMState);
qDebug() << "Has demands attention: " << info.hasState(NET::DemandsAttention);
}
});

Definition at line 62 of file kwindowinfo.h.

Constructor & Destructor Documentation

KWindowInfo::KWindowInfo ( WId  window,
NET::Properties  properties,
NET::Properties2  properties2 = NET::Properties2() 
)

Reads all the info about the given window.

Only the information requested through the properties and properties2 parameters are fetched. Refer to the methods you are interested in to see which flags to pass.

Parameters
windowThe platform specific window identifier
propertiesBitmask of NET::Property
properties2Bitmask of NET::Property2

Definition at line 239 of file kwindowinfo.cpp.

KWindowInfo::KWindowInfo ( const KWindowInfo other)

Copy constructor.

Definition at line 244 of file kwindowinfo.cpp.

Member Function Documentation

bool KWindowInfo::actionSupported ( NET::Action  action) const

Returns true if the given action is currently supported for the window.

On platform X11 the supported actions are set by the window manager and can differ depending on the window manager. Requires NET::WM2AllowedActions passed as properties2 parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), 0, NET::WM2AllowedActions);
if (info.valid())
info.actionSupported(NET::ActionClose);

Definition at line 399 of file kwindowinfo.cpp.

QStringList KWindowInfo::activities ( ) const

Returns the list of activity UUIDs this window belongs to.

The Plasma workspace allows the user to separate her work into different activities, by assigning windows, documents etc. to the specific ones. An activity is an abstract concept whose meaning can differ from one user to another. Typical examples of activities are "developing a KDE project", "studying the 19th century art", "composing music", "lazing on a Sunday afternoon" etc.

If the list is empty, or contains a null UUID, the window is on all activities.

Requires NET::WM2Activities passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), 0, NET::WM2Activities);
if (info.valid())
info.desktop();
Note
Activities are only supported on Plasma Workspace on X11
Since
5.0

Definition at line 354 of file kwindowinfo.cpp.

QByteArray KWindowInfo::applicationMenuObjectPath ( ) const

Returns object path of a window's application menu if present.

Requires NET::WMPid passed as properties parameter to the constructor.

Since
5.69

Definition at line 420 of file kwindowinfo.cpp.

QByteArray KWindowInfo::applicationMenuServiceName ( ) const

Returns service name of a window's application menu if present.

Requires NET::WMPid passed as properties parameter to the constructor.

Since
5.69

Definition at line 412 of file kwindowinfo.cpp.

QByteArray KWindowInfo::clientMachine ( ) const

Returns the client machine for the window.

On platform X11 this is the value of the WM_CLIENT_MACHINE property. Requires NET::WM2ClientMachine passed as properties2 parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), 0, NET::WM2ClientMachine);
if (info.valid())
info.clientMachine();

Definition at line 394 of file kwindowinfo.cpp.

int KWindowInfo::desktop ( ) const

Returns the virtual desktop this window is on.

If the window is on all desktops NET::OnAllDesktops is returned. You should prefer using isOnDesktop(). Requires NET::WMDesktop passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMDesktop);
if (info.valid())
info.desktop();
See also
isOnDesktop()

Definition at line 349 of file kwindowinfo.cpp.

QByteArray KWindowInfo::desktopFileName ( ) const

Returns the desktop file name of the window's application if present.

This is either the base name without full path and without file extension of the desktop file for the window's application (e.g. "org.kde.foo").

If the application's desktop file name is not at a standard location it should be the full path to the desktop file name (e.g. "/opt/kde/share/org.kde.foo.desktop").

Requires NET::WM2DesktopFileName passed as properties2 parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), 0, NET::WM2DesktopFileName);
if (info.valid())
Since
5.29

Definition at line 404 of file kwindowinfo.cpp.

NETExtendedStrut KWindowInfo::extendedStrut ( ) const

Returns the window extended (partial) strut.

Requires NET::WM2ExtendedStrut passed as properties2 parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), 0, NET::WM2ExtendedStrut);
if (info.valid())
info.extendedStrut();

Definition at line 294 of file kwindowinfo.cpp.

QRect KWindowInfo::frameGeometry ( ) const

Returns the frame geometry of the window, i.e.

including the window decoration.

Requires NET::WMFrameExtents passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMFrameExtents);
if (info.valid())
info.frameGeometry();

Definition at line 364 of file kwindowinfo.cpp.

QRect KWindowInfo::geometry ( ) const

Returns the position and size of the window contents.

Requires NET::WMGeometry passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMGeometry);
if (info.valid())
info.geometry();

Definition at line 359 of file kwindowinfo.cpp.

WId KWindowInfo::groupLeader ( ) const

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

Requires NET::WM2GroupLeader passed as properties2 parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), 0, NET::WM2GroupLeader);
if (info.valid())
info.groupLeader();

Definition at line 374 of file kwindowinfo.cpp.

bool KWindowInfo::hasState ( NET::States  s) const

Returns true if the window has the given state flag set.

Requires NET::WMState passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMState);
if (info.valid())
See also
NET::State

Definition at line 279 of file kwindowinfo.cpp.

QString KWindowInfo::iconName ( ) const

Returns the name of the window that should be shown in taskbar.

Note that this has nothing to do with normal icons but with an "iconic" representation of the window. Requires NET::WMIconName passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMIconName);
if (info.valid())
info.iconName();

Definition at line 329 of file kwindowinfo.cpp.

bool KWindowInfo::isMinimized ( ) const

Returns true if the window is minimized.

Note that it is true only if the window is truly minimized, not shaded or on another virtual desktops, which makes it different from mappingState() == NET::Iconic or QWidget::isMinimized(). Requires NET::WMState and NET::XAWMState passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMState | NET::XAWMState);
if (info.valid())
info.isMinimized();

Definition at line 284 of file kwindowinfo.cpp.

bool KWindowInfo::isOnCurrentDesktop ( ) const

Returns true if the window is on the currently active virtual desktop.

Requires NET::WMDesktop passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMDesktop);
if (info.valid())

Definition at line 334 of file kwindowinfo.cpp.

bool KWindowInfo::isOnDesktop ( int  desktop) const

Returns true if the window is on the given virtual desktop.

Requires NET::WMDesktop passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMDesktop);
if (info.valid())

Definition at line 339 of file kwindowinfo.cpp.

NET::MappingState KWindowInfo::mappingState ( ) const

Returns the mapping state of the window.

Note that it's very likely that you don't want to use this function, and use isOnDesktop(), isMinimized() etc. instead. Requires NET::XAWMState passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::XAWMState);
if (info.valid())
info.mappingState();
See also
NET::MappingState
isOnDesktop()
isMinimzed()

Definition at line 289 of file kwindowinfo.cpp.

QString KWindowInfo::name ( ) const

Returns the name of the window, as specified by the application.

The difference to visibleName() is that this is the name provided by the application without any modifications by the window manager. You should often use visibleName() instead. Requires NET::WMName passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMName);
if (info.valid())
info.name();
See also
visibleName()

Definition at line 314 of file kwindowinfo.cpp.

bool KWindowInfo::onAllDesktops ( ) const

Returns true if the window is on all desktops.

A window is on all desktops if desktop() returns NET::OnAllDesktops. Requires NET::WMDesktop passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMDesktop);
if (info.valid())
info.onAllDesktops();
See also
desktop()

Definition at line 344 of file kwindowinfo.cpp.

KWindowInfo & KWindowInfo::operator= ( const KWindowInfo other)

Assignment operator.

Definition at line 253 of file kwindowinfo.cpp.

int KWindowInfo::pid ( ) const

Returns the process ID of the window's application if present.

Requires NET::WMPid passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMPid);
if (info.valid())
info.pid();
Since
5.29

Definition at line 428 of file kwindowinfo.cpp.

unsigned long KWindowInfo::state ( ) const

Returns the window's state flags.

Requires NET::WMState passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMState);
if (info.valid())
info.state();
See also
NET::State

Definition at line 274 of file kwindowinfo.cpp.

WId KWindowInfo::transientFor ( ) const

Returns the window identifier of the main window this window belongs to.

On platform X11 this is the value of the WM_TRANSIENT_FOR property.

Requires NET::WM2TransientFor passed as properties2 parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), 0, NET::WM2TransientFor);
if (info.valid())
info.transientFor();

Definition at line 369 of file kwindowinfo.cpp.

bool KWindowInfo::valid ( bool  withdrawn_is_valid = false) const

Returns false if this window info is not valid.

In case the window does not exist false is returned. Also if there is no appropriate implementation for KWindowInfo on the current windowing system platform this method returns false. In that case all methods return a default value and thus it is recommended to check whether valid returns true.

Parameters
withdrawn_is_validif true, windows in the withdrawn state (i.e. not managed) are also considered. This is usually not the case.

Definition at line 264 of file kwindowinfo.cpp.

QString KWindowInfo::visibleIconName ( ) const

Returns the visible name of the window that should be shown in a taskbar.

Note that this has nothing to do with normal icons but with an "iconic" representation of the window. Requires NET::WMVisibleIconName passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMVisibleIconName);
if (info.valid())

Definition at line 319 of file kwindowinfo.cpp.

QString KWindowInfo::visibleIconNameWithState ( ) const

Returns a visible icon name with state.

This is a simple convenience function that returns the visible iconic name but with parentheses around minimized windows. Note that this has nothing to do with normal icons. Requires NET::WMVisibleIconName, NET::WMState and NET::XAWMState passed as properties parameter to the constructor.

Returns
the window iconic name with state
QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMVisibleIconName | NET::WMState | NET::XAWMState);
if (info.valid())
See also
visibleIconName()

Definition at line 324 of file kwindowinfo.cpp.

QString KWindowInfo::visibleName ( ) const

Returns the visible name of the window.

The visible name differs from the name by including possible <2> appended when there are two or more windows with the same name. Requires NET::WMVisibleName passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMVisibleName);
if (info.valid())
info.visibleName();
See also
name()

Definition at line 304 of file kwindowinfo.cpp.

QString KWindowInfo::visibleNameWithState ( ) const

Returns a visible name with state.

This is a simple convenience function that returns the visible name but with parentheses around minimized windows. Requires NET::WMVisibleName, NET::WMState and NET::XAWMState passed as properties parameter to the constructor.

Returns
the window name with state
QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMVisibleName | NET::WMState | NET::XAWMState);
if (info.valid())
See also
visibleName()

Definition at line 309 of file kwindowinfo.cpp.

WId KWindowInfo::win ( ) const

Returns the window identifier.

Definition at line 269 of file kwindowinfo.cpp.

QByteArray KWindowInfo::windowClassClass ( ) const

Returns the class component of the window class for the window.

On platform X11 this is part of the WM_CLASS property. Requires NET::WM2WindowClass passed as properties2 parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), 0, NET::WM2WindowClass);
if (info.valid())

Definition at line 379 of file kwindowinfo.cpp.

QByteArray KWindowInfo::windowClassName ( ) const

Returns the name component of the window class for the window.

On platform X11 this is part of the WM_CLASS property. Requires NET::WM2WindowClass passed as properties2 parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), 0, NET::WM2WindowClass);
if (info.valid())

Definition at line 384 of file kwindowinfo.cpp.

QByteArray KWindowInfo::windowRole ( ) const

Returns the window role for the window.

On platform X11 this is the value of the WM_WINDOW_ROLE property. Requires NET::WM2WindowRole passed as properties2 parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), 0, NET::WM2WindowRole);
if (info.valid())
info.windowRole();

Definition at line 389 of file kwindowinfo.cpp.

NET::WindowType KWindowInfo::windowType ( NET::WindowTypes  supported_types) const

Returns the window type of this window.

The argument should be all window types your application supports. Requires NET::WMWindowType passed as properties parameter to the constructor.

QWidget *window = new QWidget(nullptr);
window->show();
KWindowInfo info(window->winId(), NET::WMWindowType);
if (info.valid())
See also
NET::WindowType
NET::WindowTypeMask

Definition at line 299 of file kwindowinfo.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Dec 3 2020 22:41:17 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.