File indexing completed on 2024-07-21 12:15:31

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 1999 Matthias Ettrich <ettrich@kde.org>
0004     SPDX-FileCopyrightText: 2007 Lubos Lunak <l.lunak@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.1-or-later
0007 */
0008 /*
0009  * kwindowinfo.h. Part of the KDE project.
0010  */
0011 
0012 #ifndef KWINDOWINFO_H
0013 #define KWINDOWINFO_H
0014 
0015 #include <QExplicitlySharedDataPointer>
0016 #include <QStringList>
0017 #include <QWidgetList> //For WId
0018 #include <kwindowsystem_export.h>
0019 
0020 #include <netwm_def.h>
0021 
0022 class KWindowInfoPrivate;
0023 
0024 /**
0025  * This class provides information about a given window in the platform specific
0026  * windowing system. It provides the information for the current state when a
0027  * KWindowInfo instance gets created. The instance does not get updated when the
0028  * window changes. To get update about window changes connect to the
0029  * @link KWindowSystem::windowChanged windowChanged@endlink signal of KWindowSystem
0030  * and create a new KWindowInfo instance to reflect the current state.
0031  *
0032  * KWindowInfo does not encapsulate all information about the window. One needs to
0033  * request which information is required by passing the appropriate NET::Property and
0034  * NET::Property2 flags to the constructor. Please refer to the documentation of the
0035  * methods to see which flags are required. This is done to limit the interaction with
0036  * the underlying windowing system as fetching the information can cause several context
0037  * switches and roundtrips to a server instance (e.g. when using the X11 platform).
0038  *
0039  * Please note that KWindowInfo is an abstraction of the underlying windowing system
0040  * inspired by the X11 platform. Thus not all concepts apply to all platforms and some
0041  * methods might return a default value for some platforms.
0042  *
0043  * Example usage of this class illustrated by monitoring a QWidget for change of the
0044  * demands attention window state:
0045  *
0046  * @code
0047  * QWidget *widget = new QWidget(nullptr);
0048  * widget->show(); // ensures native window gets created
0049  * connect(KWindowSystem::self(), static_cast<void (KWindowSystem::*)(WId, unsigned int)>(&KWindowSystem::windowChanged),
0050  *        [window](WId winId, unsigned int properties) {
0051  *     if (widget->winId() != winId) {
0052  *         return; // not our window
0053  *     }
0054  *     if (properties & NET::WMState) {
0055  *         // let's check whether our window is demanding attention
0056  *         KWindowInfo info(widget->winId(), NET::WMState);
0057  *         qDebug() << "Has demands attention: " << info.hasState(NET::DemandsAttention);
0058  *     }
0059  * });
0060  * @endcode
0061  */
0062 class KWINDOWSYSTEM_EXPORT KWindowInfo
0063 {
0064 public:
0065     /**
0066      * Reads all the info about the given window.
0067      *
0068      * Only the information requested through the @p properties and @p properties2
0069      * parameters are fetched. Refer to the methods you are interested in to see
0070      * which flags to pass.
0071      *
0072      * @param window The platform specific window identifier
0073      * @param properties Bitmask of NET::Property
0074      * @param properties2 Bitmask of NET::Property2
0075      */
0076     KWindowInfo(WId window, NET::Properties properties, NET::Properties2 properties2 = NET::Properties2());
0077     ~KWindowInfo();
0078     /**
0079      * Returns false if this window info is not valid.
0080      *
0081      * In case the window does not exist @c false is returned. Also if there is no
0082      * appropriate implementation for KWindowInfo on the current windowing
0083      * system platform this method returns @c false. In that case all methods return a
0084      * default value and thus it is recommended to check whether valid returns @c true.
0085      *
0086      * @param withdrawn_is_valid if true, windows in the withdrawn state
0087      *        (i.e. not managed) are also considered. This is usually not the case.
0088      */
0089     bool valid(bool withdrawn_is_valid = false) const;
0090     /**
0091      * Returns the window identifier.
0092      */
0093     WId win() const;
0094     /**
0095      * Returns the window's state flags.
0096      *
0097      * Requires NET::WMState passed as properties parameter to the constructor.
0098      *
0099      * @code
0100      * QWidget *window = new QWidget(nullptr);
0101      * window->show();
0102      * KWindowInfo info(window->winId(), NET::WMState);
0103      * if (info.valid())
0104      *     info.state();
0105      * @endcode
0106      *
0107      * @see NET::State
0108      */
0109     NET::States state() const;
0110     /**
0111      * Returns true if the window has the given state flag set.
0112      *
0113      * Requires NET::WMState passed as properties parameter to the constructor.
0114      * @code
0115      * QWidget *window = new QWidget(nullptr);
0116      * window->show();
0117      * KWindowInfo info(window->winId(), NET::WMState);
0118      * if (info.valid())
0119      *     info.hasState(NET::DemandsAttention);
0120      * @endcode
0121      *
0122      * @see NET::State
0123      */
0124     bool hasState(NET::States s) const;
0125     /**
0126      * Returns true if the window is minimized.
0127      *
0128      * Note that it is true only if the window is truly minimized,
0129      * not shaded or on another virtual desktops,
0130      * which makes it different from mappingState() == NET::Iconic
0131      * or QWidget::isMinimized().
0132      * Requires NET::WMState and NET::XAWMState passed as properties parameter to the constructor.
0133      *
0134      * @code
0135      * QWidget *window = new QWidget(nullptr);
0136      * window->show();
0137      * KWindowInfo info(window->winId(), NET::WMState | NET::XAWMState);
0138      * if (info.valid())
0139      *     info.isMinimized();
0140      * @endcode
0141      */
0142     bool isMinimized() const;
0143     /**
0144      * Returns the mapping state of the window.
0145      *
0146      * Note that it's very likely that you don't want to use this function,
0147      * and use isOnDesktop(), isMinimized() etc. instead.
0148      * Requires NET::XAWMState passed as properties parameter to the constructor.
0149      *
0150      * @code
0151      * QWidget *window = new QWidget(nullptr);
0152      * window->show();
0153      * KWindowInfo info(window->winId(), NET::XAWMState);
0154      * if (info.valid())
0155      *     info.mappingState();
0156      * @endcode
0157      *
0158      * @see NET::MappingState
0159      * @see isOnDesktop()
0160      * @see isMinimzed()
0161      */
0162     NET::MappingState mappingState() const;
0163     /**
0164      * Returns the window extended (partial) strut.
0165      *
0166      * Requires NET::WM2ExtendedStrut passed as properties2 parameter to the constructor.
0167      *
0168      * @code
0169      * QWidget *window = new QWidget(nullptr);
0170      * window->show();
0171      * KWindowInfo info(window->winId(), 0, NET::WM2ExtendedStrut);
0172      * if (info.valid())
0173      *     info.extendedStrut();
0174      * @endcode
0175      */
0176     NETExtendedStrut extendedStrut() const;
0177     /**
0178      * Returns the window type of this window.
0179      *
0180      * The argument should be all window types your application supports.
0181      * Requires NET::WMWindowType passed as properties parameter to the constructor.
0182      *
0183      * @code
0184      * QWidget *window = new QWidget(nullptr);
0185      * window->show();
0186      * KWindowInfo info(window->winId(), NET::WMWindowType);
0187      * if (info.valid())
0188      *     info.windowType(NET::NormalMask | NET::DialogMask);
0189      * @endcode
0190      *
0191      * @see NET::WindowType
0192      * @see NET::WindowTypeMask
0193      */
0194     NET::WindowType windowType(NET::WindowTypes supported_types) const;
0195     /**
0196      * Returns the visible name of the window.
0197      *
0198      * The visible name differs from the name by including possible <2> appended
0199      * when there are two or more windows with the same name.
0200      * Requires NET::WMVisibleName passed as properties parameter to the constructor.
0201      *
0202      * @code
0203      * QWidget *window = new QWidget(nullptr);
0204      * window->show();
0205      * KWindowInfo info(window->winId(), NET::WMVisibleName);
0206      * if (info.valid())
0207      *     info.visibleName();
0208      * @endcode
0209      *
0210      * @see name()
0211      */
0212     QString visibleName() const;
0213     /**
0214      * Returns a visible name with state.
0215      *
0216      * This is a simple convenience function that returns the
0217      * visible name but with parentheses around minimized windows.
0218      * Requires NET::WMVisibleName, NET::WMState and NET::XAWMState passed
0219      * as properties parameter to the constructor.
0220      * @return the window name with state
0221      *
0222      * @code
0223      * QWidget *window = new QWidget(nullptr);
0224      * window->show();
0225      * KWindowInfo info(window->winId(), NET::WMVisibleName | NET::WMState | NET::XAWMState);
0226      * if (info.valid())
0227      *     info.visibleNameWithState();
0228      * @endcode
0229      *
0230      * @see visibleName()
0231      */
0232     QString visibleNameWithState() const;
0233     /**
0234      * Returns the name of the window, as specified by the application.
0235      *
0236      * The difference to visibleName() is that this is the name provided by
0237      * the application without any modifications by the window manager.
0238      * You should often use visibleName() instead.
0239      * Requires NET::WMName passed as properties parameter to the constructor.
0240      *
0241      * @code
0242      * QWidget *window = new QWidget(nullptr);
0243      * window->show();
0244      * KWindowInfo info(window->winId(), NET::WMName);
0245      * if (info.valid())
0246      *     info.name();
0247      * @endcode
0248      *
0249      * @see visibleName()
0250      */
0251     QString name() const;
0252     /**
0253      * Returns the visible name of the window that should be shown in a taskbar.
0254      *
0255      * Note that this has nothing to do with normal icons but with an "iconic"
0256      * representation of the window.
0257      * Requires NET::WMVisibleIconName passed as properties parameter to the constructor.
0258      *
0259      * @code
0260      * QWidget *window = new QWidget(nullptr);
0261      * window->show();
0262      * KWindowInfo info(window->winId(), NET::WMVisibleIconName);
0263      * if (info.valid())
0264      *     info.visibleIconName();
0265      * @endcode
0266      */
0267     QString visibleIconName() const;
0268     /**
0269      * Returns a visible icon name with state.
0270      *
0271      * This is a simple convenience function that returns the
0272      * visible iconic name but with parentheses around minimized windows.
0273      * Note that this has nothing to do with normal icons.
0274      * Requires NET::WMVisibleIconName, NET::WMState and NET::XAWMState passed
0275      * as properties parameter to the constructor.
0276      * @return the window iconic name with state
0277      *
0278      * @code
0279      * QWidget *window = new QWidget(nullptr);
0280      * window->show();
0281      * KWindowInfo info(window->winId(), NET::WMVisibleIconName | NET::WMState | NET::XAWMState);
0282      * if (info.valid())
0283      *     info.visibleIconNameWithState();
0284      * @endcode
0285      *
0286      * @see visibleIconName()
0287      */
0288     QString visibleIconNameWithState() const;
0289     /**
0290      * Returns the name of the window that should be shown in taskbar.
0291      *
0292      * Note that this has nothing to do with normal icons but with an "iconic"
0293      * representation of the window.
0294      * Requires NET::WMIconName passed as properties parameter to the constructor.
0295      *
0296      * @code
0297      * QWidget *window = new QWidget(nullptr);
0298      * window->show();
0299      * KWindowInfo info(window->winId(), NET::WMIconName);
0300      * if (info.valid())
0301      *     info.iconName();
0302      * @endcode
0303      */
0304     QString iconName() const;
0305     /**
0306      * Returns true if the window is on the currently active virtual desktop.
0307      *
0308      * Requires NET::WMDesktop passed as properties parameter to the constructor.
0309      *
0310      * @code
0311      * QWidget *window = new QWidget(nullptr);
0312      * window->show();
0313      * KWindowInfo info(window->winId(), NET::WMDesktop);
0314      * if (info.valid())
0315      *     info.isOnCurrentDesktop();
0316      * @endcode
0317      */
0318     bool isOnCurrentDesktop() const;
0319     /**
0320      * Returns true if the window is on the given virtual desktop.
0321      *
0322      * Requires NET::WMDesktop passed as properties parameter to the constructor.
0323      *
0324      * @code
0325      * QWidget *window = new QWidget(nullptr);
0326      * window->show();
0327      * KWindowInfo info(window->winId(), NET::WMDesktop);
0328      * if (info.valid())
0329      *     info.isOnDesktop(KWindowSystem::currentDesktop());
0330      * @endcode
0331      */
0332     bool isOnDesktop(int desktop) const;
0333     /**
0334      * Returns true if the window is on all desktops.
0335      *
0336      * A window is on all desktops if desktop() returns NET::OnAllDesktops.
0337      * Requires NET::WMDesktop passed as properties parameter to the constructor.
0338      *
0339      * @code
0340      * QWidget *window = new QWidget(nullptr);
0341      * window->show();
0342      * KWindowInfo info(window->winId(), NET::WMDesktop);
0343      * if (info.valid())
0344      *     info.onAllDesktops();
0345      * @endcode
0346      *
0347      * @see desktop()
0348      */
0349     bool onAllDesktops() const;
0350     /**
0351      * Returns the virtual desktop this window is on.
0352      *
0353      * If the window is on all desktops NET::OnAllDesktops is returned.
0354      * You should prefer using isOnDesktop().
0355      * Requires NET::WMDesktop passed as properties parameter to the constructor.
0356      *
0357      * @code
0358      * QWidget *window = new QWidget(nullptr);
0359      * window->show();
0360      * KWindowInfo info(window->winId(), NET::WMDesktop);
0361      * if (info.valid())
0362      *     info.desktop();
0363      * @endcode
0364      *
0365      * @see isOnDesktop()
0366      */
0367     int desktop() const;
0368     /**
0369      * Returns the list of activity UUIDs this window belongs to.
0370      *
0371      * The Plasma workspace allows the user to separate her work into
0372      * different activities, by assigning windows, documents etc. to
0373      * the specific ones. An activity is an abstract concept whose meaning
0374      * can differ from one user to another. Typical examples of activities
0375      * are "developing a KDE project", "studying the 19th century art",
0376      * "composing music", "lazing on a Sunday afternoon" etc.
0377      *
0378      * If the list is empty, or contains a null UUID, the window is on
0379      * all activities.
0380      *
0381      * Requires NET::WM2Activities passed as properties parameter to the constructor.
0382      *
0383      * @code
0384      * QWidget *window = new QWidget(nullptr);
0385      * window->show();
0386      * KWindowInfo info(window->winId(), 0, NET::WM2Activities);
0387      * if (info.valid())
0388      *     info.desktop();
0389      * @endcode
0390      *
0391      * @note Activities are only supported on Plasma Workspace on X11
0392      *
0393      * @since 5.0
0394      */
0395     QStringList activities() const;
0396     /**
0397      * Returns the position and size of the window contents.
0398      *
0399      * Requires NET::WMGeometry passed as properties parameter to the constructor.
0400      *
0401      * @code
0402      * QWidget *window = new QWidget(nullptr);
0403      * window->show();
0404      * KWindowInfo info(window->winId(), NET::WMGeometry);
0405      * if (info.valid())
0406      *     info.geometry();
0407      * @endcode
0408      */
0409     QRect geometry() const;
0410     /**
0411      * Returns the frame geometry of the window, i.e. including the window decoration.
0412      *
0413      * Requires NET::WMFrameExtents passed as properties parameter to the constructor.
0414      *
0415      * @code
0416      * QWidget *window = new QWidget(nullptr);
0417      * window->show();
0418      * KWindowInfo info(window->winId(), NET::WMFrameExtents);
0419      * if (info.valid())
0420      *     info.frameGeometry();
0421      * @endcode
0422      */
0423     QRect frameGeometry() const;
0424     /**
0425      * Returns the window identifier of the main window this window belongs to.
0426      *
0427      * On platform X11 this is the value of the WM_TRANSIENT_FOR property.
0428      *
0429      * Requires NET::WM2TransientFor passed as properties2 parameter to the constructor.
0430      *
0431      * @code
0432      * QWidget *window = new QWidget(nullptr);
0433      * window->show();
0434      * KWindowInfo info(window->winId(), 0, NET::WM2TransientFor);
0435      * if (info.valid())
0436      *     info.transientFor();
0437      * @endcode
0438      */
0439     WId transientFor() const;
0440     /**
0441      * Returns the leader window for the group the window is in, if any.
0442      *
0443      * Requires NET::WM2GroupLeader passed as properties2 parameter to the constructor.
0444      *
0445      * @code
0446      * QWidget *window = new QWidget(nullptr);
0447      * window->show();
0448      * KWindowInfo info(window->winId(), 0, NET::WM2GroupLeader);
0449      * if (info.valid())
0450      *     info.groupLeader();
0451      * @endcode
0452      */
0453     WId groupLeader() const;
0454 
0455     /**
0456      * Returns the class component of the window class for the window.
0457      *
0458      * On platform X11 this is part of the WM_CLASS property.
0459      * Requires NET::WM2WindowClass passed as properties2 parameter to the constructor.
0460      *
0461      * @code
0462      * QWidget *window = new QWidget(nullptr);
0463      * window->show();
0464      * KWindowInfo info(window->winId(), 0, NET::WM2WindowClass);
0465      * if (info.valid())
0466      *     info.windowClassClass();
0467      * @endcode
0468      */
0469     QByteArray windowClassClass() const;
0470 
0471     /**
0472      * Returns the name component of the window class for the window.
0473      *
0474      * On platform X11 this is part of the WM_CLASS property.
0475      * Requires NET::WM2WindowClass passed as properties2 parameter to the constructor.
0476      *
0477      * @code
0478      * QWidget *window = new QWidget(nullptr);
0479      * window->show();
0480      * KWindowInfo info(window->winId(), 0, NET::WM2WindowClass);
0481      * if (info.valid())
0482      *     info.windowClassName();
0483      * @endcode
0484      */
0485     QByteArray windowClassName() const;
0486 
0487     /**
0488      * Returns the window role for the window.
0489      *
0490      * On platform X11 this is the value of the WM_WINDOW_ROLE property.
0491      * Requires NET::WM2WindowRole passed as properties2 parameter to the constructor.
0492      *
0493      * @code
0494      * QWidget *window = new QWidget(nullptr);
0495      * window->show();
0496      * KWindowInfo info(window->winId(), 0, NET::WM2WindowRole);
0497      * if (info.valid())
0498      *     info.windowRole();
0499      * @endcode
0500      */
0501     QByteArray windowRole() const;
0502 
0503     /**
0504      * Returns the client machine for the window.
0505      *
0506      * On platform X11 this is the value of the WM_CLIENT_MACHINE property.
0507      * Requires NET::WM2ClientMachine passed as properties2 parameter to the constructor.
0508      *
0509      * @code
0510      * QWidget *window = new QWidget(nullptr);
0511      * window->show();
0512      * KWindowInfo info(window->winId(), 0, NET::WM2ClientMachine);
0513      * if (info.valid())
0514      *     info.clientMachine();
0515      * @endcode
0516      */
0517     QByteArray clientMachine() const;
0518 
0519     /**
0520      * Returns true if the given action is currently supported for the window.
0521      *
0522      * On platform X11 the supported actions are set by the window manager and
0523      * can differ depending on the window manager.
0524      * Requires NET::WM2AllowedActions passed as properties2 parameter to the constructor.
0525      *
0526      * @code
0527      * QWidget *window = new QWidget(nullptr);
0528      * window->show();
0529      * KWindowInfo info(window->winId(), 0, NET::WM2AllowedActions);
0530      * if (info.valid())
0531      *     info.actionSupported(NET::ActionClose);
0532      * @endcode
0533      */
0534     bool actionSupported(NET::Action action) const;
0535 
0536     /**
0537      * Returns the desktop file name of the window's application if present.
0538      *
0539      * This is either the base name without full path and without file extension of the
0540      * desktop file for the window's application (e.g. "org.kde.foo").
0541      *
0542      * If the application's desktop file name is not at a standard location it should be
0543      * the full path to the desktop file name (e.g. "/opt/kde/share/org.kde.foo.desktop").
0544      *
0545      * Requires NET::WM2DesktopFileName passed as properties2 parameter to the constructor.
0546      *
0547      * @code
0548      * QWidget *window = new QWidget(nullptr);
0549      * window->show();
0550      * KWindowInfo info(window->winId(), 0, NET::WM2DesktopFileName);
0551      * if (info.valid())
0552      *     info.desktopFileName();
0553      * @endcode
0554      *
0555      * @since 5.29
0556      **/
0557     QByteArray desktopFileName() const;
0558 
0559     /**
0560      * Returns the GTK application id of the window if present.
0561      *
0562      * This is comparable to desktopFileName.
0563      *
0564      * Requires NET::WM2GTKApplicationId passed as properties2 parameter to the constructor.
0565      *
0566      * @code
0567      * QWidget *window = new QWidget(nullptr);
0568      * window->show();
0569      * KWindowInfo info(window->winId(), 0, NET::WM2GTKApplicationId);
0570      * if (info.valid())
0571      *     info.gtkApplicationId();
0572      * @endcode
0573      *
0574      * @since 5.91
0575      **/
0576     QByteArray gtkApplicationId() const;
0577 
0578     /**
0579      * Returns the process ID of the window's application if present.
0580      *
0581      * Requires NET::WMPid passed as properties parameter to the constructor.
0582      *
0583      * @code
0584      * QWidget *window = new QWidget(nullptr);
0585      * window->show();
0586      * KWindowInfo info(window->winId(), NET::WMPid);
0587      * if (info.valid())
0588      *     info.pid();
0589      * @endcode
0590      *
0591      * @since 5.29
0592      */
0593     int pid() const;
0594 
0595     /**
0596      * Returns service name of a window's application menu if present.
0597      *
0598      * Requires NET::WMPid passed as properties parameter to the constructor.
0599      *
0600      * @since 5.69
0601      */
0602     QByteArray applicationMenuServiceName() const;
0603 
0604     /**
0605      * Returns object path of a window's application menu if present.
0606      *
0607      * Requires NET::WMPid passed as properties parameter to the constructor.
0608      *
0609      * @since 5.69
0610      */
0611     QByteArray applicationMenuObjectPath() const;
0612 
0613     /**
0614      * Copy constructor.
0615      */
0616     KWindowInfo(const KWindowInfo &);
0617     /**
0618      * Assignment operator.
0619      */
0620     KWindowInfo &operator=(const KWindowInfo &);
0621 
0622 private:
0623     QExplicitlySharedDataPointer<KWindowInfoPrivate> d;
0624 };
0625 
0626 #endif // multiple inclusion guard