KWindowSystem

kwindowsystem.h
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 *
23 * Convenience access to certain properties and features of window systems.
24 *
25 */
26class KWINDOWSYSTEM_EXPORT KWindowSystem : public QObject
27{
28 Q_OBJECT
29 Q_PROPERTY(bool isPlatformWayland READ isPlatformWayland CONSTANT)
30 Q_PROPERTY(bool isPlatformX11 READ isPlatformX11 CONSTANT)
31
32 /**
33 * @brief Whether "show desktop" is currently active
34 */
35 Q_PROPERTY(bool showingDesktop READ showingDesktop WRITE setShowingDesktop NOTIFY showingDesktopChanged)
36
37public:
38 /**
39 * Access to the singleton instance. Useful mainly for connecting to signals.
40 */
41 static KWindowSystem *self();
42
43 /**
44 * Requests that window @p window is activated.
45 *
46 * Applications shouldn't make attempts to explicitly activate
47 * their windows, and instead let the user activate them.
48 * In the special cases where this may be needed, applications
49 * can use activateWindow(). The window manager may consider whether
50 * this request wouldn't result in focus stealing, which
51 * would be obtrusive, and may refuse the request.
52 *
53 * In case of problems, consult KWin's README.md file, or ask on the kwin@kde.org
54 * mailing list.
55 *
56 * @param window the window to make active
57 * @param time X server timestamp of the user activity that
58 * caused this request
59 *
60 * @since 5.89
61 */
62 Q_INVOKABLE static void activateWindow(QWindow *window, long time = 0);
63
64 /**
65 * Returns the state of showing the desktop.
66 */
67 static bool showingDesktop();
68
69 /**
70 * Sets the state of the "showing desktop" mode of the window manager. If on,
71 * windows are hidden and desktop background is shown and focused.
72 *
73 * @param showing if true, the window manager is put in "showing desktop" mode.
74 * If false, the window manager is put out of that mode.
75 *
76 * @since 5.7.0
77 */
78 static void setShowingDesktop(bool showing);
79
80 /**
81 * Sets the parent window of @p subwindow to be @p mainwindow.
82 * This overrides the parent set the usual way as the QWidget or QWindow parent,
83 * but only for the window manager - e.g. stacking order and window grouping
84 * will be affected, but features like automatic deletion of children
85 * when the parent is deleted are unaffected and normally use
86 * the QObject parent.
87 *
88 * This function should be used before a dialog is shown for a window
89 * that belongs to another application.
90 *
91 * On Wayland, use the QString overload to provide an XDG Foreign token.
92 */
93 static void setMainWindow(QWindow *subwindow, WId mainwindow);
94
95 /**
96 * Sets the parent window of @p subwindow to be @p mainwindow.
97 *
98 * This function should be used before a dialog is shown for a window
99 * that belongs to another application.
100 *
101 * @param window the sub window
102 * @param mainwindow The main window ID or XDG Foreign token
103 *
104 * @since 6.0
105 */
106 static void setMainWindow(QWindow *subwindow, const QString &mainwindow);
107
108 /**
109 * Updates the platform-specific startup id, if any.
110 *
111 * This method is to be called when a running application instance
112 * is reused for handling the request to start this application.
113 * A typical use would be in the handler of the KDBusService activation signal.
114 *
115 * For X11, this updates the id for the Startup Notification protocol,
116 * taking the id from QX11Info::nextStartupId(), if not empty.
117 * For Wayland, this updates the token for the XDG Activation protocol,
118 * taking the token from the "XDG_ACTIVATION_TOKEN" environment variable
119 * and then unsetting it, if not empty.
120 *
121 * @param window the main window (needed by X11 platform)
122 *
123 * @since 5.91
124 */
125 static void updateStartupId(QWindow *window);
126
127 /**
128 * Enum describing the windowing system platform used by the QGuiApplication.
129 * @see platform
130 * @since 5.25
131 **/
132 enum class Platform {
133 /**
134 * A platform unknown to the application is used
135 **/
136 Unknown,
137 /**
138 * The X11 window system.
139 **/
140 X11,
141 /**
142 * The Wayland window system.
143 **/
144 Wayland,
145 };
146 Q_ENUM(Platform)
147 /**
148 * Returns the Platform used by the QGuiApplication.
149 * The Platform gets resolved the first time the method is invoked and cached for further
150 * usages.
151 * @returns The Platform used by the QGuiApplication.
152 * @since 5.25
153 **/
154 static Platform platform();
155
156 /**
157 * Convenience method to check whether the Platform is X11.
158 * @see platform
159 * @see isPlatformWayland
160 * @since 5.25
161 **/
162 static bool isPlatformX11();
163
164 /**
165 * Convenience method to check whether the Platform is Wayland.
166 * @see platform
167 * @see isPlatformX11
168 * @since 5.25
169 **/
170 static bool isPlatformWayland();
171
172 /**
173 * Sets the @p token that will be used when activateWindow is called next
174 *
175 * @since 5.83
176 */
177 Q_INVOKABLE static void setCurrentXdgActivationToken(const QString &token);
178
180 /**
181 * The state of showing the desktop has changed.
182 */
183 void showingDesktopChanged(bool showing);
184
185private:
186 friend class KWindowSystemStaticContainer;
187 friend class KX11Extras;
188 friend class KWaylandExtras;
189
191 {
192 }
193 static KWindowSystemPrivate *d_func();
194};
195
196#endif
A collection of functions to do Wayland things.
Convenience access to certain properties and features of window systems.
static bool isPlatformX11()
Convenience method to check whether the Platform is X11.
void showingDesktopChanged(bool showing)
The state of showing the desktop has changed.
static bool isPlatformWayland()
Convenience method to check whether the Platform is Wayland.
Platform
Enum describing the windowing system platform used by the QGuiApplication.
A collection of functions to obtain information from and manipulate X11 windows.
Definition kx11extras.h:29
Q_ENUM(...)
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 14 2024 11:53:18 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.