KWayland

plasmashell.h
1 /*
2  SPDX-FileCopyrightText: 2015 Martin Gräßlin <[email protected]>
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 
14 struct wl_surface;
15 struct org_kde_plasma_shell;
16 struct org_kde_plasma_surface;
17 
18 namespace KWayland
19 {
20 namespace Client
21 {
22 class EventQueue;
23 class Surface;
24 class 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  **/
51 class KWAYLANDCLIENT_EXPORT PlasmaShell : public QObject
52 {
53  Q_OBJECT
54 public:
55  explicit PlasmaShell(QObject *parent = nullptr);
56  virtual ~PlasmaShell();
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 
131 Q_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 
151 private:
152  class Private;
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  **/
173 class KWAYLANDCLIENT_EXPORT PlasmaShellSurface : public QObject
174 {
175  Q_OBJECT
176 public:
177  explicit PlasmaShellSurface(QObject *parent);
178  virtual ~PlasmaShellSurface();
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  };
238  /**
239  * Changes the requested Role to @p role.
240  * @see role
241  **/
242  void setRole(Role role);
243  /**
244  * @returns The requested Role, default value is @c Role::Normal.
245  * @see setRole
246  **/
247  Role role() const;
248  /**
249  * Requests to position this PlasmaShellSurface at @p point in global coordinates.
250  **/
251  void setPosition(const QPoint &point);
252 
253  /**
254  * Describes how a PlasmaShellSurface with role @c Role::Panel should behave.
255  * @see Role
256  **/
257  enum class PanelBehavior {
258  AlwaysVisible,
259  AutoHide,
260  WindowsCanCover,
261  WindowsGoBelow,
262  };
263  /**
264  * Sets the PanelBehavior for a PlasmaShellSurface with Role @c Role::Panel
265  * @see setRole
266  **/
267  void setPanelBehavior(PanelBehavior behavior);
268 
269  /**
270  * Setting this bit to the window, will make it say it prefers
271  * to not be listed in the taskbar. Taskbar implementations
272  * may or may not follow this hint.
273  * @since 5.5
274  */
275  void setSkipTaskbar(bool skip);
276 
277  /**
278  * Setting this bit on a window will indicate it does not prefer
279  * to be included in a window switcher.
280  * @since 5.47
281  */
282  void setSkipSwitcher(bool skip);
283 
284  /**
285  * Requests to hide a surface with Role Panel and PanelBahvior AutoHide.
286  *
287  * Once the compositor has hidden the panel the signal {@link autoHidePanelHidden} gets
288  * emitted. Once it is shown again the signal {@link autoHidePanelShown} gets emitted.
289  *
290  * To show the surface again from client side use {@link requestShowAutoHidingPanel}.
291  *
292  * @see autoHidePanelHidden
293  * @see autoHidePanelShown
294  * @see requestShowAutoHidingPanel
295  * @since 5.28
296  **/
297  void requestHideAutoHidingPanel();
298 
299  /**
300  * Requests to show a surface with Role Panel and PanelBahvior AutoHide.
301  *
302  * This request allows the client to show a surface which it previously
303  * requested to be hidden with {@link requestHideAutoHidingPanel}.
304  *
305  * @see autoHidePanelHidden
306  * @see autoHidePanelShown
307  * @see requestHideAutoHidingPanel
308  * @since 5.28
309  **/
310  void requestShowAutoHidingPanel();
311 
312  /**
313  * Set whether a PlasmaShellSurface should get focus or not.
314  *
315  * By default some roles do not take focus. With this request the compositor
316  * can be instructed to also pass focus.
317  *
318  * @param takesFocus Set to @c true if the surface should gain focus.
319  * @since 5.28
320  **/
321  // KF6 TODO rename to make it generic
322  void setPanelTakesFocus(bool takesFocus);
323 
324 Q_SIGNALS:
325  /**
326  * Emitted when the compositor hid an auto hiding panel.
327  * @see requestHideAutoHidingPanel
328  * @see autoHidePanelShown
329  * @see requestShowAutoHidingPanel
330  * @since 5.28
331  **/
332  void autoHidePanelHidden();
333 
334  /**
335  * Emitted when the compositor showed an auto hiding panel.
336  * @see requestHideAutoHidingPanel
337  * @see autoHidePanelHidden
338  * @see requestShowAutoHidingPanel
339  * @since 5.28
340  **/
341  void autoHidePanelShown();
342 
343 private:
344  friend class PlasmaShell;
345  class Private;
347 };
348 
349 }
350 }
351 
354 
355 #endif
Wrapper for the org_kde_plasma_surface interface.
Definition: plasmashell.h:173
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
Wrapper for the wl_surface interface.
Definition: surface.h:43
Wrapper for the org_kde_plasma_shell interface.
Definition: plasmashell.h:51
Role
Describes possible roles this PlasmaShellSurface can have.
Definition: plasmashell.h:229
PanelBehavior
Describes how a PlasmaShellSurface with role Role::Panel should behave.
Definition: plasmashell.h:257
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Sep 23 2021 22:51:08 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.