File indexing completed on 2024-07-14 03:57:44

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