GCC Code Coverage Report

Line	Branch	Exec	Source
1			/********************************************************************
2			Copyright 2015 Martin Gräßlin <mgraesslin@kde.org>
3
4			This library is free software; you can redistribute it and/or
5			modify it under the terms of the GNU Lesser General Public
6			License as published by the Free Software Foundation; either
7			version 2.1 of the License, or (at your option) version 3, or any
8			later version accepted by the membership of KDE e.V. (or its
9			successor approved by the membership of KDE e.V.), which shall
10			act as a proxy defined in Section 6 of version 3 of the license.
11
12			This library is distributed in the hope that it will be useful,
13			but WITHOUT ANY WARRANTY; without even the implied warranty of
14			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15			Lesser General Public License for more details.
16
17			You should have received a copy of the GNU Lesser General Public
18			License along with this library. If not, see <http://www.gnu.org/licenses/>.
19			*********************************************************************/
20			#ifndef WAYLAND_PLASMASHELL_H
21			#define WAYLAND_PLASMASHELL_H
22
23			#include <QObject>
24			#include <QSize>
25			// STD
26			#include <Wrapland/Client/wraplandclient_export.h>
27			#include <memory>
28
29			struct wl_surface;
30			struct org_kde_plasma_shell;
31			struct org_kde_plasma_surface;
32
33			namespace Wrapland
34			{
35			namespace Client
36			{
37			class EventQueue;
38			class Surface;
39			class PlasmaShellSurface;
40
41			/**
42			* @short Wrapper for the org_kde_plasma_shell interface.
43			*
44			* This class provides a convenient wrapper for the org_kde_plasma_shell interface.
45			* It's main purpose is to create a PlasmaShellSurface.
46			*
47			* To use this class one needs to interact with the Registry. There are two
48			* possible ways to create the Shell interface:
49			* @code
50			* PlasmaShell *s = registry->createPlasmaShell(name, version);
51			* @endcode
52			*
53			* This creates the PlasmaShell and sets it up directly. As an alternative this
54			* can also be done in a more low level way:
55			* @code
56			* PlasmaShell *s = new PlasmaShell;
57			* s->setup(registry->bindPlasmaShell(name, version));
58			* @endcode
59			*
60			* The PlasmaShell can be used as a drop-in replacement for any org_kde_plasma_shell
61			* pointer as it provides matching cast operators.
62			*
63			* @see Registry
64			* @see PlasmaShellSurface
65			**/
66			class WRAPLANDCLIENT_EXPORT PlasmaShell : public QObject
67			{
68			Q_OBJECT
69			public:
70			explicit PlasmaShell(QObject* parent = nullptr);
71			virtual ~PlasmaShell();
72
73			/**
74			* @returns @c true if managing a org_kde_plasma_shell.
75			**/
76			bool isValid() const;
77			/**
78			* Releases the org_kde_plasma_shell interface.
79			* After the interface has been released the PlasmaShell instance is no
80			* longer valid and can be setup with another org_kde_plasma_shell interface.
81			*
82			* Right before the interface is released the signal interfaceAboutToBeReleased is emitted.
83			* @see interfaceAboutToBeReleased
84			**/
85			void release();
86
87			/**
88			* Setup this Shell to manage the @p shell.
89			* When using Registry::createShell there is no need to call this
90			* method.
91			**/
92			void setup(org_kde_plasma_shell* shell);
93
94			/**
95			* Sets the @p queue to use for creating a Surface.
96			**/
97			void setEventQueue(EventQueue* queue);
98			/**
99			* @returns The event queue to use for creating a Surface.
100			**/
101			EventQueue* eventQueue();
102
103			/**
104			* Creates a PlasmaShellSurface for the given @p surface and sets it up.
105			*
106			* If a PlasmaShellSurface for the given @p surface has already been created
107			* a pointer to the existing one is returned instead of creating a new surface.
108			*
109			* @param surface The native surface to create the PlasmaShellSurface for
110			* @param parent The parent to use for the PlasmaShellSurface
111			* @returns created PlasmaShellSurface
112			**/
113			PlasmaShellSurface* createSurface(wl_surface* surface, QObject* parent = nullptr);
114			/**
115			* Creates a PlasmaShellSurface for the given @p surface and sets it up.
116			*
117			* If a PlasmaShellSurface for the given @p surface has already been created
118			* a pointer to the existing one is returned instead of creating a new surface.
119			*
120			* @param surface The Surface to create the PlasmaShellSurface for
121			* @param parent The parent to use for the PlasmaShellSurface
122			* @returns created PlasmaShellSurface
123			**/
124			PlasmaShellSurface* createSurface(Surface* surface, QObject* parent = nullptr);
125
126			operator org_kde_plasma_shell*();
127			operator org_kde_plasma_shell*() const;
128
129			Q_SIGNALS:
130			/**
131			* This signal is emitted right before the interface is released.
132			**/
133			void interfaceAboutToBeReleased();
134
135			/**
136			* The corresponding global for this interface on the Registry got removed.
137			*
138			* This signal gets only emitted if the Compositor got created by
139			* Registry::createPlasmaShell
140			*
141			* @since 5.5
142			**/
143			void removed();
144
145			private:
146			class Private;
147			std::unique_ptr<Private> d;
148			};
149
150			/**
151			* @short Wrapper for the org_kde_plasma_surface interface.
152			*
153			* This class is a convenient wrapper for the org_kde_plasma_surface interface.
154			*
155			* To create an instance use PlasmaShell::createSurface.
156			*
157			* A PlasmaShellSurface is a privileged Surface which can add further hints to the
158			* Wayland server about it's position and the usage role. The Wayland server is allowed
159			* to ignore all requests.
160			*
161			* Even if a PlasmaShellSurface is created for a Surface a normal ShellSurface (or similar)
162			* needs to be created to have the Surface mapped as a window by the Wayland server.
163			*
164			* @see PlasmaShell
165			* @see Surface
166			**/
167			class WRAPLANDCLIENT_EXPORT PlasmaShellSurface : public QObject
168			{
169			Q_OBJECT
170			public:
171			explicit PlasmaShellSurface(QObject* parent);
172			virtual ~PlasmaShellSurface();
173
174			/**
175			* Releases the org_kde_plasma_surface interface.
176			* After the interface has been released the PlasmaShellSurface instance is no
177			* longer valid and can be setup with another org_kde_plasma_surface interface.
178			*
179			* This method is automatically invoked when the PlasmaShell which created this
180			* PlasmaShellSurface gets released.
181			**/
182			void release();
183
184			/**
185			* Setup this PlasmaShellSurface to manage the @p surface.
186			* There is normally no need to call this method as it's invoked by
187			* PlasmaShell::createSurface.
188			**/
189			void setup(org_kde_plasma_surface* surface);
190
191			/**
192			* @returns the PlasmaShellSurface * associated with surface,
193			* if any, nullptr if not found.
194			* @since 5.6
195			*/
196			static PlasmaShellSurface* get(Surface* surf);
197
198			/**
199			* @returns @c true if managing a org_kde_plasma_surface.
200			**/
201			bool isValid() const;
202			operator org_kde_plasma_surface*();
203			operator org_kde_plasma_surface*() const;
204
205			/**
206			* Describes possible roles this PlasmaShellSurface can have.
207			* The role can be used by the Wayland server to e.g. change the stacking order accordingly.
208			**/
209			enum class Role {
210			Normal, ///< A normal Surface
211			Desktop, ///< The Surface represents a desktop, normally stacked below all other surfaces
212			Panel, ///< The Surface represents a panel (dock), normally stacked above normal surfaces
213			OnScreenDisplay, ///< The Surface represents an on screen display, like a volume changed
214			///< notification
215			Notification, ///< The Surface represents a notification @since 0.0.524
216			ToolTip, ///< The Surface represents a tooltip @since 0.0.524
217			CriticalNotification,
218			AppletPopup,
219			};
220			/**
221			* Changes the requested Role to @p role.
222			* @see role
223			**/
224			void setRole(Role role);
225			/**
226			* @returns The requested Role, default value is @c Role::Normal.
227			* @see setRole
228			**/
229			Role role() const;
230			/**
231			* Requests to position this PlasmaShellSurface at @p point in global coordinates.
232			**/
233			void setPosition(QPoint const& point);
234
235			/**
236			* Describes how a PlasmaShellSurface with role @c Role::Panel should behave.
237			* @see Role
238			**/
239			enum class PanelBehavior {
240			AlwaysVisible,
241			AutoHide,
242			WindowsCanCover,
243			WindowsGoBelow,
244			};
245			/**
246			* Sets the PanelBehavior for a PlasmaShellSurface with Role @c Role::Panel
247			* @see setRole
248			**/
249			void setPanelBehavior(PanelBehavior behavior);
250
251			/**
252			* Setting this bit to the window, will make it say it prefers
253			* to not be listed in the taskbar. Taskbar implementations
254			* may or may not follow this hint.
255			* @since 5.5
256			*/
257			void setSkipTaskbar(bool skip);
258
259			/**
260			* Setting this bit on a window will indicate it does not prefer
261			* to be included in a window switcher.
262			* @since 0.0.547
263			*/
264			void setSkipSwitcher(bool skip);
265
266			/**
267			* Requests to hide a surface with Role Panel and PanelBahvior AutoHide.
268			*
269			* Once the compositor has hidden the panel the signal {@link autoHidePanelHidden} gets
270			* emitted. Once it is shown again the signal {@link autoHidePanelShown} gets emitted.
271			*
272			* To show the surface again from client side use {@link requestShowAutoHidingPanel}.
273			*
274			* @see autoHidePanelHidden
275			* @see autoHidePanelShown
276			* @see requestShowAutoHidingPanel
277			* @since 0.0.528
278			**/
279			void requestHideAutoHidingPanel();
280
281			/**
282			* Requests to show a surface with Role Panel and PanelBahvior AutoHide.
283			*
284			* This request allows the client to show a surface which it previously
285			* requested to be hidden with {@link requestHideAutoHidingPanel}.
286			*
287			* @see autoHidePanelHidden
288			* @see autoHidePanelShown
289			* @see requestHideAutoHidingPanel
290			* @since 0.0.528
291			**/
292			void requestShowAutoHidingPanel();
293
294			/**
295			* Set whether a PlasmaShellSurface should get focus or not.
296			*
297			* By default some roles do not take focus. With this request the compositor
298			* can be instructed to also pass focus.
299			*
300			* @param takesFocus Set to @c true if the surface should gain focus.
301			* @since 0.0.528
302			**/
303			// KF6 TODO rename to make it generic
304			void setPanelTakesFocus(bool takesFocus);
305			void request_open_under_cursor();
306
307			Q_SIGNALS:
308			/**
309			* Emitted when the compositor hided an auto hiding panel.
310			* @see requestHideAutoHidingPanel
311			* @see autoHidePanelShown
312			* @see requestShowAutoHidingPanel
313			* @since 0.0.528
314			**/
315			void autoHidePanelHidden();
316
317			/**
318			* Emitted when the compositor showed an auto hiding panel.
319			* @see requestHideAutoHidingPanel
320			* @see autoHidePanelHidden
321			* @see requestShowAutoHidingPanel
322			* @since 0.0.528
323			**/
324			void autoHidePanelShown();
325
326			private:
327			friend class PlasmaShell;
328			class Private;
329			std::unique_ptr<Private> d;
330			};
331
332			}
333			}
334
335	3/6 ✗ Branch 0 not taken. ✓ Branch 1 taken 1 times. ✓ Branch 2 taken 1 times. ✗ Branch 3 not taken. ✓ Branch 4 taken 1 times. ✗ Branch 5 not taken.	1	Q_DECLARE_METATYPE(Wrapland::Client::PlasmaShellSurface::Role)
336	3/6 ✗ Branch 0 not taken. ✓ Branch 1 taken 1 times. ✓ Branch 2 taken 1 times. ✗ Branch 3 not taken. ✓ Branch 4 taken 1 times. ✗ Branch 5 not taken.	1	Q_DECLARE_METATYPE(Wrapland::Client::PlasmaShellSurface::PanelBehavior)
337
338			#endif
339