File indexing completed on 2024-07-21 03:44:47

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  * kwindowsystem.h. Part of the KDE project.
0010  */
0011 
0012 #ifndef KWINDOWSYSTEM_H
0013 #define KWINDOWSYSTEM_H
0014 
0015 #include <QObject>
0016 #include <QWidgetList> //For WId
0017 #include <kwindowsystem_export.h>
0018 
0019 class KWindowSystemPrivate;
0020 
0021 /**
0022  *
0023  * Convenience access to certain properties and features of window systems.
0024  *
0025  */
0026 class KWINDOWSYSTEM_EXPORT KWindowSystem : public QObject
0027 {
0028     Q_OBJECT
0029     Q_PROPERTY(bool isPlatformWayland READ isPlatformWayland CONSTANT)
0030     Q_PROPERTY(bool isPlatformX11 READ isPlatformX11 CONSTANT)
0031 
0032     /**
0033      * @brief Whether "show desktop" is currently active
0034      */
0035     Q_PROPERTY(bool showingDesktop READ showingDesktop WRITE setShowingDesktop NOTIFY showingDesktopChanged)
0036 
0037 public:
0038     /**
0039      * Access to the singleton instance. Useful mainly for connecting to signals.
0040      */
0041     static KWindowSystem *self();
0042 
0043     /**
0044      * Requests that window @p window is activated.
0045      *
0046      * Applications shouldn't make attempts to explicitly activate
0047      * their windows, and instead let the user activate them.
0048      * In the special cases where this may be needed, applications
0049      * can use activateWindow(). The window manager may consider whether
0050      * this request wouldn't result in focus stealing, which
0051      * would be obtrusive, and may refuse the request.
0052      *
0053      * In case of problems, consult KWin's README.md file, or ask on the kwin@kde.org
0054      * mailing list.
0055      *
0056      * @param window the window to make active
0057      * @param time X server timestamp of the user activity that
0058      *    caused this request
0059      *
0060      * @since 5.89
0061      */
0062     Q_INVOKABLE static void activateWindow(QWindow *window, long time = 0);
0063 
0064     /**
0065      * Returns the state of showing the desktop.
0066      */
0067     static bool showingDesktop();
0068 
0069     /**
0070      * Sets the state of the "showing desktop" mode of the window manager. If on,
0071      * windows are hidden and desktop background is shown and focused.
0072      *
0073      * @param showing if true, the window manager is put in "showing desktop" mode.
0074      * If false, the window manager is put out of that mode.
0075      *
0076      * @since 5.7.0
0077      */
0078     static void setShowingDesktop(bool showing);
0079 
0080     /**
0081      * Sets the parent window of @p subwindow to be @p mainwindow.
0082      * This overrides the parent set the usual way as the QWidget or QWindow parent,
0083      * but only for the window manager - e.g. stacking order and window grouping
0084      * will be affected, but features like automatic deletion of children
0085      * when the parent is deleted are unaffected and normally use
0086      * the QObject parent.
0087      *
0088      * This function should be used before a dialog is shown for a window
0089      * that belongs to another application.
0090      *
0091      * On Wayland, use the QString overload to provide an XDG Foreign token.
0092      */
0093     static void setMainWindow(QWindow *subwindow, WId mainwindow);
0094 
0095     /**
0096      * Sets the parent window of @p subwindow to be @p mainwindow.
0097      *
0098      * This function should be used before a dialog is shown for a window
0099      * that belongs to another application.
0100      *
0101      * @param window the sub window
0102      * @param mainwindow The main window ID or XDG Foreign token
0103      *
0104      * @since 6.0
0105      */
0106     static void setMainWindow(QWindow *subwindow, const QString &mainwindow);
0107 
0108     /**
0109      * Updates the platform-specific startup id, if any.
0110      *
0111      * This method is to be called when a running application instance
0112      * is reused for handling the request to start this application.
0113      * A typical use would be in the handler of the KDBusService activation signal.
0114      *
0115      * For X11, this updates the id for the Startup Notification protocol,
0116      * taking the id from QX11Info::nextStartupId(), if not empty.
0117      * For Wayland, this updates the token for the XDG Activation protocol,
0118      * taking the token from the "XDG_ACTIVATION_TOKEN" environment variable
0119      * and then unsetting it, if not empty.
0120      *
0121      * @param window the main window (needed by X11 platform)
0122      *
0123      * @since 5.91
0124      */
0125     static void updateStartupId(QWindow *window);
0126 
0127     /**
0128      * Enum describing the windowing system platform used by the QGuiApplication.
0129      * @see platform
0130      * @since 5.25
0131      **/
0132     enum class Platform {
0133         /**
0134          * A platform unknown to the application is used
0135          **/
0136         Unknown,
0137         /**
0138          * The X11 window system.
0139          **/
0140         X11,
0141         /**
0142          * The Wayland window system.
0143          **/
0144         Wayland,
0145     };
0146     Q_ENUM(Platform)
0147     /**
0148      * Returns the Platform used by the QGuiApplication.
0149      * The Platform gets resolved the first time the method is invoked and cached for further
0150      * usages.
0151      * @returns The Platform used by the QGuiApplication.
0152      * @since 5.25
0153      **/
0154     static Platform platform();
0155 
0156     /**
0157      * Convenience method to check whether the Platform is X11.
0158      * @see platform
0159      * @see isPlatformWayland
0160      * @since 5.25
0161      **/
0162     static bool isPlatformX11();
0163 
0164     /**
0165      * Convenience method to check whether the Platform is Wayland.
0166      * @see platform
0167      * @see isPlatformX11
0168      * @since 5.25
0169      **/
0170     static bool isPlatformWayland();
0171 
0172     /**
0173      * Sets the @p token that will be used when activateWindow is called next
0174      *
0175      * @since 5.83
0176      */
0177     Q_INVOKABLE static void setCurrentXdgActivationToken(const QString &token);
0178 
0179 Q_SIGNALS:
0180     /**
0181      * The state of showing the desktop has changed.
0182      */
0183     void showingDesktopChanged(bool showing);
0184 
0185 private:
0186     friend class KWindowSystemStaticContainer;
0187     friend class KX11Extras;
0188     friend class KWaylandExtras;
0189 
0190     KWindowSystem()
0191     {
0192     }
0193     static KWindowSystemPrivate *d_func();
0194 };
0195 
0196 #endif