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  ~PlasmaShellInterface() override;
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  ~PlasmaShellSurfaceInterface() override;
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  AppletPopup, ///< The surface represents an applet
100  };
101  /**
102  * @returns The requested role, default value is @c Role::Normal.
103  **/
104  Role role() const;
105  /**
106  * Describes how a PlasmaShellSurfaceInterface with role @c Role::Panel should behave.
107  **/
108  enum class PanelBehavior {
109  AlwaysVisible, ///< The panel should be always visible
110  AutoHide, ///< The panel auto hides at a screen edge and returns on mouse press against edge
111  WindowsCanCover, ///< Windows are allowed to go above the panel, it raises on mouse press against screen edge
112  WindowsGoBelow, ///< Window are allowed to go below the panel
113  };
114  /**
115  * @returns The PanelBehavior for a PlasmaShellSurfaceInterface with role @c Role::Panel
116  * @see role
117  **/
118  PanelBehavior panelBehavior() const;
119 
120  /**
121  * @returns true if this window doesn't want to be listed
122  * in the taskbar
123  * @since 5.5
124  **/
125  bool skipTaskbar() const;
126 
127  /**
128  * @returns true if this window doesn't want to be listed
129  * in a window switcher
130  * @since 5.47
131  **/
132  bool skipSwitcher() const;
133 
134  /**
135  * Informs the PlasmaShellSurfaceInterface that the auto-hiding panel got hidden.
136  * Once it is shown again the method {@link showAutoHidingPanel} should be used.
137  *
138  * @see showAutoHidingPanel
139  * @see panelAutoHideHideRequested
140  * @see panelAutoHideShowRequested
141  * @since 5.28
142  **/
143  void hideAutoHidingPanel();
144 
145  /**
146  * Informs the PlasmaShellSurfaceInterface that the auto-hiding panel got shown again.
147  *
148  * @see hideAutoHidingPanel
149  * @see panelAutoHideHideRequested
150  * @see panelAutoHideShowRequested
151  * @see 5.28
152  **/
153  void showAutoHidingPanel();
154 
155  /**
156  * Whether a PlasmaShellSurfaceInterface wants to have focus.
157  *
158  * By default some PlasmaShell roles do not get focus, but the PlasmaShellSurfaceInterface can
159  * request that it wants to have focus. The compositor can use this information to
160  * pass focus to the surface.
161  * @since 5.28
162  **/
163  // TODO KF6 rename to something generic
164  bool panelTakesFocus() const;
165 
166  /**
167  * @returns The PlasmaShellSurfaceInterface for the @p native resource.
168  * @since 5.5
169  **/
170  static PlasmaShellSurfaceInterface *get(wl_resource *native);
171 
172 Q_SIGNALS:
173  /**
174  * A change of global position has been requested.
175  **/
176  void positionChanged();
177  /**
178  * A change of the role has been requested.
179  **/
180  void roleChanged();
181  /**
182  * A change of the panel behavior has been requested.
183  **/
184  void panelBehaviorChanged();
185  /**
186  * A change in the skip taskbar property has been requested
187  */
188  void skipTaskbarChanged();
189  /**
190  * A change in the skip switcher property has been requested
191  **/
192  void skipSwitcherChanged();
193 
194  /**
195  * A surface with Role Panel and PanelBehavior AutoHide requested to be hidden.
196  *
197  * The compositor should inform the PlasmaShellSurfaceInterface about the actual change.
198  * Once the surface is hidden it should invoke {@link hideAutoHidingPanel}. If the compositor
199  * cannot hide the surface (e.g. because it doesn't border a screen edge) it should inform
200  * the surface through invoking {@link showAutoHidingPanel}. This method should also be invoked
201  * whenever the surface gets shown again due to triggering the screen edge.
202  *
203  * @see hideAutoHidingPanel
204  * @see showAutoHidingPanel
205  * @see panelAutoHideShowRequested
206  * @since 5.28
207  **/
208  void panelAutoHideHideRequested();
209 
210  /**
211  * A surface with Role Panel and PanelBehavior AutoHide requested to be shown.
212  *
213  * The compositor should inform the PlasmaShellSurfaceInterface about the actual change.
214  * Once the surface is shown it should invoke {@link showAutoHidingPanel}.
215  *
216  * @see hideAutoHidingPanel
217  * @see showAutoHidingPanel
218  * @see panelAutoHideHideRequested
219  * @since 5.28
220  **/
221  void panelAutoHideShowRequested();
222 
223  /*
224  * Emitted when panelTakesFocus changes
225  * @see panelTakesFocus
226  * @since 5.66
227  */
228  void panelTakesFocusChanged();
229 
230 private:
231  friend class PlasmaShellInterface;
232  explicit PlasmaShellSurfaceInterface(PlasmaShellInterface *shell, SurfaceInterface *parent, wl_resource *parentResource);
233  class Private;
234  Private *d_func() const;
235 };
236 
237 }
238 }
239 
242 
243 #endif
Global for the org_kde_plasma_shell interface.
Class holding the Wayland server display loop.
Definition: display.h:86
Resource for the org_kde_plasma_shell_surface interface.
Represents a bound Resource.
Definition: resource.h:31
Base class for all Globals.
Definition: global.h:46
Role
Describes possible roles this PlasmaShellSurfaceInterface can have.
PanelBehavior
Describes how a PlasmaShellSurfaceInterface with role Role::Panel should behave.
Resource representing a wl_surface.
virtual QVariant get(ScriptableExtension *callerPrincipal, quint64 objId, const QString &propName)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Jan 30 2023 03:56:24 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.