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

KDE's Doxygen guidelines are available online.