1/*
2 SPDX-FileCopyrightText: 2015 Martin Gräßlin <mgraesslin@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5*/
6#ifndef WAYLAND_PLASMASHELL_H
7#define WAYLAND_PLASMASHELL_H
8
9#include <QObject>
10#include <QSize>
11
12#include "KWayland/Client/kwaylandclient_export.h"
13
14struct wl_surface;
15struct org_kde_plasma_shell;
16struct org_kde_plasma_surface;
17
18namespace KWayland
19{
20namespace Client
21{
22class EventQueue;
23class Surface;
24class PlasmaShellSurface;
25
26/**
27 * @short Wrapper for the org_kde_plasma_shell interface.
28 *
29 * This class provides a convenient wrapper for the org_kde_plasma_shell interface.
30 * It's main purpose is to create a PlasmaShellSurface.
31 *
32 * To use this class one needs to interact with the Registry. There are two
33 * possible ways to create the Shell interface:
34 * @code
35 * PlasmaShell *s = registry->createPlasmaShell(name, version);
36 * @endcode
37 *
38 * This creates the PlasmaShell and sets it up directly. As an alternative this
39 * can also be done in a more low level way:
40 * @code
41 * PlasmaShell *s = new PlasmaShell;
42 * s->setup(registry->bindPlasmaShell(name, version));
43 * @endcode
44 *
45 * The PlasmaShell can be used as a drop-in replacement for any org_kde_plasma_shell
46 * pointer as it provides matching cast operators.
47 *
48 * @see Registry
49 * @see PlasmaShellSurface
50 **/
51class KWAYLANDCLIENT_EXPORT PlasmaShell : public QObject
52{
53 Q_OBJECT
54public:
55 explicit PlasmaShell(QObject *parent = nullptr);
56 ~PlasmaShell() override;
57
58 /**
59 * @returns @c true if managing a org_kde_plasma_shell.
60 **/
61 bool isValid() const;
62 /**
63 * Releases the org_kde_plasma_shell interface.
64 * After the interface has been released the PlasmaShell instance is no
65 * longer valid and can be setup with another org_kde_plasma_shell interface.
66 *
67 * Right before the interface is released the signal interfaceAboutToBeReleased is emitted.
68 * @see interfaceAboutToBeReleased
69 **/
70 void release();
71 /**
72 * Destroys the data held by this PlasmaShell.
73 * This method is supposed to be used when the connection to the Wayland
74 * server goes away. Once the connection becomes invalid, it's not
75 * possible to call release anymore as that calls into the Wayland
76 * connection and the call would fail. This method cleans up the data, so
77 * that the instance can be deleted or set up to a new org_kde_plasma_shell interface
78 * once there is a new connection available.
79 *
80 * This method is automatically invoked when the Registry which created this
81 * PlasmaShell gets destroyed.
82 *
83 * Right before the data is destroyed, the signal interfaceAboutToBeDestroyed is emitted.
84 *
85 * @see release
86 * @see interfaceAboutToBeDestroyed
87 **/
88 void destroy();
89 /**
90 * Setup this Shell to manage the @p shell.
91 * When using Registry::createShell there is no need to call this
92 * method.
93 **/
94 void setup(org_kde_plasma_shell *shell);
95
96 /**
97 * Sets the @p queue to use for creating a Surface.
98 **/
99 void setEventQueue(EventQueue *queue);
100 /**
101 * @returns The event queue to use for creating a Surface.
102 **/
103 EventQueue *eventQueue();
104
105 /**
106 * Creates a PlasmaShellSurface for the given @p surface and sets it up.
107 *
108 * If a PlasmaShellSurface for the given @p surface has already been created
109 * a pointer to the existing one is returned instead of creating a new surface.
110 *
111 * @param surface The native surface to create the PlasmaShellSurface for
112 * @param parent The parent to use for the PlasmaShellSurface
113 * @returns created PlasmaShellSurface
114 **/
115 PlasmaShellSurface *createSurface(wl_surface *surface, QObject *parent = nullptr);
116 /**
117 * Creates a PlasmaShellSurface for the given @p surface and sets it up.
118 *
119 * If a PlasmaShellSurface for the given @p surface has already been created
120 * a pointer to the existing one is returned instead of creating a new surface.
121 *
122 * @param surface The Surface to create the PlasmaShellSurface for
123 * @param parent The parent to use for the PlasmaShellSurface
124 * @returns created PlasmaShellSurface
125 **/
126 PlasmaShellSurface *createSurface(Surface *surface, QObject *parent = nullptr);
127
128 operator org_kde_plasma_shell *();
129 operator org_kde_plasma_shell *() const;
130
131Q_SIGNALS:
132 /**
133 * This signal is emitted right before the interface is released.
134 **/
135 void interfaceAboutToBeReleased();
136 /**
137 * This signal is emitted right before the data is destroyed.
138 **/
139 void interfaceAboutToBeDestroyed();
140
141 /**
142 * The corresponding global for this interface on the Registry got removed.
143 *
144 * This signal gets only emitted if the Compositor got created by
145 * Registry::createPlasmaShell
146 *
147 * @since 5.5
148 **/
149 void removed();
150
151private:
152 class Private;
153 QScopedPointer<Private> d;
154};
155
156/**
157 * @short Wrapper for the org_kde_plasma_surface interface.
158 *
159 * This class is a convenient wrapper for the org_kde_plasma_surface interface.
160 *
161 * To create an instance use PlasmaShell::createSurface.
162 *
163 * A PlasmaShellSurface is a privileged Surface which can add further hints to the
164 * Wayland server about it's position and the usage role. The Wayland server is allowed
165 * to ignore all requests.
166 *
167 * Even if a PlasmaShellSurface is created for a Surface a normal ShellSurface (or similar)
168 * needs to be created to have the Surface mapped as a window by the Wayland server.
169 *
170 * @see PlasmaShell
171 * @see Surface
172 **/
173class KWAYLANDCLIENT_EXPORT PlasmaShellSurface : public QObject
174{
175 Q_OBJECT
176public:
177 explicit PlasmaShellSurface(QObject *parent);
178 ~PlasmaShellSurface() override;
179
180 /**
181 * Releases the org_kde_plasma_surface interface.
182 * After the interface has been released the PlasmaShellSurface instance is no
183 * longer valid and can be setup with another org_kde_plasma_surface interface.
184 *
185 * This method is automatically invoked when the PlasmaShell which created this
186 * PlasmaShellSurface gets released.
187 **/
188 void release();
189 /**
190 * Destroys the data held by this PlasmaShellSurface.
191 * This method is supposed to be used when the connection to the Wayland
192 * server goes away. If the connection is not valid anymore, it's not
193 * possible to call release anymore as that calls into the Wayland
194 * connection and the call would fail. This method cleans up the data, so
195 * that the instance can be deleted or set up to a new org_kde_plasma_surface interface
196 * once there is a new connection available.
197 *
198 * This method is automatically invoked when the PlasmaShell which created this
199 * PlasmaShellSurface gets destroyed.
200 *
201 * @see release
202 **/
203 void destroy();
204 /**
205 * Setup this PlasmaShellSurface to manage the @p surface.
206 * There is normally no need to call this method as it's invoked by
207 * PlasmaShell::createSurface.
208 **/
209 void setup(org_kde_plasma_surface *surface);
210
211 /**
212 * @returns the PlasmaShellSurface * associated with surface,
213 * if any, nullptr if not found.
214 * @since 5.6
215 */
216 static PlasmaShellSurface *get(Surface *surf);
217
218 /**
219 * @returns @c true if managing a org_kde_plasma_surface.
220 **/
221 bool isValid() const;
222 operator org_kde_plasma_surface *();
223 operator org_kde_plasma_surface *() const;
224
225 /**
226 * Describes possible roles this PlasmaShellSurface can have.
227 * The role can be used by the Wayland server to e.g. change the stacking order accordingly.
228 **/
229 enum class Role {
230 Normal, ///< A normal Surface
231 Desktop, ///< The Surface represents a desktop, normally stacked below all other surfaces
232 Panel, ///< The Surface represents a panel (dock), normally stacked above normal surfaces
233 OnScreenDisplay, ///< The Surface represents an on screen display, like a volume changed notification
234 Notification, ///< The Surface represents a notification @since 5.24
235 ToolTip, ///< The Surface represents a tooltip @since 5.24
236 CriticalNotification, ///< The Surface represents a critical notification, like battery is running out @since 5.58
237 AppletPopup, ///< The Surface used for applets
238 };
239 /**
240 * Changes the requested Role to @p role.
241 * @see role
242 **/
243 void setRole(Role role);
244 /**
245 * @returns The requested Role, default value is @c Role::Normal.
246 * @see setRole
247 **/
248 Role role() const;
249 /**
250 * Requests to position this PlasmaShellSurface at @p point in global coordinates.
251 **/
252 void setPosition(const QPoint &point);
253
254 /**
255 * Request that the initial position of this surface will be under the cursor
256 *
257 * Has to be called before attaching any buffer to the corresponding surface.
258 * @since 5.94
259 **/
260 void openUnderCursor();
261
262 /**
263 * Describes how a PlasmaShellSurface with role @c Role::Panel should behave.
264 * @see Role
265 **/
266 enum class PanelBehavior {
267 AlwaysVisible,
268 AutoHide,
269 WindowsCanCover,
270 WindowsGoBelow,
271 };
272 /**
273 * Sets the PanelBehavior for a PlasmaShellSurface with Role @c Role::Panel
274 * @see setRole
275 **/
276 void setPanelBehavior(PanelBehavior behavior);
277
278 /**
279 * Setting this bit to the window, will make it say it prefers
280 * to not be listed in the taskbar. Taskbar implementations
281 * may or may not follow this hint.
282 * @since 5.5
283 */
284 void setSkipTaskbar(bool skip);
285
286 /**
287 * Setting this bit on a window will indicate it does not prefer
288 * to be included in a window switcher.
289 * @since 5.47
290 */
291 void setSkipSwitcher(bool skip);
292
293 /**
294 * Requests to hide a surface with Role Panel and PanelBahvior AutoHide.
295 *
296 * Once the compositor has hidden the panel the signal {@link autoHidePanelHidden} gets
297 * emitted. Once it is shown again the signal {@link autoHidePanelShown} gets emitted.
298 *
299 * To show the surface again from client side use {@link requestShowAutoHidingPanel}.
300 *
301 * @see autoHidePanelHidden
302 * @see autoHidePanelShown
303 * @see requestShowAutoHidingPanel
304 * @since 5.28
305 **/
306 void requestHideAutoHidingPanel();
307
308 /**
309 * Requests to show a surface with Role Panel and PanelBahvior AutoHide.
310 *
311 * This request allows the client to show a surface which it previously
312 * requested to be hidden with {@link requestHideAutoHidingPanel}.
313 *
314 * @see autoHidePanelHidden
315 * @see autoHidePanelShown
316 * @see requestHideAutoHidingPanel
317 * @since 5.28
318 **/
319 void requestShowAutoHidingPanel();
320
321 /**
322 * Set whether a PlasmaShellSurface should get focus or not.
323 *
324 * By default some roles do not take focus. With this request the compositor
325 * can be instructed to also pass focus.
326 *
327 * @param takesFocus Set to @c true if the surface should gain focus.
328 * @since 5.28
329 **/
330 // KF6 TODO rename to make it generic
331 void setPanelTakesFocus(bool takesFocus);
332
333Q_SIGNALS:
334 /**
335 * Emitted when the compositor hid an auto hiding panel.
336 * @see requestHideAutoHidingPanel
337 * @see autoHidePanelShown
338 * @see requestShowAutoHidingPanel
339 * @since 5.28
340 **/
341 void autoHidePanelHidden();
342
343 /**
344 * Emitted when the compositor showed an auto hiding panel.
345 * @see requestHideAutoHidingPanel
346 * @see autoHidePanelHidden
347 * @see requestShowAutoHidingPanel
348 * @since 5.28
349 **/
350 void autoHidePanelShown();
351
352private:
353 friend class PlasmaShell;
354 class Private;
355 QScopedPointer<Private> d;
356};
357
358}
359}
360
361Q_DECLARE_METATYPE(KWayland::Client::PlasmaShellSurface::Role)
362Q_DECLARE_METATYPE(KWayland::Client::PlasmaShellSurface::PanelBehavior)
363
364#endif
365

source code of kwayland/src/client/plasmashell.h