1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1999 Matthias Ettrich <ettrich@kde.org>
4 SPDX-FileCopyrightText: 2007 Lubos Lunak <l.lunak@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.1-or-later
7*/
8/*
9 * kwindowsystem.h. Part of the KDE project.
10 */
11
12#ifndef KWINDOWSYSTEM_H
13#define KWINDOWSYSTEM_H
14
15#include <QObject>
16#include <QWidgetList> //For WId
17#include <kwindowsystem_export.h>
18
19class KWindowSystemPrivate;
20
21/*!
22 * \qmltype KWindowSystem
23 * \inqmlmodule org.kde.kwindowsystem
24 * \nativetype KWindowSystem
25 * \brief Convenience access to certain properties and features of window systems.
26 */
27/*!
28 * \class KWindowSystem
29 * \inmodule KWindowSystem
30 * \brief Convenience access to certain properties and features of window systems.
31 */
32class KWINDOWSYSTEM_EXPORT KWindowSystem : public QObject
33{
34 Q_OBJECT
35 /*!
36 * \qmlproperty bool KWindowSystem::isPlatformWayland
37 */
38 /*!
39 * \property KWindowSystem::isPlatformWayland
40 */
41 Q_PROPERTY(bool isPlatformWayland READ isPlatformWayland CONSTANT)
42 /*!
43 * \qmlproperty bool KWindowSystem::isPlatformX11
44 */
45 /*!
46 * \property KWindowSystem::isPlatformX11
47 */
48 Q_PROPERTY(bool isPlatformX11 READ isPlatformX11 CONSTANT)
49
50 /*!
51 * \qmlproperty bool KWindowSystem::showingDesktop
52 *
53 * \brief Whether "show desktop" is currently active.
54 */
55 /*!
56 * \property KWindowSystem::showingDesktop
57 *
58 * \brief Whether "show desktop" is currently active.
59 */
60 Q_PROPERTY(bool showingDesktop READ showingDesktop WRITE setShowingDesktop NOTIFY showingDesktopChanged)
61
62public:
63 /*
64 * Access to the singleton instance. Useful mainly for connecting to signals.
65 */
66 static KWindowSystem *self();
67
68 /*!
69 * Requests that window \a window is activated.
70 *
71 * Applications shouldn't make attempts to explicitly activate
72 * their windows, and instead let the user activate them.
73 * In the special cases where this may be needed, applications
74 * can use activateWindow(). The window manager may consider whether
75 * this request wouldn't result in focus stealing, which
76 * would be obtrusive, and may refuse the request.
77 *
78 * In case of problems, consult KWin's README.md file, or ask on the kwin@kde.org
79 * mailing list.
80 *
81 * \a window the window to make active
82 * \a time X server timestamp of the user activity that
83 * caused this request
84 *
85 * \since 5.89
86 */
87 Q_INVOKABLE static void activateWindow(QWindow *window, long time = 0);
88
89 /*!
90 * Returns the state of showing the desktop.
91 */
92 static bool showingDesktop();
93
94 /*!
95 * Sets the state of the "showing desktop" mode of the window manager. If on,
96 * windows are hidden and desktop background is shown and focused.
97 *
98 * \a showing if true, the window manager is put in "showing desktop" mode.
99 * If false, the window manager is put out of that mode.
100 *
101 * \since 5.7.0
102 */
103 static void setShowingDesktop(bool showing);
104
105 /*!
106 * Sets the parent window of \a subwindow to be \a mainwindow.
107 * This overrides the parent set the usual way as the QWidget or QWindow parent,
108 * but only for the window manager - e.g. stacking order and window grouping
109 * will be affected, but features like automatic deletion of children
110 * when the parent is deleted are unaffected and normally use
111 * the QObject parent.
112 *
113 * This function should be used before a dialog is shown for a window
114 * that belongs to another application.
115 *
116 * On Wayland, use the QString overload to provide an XDG Foreign token.
117 */
118 static void setMainWindow(QWindow *subwindow, WId mainwindow);
119
120 /*!
121 * Sets the parent window of \a subwindow to be \a mainwindow.
122 *
123 * This function should be used before a dialog is shown for a window
124 * that belongs to another application.
125 *
126 * \a subwindow the sub window
127 * \a mainwindow The main window ID or XDG Foreign token
128 *
129 * \since 6.0
130 */
131 static void setMainWindow(QWindow *subwindow, const QString &mainwindow);
132
133 /*!
134 * Updates the platform-specific startup id, if any.
135 *
136 * This method is to be called when a running application instance
137 * is reused for handling the request to start this application.
138 * A typical use would be in the handler of the KDBusService activation signal.
139 *
140 * For X11, this updates the id for the Startup Notification protocol,
141 * taking the id from QX11Info::nextStartupId(), if not empty.
142 * For Wayland, this updates the token for the XDG Activation protocol,
143 * taking the token from the "XDG_ACTIVATION_TOKEN" environment variable
144 * and then unsetting it, if not empty.
145 *
146 * \a window the main window (needed by X11 platform)
147 *
148 * \since 5.91
149 */
150 static void updateStartupId(QWindow *window);
151
152 /*!
153 * \enum KWindowSystem::Platform
154 * \brief Enum describing the windowing system platform used by the QGuiApplication.
155 * \value Unknown
156 * A platform unknown to the application is used
157 * \value X11
158 * The X11 window system.
159 * \value Wayland
160 * The Wayland window system.
161 * \sa platform()
162 * \since 5.25
163 **/
164 enum class Platform {
165 Unknown,
166 X11,
167 Wayland,
168 };
169 Q_ENUM(Platform)
170 /*!
171 * Returns the Platform used by the QGuiApplication.
172 * The Platform gets resolved the first time the method is invoked and cached for further
173 * usages.
174 * Returns The Platform used by the QGuiApplication.
175 * \since 5.25
176 **/
177 static Platform platform();
178
179 /*!
180 * Returns whether the Platform is X11.
181 * \sa platform
182 * \sa isPlatformWayland
183 * \since 5.25
184 **/
185 static bool isPlatformX11();
186
187 /*!
188 * Returns whether the Platform is Wayland.
189 * \sa platform
190 * \sa isPlatformX11
191 * \since 5.25
192 **/
193 static bool isPlatformWayland();
194
195 /*!
196 * Sets the \a token that will be used when activateWindow is called next
197 *
198 * \since 5.83
199 */
200 Q_INVOKABLE static void setCurrentXdgActivationToken(const QString &token);
201
202Q_SIGNALS:
203 /*!
204 * The state of \a showing the desktop has changed.
205 */
206 void showingDesktopChanged(bool showing);
207
208private:
209 friend class KWindowSystemStaticContainer;
210 friend class KX11Extras;
211 friend class KWaylandExtras;
212
213 KWindowSystem()
214 {
215 }
216 static KWindowSystemPrivate *d_func();
217};
218
219#endif
220

source code of kwindowsystem/src/kwindowsystem.h