KWayland

plasmashell_interface.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_SERVER_PLASMA_SHELL_INTERFACE_H
7 #define WAYLAND_SERVER_PLASMA_SHELL_INTERFACE_H
8 
9 #include <QObject>
10 
11 #include <KWayland/Server/kwaylandserver_export.h>
12 
13 #include "global.h"
14 #include "resource.h"
15 
16 struct wl_resource;
17 
18 namespace KWayland
19 {
20 namespace Server
21 {
22 class Display;
23 class SurfaceInterface;
24 class PlasmaShellSurfaceInterface;
25 
26 /**
27  * @brief Global for the org_kde_plasma_shell interface.
28  *
29  * The PlasmaShellInterface allows to add additional information to a SurfaceInterface.
30  * It goes beyond what a ShellSurfaceInterface provides and is adjusted toward the needs
31  * of the Plasma desktop.
32  *
33  * A server providing this interface should think about how to restrict access to it as
34  * it allows to perform absolute window positioning.
35  *
36  * @since 5.4
37  **/
38 class KWAYLANDSERVER_EXPORT PlasmaShellInterface : public Global
39 {
40  Q_OBJECT
41 public:
42  virtual ~PlasmaShellInterface();
43 
44 Q_SIGNALS:
45  /**
46  * Emitted whenever a PlasmaShellSurfaceInterface got created.
47  **/
48  void surfaceCreated(KWayland::Server::PlasmaShellSurfaceInterface *);
49 
50 private:
51  friend class Display;
52  explicit PlasmaShellInterface(Display *display, QObject *parent);
53  class Private;
54 };
55 
56 /**
57  * @brief Resource for the org_kde_plasma_shell_surface interface.
58  *
59  * PlasmaShellSurfaceInterface gets created by PlasmaShellInterface.
60  *
61  * @since 5.4
62  **/
63 class KWAYLANDSERVER_EXPORT PlasmaShellSurfaceInterface : public Resource
64 {
65  Q_OBJECT
66 public:
67  virtual ~PlasmaShellSurfaceInterface();
68 
69  /**
70  * @returns the SurfaceInterface this PlasmaShellSurfaceInterface got created for
71  **/
72  SurfaceInterface *surface() const;
73  /**
74  * @returns The PlasmaShellInterface which created this PlasmaShellSurfaceInterface.
75  **/
76  PlasmaShellInterface *shell() const;
77 
78  /**
79  * @returns the requested position in global coordinates.
80  **/
81  QPoint position() const;
82  /**
83  * @returns Whether a global position has been requested.
84  **/
85  bool isPositionSet() const;
86 
87  /**
88  * Describes possible roles this PlasmaShellSurfaceInterface can have.
89  * The role can be used by the server to e.g. change the stacking order accordingly.
90  **/
91  enum class Role {
92  Normal, ///< A normal surface
93  Desktop, ///< The surface represents a desktop, normally stacked below all other surfaces
94  Panel, ///< The surface represents a panel (dock), normally stacked above normal surfaces
95  OnScreenDisplay, ///< The surface represents an on screen display, like a volume changed notification
96  Notification, ///< The surface represents a notification @since 5.24
97  ToolTip, ///< The surface represents a tooltip @since 5.24
98  CriticalNotification, ///< The surface represents a critical notification, like battery is running out @since 5.58
99  };
100  /**
101  * @returns The requested role, default value is @c Role::Normal.
102  **/
103  Role role() const;
104  /**
105  * Describes how a PlasmaShellSurfaceInterface with role @c Role::Panel should behave.
106  **/
107  enum class PanelBehavior {
108  AlwaysVisible, ///< The panel should be always visible
109  AutoHide, ///< The panel auto hides at a screen edge and returns on mouse press against edge
110  WindowsCanCover, ///< Windows are allowed to go above the panel, it raises on mouse press against screen edge
111  WindowsGoBelow, ///< Window are allowed to go below the panel
112  };
113  /**
114  * @returns The PanelBehavior for a PlasmaShellSurfaceInterface with role @c Role::Panel
115  * @see role
116  **/
117  PanelBehavior panelBehavior() const;
118 
119  /**
120  * @returns true if this window doesn't want to be listed
121  * in the taskbar
122  * @since 5.5
123  **/
124  bool skipTaskbar() const;
125 
126  /**
127  * @returns true if this window doesn't want to be listed
128  * in a window switcher
129  * @since 5.47
130  **/
131  bool skipSwitcher() const;
132 
133  /**
134  * Informs the PlasmaShellSurfaceInterface that the auto-hiding panel got hidden.
135  * Once it is shown again the method {@link showAutoHidingPanel} should be used.
136  *
137  * @see showAutoHidingPanel
138  * @see panelAutoHideHideRequested
139  * @see panelAutoHideShowRequested
140  * @since 5.28
141  **/
142  void hideAutoHidingPanel();
143 
144  /**
145  * Informs the PlasmaShellSurfaceInterface that the auto-hiding panel got shown again.
146  *
147  * @see hideAutoHidingPanel
148  * @see panelAutoHideHideRequested
149  * @see panelAutoHideShowRequested
150  * @see 5.28
151  **/
152  void showAutoHidingPanel();
153 
154  /**
155  * Whether a PlasmaShellSurfaceInterface wants to have focus.
156  *
157  * By default some PlasmaShell roles do not get focus, but the PlasmaShellSurfaceInterface can
158  * request that it wants to have focus. The compositor can use this information to
159  * pass focus to the surface.
160  * @since 5.28
161  **/
162  // TODO KF6 rename to something generic
163  bool panelTakesFocus() const;
164 
165  /**
166  * @returns The PlasmaShellSurfaceInterface for the @p native resource.
167  * @since 5.5
168  **/
169  static PlasmaShellSurfaceInterface *get(wl_resource *native);
170 
171 Q_SIGNALS:
172  /**
173  * A change of global position has been requested.
174  **/
175  void positionChanged();
176  /**
177  * A change of the role has been requested.
178  **/
179  void roleChanged();
180  /**
181  * A change of the panel behavior has been requested.
182  **/
183  void panelBehaviorChanged();
184  /**
185  * A change in the skip taskbar property has been requested
186  */
187  void skipTaskbarChanged();
188  /**
189  * A change in the skip switcher property has been requested
190  **/
191  void skipSwitcherChanged();
192 
193  /**
194  * A surface with Role Panel and PanelBehavior AutoHide requested to be hidden.
195  *
196  * The compositor should inform the PlasmaShellSurfaceInterface about the actual change.
197  * Once the surface is hidden it should invoke {@link hideAutoHidingPanel}. If the compositor
198  * cannot hide the surface (e.g. because it doesn't border a screen edge) it should inform
199  * the surface through invoking {@link showAutoHidingPanel}. This method should also be invoked
200  * whenever the surface gets shown again due to triggering the screen edge.
201  *
202  * @see hideAutoHidingPanel
203  * @see showAutoHidingPanel
204  * @see panelAutoHideShowRequested
205  * @since 5.28
206  **/
207  void panelAutoHideHideRequested();
208 
209  /**
210  * A surface with Role Panel and PanelBehavior AutoHide requested to be shown.
211  *
212  * The compositor should inform the PlasmaShellSurfaceInterface about the actual change.
213  * Once the surface is shown it should invoke {@link showAutoHidingPanel}.
214  *
215  * @see hideAutoHidingPanel
216  * @see showAutoHidingPanel
217  * @see panelAutoHideHideRequested
218  * @since 5.28
219  **/
220  void panelAutoHideShowRequested();
221 
222  /*
223  * Emitted when panelTakesFocus changes
224  * @see panelTakesFocus
225  * @since 5.66
226  */
227  void panelTakesFocusChanged();
228 
229 private:
230  friend class PlasmaShellInterface;
231  explicit PlasmaShellSurfaceInterface(PlasmaShellInterface *shell, SurfaceInterface *parent, wl_resource *parentResource);
232  class Private;
233  Private *d_func() const;
234 };
235 
236 }
237 }
238 
241 
242 #endif
Global for the org_kde_plasma_shell interface.
Resource for the org_kde_plasma_shell_surface interface.
Resource representing a wl_surface.
Class holding the Wayland server display loop.
Definition: display.h:86
Base class for all Globals.
Definition: global.h:46
Represents a bound Resource.
Definition: resource.h:31
PanelBehavior
Describes how a PlasmaShellSurfaceInterface with role Role::Panel should behave.
Role
Describes possible roles this PlasmaShellSurfaceInterface can have.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Sep 24 2021 22:51:11 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.