Differential D12820 Diff 44643 src/client/plasmavirtualdesktop.h

Changeset View

Standalone View

src/client/plasmavirtualdesktop.h

This file was added.

1		/****************************************************************************
2		Copyright 2018 Marco Martin <notmart@gmail.com>
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 KWAYLAND_CLIENT_PLASMAVIRTUALDESKTOP_H
21		#define KWAYLAND_CLIENT_PLASMAVIRTUALDESKTOP_H
22
23		#include <QObject>
24
25		#include <KWayland/Client/kwaylandclient_export.h>
26
27		struct org_kde_plasma_virtual_desktop_management;
28		struct org_kde_plasma_virtual_desktop;
29
30		namespace KWayland
31		{
32		namespace Client
33		{
34
35		class EventQueue;
36		class PlasmaVirtualDesktop;
37
38		/**
39		* @short Wrapper for the org_kde_plasma_virtual_desktop_management interface.
40		*
41		* This class provides a convenient wrapper for the org_kde_plasma_virtual_desktop_management interface.
42		*
43		* To use this class one needs to interact with the Registry. There are two
44		* possible ways to create the PlasmaVirtualDesktopManagement interface:
45		* @code
46		* PlasmaVirtualDesktopManagement *c = registry->createPlasmaVirtualDesktopManagement(name, version);
47		* @endcode
48		*
49		* This creates the PlasmaVirtualDesktopManagement and sets it up directly. As an alternative this
50		* can also be done in a more low level way:
51		* @code
52		* PlasmaVirtualDesktopManagement *c = new PlasmaVirtualDesktopManagement;
53		* c->setup(registry->bindPlasmaVirtualDesktopManagement(name, version));
54		* @endcode
55		*
56		* The PlasmaVirtualDesktopManagement can be used as a drop-in replacement for any org_kde_plasma_virtual_desktop_management
57		* pointer as it provides matching cast operators.
58		* @since 5.46
59		*
60		* @see Registry
61		**/
62		class KWAYLANDCLIENT_EXPORT PlasmaVirtualDesktopManagement : public QObject
63		{
64		Q_OBJECT
65		public:
66		/**
67		* Creates a new PlasmaVirtualDesktopManagement.
68		* Note: after constructing the PlasmaVirtualDesktopManagement it is not yet valid and one needs
69		* to call setup. In order to get a ready to use PlasmaVirtualDesktopManagement prefer using
70		* Registry::createPlasmaVirtualDesktopManagement.
71		**/
72		explicit PlasmaVirtualDesktopManagement(QObject *parent = nullptr);
73		virtual ~PlasmaVirtualDesktopManagement();
74
75		/**
76		* Setup this PlasmaVirtualDesktopManagement to manage the @p plasmavirtualdesktopmanagement.
77		* When using Registry::createPlasmaVirtualDesktopManagement there is no need to call this
78		* method.
79		**/
80		void setup(org_kde_plasma_virtual_desktop_management *plasmavirtualdesktopmanagement);
81		/**
82		* @returns @c true if managing a org_kde_plasma_virtual_desktop_management.
83		**/
84		bool isValid() const;
85		/**
86		* Releases the org_kde_plasma_virtual_desktop_management interface.
87		* After the interface has been released the PlasmaVirtualDesktopManagement instance is no
88		* longer valid and can be setup with another org_kde_plasma_virtual_desktop_management interface.
89		**/
90		void release();
91		/**
92		* Destroys the data held by this PlasmaVirtualDesktopManagement.
93		* This method is supposed to be used when the connection to the Wayland
94		* server goes away. If the connection is not valid anymore, it's not
95		* possible to call release anymore as that calls into the Wayland
96		* connection and the call would fail. This method cleans up the data, so
97		* that the instance can be deleted or set up to a new org_kde_plasma_virtual_desktop_management interface
98		* once there is a new connection available.
99		*
100		* It is suggested to connect this method to ConnectionThread::connectionDied:
101		* @code
102		* connect(connection, &ConnectionThread::connectionDied, plasmavirtualdesktopmanagement, &PlasmaVirtualDesktopManagement::destroy);
103		* @endcode
104		*
105		* @see release
106		**/
107		void destroy();
108
109		/**
110		* Sets the @p queue to use for creating objects with this PlasmaVirtualDesktopManagement.
111		**/
112		void setEventQueue(EventQueue *queue);
113
114		/**
115		* @returns The event queue to use for creating objects with this PlasmaVirtualDesktopManagement.
116		* The object is owned by the manager and the caller should not delete it.
117		**/
118		EventQueue *eventQueue();
119
120		/**
121		* @returns the PlasmaVirtualDesktop representing the desktop id.
122		* The PlasmaVirtualDesktop instance is guaranteed to be unique for each id.
123		*/
124		PlasmaVirtualDesktop *getVirtualDesktop(const QString &id);
125
126		/**
127		* Requests for the desktop identified by id to be removed.
128		* The server may or may not acconsent to the request.
129		*/
130		void requestRemoveVirtualDesktop(const QString &id);
131
132		/**
133		* Ask the server to create a new virtual desktop, and position it at a specified position.
134		* If the position is zero or less, it will be positioned at the beginning,
135		* if the cosition is the count or more, it will be positioned at the end.
136		* @param name The name we want for the desktop
137		* @param position The position for the desktop to be created
138		*/
139		void requestCreateVirtualDesktop(const QString &name, quint32 position = std::numeric_limits<uint32_t>::max());
140
141		/**
142		* @returns All the existent virtual desktops
	romanggUnsubmitted Not Done This signal is unneeded when `desktopRemoved` is there as well. romangg: This signal is unneeded when `desktopRemoved` is there as well.
143		*/
144		QList <PlasmaVirtualDesktop *> desktops() const;
145
146		operator org_kde_plasma_virtual_desktop_management*();
147		operator org_kde_plasma_virtual_desktop_management*() const;
148
149		Q_SIGNALS:
150		void removed();
151
152		/**
153		* Emitted when a new desktop has been added
154		*/
155		void desktopCreated(const QString &id, quint32 position);
156
157		/**
158		* Emitted when a desktop has been removed
159		*/
160		void desktopRemoved(const QString &id);
161
162		/**
163		* This event is sent after all other properties has been
164		* sent after binding to the desktop manager object and after any
165		* other property changes done after that. This allows
166		* changes to the org_kde_plasma_virtual_desktop_management properties
167		* to be seen as atomic, even if they happen via multiple events.
168		*/
169		void done();
170
171		private:
172		class Private;
173		QScopedPointer<Private> d;
174		};
175
176		class KWAYLANDCLIENT_EXPORT PlasmaVirtualDesktop : public QObject
177		{
178		Q_OBJECT
179		public:
180		virtual ~PlasmaVirtualDesktop();
181
182		/**
183		* Setup this PlasmaVirtualDesktop to manage the @p plasmavirtualdesktop.
184		* When using PlasmaVirtualDesktopManagement::createPlasmaVirtualDesktop there is no need to call this
185		* method.
186		**/
187		void setup(org_kde_plasma_virtual_desktop *plasmavirtualdesktop);
188
189		/**
190		* @returns @c true if managing a org_kde_plasma_virtual_desktop.
191		**/
192		bool isValid() const;
193
194		/**
195		* Releases the org_kde_plasma_virtual_desktop interface.
196		* After the interface has been released the PlasmaVirtualDesktop instance is no
197		* longer valid and can be setup with another org_kde_plasma_virtual_desktop interface.
198		**/
199		void release();
200
201		/**
202		* Destroys the data held by this PlasmaVirtualDesktop.
203		* This method is supposed to be used when the connection to the Wayland
204		* server goes away. If the connection is not valid anymore, it's not
205		* possible to call release anymore as that calls into the Wayland
206		* connection and the call would fail. This method cleans up the data, so
207		* that the instance can be deleted or set up to a new org_kde_plasma_virtual_desktop interface
208		* once there is a new connection available.
209		*
210		* It is suggested to connect this method to ConnectionThread::connectionDied:
211		* @code
212		* connect(connection, &ConnectionThread::connectionDied, plasmavirtualdesktop, &PlasmaVirtualDesktop::destroy);
213		* @endcode
214		*
215		* @see release
216		**/
217		void destroy();
218
219		/**
220		* Requests this desktop to be activated.
221		* The server may or may not decide to consent to the request.
222		*/
223		void requestActivate();
224
225		/**
226		* @returns The unique id of this desktop. The format of the id is decided by the compositor
227		*/
228		QString id() const;
229
230
231		/**
232		* @returns User readable name for the desktop.
233		*/
234		QString name() const;
235
236		/**
237		* @returns True if the desktop is the active one.
238		* when this property changes, activated or deactivated will be emitted.
239		* @see activated
240		* @see deactivated
241		*/
242		bool isActive() const;
243
244		operator org_kde_plasma_virtual_desktop*();
245		operator org_kde_plasma_virtual_desktop*() const;
246
247		Q_SIGNALS:
248		/**
249		* TODO: activeChanged(bool)?
250		* Emitted when this desktop has been activated by the server
251		*/
252		void activated();
253
254		/**
255		* Emitted when this desktop has been activated by the server
256		*/
257		void deactivated();
258
259		/**
260		* This event is sent after all other properties has been
261		* sent after binding to the desktop manager object and after any
262		* other property changes done after that. This allows
263		* changes to the org_kde_plasma_virtual_desktop properties
264		* to be seen as atomic, even if they happen via multiple events.
265		*/
266		void done();
267
268		/**
269		* This virtual desktop has just been removed by the server:
270		* This object itself is about to be deleted. All windows will
271		* lose the association to this desktop.
272		*/
273		void removed();
274
275		private:
276		friend class PlasmaVirtualDesktopManagement;
277		explicit PlasmaVirtualDesktop(QObject *parent = nullptr);
278		class Private;
279		QScopedPointer<Private> d;
280		};
281
282
283		}
284		}
285
286		#endif