diff --git a/src/kwindowinfo.h b/src/kwindowinfo.h index 068183c..013d6f7 100644 --- a/src/kwindowinfo.h +++ b/src/kwindowinfo.h @@ -1,607 +1,607 @@ /* This file is part of the KDE libraries SPDX-FileCopyrightText: 1999 Matthias Ettrich SPDX-FileCopyrightText: 2007 Lubos Lunak SPDX-License-Identifier: LGPL-2.1-or-later */ /* * kwindowinfo.h. Part of the KDE project. */ #ifndef KWINDOWINFO_H #define KWINDOWINFO_H #include #include //For WId #include #include #include class KWindowInfoPrivate; /** * 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 * @link KWindowSystem::windowChanged windowChanged@endlink 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: * * @code * QWidget *widget = new QWidget(nullptr); * widget->show(); // ensures native window gets created * connect(KWindowSystem::self(), static_cast(&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); * } * }); * @endcode */ class KWINDOWSYSTEM_EXPORT KWindowInfo { public: /** * Reads all the info about the given window. * * Only the information requested through the @p properties and @p properties2 * parameters are fetched. Refer to the methods you are interested in to see * which flags to pass. * * @param window The platform specific window identifier * @param properties Bitmask of NET::Property * @param properties2 Bitmask of NET::Property2 */ KWindowInfo(WId window, NET::Properties properties, NET::Properties2 properties2 = NET::Properties2()); ~KWindowInfo(); /** * Returns false if this window info is not valid. * * In case the window does not exist @c false is returned. Also if there is no * appropriate implementation for KWindowInfo on the current windowing * system platform this method returns @c false. In that case all methods return a * default value and thus it is recommended to check whether valid returns @c true. * * @param withdrawn_is_valid if true, windows in the withdrawn state * (i.e. not managed) are also considered. This is usually not the case. */ bool valid(bool withdrawn_is_valid = false) const; /** * Returns the window identifier. */ WId win() const; /** * Returns the window's state flags. * * Requires NET::WMState passed as properties parameter to the constructor. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMState); * if (info.valid()) * info.state(); * @endcode * * @see NET::State */ NET::States state() const; /** * Returns true if the window has the given state flag set. * * Requires NET::WMState passed as properties parameter to the constructor. * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMState); * if (info.valid()) * info.hasState(NET::DemandsAttention); * @endcode * * @see NET::State */ bool hasState(NET::States s) 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMState | NET::XAWMState); * if (info.valid()) * info.isMinimized(); * @endcode */ bool isMinimized() 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::XAWMState); * if (info.valid()) * info.mappingState(); * @endcode * * @see NET::MappingState * @see isOnDesktop() * @see isMinimzed() */ NET::MappingState mappingState() const; /** * Returns the window extended (partial) strut. * * Requires NET::WM2ExtendedStrut passed as properties2 parameter to the constructor. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), 0, NET::WM2ExtendedStrut); * if (info.valid()) * info.extendedStrut(); * @endcode */ NETExtendedStrut extendedStrut() 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMWindowType); * if (info.valid()) * info.windowType(NET::NormalMask | NET::DialogMask); * @endcode * * @see NET::WindowType * @see NET::WindowTypeMask */ NET::WindowType windowType(NET::WindowTypes supported_types) 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMVisibleName); * if (info.valid()) * info.visibleName(); * @endcode * * @see name() */ QString visibleName() 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. * @return the window name with state * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMVisibleName | NET::WMState | NET::XAWMState); * if (info.valid()) * info.visibleNameWithState(); * @endcode * * @see visibleName() */ QString visibleNameWithState() 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMName); * if (info.valid()) * info.name(); * @endcode * * @see visibleName() */ QString name() 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMVisibleIconName); * if (info.valid()) * info.visibleIconName(); * @endcode */ QString visibleIconName() 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. * @return the window iconic name with state * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMVisibleIconName | NET::WMState | NET::XAWMState); * if (info.valid()) * info.visibleIconNameWithState(); * @endcode * * @see visibleIconName() */ QString visibleIconNameWithState() 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMIconName); * if (info.valid()) * info.iconName(); * @endcode */ QString iconName() const; /** * Returns true if the window is on the currently active virtual desktop. * * Requires NET::WMDesktop passed as properties parameter to the constructor. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMDesktop); * if (info.valid()) * info.isOnCurrentDesktop(); * @endcode */ bool isOnCurrentDesktop() const; /** * Returns true if the window is on the given virtual desktop. * * Requires NET::WMDesktop passed as properties parameter to the constructor. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMDesktop); * if (info.valid()) * info.isOnDesktop(KWindowSystem::currentDesktop()); * @endcode */ bool isOnDesktop(int desktop) 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMDesktop); * if (info.valid()) * info.onAllDesktops(); * @endcode * * @see desktop() */ bool onAllDesktops() 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMDesktop); * if (info.valid()) * info.desktop(); * @endcode * * @see isOnDesktop() */ int desktop() 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), 0, NET::WM2Activities); * if (info.valid()) * info.desktop(); * @endcode * * @note Activities are only supported on Plasma Workspace on X11 * * @since 5.0 */ QStringList activities() const; /** * Returns the position and size of the window contents. * * Requires NET::WMGeometry passed as properties parameter to the constructor. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMGeometry); * if (info.valid()) * info.geometry(); * @endcode */ QRect geometry() const; /** * Returns the frame geometry of the window, i.e. including the window decoration. * * Requires NET::WMFrameExtents passed as properties parameter to the constructor. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMFrameExtents); * if (info.valid()) * info.frameGeometry(); * @endcode */ QRect frameGeometry() 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), 0, NET::WM2TransientFor); * if (info.valid()) * info.transientFor(); * @endcode */ WId transientFor() const; /** * Returns the leader window for the group the window is in, if any. * * Requires NET::WM2GroupLeader passed as properties2 parameter to the constructor. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), 0, NET::WM2GroupLeader); * if (info.valid()) * info.groupLeader(); * @endcode */ WId groupLeader() 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), 0, NET::WM2WindowClass); * if (info.valid()) * info.windowClassClass(); * @endcode */ QByteArray windowClassClass() 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), 0, NET::WM2WindowClass); * if (info.valid()) * info.windowClassName(); * @endcode */ QByteArray windowClassName() 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), 0, NET::WM2WindowRole); * if (info.valid()) * info.windowRole(); * @endcode */ QByteArray windowRole() 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), 0, NET::WM2ClientMachine); * if (info.valid()) * info.clientMachine(); * @endcode */ QByteArray clientMachine() 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), 0, NET::WM2AllowedActions); * if (info.valid()) * info.actionSupported(NET::ActionClose); * @endcode */ bool actionSupported(NET::Action action) 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. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), 0, NET::WM2DesktopFileName); * if (info.valid()) * info.desktopFileName(); * @endcode * * @since 5.29 **/ QByteArray desktopFileName() const; /** * Returns the process ID of the window's application if present. * * Requires NET::WMPid passed as properties parameter to the constructor. * * @code * QWidget *window = new QWidget(nullptr); * window->show(); * KWindowInfo info(window->winId(), NET::WMPid); * if (info.valid()) - * info.desktopFileName(); + * info.pid(); * @endcode * * @since 5.29 */ int pid() 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 */ QByteArray applicationMenuServiceName() 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 */ QByteArray applicationMenuObjectPath() const; /** * Copy constructor. */ KWindowInfo(const KWindowInfo &); /** * Assignment operator. */ KWindowInfo &operator=(const KWindowInfo &); private: QExplicitlySharedDataPointer d; }; #endif // multiple inclusion guard