KWaylandServer

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

KDE's Doxygen guidelines are available online.